diff -r 333964c621f1 -r cb59d6afeb61 openpkg/rc.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/rc.pod	Tue Jan 06 23:40:39 2009 +0100
@@ -0,0 +1,430 @@
+##
+##  rc.pod -- RPM Auxiliary Tool (Manual Page)
+##  Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
+##  Copyright (c) 2000-2007 Ralf S. Engelschall <http://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
+
+B<@l_prefix@/bin/openpkg rc> - OpenPKG Run-Command Processor
+
+=head1 SYNOPSIS
+
+B<@l_prefix@/bin/openpkg rc> [B<-s>|B<--silent>] [B<-v>|B<--verbose>] [B<-d>|B<--debug>] [B<-k>|B<--keep>] I<package> I<command> [I<command> ...]
+
+B<@l_prefix@/bin/openpkg rc> B<-p>|B<--print> I<package> I<command> [I<command> ...]
+
+eval `B<@l_prefix@/bin/openpkg rc> B<-e>|B<--eval> I<package> I<command> [I<command> ...]`
+
+B<@l_prefix@/bin/openpkg rc> B<-q>|B<--query> I<variable> [I<variable> ...]
+
+B<@l_prefix@/bin/openpkg rc> B<-c>|B<--config>
+
+B<@l_prefix@/bin/openpkg rc> B<-h>|B<--help>
+
+=head1 DESCRIPTION
+
+The B<@l_prefix@/bin/openpkg rc> program is the run-command (rc) processor
+of the B<OpenPKG> instance C<@l_prefix@>. It allows querying the rc
+configuration variables and the execution of rc command scripts of one
+or more installed B<OpenPKG> packages. The implemented run-command
+facility is partly modeled after the classical UNIX(tm) System V
+run-command facility plus ideas taken from the FreeBSD and NetBSD
+run-command facilities. It mainly merges the classical startup/shutdown
+procedures with periodical procedures into a single approach.
+
+=head1 USAGE
+
+=over 4
+
+=item B<@l_prefix@/bin/openpkg rc> [B<-s>|B<--silent>] [B<-v>|B<--verbose>] [B<-d>|B<--debug>] [B<-k>|B<--keep>] I<package> I<command> [I<command> ...]
+
+B<Run-Command Execution.> This executes one or more specified
+I<command>s in a particular I<package> or in all installed packages if
+I<package> is "C<all>". Option B<--silent> can be used to explicitly
+disable progress messages on C<stderr>. Option B<--verbose> can be used
+to explicitly enable progress messages on C<stderr>. By default, B<rc>
+automatically determines whether progress messages should be displayed
+or not depending on whether C<stderr> is connected to a terminal device.
+Option B<--keep> can be used for debugging purposes to keep the
+temporary files were generated during internal processing.
+
+=item B<@l_prefix@/bin/openpkg rc> B<-p>|B<--print> I<package> I<command> [I<command> ...]
+
+B<Run-Command Printing.> This is like the run-command execution (see
+above), but instead of immediately executing all involved individual
+run-command scripts, they are concatenated (but with all configuration
+parts reduced to a single configuration part) and printed to C<stdout>.
+Use this for debugging or post-processing purposes.
+
+=item eval `B<@l_prefix@/bin/openpkg rc> B<-e>|B<--eval> I<package> I<command> [I<command> ...]`
+
+B<Run-Command Evaluation.> This is like the run-command execution
+(see above), but the resulting exported shell environment variables
+are output to a temporary file as a (Bourne-Shell or C-Shell syntax)
+shell script, suitable for evaluation within the shell environment
+of the caller. A one-line script is printed to C<stdout> which then
+"sources" (and immediately removes) this temporary file. This is
+slightly different from printing the temporary script directly to
+C<stdout>, because not all shell implementations like to "B<eval>"
+large multi-line scripts. Hence, use this for executing the "C<env>"
+run-commands within the current shell.
+
+=item B<@l_prefix@/bin/openpkg rc> B<-q>|B<--query> I<variable> [I<variable> ...]
+
+B<Configuration Variable Querying.> This queries the effective values
+(see B<RUN-COMMAND CONFIGURATION> section below) of one or more
+run-command configuration I<variable>s. Use this within a shell script
+to selectively query a particular variable.
+
+=item B<@l_prefix@/bin/openpkg rc> B<-c>|B<--config>
+
+B<Configuration Variable Summary.> This displays on C<stdout> a
+three-column table showing the name, default and effective values of
+all run-command configuration variables. If C<stdout> is connected to
+terminal device, variables where the default and effective values differ
+are shown in bold mode.
+
+=item B<@l_prefix@/bin/openpkg rc> B<-h>|B<--help>
+
+B<Requesting Help.> This just displays a short summary of
+the usage for this program.
+
+=back
+
+=head1 FILES
+
+=head2 RUN-COMMAND FILES (C<@l_prefix@/bin/openpkg rc.d/rc.*>)
+
+The foundation of the B<OpenPKG> run-command facility are the individual
+run-command files C<rc.*> of the installed packages. They are all
+located in the directory C<@l_prefix@/bin/openpkg rc.d/> and are named
+"C<rc.>I<package>". They consist of one or more sections, each starting
+with a section header "C<%>I<name> [I<options>]" and following a GNU
+Bash compatible shell script. There are three classes of sections:
+
+=over 4
+
+=item B<Special Sections>
+
+There are 2 sections which have a special meaning to the B<rc> program
+and cannot be used for different purposes.
+
+=over 4
+
+=item C<%config>
+
+This section has to consist of run-command configuration
+variable default settings in Bourne-Shell syntax only, i.e.,
+it has to contain one or more lines, each of exactly the form
+"I<package>C<_>I<variable>C<=>I<value>". Notice that in section
+"C<%config>" of run-command file "C<rc.foo>" the variables all have
+to be prefixed (by convention) with "C<foo_>". It is allowed that the
+I<value>s reference other variables defined before in the same section
+or from the "C<%config>" section of the bootstrap package "C<openpkg>".
+Additionally, by convention all lines have to be indented by 4 spaces.
+
+NOTICE: All sections of all run-command scripts see all C<%config>
+sections of all packages.
+
+=item C<%common>
+
+This section can consist of an arbitrary shell script
+which is automatically prepended to the shell scripts
+of all other sections on execution. It is usually used
+to define common and local variables and functions.
+
+=back
+
+=item B<Conventional Sections>
+
+There are 9 sections which have no special meaning to the B<rc> program,
+but are used in B<OpenPKG> by convention for standard purposes. Hence,
+do not use them for arbitrary things instead.
+
+Throughout these sections it is possible to specify the user to be
+switched to before the code is executed.
+
+A priority can be given for each section to control execution sequence
+if "C<all>" packages are given. Higher priority leads to earlier
+starting and later stopping. The priority is a number where low numbers
+mean high priority (numerically sorted for starting). If omitted, the
+priority defaults to 500.
+
+Output generated on F<stdout> and F<stderr> is captured and normally
+suppressed. In case the sections script exits with a non-zero return
+value, the intercepted messages are consolidated, reformatted with a
+surrounding ASCII-art border and printed to F<stderr>. If the section
+is tagged with option B<-o>, F<stdout> messages are passed through
+verbatim, even if the section script exists with a zero return value.
+
+=over 4
+
+=item C<%start> [B<-u> I<user>] [B<-p> I<priority>]
+
+This section should start daemons or initialize components.
+It is especially executed by B<OpenPKG> during system startup.
+
+=item C<%stop> [B<-u> I<user>] [B<-p> I<priority>]
+
+This section should stop daemons or cleaning up components. It is
+especially executed by B<OpenPKG> during system shutdown and package
+deinstallation.
+
+=item C<%restart> [B<-u> I<user>] [B<-p> I<priority>]
+
+This section should restart daemons.
+It is especially executed by B<OpenPKG> during package upgrades.
+
+=item C<%status -o> [B<-u> I<user>] [B<-p> I<priority>]
+
+This section has to provide status information for a package
+by printing to C<stdout> (hence the B<-o> option is always required),
+in Bourne-Shell syntax, the definition of three variables:
+
+=over 4
+
+=item I<package>C<_enable>
+
+Whether package is enabled, i.e., whether it accepts run-commands. This
+variable just has to be printed, because is already set in current
+script environment.
+
+=item I<package>C<_usable>
+
+Whether package is usable, i.e., whether it is already correctly
+configured, etc. This variable has to be individually determined.
+
+=item I<package>C<_active>
+
+Whether package is active, i.e., whether it is already running.
+This variable has to be individually determined.
+
+=back
+
+=item C<%monthly> [B<-u> I<user>] [B<-p> I<priority>]
+
+=item C<%weekly> [B<-u> I<user>] [B<-p> I<priority>]
+
+=item C<%hourly> [B<-u> I<user>] [B<-p> I<priority>]
+
+=item C<%quarterly> [B<-u> I<user>] [B<-p> I<priority>]
+
+These sections should perform periodical tasks for a package and
+are executed on a monthly, weekly, hourly or quarterly basis.
+
+=item C<%env>
+
+This section is intended to export one or more environment variables
+which are imported into the shell environment of the caller through the
+B<--eval> command line option.
+
+=back
+
+=item B<Custom Sections>
+
+All other sections are custom ones and can be fully individual to each
+package. Some often seen sections are C<%reload> (just reload the
+configuration without full stop and start procedure), C<%info> (output
+arbitrary information about package), etc.
+
+=back
+
+=head2 RUN-COMMAND CONFIGURATION (C<@l_prefix@/bin/openpkg rc.conf>)
+
+The run-command configuration variables defined in the "C<%config>"
+sections of all installed packages can be overridden by the
+administrator in the global file C<@l_prefix@/bin/openpkg rc.conf>. This file is
+usually empty, but can be filled with Bourne-Shell compatible variable
+assignment statements like "I<package>C<_>I<variable>=I<value>".
+
+=head2 RUN-COMMAND FUNCTIONS (C<@l_prefix@/bin/openpkg rc.func>)
+
+The file C<@l_prefix@/bin/openpkg rc.func> is prepended to the scripts of all
+executed run-command sections and provides reusable functions.
+Currently the following functions are defined:
+
+=over 4
+
+=item B<rcMsg> [B<-e>] [B<-w>] I<message>
+
+Print a message to the output device of the run-command caller. The
+message is printed to the captured F<stderr> (but are visible to
+the caller of the run-command script only if the script fails). All
+messages are prefixed with "C<rc:>". If option B<-e> is given, the
+prefix is "C<rc:ERROR:>". If option B<-w> is given, the prefix is
+"C<rc:WARNING:>".
+
+=item B<rcPath> [B<-a>] [B<-r>] [B<-p>] [B<-e>] I<variable> I<dir> [I<dir> ...]
+
+Add (option B<-a>) or remove (option B<-r>) one or more I<dir>ectories
+to/from the colon-separated value of a I<var>able. By default, on
+addition, the directory is appended to the end, if option B<-p> is used
+the directory is prepended to the start. If option B<-e> is used, the
+directories are added only if they exist on the underlying filesystem.
+Use this function for conveniently manipulating C<PATH>, C<MANPATH>,
+C<INFOPATH>, C<LD_LIBRARY_PATH> and similar variables.
+
+=item B<rcTmp> [B<-i>] [B<-f>] [B<-n> I<name>] [B<-k>]
+
+Convenience interface to secure temporary file handling. Option B<-i>
+first has to be used to initialize a secure temporary directory (option
+B<-k> later will kill this again). Under option B<-f> you then can get
+reasonable temporary filenames under the created temporary directory. By
+default, the temporary filename is just "C<tmp>", but can be specified
+with option B<-n> to be I<name>.
+
+=item B<rcService> I<package> I<status> I<value>
+
+Convenience interface to checking the C<%status> variables
+I<package>C<_>I<status> which have to be provided by the C<%config> (if
+I<status> is "C<enable>" this is enough) and C<%status> (if I<status> is
+"C<enable>", "C<usable>" and "C<active>"). The B<rcService> especially
+caches the resolving of the variable values. Returns 0 if the resolved
+value is I<value>, else returns 1.
+
+=item B<rcVarIsYes> I<name>
+
+Checks whether variable I<name> has a value of "C<yes>", "C<true>",
+"C<on>", or "C<1>" (with arbitrary lower or upper case letters). Returns
+0 if value is one of these positive ones, else returns 1.
+
+=back
+
+=head1 EXAMPLES
+
+First, an example run-command script C<@l_prefix@/bin/openpkg rc.d/rc.foo> for a
+fictional daemon package "C<foo>":
+
+ %config
+    foo_enable="${openpkg_rc_def}"
+    foo_listen="127.0.0.1"
+    foo_log_prolog="true"
+    foo_log_epilog="true"
+    foo_log_numfiles="10"
+    foo_log_minsize="1M"
+    foo_log_complevel="9"
+
+ %common
+    foo_homedir="@l_prefix@/share/foo"
+    foo_cfgfile="@l_prefix@/etc/foo/foo.cfg"
+    foo_pidfile="@l_prefix@/var/foo/foo.pid"
+    foo_logfile="@l_prefix@/var/foo/foo.log"
+    foo_signal () {
+        if [ -f ${foo_pidfile} ]; then
+            kill -$1 `cat ${foo_pidfile}`
+            return $?
+        else
+            return 1
+        fi
+    }
+
+ %status
+     foo_usable="no"
+     if [ ".`grep '<<PASSWORD>>' ${foo_cfgfile}`" = . ]; then
+         foo_usable="yes"
+     fi
+     foo_active="no"
+     if [ -f ${foo_pidfile} ]; then
+         foo_signal 0
+         if [ $? -eq 0 ]; then
+             foo_active="yes"
+         fi
+     fi
+     echo "foo_enable=${foo_enable}"
+     echo "foo_usable=${foo_usable}"
+     echo "foo_active=${foo_active}"
+
+ %start
+     rcService foo enable yes || exit 0
+     rcService foo active yes && exit 0
+     @l_prefix@/sbin/foo --listen ${foo_listen}
+
+ %stop
+     rcService foo enable yes || exit 0
+     rcService foo active yes || exit 0
+     foo_signal TERM
+
+ %restart
+     rcService foo enable yes || exit 0
+     rcService foo active yes || exit 0
+     rc foo stop start
+
+ %daily
+     rcService foo enable yes || exit 0
+     shtool rotate -f \
+         -n ${foo_log_numfiles} -s ${foo_log_minsize} -d \
+         -z ${foo_log_complevel} -o @l_rusr@ -g @l_rgrp@ -m 644 \
+         -P "${foo_log_prolog}" -E "${foo_log_epilog}" \
+         ${foo_logfile}
+
+ %env
+     if rcService foo enable yes; then
+         FOO_HOME="$foo_homedir"
+         export FOO_HOME
+     fi
+
+Now, show all run-command configuration variables, their
+default values and their effective values of package "C<foo>":
+
+ $ @l_prefix@/bin/openpkg rc --config | grep "^foo_"
+
+Override the default value of a run-command configuration
+variable C<foo_listen>:
+
+ $ echo 'foo_listen="192.168.0.1"' >>@l_prefix@/bin/openpkg rc.conf
+
+Stop and start from scratch the package "C<foo>":
+
+ $ @l_prefix@/bin/openpkg rc foo stop start
+
+Query the effective value of run-command configuration
+variable C<foo_enable> in a script:
+
+ if [ ".`@l_prefix@/bin/openpkg rc -q foo_enable`" = .yes ]; then ...
+
+Import all environment settings from all (including "C<foo>") installed
+packages into the current Bourne-Shell environment:
+
+ $ eval `@l_prefix@/bin/openpkg rc --eval all env`
+ $ echo $FOO_HOME
+
+=head1 SEE ALSO
+
+B<OpenPKG> http://www.openpkg.org/
+
+=head1 HISTORY
+
+The B<OpenPKG> run-command facility consisting of the scripts C<rc>
+and C<rc.func> were originally invented in November 2000 by Ralf S.
+Engelschall for B<OpenPKG>. They were completely worked off from scratch
+in July 2003 for B<OpenPKG 1.3>.
+
+=head1 AUTHOR
+
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+
+=cut
+