OSSP CVS Repository

ossp - ossp-pkg/rc/rc.pod 1.39
Not logged in
[Honeypot]  [Browse]  [Directory]  [Home]  [Login
[Reports]  [Search]  [Ticket]  [Timeline
  [Raw

ossp-pkg/rc/rc.pod 1.39
##
##  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 F<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.

=head1 OPTIONS ORDERING

B<OSSP rc> reads its options from three sources and builds a global
configuration which it uses when later processing F<rcfile>s and B<section>s.
The first source used is the F<rc.conf> file (see SEE ALSO). Next, B<OSSP rc>
reads options from the environment (see ENVIRONMENT). Finally, it reads
options from the command line. Of course, this means that any option given on
the command line overrides that of the other two sources.  This allows for
flexibility when wishing to set a standard set of OSSP rc options, and
override them conditionally.

Some option values are mandatory, and if they do not exist in any of the three
sources then B<OSSP rc> supplies a default value. The global configuration
being used at any moment can be learned by using the --info switch.

=head1 ENVIRONMENT

The environment may contain options variables and values as well. Such
variable names must begin with 'OSSP_RC_' and follow with a long option name.
The value assigned to a environment variable indicates the processing
behaviour of B<OSSP rc> just as it would if given on the command line or in
the F<rc.conf> file.

=head1 COMMAND INTERPRETER

As long as a valid interpreter path is specified in the section labels of a
F<rcfile>, the run-commands resulting from a --eval, --exec, or --print
operation can be written in any runtime-interpreted language. This means that
a perl programmer can write run-commands 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.

=head1 RETURN VALUE

 0 Success
 1 Failure

 A non-zero return value signals failure, and may indicate such error states
 as an illegal combination of options or nonexisting locations directory.

=head1 ERROR HANDLING

Fine-tuned error handling is possible by writing one or both of the following
section labels into an F<rcfile>. 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 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> will cause errors to be ignored. In any
case of error however, rcfile processing will stop.

=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 nothing happens and processing silently procedes.

=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 run-commands, 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 B<sections>
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>  - Run-commands 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 Linux distributions.

rc-sample(5).
rc.conf(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

CVSTrac 2.0.1