OSSP CVS Repository

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

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

@l_prefix@/etc/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<--ParseSectionDef regex>]
[B<--ParseSectionRef regex>]
[B<--NameConfig> name]
[B<--NameCommon> name]
I<rcfile>
I<section>

=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) and run the commands listed in the
section(s).

The run command processor can alternatively 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 and each of them is
identified by a label build from the B<section> name.  The distribution
contains various examples.

With a single call to rc usually one F<rcfile> may be processed at, although
many sections can be passed which are executed in given order.  The only
exception to this rule is when the reserved keyword `all' is used as F<rcfile>
meaning `all F<rcfile>s.'

=back 4

=head1 OPTIONS

=over 4
=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 and the optional part is a regex to filter out 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, the fallback is
to look for C<$OSSP_RC_CONF>, and "@l_prefix@/etc/rc.conf", in that order.

=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<--ParseSectionDef regex>

regex matching a section within a F<rcfile>.

=item B<--ParseSectionRef regex>

regex matching a reference within a F<rcfile>.

=item B<--NameConfig> name

name of the config section, defaults to %config.

=item B<--NameCommon> name

name of the common section, defaults to %common.

=back 4

=head1 ENVIRONMENT

=over 4

Every command line longoption is also a keyword in the F<rc.conf> file and,
prefixed with "OSSP_RC_" and it's name in upper case, also available as an
environment variable.

=back 4

=head1 RETURN VALUE

=over 4

-1 Error in rc
 0 Success
 1 Error in command executed by rc

=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.

=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 FreeBSD, Solaris,
and Red Hat distributions.

rc.conf(1), rc.func(1), rc.env(1), rcfile(1), and rc-sample(1).

=head1 AUTHORS

Ralf S. Engelschall

Michael Schloh von Bennewitz

=head1 HISTORY

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.

=cut

CVSTrac 2.0.1