ossp-pkg/rc/rc.pod
1.19
##
## rc.pod -- OSSP Run Command Processor (Manual Page)
## Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
## Copyright (c) 2000-2002 The OSSP Project <http://www.ossp.org/>
## Copyright (c) 2000-2002 Ralf S. Engelschall <rse@engelschall.com>
##
## Permission to use, copy, modify, and distribute this software for
## any purpose with or without fee is hereby granted, provided that
## the above copyright notice and this permission notice appear in all
## copies.
##
## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
## SUCH DAMAGE.
##
=pod
=head1 NAME
=over 4
B<rc> - OSSP Run Command Processor
=back 4
=head1 SYNOPSIS
=over 4
=item B<General>
@l_prefix@/etc/rc
[B<-c>|B<--conf> I<file>[C<:>I<file>[...]]]
[B<-t>|B<--tmp> I<dir>]
[B<-r>|B<--raw>]
[B<-v>|B<--verbose>]
[B<-D>|B<--debug>]
=item B<Run-Command Execution>
@l_prefix@/etc/rc
[I<General options>]
[B<-x>|B<--exec>]
[B<-p>|B<--print>]
[B<-e>|B<--eval>]
[B<-d>|B<--dirs> I<dir>[C<:>I<dir>[...]]
[B<-f>|B<--func> I<file>[C<:>I<file>[...]]]
[B<-F>|B<--force>]
I<rcfile>
I<section>
[I<section> ...]
=item B<Configuration Query>
@l_prefix@/etc/rc
[I<General options>]
B<-q>|B<--query> I<format>
[B<-d>|B<--dirs> I<dir>[C<:>I<dir>[...]]
[B<-F>|B<--force>]
I<rcfile>
=item B<Looking up available labels>
[I<General options>]
<-l>|<--labels>
[B<-d>|B<--dirs> I<dir>[C<:>I<dir>[...]]
[B<-F>|B<--force>]
I<rcfile>
# FIXME Ralf, what's that?
# @l_prefix@/etc/rc
# [I<parameter-options>]
# [B<-c>|B<--conf>]
# [I<package>]
=item B<Facility Information>
@l_prefix@/etc/rc
[I<General options>]
[B<-i>|B<--info>]
=item B<Other>
@l_prefix@/etc/rc
[B<-?>|B<--usage>]
[B<-h>|B<--help>]
[B<-V>|B<--version>]
=back 4
=head1 DESCRIPTION
=over 4
OSSP rc is a run command processor. It's primary function is to scan F<rcfile>
script files for B<section>(s) identified by corresponding label(s) and run the
commands in the section(s).
The run command processor can also only print the commands without executing
them or reformat them to C<eval> input. The F<rcfile> files contain variables
and the command processor has functionality to query their default, set and
effective values.
To understand the structure and syntax of F<rcfile> script files, an example
called F<rc.example> is included in the distribution. The rc environment and
behaviour is very configurable, so the syntax may vary and not match exactly
the example provided.
With a single call to rc usually one F<rcfile> may be processed at, although
many sections can be given to source their corresponding commands, see
EXAMPLES below.
There is one exception to this rule in which an rc keyword named `all' is
reserved to mean `all F<rcfile>s.' The user may thus give the `all' wildcard
in place of the C<rcfile> parameter to process the commands from the given
sections of all C<rcfile>s found.
#THL! does "all stop start" mean "a stop stop, a start, b start" or " a stop,
#a start, b stop, b start"?
#Prioritaeten
#Using the `all' wildcard may be risky in some cases, because successful
#performance then depends not only on the code written into each program's
#sections but also if every single program found has the named section label at
#all. For information about the rc exit status after such an operation see
#`DIAGNOSTICS.'
=back 4
=head1 OPTIONS
=over 4
Inclusive options which may be used with another
=item B<-c>, B<--conf> F<file>
specify the location of the configuration file.
=item B<-f>, B<--func> F<file>[C<:>F<file>[...]]
specify the location of one or more optional function files, containing
commands which are prepended to the sections of their corresponding
C<rcfile>s.
=item B<-F>, B<--force>
Disable ${OSSP_RC_PREFIX} and ${OSSP_RC_SUFFIX} expansion on F<rcfile>.
Disable searching for F<rcfile>. This mode assumes F<rcfile> is a filename. It
is automagically entered when the F<rcfile> matches the regex '^\.{0,2}/'.
=item B<-d>, B<--dirs> I<dir>[C<:>I<dir>[...]
override OSSP_RC_DIRS, and use these paths to search for F<rcfile>s instead.
=item B<-t>, B<--tmpdir> I<dir>
specify the location of the temporary directory
=item B<-v>, B<--verbose>
verbosely report processing, including all warnings
=item B<-s>, B<--silent>
be silent, and disable output
=item B<-D>, B<--debug>
don't remove temporary files, and output debug messages to stderr
=item B<-r>, B<--raw>
output text using no terminal control sequences
=back 4
Mutually exclusive options, i.e. only a single one can be given
=over 4
=item B<-h>, B<--help>
print this help, then exit
=item B<-?>, B<--usage>
print short usage summary, then exit.
=item B<-V>, B<--version>
print version and copyright, then exit
=item B<-p>, B<--print>
output the commands as they would by seen by the command interpreter, but do
not run them.
=item B<-e>, B<--eval>
output the text for a command suitable for shell evaluation, but do not run
it.
=item B<-x>, B<--exec>
execute the command interpreter in a subprocess and actually run the commands.
=item B<-q>, B<--query>
print the value(s) of rc configuration variables defined in the %config section.
=item B<-l>, B<--labels>
learn what section labels a F<rcfile> offers.
=item B<-i>, B<--info>
print a comprehensive summary of the rc environment
=back 4
=head1 NOTES
=over 4
=item B<-h>, B<--help>, B<-V>, B<--version>, B<-v>, B<--verbose>, and B<-q>
B<--silent>
The B<--help>, B<--version>, B<--verbose>, and B<--silent> options are used to
control the screen output of B<rc> and control the general output of all
sections found in the F<rcfile>s as well. For example, specifying
B<--silent> will mute B<rc>'s output and also all command output that B<rc>
runs.
=item B<-r>, B<--raw> I<dir>
The option B<-r> or B<--raw> turns on raw output mode. In this case, no
formatting is done to the screen output. This mode is different from formatted
output mode, in which the output is annotated with terminal control sequences
for better readability.
=item B<-t>, B<--tmp> I<dir>
Specifying this option will force B<rc> to use the given temporary
directory I<dir> for all its temporary output.
=item B<-e>, B<--eval> and B<-p>, B<--print>
With the B<--eval> or B<--print> options, the run command will not be
executed. Rather, B<rc> will print a command suitable for later evaluation in
the current shell. Given alone, this option will cause B<rc> to not execute
the run command. Used together with B<--exec>, B<rc> will execute the run
command and print a similar command for later execution as well. The B<--eval>
option cannot be used together with B<--print>, because of conflicting output
and the way that B<rc> constructs the evaluation text. Specifically, most
Bourne shells and derivatives report errors with commands spanning multiple
lines.
Consider using the B<--eval> option for batch evaluation with the Bourne shell
C<eval> command. Use the B<--print> option for better human readability. See
`EXAMPLES' for an example.
=item B<-x>, B<--exec>
The B<--exec> is the most common option of all, in which B<rc> executes a run command
made up of a given program and section. Options controlling the flow of
execution include B<--print>, B<--eval>, and B<--exec>.
=item B<-q>, B<--query>
The B<--query> option queries the I<effective> value of one or more
configuration variables. These variables are set in the C<%config> section of
the corresponding F<rcfile>. The B<--query> option reports the
I<effective> value, and not necessarily that written in the F<rcfile>
file, which can be overridden by variable settings in the F<rc.env> file.
Used with the B<--query> option, B<rc> will expect exactly one command line
argument to follow. This must be a I<format> string containing arbitrary text
and optionally one or more B<OSSP var> variable specifications
("C<${>I<name>C<}>" in its simplest form.)
!FIXME what is var here!
=back 4
=head1 DEFAULT VALUES
=over 4
In B<OSSP rc>, all options have a reasonable default value. This allows for a
configurationless B<rc> installation.
=item B<-r>, B<--raw>
The B<--raw> option determines its default at runtime. If the raw mode option
is not specified, B<rc> will determine whether F<stdout> is connected to a
terminal. If so, B<rc> will run in formatted output mode. If F<stdout> is not
connected to a terminal (such as with most daemons,) B<rc> will run in raw
output mode even though it was not specified as an option.
=item B<-t>, B<--tmpdir> I<dir>
If the B<--dirs> option is not given, B<rc> will try to use C<$TMPDIR>,
C<$TEMPDIR>, C<~/tmp> and C</tmp> (in that order.)
=item B<-p>, B<--print>, B<-e>, B<--eval>, B<-x>, B<--exec>
If neither B<--print>, B<--eval>, or B<-exec> is given B<rc> will default to
B<--exec>.
=item B<-c>, B<--conf> F<file>
Using F<file> from command line option -c aka --conf, fallback to
${OSSP_RC_CONF}, fallback to "@l_prefix@/etc/rc.conf".
=item B<-f>, B<--func> F<file>[C<:>F<file>[...]]
=item B<-F>, B<--force>
=item B<-d>, B<--dirs> I<dir>[C<:>I<dir>[...]
#!FIXME! Sprech mal von Pfad und Dateien defaults wieviel rc.conf erlaubt
#!FIXME! sind, und welche genommen wird oder sonst wie gemerged.
F<rc.conf>
F<rc.func>
F<rc.env>
F<rcfile>
=head1 ENVIRONMENT
=over 4
Every command line longoption is also a keyword in the rc.conf file and,
prefixed with "OSSP_RC_" and it's name in upper case, also available as an
environment variable.
The environment determines where rc will search before beginning to process
run commands. It also influences B<rc's> behaviour, just as the command line
options do. There is no difference between typing an option in the command
line, and appending the same option to the OSSP_RC_OPTS variable.
#!FIXME! Study this and determine if it is needed
#OSSP_RC_IMPLS - Other rc implementations
#
#The OSSP_RC_IMPLS variable plays a role only when the user has more than one
#logical set of run command sections. If rc reads anything but EOL in this
#variable, it will assume that more than one rc implementation exists. The
#variable should contain a chain of paths where other rc implementations are.
#This allows the user to build several OSSP rc hierarchies and then switch from
#each... Blah FIXME I don't know if we should be paying attention to the
#ENVIRONMENT guys. Maybe this is not a good solution for our dynamic OpenPKG
#environment problem after all.
=back 4
=head1 RETURN VALUE
=over 4
-1 Faulty run command hierarchy
0 Success
1 One or more run commands failed
=back 4
=head1 EXAMPLES
=over 4
Some short one line examples include the following. Note that a run command
consists of a single program name and one or more sections. The wildcard `all'
can be given in place of a program name to denote all programs with entries in
the rc registry F<$OSSP_RC_ROOT/rc.d>.
/usr/local/bin/rc --info
/etc/rc --query lmtp2nntp
/mybin/rc sshd start
/etc/rc lmtp2nntp start
/sfw/etc/rc --conf /etc/rc.conf --debug smtpd stop
/sfw/etc/rc --silent ntpd start sync stop start
/usr/local/bin/rc httpd restart
To evaluate a run command for all programs with an identical section name, a
short expression can be written into a F<.profile> file. When the shell
initializes itself, the run commands will execute according to the C<eval>
command. This is often seen when importing the environment of packages of an
B<OpenPKG> hierarchy.
=over 4
$ eval `@l_prefix@/etc/rc --eval all env`
=back 4
=back 4
=head1 FILES
=over 4
F<rc.conf> - Master configuration file
The following filenames are specified in F<rc.conf>. Both their names and
locations may be different due to user customizations.
=over 4
F<rc.func> - User defined functions file
F<rc.env> - Postprocess variable declaration file
F<rc.\<rcfile\>> - Run command file
=back 4
=back 4
=head1 SEE ALSO
=over 4
OSSP rc integrates concepts taken from other run command architectures. For
more information, inspect the /etc/rc structures provided by FreeBSD, Solaris,
and Red Hat distributions.
rc.conf(1), rc.func(1), rc.env(1), rcfile(1), and rc-sample(1).
=back 4
=head1 DIAGNOSTICS
=over 4
If rc fails while processing a run command, the exit status will be 1. If rc
failed due to a broken run command configuration, the exit status will be -1.
This can happen if a script file is moved or renamed, for example. If the run
command configuration is broken, no further action is taken and no run
commands are processed.
Importantly, if the keyword `all' is given as the program wildcard parameter,
then processing will begin and continue until the first error is reached.
Should an error arise, processing will stop and the exit status will be 1.
There is no way to learn which command caused the error unless it is apparent
from the text output of the rc process.
=back 4
=head1 AUTHORS
=over 4
Ralf S. Engelschall
Michael Schloh von Bennewitz
=back 4
=head1 HISTORY
=over 4
B<OSSP rc> is a replacement for the prototype run command facility used in the
OpenPKG project (http://www.openpkg.org/). The prototype was a slow and less
robust Bourne shell script. B<OSSP rc> is intended to faster, more robust, and
more flexible. This flexibility allows for wider range of use, however. B<OSSP
rc> can therefore be used in a variety of situations, and is no longer
exclusive to the OpenPKG project.
=back 4
=cut
