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