1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/rc.pod Tue Jan 06 23:40:39 2009 +0100
1.3 @@ -0,0 +1,430 @@
1.4 +##
1.5 +## rc.pod -- RPM Auxiliary Tool (Manual Page)
1.6 +## Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
1.7 +## Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>
1.8 +##
1.9 +## Permission to use, copy, modify, and distribute this software for
1.10 +## any purpose with or without fee is hereby granted, provided that
1.11 +## the above copyright notice and this permission notice appear in all
1.12 +## copies.
1.13 +##
1.14 +## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
1.15 +## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.16 +## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1.17 +## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
1.18 +## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.19 +## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.20 +## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1.21 +## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1.22 +## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1.23 +## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1.24 +## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1.25 +## SUCH DAMAGE.
1.26 +##
1.27 +
1.28 +=pod
1.29 +
1.30 +=head1 NAME
1.31 +
1.32 +B<@l_prefix@/bin/openpkg rc> - OpenPKG Run-Command Processor
1.33 +
1.34 +=head1 SYNOPSIS
1.35 +
1.36 +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> ...]
1.37 +
1.38 +B<@l_prefix@/bin/openpkg rc> B<-p>|B<--print> I<package> I<command> [I<command> ...]
1.39 +
1.40 +eval `B<@l_prefix@/bin/openpkg rc> B<-e>|B<--eval> I<package> I<command> [I<command> ...]`
1.41 +
1.42 +B<@l_prefix@/bin/openpkg rc> B<-q>|B<--query> I<variable> [I<variable> ...]
1.43 +
1.44 +B<@l_prefix@/bin/openpkg rc> B<-c>|B<--config>
1.45 +
1.46 +B<@l_prefix@/bin/openpkg rc> B<-h>|B<--help>
1.47 +
1.48 +=head1 DESCRIPTION
1.49 +
1.50 +The B<@l_prefix@/bin/openpkg rc> program is the run-command (rc) processor
1.51 +of the B<OpenPKG> instance C<@l_prefix@>. It allows querying the rc
1.52 +configuration variables and the execution of rc command scripts of one
1.53 +or more installed B<OpenPKG> packages. The implemented run-command
1.54 +facility is partly modeled after the classical UNIX(tm) System V
1.55 +run-command facility plus ideas taken from the FreeBSD and NetBSD
1.56 +run-command facilities. It mainly merges the classical startup/shutdown
1.57 +procedures with periodical procedures into a single approach.
1.58 +
1.59 +=head1 USAGE
1.60 +
1.61 +=over 4
1.62 +
1.63 +=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> ...]
1.64 +
1.65 +B<Run-Command Execution.> This executes one or more specified
1.66 +I<command>s in a particular I<package> or in all installed packages if
1.67 +I<package> is "C<all>". Option B<--silent> can be used to explicitly
1.68 +disable progress messages on C<stderr>. Option B<--verbose> can be used
1.69 +to explicitly enable progress messages on C<stderr>. By default, B<rc>
1.70 +automatically determines whether progress messages should be displayed
1.71 +or not depending on whether C<stderr> is connected to a terminal device.
1.72 +Option B<--keep> can be used for debugging purposes to keep the
1.73 +temporary files were generated during internal processing.
1.74 +
1.75 +=item B<@l_prefix@/bin/openpkg rc> B<-p>|B<--print> I<package> I<command> [I<command> ...]
1.76 +
1.77 +B<Run-Command Printing.> This is like the run-command execution (see
1.78 +above), but instead of immediately executing all involved individual
1.79 +run-command scripts, they are concatenated (but with all configuration
1.80 +parts reduced to a single configuration part) and printed to C<stdout>.
1.81 +Use this for debugging or post-processing purposes.
1.82 +
1.83 +=item eval `B<@l_prefix@/bin/openpkg rc> B<-e>|B<--eval> I<package> I<command> [I<command> ...]`
1.84 +
1.85 +B<Run-Command Evaluation.> This is like the run-command execution
1.86 +(see above), but the resulting exported shell environment variables
1.87 +are output to a temporary file as a (Bourne-Shell or C-Shell syntax)
1.88 +shell script, suitable for evaluation within the shell environment
1.89 +of the caller. A one-line script is printed to C<stdout> which then
1.90 +"sources" (and immediately removes) this temporary file. This is
1.91 +slightly different from printing the temporary script directly to
1.92 +C<stdout>, because not all shell implementations like to "B<eval>"
1.93 +large multi-line scripts. Hence, use this for executing the "C<env>"
1.94 +run-commands within the current shell.
1.95 +
1.96 +=item B<@l_prefix@/bin/openpkg rc> B<-q>|B<--query> I<variable> [I<variable> ...]
1.97 +
1.98 +B<Configuration Variable Querying.> This queries the effective values
1.99 +(see B<RUN-COMMAND CONFIGURATION> section below) of one or more
1.100 +run-command configuration I<variable>s. Use this within a shell script
1.101 +to selectively query a particular variable.
1.102 +
1.103 +=item B<@l_prefix@/bin/openpkg rc> B<-c>|B<--config>
1.104 +
1.105 +B<Configuration Variable Summary.> This displays on C<stdout> a
1.106 +three-column table showing the name, default and effective values of
1.107 +all run-command configuration variables. If C<stdout> is connected to
1.108 +terminal device, variables where the default and effective values differ
1.109 +are shown in bold mode.
1.110 +
1.111 +=item B<@l_prefix@/bin/openpkg rc> B<-h>|B<--help>
1.112 +
1.113 +B<Requesting Help.> This just displays a short summary of
1.114 +the usage for this program.
1.115 +
1.116 +=back
1.117 +
1.118 +=head1 FILES
1.119 +
1.120 +=head2 RUN-COMMAND FILES (C<@l_prefix@/bin/openpkg rc.d/rc.*>)
1.121 +
1.122 +The foundation of the B<OpenPKG> run-command facility are the individual
1.123 +run-command files C<rc.*> of the installed packages. They are all
1.124 +located in the directory C<@l_prefix@/bin/openpkg rc.d/> and are named
1.125 +"C<rc.>I<package>". They consist of one or more sections, each starting
1.126 +with a section header "C<%>I<name> [I<options>]" and following a GNU
1.127 +Bash compatible shell script. There are three classes of sections:
1.128 +
1.129 +=over 4
1.130 +
1.131 +=item B<Special Sections>
1.132 +
1.133 +There are 2 sections which have a special meaning to the B<rc> program
1.134 +and cannot be used for different purposes.
1.135 +
1.136 +=over 4
1.137 +
1.138 +=item C<%config>
1.139 +
1.140 +This section has to consist of run-command configuration
1.141 +variable default settings in Bourne-Shell syntax only, i.e.,
1.142 +it has to contain one or more lines, each of exactly the form
1.143 +"I<package>C<_>I<variable>C<=>I<value>". Notice that in section
1.144 +"C<%config>" of run-command file "C<rc.foo>" the variables all have
1.145 +to be prefixed (by convention) with "C<foo_>". It is allowed that the
1.146 +I<value>s reference other variables defined before in the same section
1.147 +or from the "C<%config>" section of the bootstrap package "C<openpkg>".
1.148 +Additionally, by convention all lines have to be indented by 4 spaces.
1.149 +
1.150 +NOTICE: All sections of all run-command scripts see all C<%config>
1.151 +sections of all packages.
1.152 +
1.153 +=item C<%common>
1.154 +
1.155 +This section can consist of an arbitrary shell script
1.156 +which is automatically prepended to the shell scripts
1.157 +of all other sections on execution. It is usually used
1.158 +to define common and local variables and functions.
1.159 +
1.160 +=back
1.161 +
1.162 +=item B<Conventional Sections>
1.163 +
1.164 +There are 9 sections which have no special meaning to the B<rc> program,
1.165 +but are used in B<OpenPKG> by convention for standard purposes. Hence,
1.166 +do not use them for arbitrary things instead.
1.167 +
1.168 +Throughout these sections it is possible to specify the user to be
1.169 +switched to before the code is executed.
1.170 +
1.171 +A priority can be given for each section to control execution sequence
1.172 +if "C<all>" packages are given. Higher priority leads to earlier
1.173 +starting and later stopping. The priority is a number where low numbers
1.174 +mean high priority (numerically sorted for starting). If omitted, the
1.175 +priority defaults to 500.
1.176 +
1.177 +Output generated on F<stdout> and F<stderr> is captured and normally
1.178 +suppressed. In case the sections script exits with a non-zero return
1.179 +value, the intercepted messages are consolidated, reformatted with a
1.180 +surrounding ASCII-art border and printed to F<stderr>. If the section
1.181 +is tagged with option B<-o>, F<stdout> messages are passed through
1.182 +verbatim, even if the section script exists with a zero return value.
1.183 +
1.184 +=over 4
1.185 +
1.186 +=item C<%start> [B<-u> I<user>] [B<-p> I<priority>]
1.187 +
1.188 +This section should start daemons or initialize components.
1.189 +It is especially executed by B<OpenPKG> during system startup.
1.190 +
1.191 +=item C<%stop> [B<-u> I<user>] [B<-p> I<priority>]
1.192 +
1.193 +This section should stop daemons or cleaning up components. It is
1.194 +especially executed by B<OpenPKG> during system shutdown and package
1.195 +deinstallation.
1.196 +
1.197 +=item C<%restart> [B<-u> I<user>] [B<-p> I<priority>]
1.198 +
1.199 +This section should restart daemons.
1.200 +It is especially executed by B<OpenPKG> during package upgrades.
1.201 +
1.202 +=item C<%status -o> [B<-u> I<user>] [B<-p> I<priority>]
1.203 +
1.204 +This section has to provide status information for a package
1.205 +by printing to C<stdout> (hence the B<-o> option is always required),
1.206 +in Bourne-Shell syntax, the definition of three variables:
1.207 +
1.208 +=over 4
1.209 +
1.210 +=item I<package>C<_enable>
1.211 +
1.212 +Whether package is enabled, i.e., whether it accepts run-commands. This
1.213 +variable just has to be printed, because is already set in current
1.214 +script environment.
1.215 +
1.216 +=item I<package>C<_usable>
1.217 +
1.218 +Whether package is usable, i.e., whether it is already correctly
1.219 +configured, etc. This variable has to be individually determined.
1.220 +
1.221 +=item I<package>C<_active>
1.222 +
1.223 +Whether package is active, i.e., whether it is already running.
1.224 +This variable has to be individually determined.
1.225 +
1.226 +=back
1.227 +
1.228 +=item C<%monthly> [B<-u> I<user>] [B<-p> I<priority>]
1.229 +
1.230 +=item C<%weekly> [B<-u> I<user>] [B<-p> I<priority>]
1.231 +
1.232 +=item C<%hourly> [B<-u> I<user>] [B<-p> I<priority>]
1.233 +
1.234 +=item C<%quarterly> [B<-u> I<user>] [B<-p> I<priority>]
1.235 +
1.236 +These sections should perform periodical tasks for a package and
1.237 +are executed on a monthly, weekly, hourly or quarterly basis.
1.238 +
1.239 +=item C<%env>
1.240 +
1.241 +This section is intended to export one or more environment variables
1.242 +which are imported into the shell environment of the caller through the
1.243 +B<--eval> command line option.
1.244 +
1.245 +=back
1.246 +
1.247 +=item B<Custom Sections>
1.248 +
1.249 +All other sections are custom ones and can be fully individual to each
1.250 +package. Some often seen sections are C<%reload> (just reload the
1.251 +configuration without full stop and start procedure), C<%info> (output
1.252 +arbitrary information about package), etc.
1.253 +
1.254 +=back
1.255 +
1.256 +=head2 RUN-COMMAND CONFIGURATION (C<@l_prefix@/bin/openpkg rc.conf>)
1.257 +
1.258 +The run-command configuration variables defined in the "C<%config>"
1.259 +sections of all installed packages can be overridden by the
1.260 +administrator in the global file C<@l_prefix@/bin/openpkg rc.conf>. This file is
1.261 +usually empty, but can be filled with Bourne-Shell compatible variable
1.262 +assignment statements like "I<package>C<_>I<variable>=I<value>".
1.263 +
1.264 +=head2 RUN-COMMAND FUNCTIONS (C<@l_prefix@/bin/openpkg rc.func>)
1.265 +
1.266 +The file C<@l_prefix@/bin/openpkg rc.func> is prepended to the scripts of all
1.267 +executed run-command sections and provides reusable functions.
1.268 +Currently the following functions are defined:
1.269 +
1.270 +=over 4
1.271 +
1.272 +=item B<rcMsg> [B<-e>] [B<-w>] I<message>
1.273 +
1.274 +Print a message to the output device of the run-command caller. The
1.275 +message is printed to the captured F<stderr> (but are visible to
1.276 +the caller of the run-command script only if the script fails). All
1.277 +messages are prefixed with "C<rc:>". If option B<-e> is given, the
1.278 +prefix is "C<rc:ERROR:>". If option B<-w> is given, the prefix is
1.279 +"C<rc:WARNING:>".
1.280 +
1.281 +=item B<rcPath> [B<-a>] [B<-r>] [B<-p>] [B<-e>] I<variable> I<dir> [I<dir> ...]
1.282 +
1.283 +Add (option B<-a>) or remove (option B<-r>) one or more I<dir>ectories
1.284 +to/from the colon-separated value of a I<var>able. By default, on
1.285 +addition, the directory is appended to the end, if option B<-p> is used
1.286 +the directory is prepended to the start. If option B<-e> is used, the
1.287 +directories are added only if they exist on the underlying filesystem.
1.288 +Use this function for conveniently manipulating C<PATH>, C<MANPATH>,
1.289 +C<INFOPATH>, C<LD_LIBRARY_PATH> and similar variables.
1.290 +
1.291 +=item B<rcTmp> [B<-i>] [B<-f>] [B<-n> I<name>] [B<-k>]
1.292 +
1.293 +Convenience interface to secure temporary file handling. Option B<-i>
1.294 +first has to be used to initialize a secure temporary directory (option
1.295 +B<-k> later will kill this again). Under option B<-f> you then can get
1.296 +reasonable temporary filenames under the created temporary directory. By
1.297 +default, the temporary filename is just "C<tmp>", but can be specified
1.298 +with option B<-n> to be I<name>.
1.299 +
1.300 +=item B<rcService> I<package> I<status> I<value>
1.301 +
1.302 +Convenience interface to checking the C<%status> variables
1.303 +I<package>C<_>I<status> which have to be provided by the C<%config> (if
1.304 +I<status> is "C<enable>" this is enough) and C<%status> (if I<status> is
1.305 +"C<enable>", "C<usable>" and "C<active>"). The B<rcService> especially
1.306 +caches the resolving of the variable values. Returns 0 if the resolved
1.307 +value is I<value>, else returns 1.
1.308 +
1.309 +=item B<rcVarIsYes> I<name>
1.310 +
1.311 +Checks whether variable I<name> has a value of "C<yes>", "C<true>",
1.312 +"C<on>", or "C<1>" (with arbitrary lower or upper case letters). Returns
1.313 +0 if value is one of these positive ones, else returns 1.
1.314 +
1.315 +=back
1.316 +
1.317 +=head1 EXAMPLES
1.318 +
1.319 +First, an example run-command script C<@l_prefix@/bin/openpkg rc.d/rc.foo> for a
1.320 +fictional daemon package "C<foo>":
1.321 +
1.322 + %config
1.323 + foo_enable="${openpkg_rc_def}"
1.324 + foo_listen="127.0.0.1"
1.325 + foo_log_prolog="true"
1.326 + foo_log_epilog="true"
1.327 + foo_log_numfiles="10"
1.328 + foo_log_minsize="1M"
1.329 + foo_log_complevel="9"
1.330 +
1.331 + %common
1.332 + foo_homedir="@l_prefix@/share/foo"
1.333 + foo_cfgfile="@l_prefix@/etc/foo/foo.cfg"
1.334 + foo_pidfile="@l_prefix@/var/foo/foo.pid"
1.335 + foo_logfile="@l_prefix@/var/foo/foo.log"
1.336 + foo_signal () {
1.337 + if [ -f ${foo_pidfile} ]; then
1.338 + kill -$1 `cat ${foo_pidfile}`
1.339 + return $?
1.340 + else
1.341 + return 1
1.342 + fi
1.343 + }
1.344 +
1.345 + %status
1.346 + foo_usable="no"
1.347 + if [ ".`grep '<<PASSWORD>>' ${foo_cfgfile}`" = . ]; then
1.348 + foo_usable="yes"
1.349 + fi
1.350 + foo_active="no"
1.351 + if [ -f ${foo_pidfile} ]; then
1.352 + foo_signal 0
1.353 + if [ $? -eq 0 ]; then
1.354 + foo_active="yes"
1.355 + fi
1.356 + fi
1.357 + echo "foo_enable=${foo_enable}"
1.358 + echo "foo_usable=${foo_usable}"
1.359 + echo "foo_active=${foo_active}"
1.360 +
1.361 + %start
1.362 + rcService foo enable yes || exit 0
1.363 + rcService foo active yes && exit 0
1.364 + @l_prefix@/sbin/foo --listen ${foo_listen}
1.365 +
1.366 + %stop
1.367 + rcService foo enable yes || exit 0
1.368 + rcService foo active yes || exit 0
1.369 + foo_signal TERM
1.370 +
1.371 + %restart
1.372 + rcService foo enable yes || exit 0
1.373 + rcService foo active yes || exit 0
1.374 + rc foo stop start
1.375 +
1.376 + %daily
1.377 + rcService foo enable yes || exit 0
1.378 + shtool rotate -f \
1.379 + -n ${foo_log_numfiles} -s ${foo_log_minsize} -d \
1.380 + -z ${foo_log_complevel} -o @l_rusr@ -g @l_rgrp@ -m 644 \
1.381 + -P "${foo_log_prolog}" -E "${foo_log_epilog}" \
1.382 + ${foo_logfile}
1.383 +
1.384 + %env
1.385 + if rcService foo enable yes; then
1.386 + FOO_HOME="$foo_homedir"
1.387 + export FOO_HOME
1.388 + fi
1.389 +
1.390 +Now, show all run-command configuration variables, their
1.391 +default values and their effective values of package "C<foo>":
1.392 +
1.393 + $ @l_prefix@/bin/openpkg rc --config | grep "^foo_"
1.394 +
1.395 +Override the default value of a run-command configuration
1.396 +variable C<foo_listen>:
1.397 +
1.398 + $ echo 'foo_listen="192.168.0.1"' >>@l_prefix@/bin/openpkg rc.conf
1.399 +
1.400 +Stop and start from scratch the package "C<foo>":
1.401 +
1.402 + $ @l_prefix@/bin/openpkg rc foo stop start
1.403 +
1.404 +Query the effective value of run-command configuration
1.405 +variable C<foo_enable> in a script:
1.406 +
1.407 + if [ ".`@l_prefix@/bin/openpkg rc -q foo_enable`" = .yes ]; then ...
1.408 +
1.409 +Import all environment settings from all (including "C<foo>") installed
1.410 +packages into the current Bourne-Shell environment:
1.411 +
1.412 + $ eval `@l_prefix@/bin/openpkg rc --eval all env`
1.413 + $ echo $FOO_HOME
1.414 +
1.415 +=head1 SEE ALSO
1.416 +
1.417 +B<OpenPKG> http://www.openpkg.org/
1.418 +
1.419 +=head1 HISTORY
1.420 +
1.421 +The B<OpenPKG> run-command facility consisting of the scripts C<rc>
1.422 +and C<rc.func> were originally invented in November 2000 by Ralf S.
1.423 +Engelschall for B<OpenPKG>. They were completely worked off from scratch
1.424 +in July 2003 for B<OpenPKG 1.3>.
1.425 +
1.426 +=head1 AUTHOR
1.427 +
1.428 + Ralf S. Engelschall
1.429 + rse@engelschall.com
1.430 + www.engelschall.com
1.431 +
1.432 +=cut
1.433 +
