head 1.45;
access;
symbols
OSSP_RC_0_7_3:1.45
OSSP_RC_0_7_2:1.45
OSSP_RC_0_7_1:1.44
OSSP_RC_ALPHA_06:1.31
OSSP_RC_EXBROKEN:1.31
OSSP_RC_SPEC:1.26;
locks; strict;
comment @# @;
1.45
date 2003.07.09.10.21.21; author thl; state Exp;
branches;
next 1.44;
1.44
date 2003.07.07.12.55.42; author ms; state Exp;
branches;
next 1.43;
1.43
date 2003.06.26.18.45.14; author ms; state Exp;
branches;
next 1.42;
1.42
date 2003.06.23.17.22.41; author ms; state Exp;
branches;
next 1.41;
1.41
date 2003.06.23.17.11.28; author ms; state Exp;
branches;
next 1.40;
1.40
date 2003.06.23.17.08.20; author ms; state Exp;
branches;
next 1.39;
1.39
date 2003.06.23.17.06.44; author ms; state Exp;
branches;
next 1.38;
1.38
date 2003.06.23.16.55.05; author ms; state Exp;
branches;
next 1.37;
1.37
date 2003.06.23.16.44.55; author ms; state Exp;
branches;
next 1.36;
1.36
date 2003.06.23.15.46.05; author ms; state Exp;
branches;
next 1.35;
1.35
date 2003.06.23.14.53.10; author ms; state Exp;
branches;
next 1.34;
1.34
date 2003.06.23.14.46.33; author ms; state Exp;
branches;
next 1.33;
1.33
date 2003.06.23.14.43.48; author ms; state Exp;
branches;
next 1.32;
1.32
date 2003.06.23.11.29.44; author ms; state Exp;
branches;
next 1.31;
1.31
date 2003.05.21.12.49.20; author ms; state Exp;
branches;
next 1.30;
1.30
date 2002.04.11.16.52.45; author ms; state Exp;
branches;
next 1.29;
1.29
date 2002.03.01.22.48.23; author ms; state Exp;
branches;
next 1.28;
1.28
date 2002.02.28.15.30.04; author ms; state Exp;
branches;
next 1.27;
1.27
date 2002.02.04.22.35.20; author ms; state Exp;
branches;
next 1.26;
1.26
date 2002.01.31.21.14.10; author ms; state Exp;
branches;
next 1.25;
1.25
date 2002.01.31.10.11.43; author ms; state Exp;
branches;
next 1.24;
1.24
date 2002.01.30.22.55.26; author ms; state Exp;
branches;
next 1.23;
1.23
date 2002.01.29.15.35.05; author ms; state Exp;
branches;
next 1.22;
1.22
date 2002.01.29.09.14.38; author ms; state Exp;
branches;
next 1.21;
1.21
date 2002.01.29.08.42.20; author ms; state Exp;
branches;
next 1.20;
1.20
date 2002.01.29.07.31.11; author ms; state Exp;
branches;
next 1.19;
1.19
date 2002.01.28.16.01.23; author ms; state Exp;
branches;
next 1.18;
1.18
date 2002.01.28.14.30.04; author ms; state Exp;
branches;
next 1.17;
1.17
date 2002.01.28.14.25.47; author ms; state Exp;
branches;
next 1.16;
1.16
date 2002.01.28.12.08.13; author ms; state Exp;
branches;
next 1.15;
1.15
date 2002.01.23.15.36.05; author ms; state Exp;
branches;
next 1.14;
1.14
date 2002.01.23.14.58.51; author ms; state Exp;
branches;
next 1.13;
1.13
date 2002.01.23.13.44.50; author ms; state Exp;
branches;
next 1.12;
1.12
date 2002.01.23.13.40.54; author ms; state Exp;
branches;
next 1.11;
1.11
date 2002.01.23.13.31.20; author ms; state Exp;
branches;
next 1.10;
1.10
date 2002.01.23.13.29.21; author ms; state Exp;
branches;
next 1.9;
1.9
date 2002.01.23.13.10.39; author ms; state Exp;
branches;
next 1.8;
1.8
date 2002.01.23.13.09.20; author ms; state Exp;
branches;
next 1.7;
1.7
date 2002.01.22.20.10.27; author ms; state Exp;
branches;
next 1.6;
1.6
date 2002.01.22.18.00.59; author ms; state Exp;
branches;
next 1.5;
1.5
date 2002.01.21.18.14.54; author ms; state Exp;
branches;
next 1.4;
1.4
date 2002.01.18.16.47.53; author ms; state Exp;
branches;
next 1.3;
1.3
date 2002.01.17.15.47.10; author ms; state Exp;
branches;
next 1.2;
1.2
date 2002.01.06.12.40.50; author openpkg-cvs; state Exp;
branches;
next 1.1;
1.1
date 2002.01.04.22.32.04; author openpkg-cvs; state Exp;
branches;
next ;
desc
@@
1.45
log
@put top topics in first paragraph
@
text
@##
## rc.pod -- OSSP Run-command Processor (manual page)
## Copyright (c) 2002-2003 Cable & Wireless Deutschland GmbH
## Copyright (c) 2002-2003 The OSSP Project
## Copyright (c) 2002-2003 Ralf S. Engelschall
##
## 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 - OSSP Run-command Processor
=head1 SYNOPSIS
B
[B<-?>|B<--usage>]
[B<-D>|B<--debug>]
[B<-L>|B<--locate> I[C<:>I[...]]]
[B<-V>|B<--version>]
[B<-c>|B<--conf> I[C<:>I[...]]]
[B<-e>|B<--eval>]
[B<-f>|B<--func> I[C<:>I[...]]]
[B<-h>|B<--help>]
[B<-i>|B<--info>]
[B<-l>|B<--labels>]
[B<-p>|B<--print>]
[B<-q>|B<--query>] I
[B<-s>|B<--silent>]
[B<-r>|B<--raw>]
[B<-t>|B<--tmp> I]
[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<>
I<>
=head1 DESCRIPTION
OSSP rc is a run-command processor. Its primary function is to assemble
a temporary file from excerpts of Fs which are built out of text
snippets grouped into Bs. The user specifies the desired parts
to use and also controls the order of assembly.
OSSP rc defaults to Bute the concatenated temporary file, but it
can also B it in human readable format or create shell
instructions suitable for the calling shell to Buate the temporary
file. The Fs contain variables and the command processor has
functionality to B their default, set and effective values.
The structure of the Fs is simple but the syntax is highly
configurable. Included Bs are labeled for identification by the
user, while rc uses regular expressions to identifiy their boundaries.
The default regular expression leads to identification of section text
starting with a percent (%) and any subsequent text until a whitespace
identifies the label. Various examples are listed below.
Often, only a single B is processed. To process all Bs,
substitute the keyword 'all' for the B name. This convenience
inhibits 'all' being used as a file name.
=head1 OPTIONS
=over 4
=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 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 determined 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.
=back
=head1 OPTIONS ORDERING
B reads its options from three sources and builds a global
configuration which it uses when later processing Fs and Bs.
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
/usr/local/bin/rc --query lmtp2nntp
/usr/local/bin/rc httpd reload
/usr/local/bin/rc --conf /etc/rc.conf --debug smtpd stop
/usr/local/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.
/usr/local/bin/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.
/usr/local/bin/rc all start sFac="LOG_USER" # pass LOG_USER as argument to 'start'
/usr/local/bin/rc lmtp2nntp start nSleep=2 # sleep for 2 seconds before returning
/usr/local/bin/rc ftpd start nMax=32 # a maximum of 32 users can connect
/usr/local/bin/rc rsyncd restart nSleep=4 # pause 4 seconds between start and stop
/usr/local/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
@
1.44
log
@Correct and update copyrights and source headers.
@
text
@d36 1
a36 1
[B<-D>|B<--debug>]
d41 1
a41 1
[B<-f>|B<--func> I[C<:>I[...]]]
d43 1
a43 1
[B<-i>|B<--info>]
d51 1
a51 1
[B<-x>|B<--exec>]
d71 10
a80 8
OSSP rc is a run-command processor. Its primary function is to scan F
script files for one or more Bs 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.
d83 9
a91 10
configurable. A F is divided into Bs, 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 Bs of a
B processed match exactly the Bs given on the command line,
and even the ordering is kept.
d95 2
d134 1
a134 1
print this help, then exit.
d157 1
a157 1
sequences for color, bold and italic rendering. The default is determines at
d228 2
d302 1
a302 1
/sbin/rc --query lmtp2nntp
d304 2
a305 2
/cw/etc/rc --conf /etc/rc.conf --debug smtpd stop
/opt/bin/rc ntpd --silent start sync stop start
d319 1
a319 1
/opt/binbin/rc --print --info mico
d330 5
a334 5
./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
@
1.43
log
@Break off before fully implementing common section run ops, but after
reorganization of class data, and additional member functions for section and
script manipulation.
@
text
@d3 3
a5 3
## Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
## Copyright (c) 2000-2002 The OSSP Project
## Copyright (c) 2000-2002 Ralf S. Engelschall
@
1.42
log
@Clean up examples and %error %default text.
@
text
@d117 1
a117 1
options will override the defaults built-in to OSSP rc.
@
1.41
log
@Fix missing punctuation.
@
text
@d276 1
a276 2
=item B<%error>
d284 1
a284 2
=item B<%default>
d325 5
a329 5
/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
@
1.40
log
@Reduce contractions.
@
text
@d100 1
a100 1
do not remove temporary files, and output debug messages to stderr
d110 1
a110 1
print version and copyright, then exit
d131 1
a131 1
print this help, then exit
d135 1
a135 1
print a comprehensive summary of the rc environment
d159 1
a159 1
be silent, and disable output
@
1.39
log
@Last text edit of options and their ordering.
@
text
@d100 1
a100 1
don't remove temporary files, and output debug messages to stderr
d169 1
a169 1
be verbose, output what's going on.
d179 1
a179 1
umask a F has to have, otherwise it's ignored.
d183 1
a183 1
owner of the F must match uid|name, otherwise it's ignored.
d187 1
a187 1
group of the F must match gid|name, otherwise it's ignored.
d289 1
a289 1
command line. If the appropriate section label doesn't exist and neither does
@
1.38
log
@Edit environment and command interpreter text.
@
text
@d225 14
a238 6
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.
d347 1
@
1.37
log
@Edit text on special %error and %default sections.
@
text
@d234 5
a238 9
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
d251 1
a251 1
then the Bourne shell will be used by default. See FILES/rc.foo for details.
@
1.36
log
@Conform to original OpenPKG rc behaviour by processing in execute run mode by
default, correct and explain return values, and adjust test suite.
@
text
@d127 1
a127 1
corresponding Cs just before execution.
d267 4
a270 4
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.
d276 4
a279 4
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).
d286 1
a286 2
B<%default>, then an error is assumed and control flows to the B<%error>
section.
d315 1
a315 1
Arguments in the form of name=value pairs may be passed to the section(s)
d339 2
a340 2
more information, inspect the /etc/rc structures provided by the NetBSD,
FreeBSD, Solaris, and Red Hat distributions.
@
1.35
log
@Use term run-command consistently throughout docs.
@
text
@a258 1
-1 Error in rc
d260 4
a263 1
1 Error in command executed by rc
@
1.34
log
@Really get the example text right.
@
text
@d247 1
a247 1
F, the runcommands resulting from a --eval, --exec, or --print
d249 1
a249 1
a perl programmer can write runcommands in perl, and specify the perl
d309 1
a309 1
the runcommands, use the 'print' run mode.
d333 1
a333 1
F - Runcommands for 'foo' application
@
1.33
log
@Edit examples and group them according to the three run modes, and improve
most basic error message.
@
text
@d323 4
a326 4
/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
@
1.32
log
@Remember possible feature, 'activate warnings on rcfile pattern'.
@
text
@d115 1
a115 1
will be examined. If absent, F<@@l_prefix@@/etc/rc.conf> will be used. If no
d289 3
a291 4
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.
d295 1
d297 16
a312 2
/sfw/etc/rc.d/rc.ntpd --silent start sync stop start
/usr/local/bin/rc httpd reload # sends a HUP signal
a327 8
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`
d354 3
a356 3
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.
@
1.31
log
@Implement eval mode.
@
text
@d72 2
a73 1
script files for B(s) and run the commands listed in the section(s).
d81 5
a85 3
configurable. A F is divided into Bs and each of them is
identified by a label build from the B name. The distribution
contains various examples.
d87 4
a90 4
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.'
@
1.30
log
@Flush the toilet.
@
text
@d329 2
a330 2
more information, inspect the /etc/rc structures provided by the FreeBSD,
Solaris, and Red Hat distributions.
d346 2
a347 2
therefore be used in a variety of situations. It is no longer exclusive to the
OpenPKG project.
@
1.29
log
@Fixed the build, improved the design, improved the configuration and option
processing.
@
text
@d2 1
a2 1
## rc.pod -- OSSP Run-command processor (manual page)
d30 1
a30 1
B - OSSP Runcommand Processor
d71 1
a71 1
OSSP rc is a runcommand processor. Its primary function is to scan F
d74 1
a74 1
The runcommand processor can alternatively C the commands in human
d328 1
a328 1
OSSP rc integrates concepts taken from other runcommand architectures. For
d342 1
a342 1
B is a drop-in replacement for the prototype runcommand facility used
@
1.28
log
@Cleanup and structuring.
@
text
@d74 1
a74 1
The runcommand processor can alternatively print the commands in human
@
1.27
log
@Fixed copyright.
PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d52 1
d65 3
a67 2
I
I
@
1.26
log
@Corrections, additions, and moving items from 00TODO to rc.pod.
PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d2 1
a2 1
## rc.pod -- OSSP Runcommand Processor (Manual Page)
@
1.25
log
@Add text on section arguments and OSSP_RC_DEACT, improve examples, line up
text, remove unneeded =over and =back tags. Prepare for description of control
flow and command interpreter logic.
PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d55 1
d58 2
d62 2
d184 4
d190 1
a190 1
regex matching a section within a F.
d194 9
a202 1
regex matching a reference within a F.
d212 8
d234 2
a235 2
print a 'No commands run: OSSP_RC_DEACT set to yes' error message to the
standard output.
d239 13
d258 24
d292 1
a292 1
/sfw/etc/rc --silent ntpd start sync stop start
d295 13
a307 7
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
d330 1
a330 1
rc-sample(5), rc.conf(1), and rcfile(1).
@
1.24
log
@Add ASN.1 example, revise and correct manpages, update todo list.
PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@a29 2
=over 4
a31 2
=back 4
d34 1
a34 3
=over 4
@@l_prefix@@/etc/rc
a61 2
=back 4
a63 2
=over 4
a81 2
=back 4
a83 1
=over 4
a194 2
=back 4
a203 2
=over 4
d206 5
a210 1
'OSSP_RC_' and be all upper case.
d212 1
a212 1
=back 4
a215 2
=over 4
a219 2
=back 4
d225 1
a225 1
one-line examples of commonly used rc commands.
d227 13
a239 9
/usr/local/bin/rc --info
/sbin/rc --query lmtp2nntp
/cw/etc/rc --conf /etc/rc.conf --debug smtpd stop
/mybin/rc sshd start LOG_USER # calls logger(1) and passes LOG_USER
/etc/rc lmtp2nntp start 2 # sleep for 2 seconds before returning
/sfw/etc/rc --silent ntpd start sync stop start
/usr/local/bin/rc httpd reload # sends a HUP signal
/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
d247 1
a247 1
$ eval `@@l_prefix@@/etc/rc --eval all env`
d251 4
a254 8
=over 4
F - Master configuration file
F - User defined functions library
F - Postprocess variable declaration file
F - Runcommands for 'foo' application
=back 4
a257 2
=over 4
a263 2
=back 4
d266 3
a268 6
=over 4
Ralf S. Engelschall
Michael Schloh von Bennewitz
=back 4
@
1.23
log
@Pseudocoded anad small adjustments.
PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d2 1
a2 1
## rc.pod -- OSSP Run Command Processor (Manual Page)
d32 1
a32 1
B - OSSP Run Command Processor
d74 2
a75 3
OSSP rc is a run command processor. It's primary function is to scan
F script files for B(s) and run the commands listed in the
section(s).
d77 1
a77 1
The run command processor can alternatively print the commands in human
d83 2
a84 2
configurable. A F is divided into Bs and each of them is
identified by a label build from the B name. The distribution
d88 3
a90 3
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
meaning `all Fs.'
d108 2
a109 2
filter files and the optional part is a regex to filter out parts of a file.
This option can be specified more than once.
d117 4
a120 2
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.
d155 1
a155 1
output text using no terminal control sequences. The rc facility usually
d157 1
a157 1
sequences for color, bold and italic rendering. The default is determines at
d166 1
a166 1
specify the location of the temporary directory. If omitted, the fallback is
d210 7
d221 3
a223 3
Every command line longoption is also a keyword in the F file and,
prefixed with "OSSP_RC_" and it's name in upper case, also available as an
environment variable.
d239 4
a242 6
=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>.
d245 4
a248 4
/etc/rc --query lmtp2nntp
/mybin/rc sshd start
/etc/rc lmtp2nntp start
/sfw/etc/rc --conf /etc/rc.conf --debug smtpd stop
d250 3
a252 1
/usr/local/bin/rc httpd restart
d254 1
a254 1
To evaluate a run command for all programs with an identical section name, a
d256 1
a256 1
initializes itself, the run commands will execute according to the C
d258 3
a260 1
B hierarchy.
d264 8
a271 4
F - Master configuration file
F - User defined functions library
F - Postprocess variable declaration file
F - Run commands for "foo" application
d275 1
a275 3
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.
d277 7
a283 1
rc.conf(1), rc.func(1), rc.env(1), rcfile(1), and rc-sample(1).
d287 2
d290 1
d292 1
a292 1
Michael Schloh von Bennewitz
d296 6
a301 6
B 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 is intended to faster, more robust, and
more flexible. This flexibility allows for wider range of use, however. B can therefore be used in a variety of situations, and is no longer
exclusive to the OpenPKG project.
@
1.22
log
@remove useless =over
@
text
@d43 1
a43 1
[B<-F>|B<--force>]
a45 1
[B<-d>|B<--dirs> I[C<:>I[...]]]
d58 7
d106 1
a106 1
=item B<-F>|B<--force>
d108 3
a110 4
Usually F is a fraction of a filename and the run command facility
prefixes this name with ${OSSP_RC_PREFIX} and appends ${OSSP_RC_SUFFIX} to it,
then searches the file in directories given using --dirs. If the initial
F matches the regex '^\.{0,2}/', --force is automagically assumed.
a120 4
=item B<-d>|B<--dirs> I[C<:>I[...]]
directories to search for Fs.
d178 28
@
1.21
log
@unlock
@
text
@a224 2
=over 4
a229 2
=back 4
a231 2
=over 4
a237 2
=back 4
a239 2
=over 4
a243 2
=back 4
a245 2
=over 4
a251 2
=back 4
@
1.20
log
@set administrative lock
@
text
@a0 4
--------------------------------------------------------------------------------
DO NOT EDIT. MAJOR REWRITES JOINING OPTIONS, NOTES AND DEFAULTS IN PROGRESS. THL
--------------------------------------------------------------------------------
a39 2
=item B
d41 15
a55 1
[B<-c>|B<--conf> I[C<:>I[...]]]
d57 1
a57 8
[B<-r>|B<--raw>]
[B<-v>|B<--verbose>]
[B<-D>|B<--debug>]
=item B
@@l_prefix@@/etc/rc
[I]
a58 5
[B<-p>|B<--print>]
[B<-e>|B<--eval>]
[B<-d>|B<--dirs> I[C<:>I[...]]
[B<-f>|B<--func> I[C<:>I[...]]]
[B<-F>|B<--force>]
a60 37
[I ...]
=item B
@@l_prefix@@/etc/rc
[I]
B<-q>|B<--query> I
[B<-d>|B<--dirs> I[C<:>I[...]]
[B<-F>|B<--force>]
I
=item B
[I]
<-l>|<--labels>
[B<-d>|B<--dirs> I[C<:>I[...]]
[B<-F>|B<--force>]
I
# FIXME Ralf, what's that?
# @@l_prefix@@/etc/rc
# [I]
# [B<-c>|B<--conf>]
# [I]
=item B
@@l_prefix@@/etc/rc
[I]
[B<-i>|B<--info>]
=item B
@@l_prefix@@/etc/rc
[B<-?>|B<--usage>]
[B<-h>|B<--help>]
[B<-V>|B<--version>]
d68 13
a80 13
OSSP rc is a run command processor. It's primary function is to scan F
script files for B(s) identified by corresponding label(s) and run the
commands in the section(s).
The run command processor can also only print the commands without executing
them or reformat them to C input. The F files contain variables
and the command processor has functionality to query their default, set and
effective values.
To understand the structure and syntax of F script files, an example
called F is included in the distribution. The rc environment and
behaviour is very configurable, so the syntax may vary and not match exactly
the example provided.
d83 3
a85 17
many sections can be given to source their corresponding commands, see
EXAMPLES below.
There is one exception to this rule in which an rc keyword named `all' is
reserved to mean `all Fs.' The user may thus give the `all' wildcard
in place of the C parameter to process the commands from the given
sections of all Cs found.
#THL! does "all stop start" mean "a stop stop, a start, b start" or " a stop,
#a start, b stop, b start"?
#Prioritaeten
#Using the `all' wildcard may be risky in some cases, because successful
#performance then depends not only on the code written into each program's
#sections but also if every single program found has the named section label at
#all. For information about the rc exit status after such an operation see
#`DIAGNOSTICS.'
d92 1
d94 1
a94 27
Inclusive options which may be used with another
=item B<-c>, B<--conf> F
specify the location of the configuration file.
=item B<-f>, B<--func> F[C<:>F[...]]
specify the location of one or more optional function files, containing
commands which are prepended to the sections of their corresponding
Cs.
=item B<-F>, B<--force>
Disable ${OSSP_RC_PREFIX} and ${OSSP_RC_SUFFIX} expansion on F.
Disable searching for F. This mode assumes F is a filename. It
is automagically entered when the F matches the regex '^\.{0,2}/'.
=item B<-d>, B<--dirs> I[C<:>I[...]
override OSSP_RC_DIRS, and use these paths to search for Fs instead.
=item B<-t>, B<--tmpdir> I
specify the location of the temporary directory
=item B<-v>, B<--verbose>
d96 1
a96 7
verbosely report processing, including all warnings
=item B<-s>, B<--silent>
be silent, and disable output
=item B<-D>, B<--debug>
d100 1
a100 1
=item B<-r>, B<--raw>
d102 4
a105 1
output text using no terminal control sequences
d107 1
a107 15
=back 4
Mutually exclusive options, i.e. only a single one can be given
=over 4
=item B<-h>, B<--help>
print this help, then exit
=item B<-?>, B<--usage>
print short usage summary, then exit.
=item B<-V>, B<--version>
d111 1
a111 1
=item B<-p>, B<--print>
d113 2
a114 2
output the commands as they would by seen by the command interpreter, but do
not run them.
d116 1
a116 1
=item B<-e>, B<--eval>
d118 1
a118 2
output the text for a command suitable for shell evaluation, but do not run
it.
d120 1
a120 1
=item B<-x>, B<--exec>
d122 1
a122 1
execute the command interpreter in a subprocess and actually run the commands.
d124 1
a124 1
=item B<-q>, B<--query>
d126 3
a128 1
print the value(s) of rc configuration variables defined in the %config section.
d130 1
a130 1
=item B<-l>, B<--labels>
d132 1
a132 1
learn what section labels a F offers.
d134 1
a134 1
=item B<-i>, B<--info>
d138 1
a138 1
=back 4
d140 1
a140 1
=head1 NOTES
d142 1
a142 1
=over 4
d144 1
a144 2
=item B<-h>, B<--help>, B<-V>, B<--version>, B<-v>, B<--verbose>, and B<-q>
B<--silent>
d146 1
a146 53
The B<--help>, B<--version>, B<--verbose>, and B<--silent> options are used to
control the screen output of B and control the general output of all
sections found in the Fs as well. For example, specifying
B<--silent> will mute B's output and also all command output that B
runs.
=item B<-r>, B<--raw> I
The option B<-r> or B<--raw> turns on raw output mode. In this case, no
formatting is done to the screen output. This mode is different from formatted
output mode, in which the output is annotated with terminal control sequences
for better readability.
=item B<-t>, B<--tmp> I
Specifying this option will force B to use the given temporary
directory I for all its temporary output.
=item B<-e>, B<--eval> and B<-p>, B<--print>
With the B<--eval> or B<--print> options, the run command will not be
executed. Rather, B will print a command suitable for later evaluation in
the current shell. Given alone, this option will cause B to not execute
the run command. Used together with B<--exec>, B will execute the run
command and print a similar command for later execution as well. The B<--eval>
option cannot be used together with B<--print>, because of conflicting output
and the way that B constructs the evaluation text. Specifically, most
Bourne shells and derivatives report errors with commands spanning multiple
lines.
Consider using the B<--eval> option for batch evaluation with the Bourne shell
C command. Use the B<--print> option for better human readability. See
`EXAMPLES' for an example.
=item B<-x>, B<--exec>
The B<--exec> is the most common option of all, in which B executes a run command
made up of a given program and section. Options controlling the flow of
execution include B<--print>, B<--eval>, and B<--exec>.
=item B<-q>, B<--query>
The B<--query> option queries the I value of one or more
configuration variables. These variables are set in the C<%config> section of
the corresponding F. The B<--query> option reports the
I value, and not necessarily that written in the F
file, which can be overridden by variable settings in the F file.
Used with the B<--query> option, B will expect exactly one command line
argument to follow. This must be a I string containing arbitrary text
and optionally one or more B variable specifications
("C<${>IC<}>" in its simplest form.)
!FIXME what is var here!
d148 2
a149 1
=back 4
d151 1
a151 1
=head1 DEFAULT VALUES
d153 4
a156 1
=over 4
d158 1
a158 2
In B, all options have a reasonable default value. This allows for a
configurationless B installation.
d160 1
a160 1
=item B<-r>, B<--raw>
d162 1
a162 5
The B<--raw> option determines its default at runtime. If the raw mode option
is not specified, B will determine whether F is connected to a
terminal. If so, B will run in formatted output mode. If F is not
connected to a terminal (such as with most daemons,) B will run in raw
output mode even though it was not specified as an option.
d164 3
a166 1
=item B<-t>, B<--tmpdir> I
d168 1
a168 2
If the B<--dirs> option is not given, B will try to use C<$TMPDIR>,
C<$TEMPDIR>, C<~/tmp> and C (in that order.)
d170 1
a170 1
=item B<-p>, B<--print>, B<-e>, B<--eval>, B<-x>, B<--exec>
d172 1
a172 2
If neither B<--print>, B<--eval>, or B<-exec> is given B will default to
B<--exec>.
d174 3
a176 1
=item B<-c>, B<--conf> F
d178 1
a178 14
Using F from command line option -c aka --conf, fallback to
${OSSP_RC_CONF}, fallback to "@@l_prefix@@/etc/rc.conf".
=item B<-f>, B<--func> F[C<:>F[...]]
=item B<-F>, B<--force>
=item B<-d>, B<--dirs> I[C<:>I[...]
#!FIXME! Sprech mal von Pfad und Dateien defaults wieviel rc.conf erlaubt
#!FIXME! sind, und welche genommen wird oder sonst wie gemerged.
F
F
F
F
d184 1
a184 1
Every command line longoption is also a keyword in the rc.conf file and,
a187 17
The environment determines where rc will search before beginning to process
run commands. It also influences B