OpenPKG Specs: openpkg/rc.pod@3ca9c03168f4 (annotated)

openpkg/rc.pod@3ca9c03168f4 (annotated)

openpkg/rc.pod

Thu, 08 Jan 2009 23:26:54 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 08 Jan 2009 23:26:54 +0100
changeset 49: 3ca9c03168f4
child 427: 71503088f51b
permissions: -rw-r--r--

Import package vendor original specs for necessary manipulations.

 ##
 ##  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
 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

OpenPKG Specs / annotate

openpkg/rc.pod@3ca9c03168f4 (annotated)

openpkg/rc.pod