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> do not 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 will be used. If no F exists at all, then only command line and environment specified options will override B's default values. =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 Fs 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 configuration. =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 is 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 is ignored. =item B<--RequireOwner uid|name> owner of the F must match uid|name, otherwise it is ignored. =item B<--RequireGroup gid|name> group of the F must match gid|name, otherwise it is 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. =head1 OPTIONS ORDERING B reads its options from three sources and builds a global configuration which it uses when later processing Fs and B

s. The first source used is the F file (see SEE ALSO). Next, B 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 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 just as it would if given on the command line or in the F file. =head1 COMMAND INTERPRETER As long as a valid interpreter path is specified in the section labels of a F, 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. 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. =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. 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. 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 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 will cause errors to be ignored. In any case of error however, rcfile processing will stop. 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 does not 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 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 offers more than just command execution. In the following examples because the 'eval' run mode option is specified, B will prepare the commands by writing a composite script to a tempfile. Then B 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 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 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. ./rc all start sFac="LOG_USER" # pass LOG_USER as argument to 'start' ./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 /bin/rc rsyncd restart nSleep=4 # pause 4 seconds between start and stop /bin/rc -rdv all stop nSleep=2 start nSleep=4 sLevel="LOG_INFO" bQuiet=1 =head1 FILES F - Master configuration file F - User defined functions library F - Postprocess variable declaration file F - 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 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 feature rich. Its generic design and improved flexibility allows for wider range of use, and B can therefore be used in a larger variety of situations. Today, B is not exclusive to the OpenPKG project. =cut