OpenPKG Specs / file revision

 ##

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