s and run the commands listed in each B

. The run-command processor can alternatively C 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, 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. Often, only a single B name is processed. To process all Bs, substitute the keyword 'all' for the B name. The B

s of a B processed match exactly the B

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[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<--ParseConfigAss regex> regex matching the variable assignments in a F. =item B<--ParseSectionDef regex> regex matching a section label in a F. =item B<--ParseSectionRef regex> regex matching a reference in a F. =item B<--ParseSectionParam regex> regex matching a section parameter in a F. =item B<--ParseTerminal regex> regex matching a terminal symbol in a F. 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 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 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 - Set to 'yes' or 'true' to totally deactivate B =head1 COMMAND INTERPRETER As long as a valid interpreter path is specified in the section labels of a F, 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. 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 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(s). These sections typically reference the local F'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'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 is synonymous to a C option (which doesn't exist). =item B<%default> The commands in the B<%default> section are run when the corresponding F 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 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.d/rc.ntpd --silent start sync stop start /usr/local/bin/rc httpd reload # sends a HUP signal Arguments in the form of name=value pairs may be passed to the section(s) given on the command line. In the F, 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' /etc/rc lmtp2nntp start nSleep=2 # sleep for 2 seconds before returning /etc/rc.d/rc.rsyncd restart nSleep=4 # pause 4 seconds between start and stop /cw/etc/rc.d/rc.ftpd start nMax=32 # a maximum of 32 users can connect rc -rdv all stop nSleep=2 start nSleep=4 sLevel="LOG_INFO" bQuiet=1 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 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 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 is comparitively faster, more robust, and more flexible. This flexibility allows for wider range of use, and B can therefore be used in a larger variety of situations. It is no longer exclusive to the OpenPKG project. =cut