=head1 DESCRIPTION OSSP rc is a runcommand processor. Its primary function is to scan F script files for B

(s) and run the commands listed in the section(s). The runcommand processor can alternatively print the commands in human readable format or reformat them for shell C input without executing them. The F files contain variables and the command processor has functionality to query their default, set and effective values. The structure of the Fs is simple but the syntax is highly configurable. A F is divided into B

s and each of them is identified by a label build from the B

name. The distribution contains various examples. With a single call to rc usually one F may be processed at, although many B 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 meaning 'all Fs.' =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[C<:>I] locations to search for Fs where I 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[C<:>I[...]] specify the location of the configuration file. If omitted, C<$OSSP_RC_CONF> will be examined. If absent, F<@l_prefix@/etc/rc.conf> will be used. If no F 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[C<:>I[...]] 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 Cs 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 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 query the effective value of configuration variables from the %config section and print them using the I 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 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, 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 has to have, otherwise it's ignored. =item B<--RequireOwner uid|name> owner of the F must match uid|name, otherwise it's ignored. =item B<--RequireGroup gid|name> group of the F must match gid|name, otherwise it's ignored. =item B<--ParseSectionDef regex> regex matching a section within a F. =item B<--ParseSectionRef regex> regex matching a reference within a F. =item B<--NameConfig> name name of the config section, defaults to %config. =item B<--NameCommon> name name of the common section, defaults to %common. Every command line longoption corresponds to a keyword in the F 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 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 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, and each subsequent usage will return success and print a 'No commands run: OSSP_RC_DEACT set to yes' error message to the standard output. B - Set to 'yes' or 'true' to totally deactivate B =head1 RETURN VALUE -1 Error in rc 0 Success 1 Error in command executed by rc =head1 EXAMPLES A runcommand 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>. The following are one-line examples of commonly used rc commands with no arguments. /usr/local/bin/rc --info /sbin/rc --query lmtp2nntp /cw/etc/rc --conf /etc/rc.conf --debug smtpd stop /sfw/etc/rc --silent ntpd start sync stop start /usr/local/bin/rc httpd reload # sends a HUP signal Arguments may also be passed in to B, which will forward them to each section as it is called. /mybin/rc sshd start LOG_USER # calls logger(1) and passes LOG_USER /etc/rc lmtp2nntp start 2 # sleep for 2 seconds before returning /etc/rc.d/rc.rsyncd restart 4 # leave a 4 second pause between start and stop /cw/etc/rc.d/rc.ftpd start 32 # a maximum of 32 users can connect To evaluate a runcommand 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 runcommands will execute according to the C command. This is often seen when importing the environment of packages of an B hierarchy, but is always a custom modification made by the user. $ eval `@l_prefix@/etc/rc --eval all env` =head1 FILES F - Master configuration file F - User defined functions library F - Postprocess variable declaration file F - Runcommands for 'foo' application =head1 SEE ALSO OSSP rc integrates concepts taken from other runcommand architectures. For more information, inspect the /etc/rc structures provided by the FreeBSD, Solaris, and Red Hat distributions. rc-sample(5), rc.conf(1), and rcfile(1). =head1 AUTHORS Ralf S. Engelschall Michael Schloh von Bennewitz Thomas Lotterer =head1 HISTORY B is a drop-in replacement for the prototype runcommand facility used in OpenPKG (http://www.openpkg.org/). The prototype was a slow and less robust Bourne shell script. B is comparitively faster, more robust, and more flexible. This flexibility allows for wider range of use, and B can therefore be used in a variety of situations. It is no longer exclusive to the OpenPKG project. =cut