ossp-pkg/rc/rc.pod
1.34
##
## 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
B<rc> - OSSP Run-command Processor
=head1 SYNOPSIS
B<rc>
[B<-?>|B<--usage>]
[B<-D>|B<--debug>]
[B<-L>|B<--locate> I<dir>[C<:>I<dir>[...]]]
[B<-V>|B<--version>]
[B<-c>|B<--conf> I<file>[C<:>I<file>[...]]]
[B<-e>|B<--eval>]
[B<-f>|B<--func> I<file>[C<:>I<file>[...]]]
[B<-h>|B<--help>]
[B<-i>|B<--info>]
[B<-l>|B<--labels>]
[B<-p>|B<--print>]
[B<-q>|B<--query>] I<format>
[B<-s>|B<--silent>]
[B<-r>|B<--raw>]
[B<-t>|B<--tmp> I<dir>]
[B<-v>|B<--verbose>]
[B<-x>|B<--exec>]
[B<--RequireUmask umask>]
[B<--RequireOwner uid|name>]
[B<--RequireGroup gid|name>]
[B<--ParseEnvAss regex>]
[B<--ParseSectionDef regex>]
[B<--ParseSectionRef regex>]
[B<--ParseSectionParam regex>]
[B<--ParseTerminal regex>]
[B<--NameConfig> name]
[B<--NameCommon> name]
[B<--NameDefault> name]
[B<--NameError> name]
I<<rcfile>>
I<<section[...]>>
=head1 DESCRIPTION
OSSP rc is a run-command processor. Its primary function is to scan F<rcfile>
script files for one or more B<section>s and run the commands listed in each
B<section>.
The run-command processor can alternatively C<print> the commands in human
readable format or reformat them for shell C<eval> input without executing
them. The F<rcfile> files contain variables and the command processor has
functionality to query their default, set and effective values.
The structure of the F<rcfile>s is simple but the syntax is highly
configurable. A F<rcfile> is divided into B<section>s, clearly identified by
applying a regular expression. The default regular expression leads to
identification of section text starting with a percent (%) and label (any
text). Various examples of this and other syntax possibilities is given in the
manpage B<rc(1)>.
Often, only a single B<rcfile> name is processed. To process all B<rcfile>s,
substitute the keyword 'all' for the B<rcfile> name. The B<section>s of a
B<rcfil> processed match exactly the B<section>s given on the command line,
and even the ordering is kept.
=head1 OPTIONS
=item B<-?>|B<--usage>
print short usage summary, then exit.
=item B<-D>|B<--debug>
don't remove temporary files, and output debug messages to stderr
=item B<-L>|B<--locate> I<file>[C<:>I<part>]
locations to search for F<rcfile>s where I<file> can contain regex patterns to
filter files. The trailing part (after the ':') is a regex filter used to
ignore parts of a file. This option can be specified more than once.
=item B<-V>|B<--version>
print version and copyright, then exit
=item B<-c>|B<--conf> I<file>[C<:>I<file>[...]]
specify the location of the configuration file. If omitted, C<$OSSP_RC_CONF>
will be examined. If absent, F</etc/rc.conf> will be used. If no
F<rc.conf> exists at all, then only command line and environment specified
options will override the defaults built-in to OSSP rc.
=item B<-e>|B<--eval>
output the commands text in a format suitable for shell evaluation, but do not run it.
=item B<-f>|B<--func> I<file>[C<:>I<file>[...]]
specify the location of one or more optional function files. They act like
libraries, containing commands which are prepended to the sections of their
corresponding C<rcfile>s just before execution.
=item B<-h>|B<--help>
print this help, then exit
=item B<-i>|B<--info>
print a comprehensive summary of the rc environment
=item B<-l>|B<--labels>
learn what section labels a F<rcfile> offers.
=item B<-p>|B<--print>
output the commands text in a format suitable for human reading, but do not run it.
=item B<-q>|B<--query> I<format>
query the effective value of configuration variables from the %config section
and print them using the I<format> string specified in RPM style.
=item B<-r>|B<--raw>
output text using no terminal control sequences. The rc facility usually
tries to improve output text for human readability using terminal control
sequences for color, bold and italic rendering. The default is determines at
runtime and is automagically disabled if stdout is detached from a terminal.
=item B<-s>|B<--silent>
be silent, and disable output
=item B<-t>|B<--tmp> I<dir>
specify the location of the temporary directory. If omitted, the fallback is
to look for C<$TMPDIR>, C<$TMPDIR>, try using C<~/tmp> and C</tmp>, in that
order.
=item B<-v>|B<--verbose>
be verbose, output what's going on.
=item B<-x>|B<--exec>
execute the command interpreter in a subprocess and actually run the commands.
If neither B<--print>, B<--eval>, or B<-exec> is given, the default is
B<--exec> anyway.
=item B<--RequireUmask umask>
umask a F<rcfile> has to have, otherwise it's ignored.
=item B<--RequireOwner uid|name>
owner of the F<rcfile> must match uid|name, otherwise it's ignored.
=item B<--RequireGroup gid|name>
group of the F<rcfile> must match gid|name, otherwise it's ignored.
=item B<--ParseConfigAss regex>
regex matching the variable assignments in a F<rcfile>.
=item B<--ParseSectionDef regex>
regex matching a section label in a F<rcfile>.
=item B<--ParseSectionRef regex>
regex matching a reference in a F<rcfile>.
=item B<--ParseSectionParam regex>
regex matching a section parameter in a F<rcfile>.
=item B<--ParseTerminal regex>
regex matching a terminal symbol in a F<rcfile>. See LANGUAGE.
=item B<--NameConfig> name
name of the config section, defaults to %config.
=item B<--NameCommon> name
name of the common section, defaults to %common.
=item B<--NameDefault> name
name of the default section, defaults to %default.
=item B<--NameError> name
name of the error section, defaults to %error.
Every command line longoption corresponds to a keyword in the F<rc.conf> file.
When prefixed with 'OSSP_RC_' and its name in upper case, an option can be set
as an environment variable. First, options from the F<rc.conf> file are read.
Then, options from the environment are read. Last, options from the command
line are read. This allows for flexibility when wishing to set a standard set
of OSSP rc options, and override them conditionally.
=head1 ENVIRONMENT
The environment contains options just as the command line and F<rc.conf> file
does. An option's corresponding environment variable name must start with
'OSSP_RC_' and be all upper case. As a security measure, one environment
variable exists that is not found as an option elsewhere. This variable
deactivates B<OSSP rc>, and each subsequent usage will return success and
write 'No commands run: OSSP_RC_DEACT set to yes' to the console and syslog
with LOG_USER and LOG_ERR (see syslog(3)).
B<OSSP_RC_DEACT> - Set to 'yes' or 'true' to totally deactivate B<OSSP rc>
=head1 COMMAND INTERPRETER
As long as a valid interpreter path is specified in the section labels of a
F<rcfile>, the runcommands resulting from a --eval, --exec, or --print
operation can be written in any runtime-interpreted language. This means that
a perl programmer can write runcommands in perl, and specify the perl
interpreter path in the corresponding section label of the F<rcfile>. A
different programming language can be used for each section, even though this
would complicate inclusion of script from the B<%common> section and
F<rc.func> sections (because each section is associated with only one
interpreter). If the command interpreter in a section label is not specified,
then the Bourne shell will be used by default. See FILES/rc.foo for details.
=head1 RETURN VALUE
-1 Error in rc
0 Success
1 Error in command executed by rc
=head1 ERROR HANDLING
Rich and fine-tuned error handling is possible by writing one or both of the
following sections into F<rcfile>(s). These sections typically reference the
local F<rcfile>'s variables ${rc_errcode} and ${rc_errstring} for more
information about which error was encountered and its text.
=item B<%error>
If an error condition arises during an F<rcfile>'s processing, control will
pass to the B<%error> section whose commands will begin to run. Should no such
B<%error> section exist, rc will stop any rcfile processing and write error
strings to the console and syslog using LOG_USER and LOG_ERR (see syslog(3)).
An empty B<%error> section in each F<rcfile> is synonymous to a
C<IgnoreAllErrors> option (which doesn't exist).
=item B<%default>
The commands in the B<%default> section are run when the corresponding
F<rcfile> contains no section label matching the one(s) specified on the
command line. If the appropriate section label doesn't exist and neither does
B<%default>, then an error is assumed and control flows to the B<%error>
section.
=head1 EXAMPLES
The following are one-line examples of commonly used rc commands with no
arguments. Because no run mode option is specified, B<OSSP rc> will process
the commands by executing them directly.
/usr/local/bin/rc --info
/sbin/rc --query lmtp2nntp
/usr/local/bin/rc httpd reload
/cw/etc/rc --conf /etc/rc.conf --debug smtpd stop
/opt/bin/rc ntpd --silent start sync stop start
B<OSSP rc> offers more than just command execution. In the following examples
because the 'eval' run mode option is specified, B<OSSP rc> will prepare the
commands by writing a composite script to a tempfile. Then B<OSSP rc> will
print the file's location in a format most conveniently parsable by eval(1) or
the bourne shell for evaluation.
eval `/usr/local/bin/rc --eval all env`
/usr/local/bin/rc --eval sendmail start | sh
To read the results of a B<OSSP rc> operation without executing or evaluting
the runcommands, use the 'print' run mode.
/opt/binbin/rc --print --info mico
/usr/local/bin/rc --print httpd reload
Arguments in the form of name=value pairs may be passed to the section(s)
given on the command line. In the F<rcfile>, such arguments will appear as
normal configuration variables. They can be referenced as such (by default as
${myarg}). On the command line, the arguments following a section will be
local to the section and unusable by the others. If a argument is needed by
more than one section, then repeat its definition after each section given on
the command line.
/mybin/rc all start sFac="LOG_USER" # pass LOG_USER as an argument to 'start'
/opt/bin/rc lmtp2nntp start nSleep=2 # sleep for 2 seconds before returning
/cw/etc/rc/ ftpd start nMax=32 # a maximum of 32 users can connect
./rc rsyncd restart nSleep=4 # pause 4 seconds between start and stop
./rc -rdv all stop nSleep=2 start nSleep=4 sLevel="LOG_INFO" bQuiet=1
=head1 FILES
F<rc.conf> - Master configuration file
F<rc.func> - User defined functions library
F<rc.env> - Postprocess variable declaration file
F<rc.foo> - Runcommands for 'foo' application
=head1 SEE ALSO
OSSP rc integrates concepts taken from other run-command architectures. For
more information, inspect the /etc/rc structures provided by the NetBSD,
FreeBSD, Solaris, and Red Hat distributions.
rc-sample(5).
=head1 AUTHORS
Ralf S. Engelschall
Michael Schloh von Bennewitz
Thomas Lotterer
=head1 HISTORY
B<OSSP rc> is a drop-in replacement for the prototype run-command facility used
in OpenPKG (http://www.openpkg.org/). The prototype was a slow and less robust
Bourne shell script. B<OSSP rc> is comparitively faster, more robust, and more
feature rich. Its generic design and improved flexibility allows for wider
range of use, and B<OSSP rc> can therefore be used in a larger variety of
situations. Today, B<OSSP rc> is not exclusive to the OpenPKG project.
=cut
