michael@428: .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
michael@13: .\"
michael@13: .\" Standard preamble:
michael@13: .\" ========================================================================
michael@13: .de Sp \" Vertical space (when we can't use .PP)
michael@13: .if t .sp .5v
michael@13: .if n .sp
michael@13: ..
michael@13: .de Vb \" Begin verbatim text
michael@13: .ft CW
michael@13: .nf
michael@13: .ne \\$1
michael@13: ..
michael@13: .de Ve \" End verbatim text
michael@13: .ft R
michael@13: .fi
michael@13: ..
michael@13: .\" Set up some character translations and predefined strings.  \*(-- will
michael@13: .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
michael@428: .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
michael@428: .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
michael@428: .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
michael@428: .\" nothing in troff, for use with C<>.
michael@428: .tr \(*W-
michael@13: .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
michael@13: .ie n \{\
michael@13: .    ds -- \(*W-
michael@13: .    ds PI pi
michael@13: .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
michael@13: .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
michael@13: .    ds L" ""
michael@13: .    ds R" ""
michael@13: .    ds C` 
michael@13: .    ds C' 
michael@13: 'br\}
michael@13: .el\{\
michael@13: .    ds -- \|\(em\|
michael@13: .    ds PI \(*p
michael@13: .    ds L" ``
michael@13: .    ds R" ''
michael@13: 'br\}
michael@13: .\"
michael@428: .\" Escape single quotes in literal strings from groff's Unicode transform.
michael@428: .ie \n(.g .ds Aq \(aq
michael@428: .el       .ds Aq '
michael@428: .\"
michael@13: .\" If the F register is turned on, we'll generate index entries on stderr for
michael@428: .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
michael@13: .\" entries marked with X<> in POD.  Of course, you'll have to process the
michael@13: .\" output yourself in some meaningful fashion.
michael@428: .ie \nF \{\
michael@13: .    de IX
michael@13: .    tm Index:\\$1\t\\n%\t"\\$2"
michael@13: ..
michael@13: .    nr % 0
michael@13: .    rr F
michael@13: .\}
michael@428: .el \{\
michael@428: .    de IX
michael@428: ..
michael@428: .\}
michael@13: .\"
michael@13: .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
michael@13: .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
michael@13: .    \" fudge factors for nroff and troff
michael@13: .if n \{\
michael@13: .    ds #H 0
michael@13: .    ds #V .8m
michael@13: .    ds #F .3m
michael@13: .    ds #[ \f1
michael@13: .    ds #] \fP
michael@13: .\}
michael@13: .if t \{\
michael@13: .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
michael@13: .    ds #V .6m
michael@13: .    ds #F 0
michael@13: .    ds #[ \&
michael@13: .    ds #] \&
michael@13: .\}
michael@13: .    \" simple accents for nroff and troff
michael@13: .if n \{\
michael@13: .    ds ' \&
michael@13: .    ds ` \&
michael@13: .    ds ^ \&
michael@13: .    ds , \&
michael@13: .    ds ~ ~
michael@13: .    ds /
michael@13: .\}
michael@13: .if t \{\
michael@13: .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
michael@13: .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
michael@13: .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
michael@13: .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
michael@13: .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
michael@13: .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
michael@13: .\}
michael@13: .    \" troff and (daisy-wheel) nroff accents
michael@13: .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
michael@13: .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
michael@13: .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
michael@13: .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
michael@13: .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
michael@13: .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
michael@13: .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
michael@13: .ds ae a\h'-(\w'a'u*4/10)'e
michael@13: .ds Ae A\h'-(\w'A'u*4/10)'E
michael@13: .    \" corrections for vroff
michael@13: .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
michael@13: .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
michael@13: .    \" for low resolution devices (crt and lpr)
michael@13: .if \n(.H>23 .if \n(.V>19 \
michael@13: \{\
michael@13: .    ds : e
michael@13: .    ds 8 ss
michael@13: .    ds o a
michael@13: .    ds d- d\h'-1'\(ga
michael@13: .    ds D- D\h'-1'\(hy
michael@13: .    ds th \o'bp'
michael@13: .    ds Th \o'LP'
michael@13: .    ds ae ae
michael@13: .    ds Ae AE
michael@13: .\}
michael@13: .rm #[ #] #H #V #F C
michael@13: .\" ========================================================================
michael@13: .\"
michael@13: .IX Title "RC 8"
michael@13: .TH RC 8 "OpenPKG" "RC(8)" "OpenPKG"
michael@428: .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
michael@428: .\" way too many mistakes in technical documents.
michael@428: .if n .ad l
michael@428: .nh
michael@13: .SH "NAME"
michael@428: @l_prefix@/bin/openpkg rc \- OpenPKG Run\-Command Processor
michael@13: .SH "SYNOPSIS"
michael@13: .IX Header "SYNOPSIS"
michael@428: \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR [\fB\-s\fR|\fB\-\-silent\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-d\fR|\fB\-\-debug\fR] [\fB\-k\fR|\fB\-\-keep\fR] [\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR] \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]
michael@13: .PP
michael@428: \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-p\fR|\fB\-\-print\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]
michael@13: .PP
michael@428: eval `\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-e\fR|\fB\-\-eval\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]`
michael@13: .PP
michael@428: \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-q\fR|\fB\-\-query\fR \fIvariable\fR [\fIvariable\fR ...]
michael@13: .PP
michael@428: \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-c\fR|\fB\-\-config\fR
michael@13: .PP
michael@428: \&\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-h\fR|\fB\-\-help\fR
michael@13: .SH "DESCRIPTION"
michael@13: .IX Header "DESCRIPTION"
michael@428: The \fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR program is the run-command (rc) processor
michael@13: of the \fBOpenPKG\fR instance \f(CW\*(C`@l_prefix@\*(C'\fR. It allows querying the rc
michael@13: configuration variables and the execution of rc command scripts of one
michael@13: or more installed \fBOpenPKG\fR packages. The implemented run-command
michael@13: facility is partly modeled after the classical \s-1UNIX\s0(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: .SH "USAGE"
michael@13: .IX Header "USAGE"
michael@428: .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR [\fB\-s\fR|\fB\-\-silent\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-d\fR|\fB\-\-debug\fR] [\fB\-k\fR|\fB\-\-keep\fR] [\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR] \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4
michael@428: .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR [\fB\-s\fR|\fB\-\-silent\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-d\fR|\fB\-\-debug\fR] [\fB\-k\fR|\fB\-\-keep\fR] [\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR] \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4
michael@428: .IX Item "@l_prefix@/bin/openpkg rc [-s|--silent] [-v|--verbose] [-d|--debug] [-k|--keep] [-D|--define name=value] package command [command ...]"
michael@428: \&\fBRun-Command Execution.\fR This executes one or more specified
michael@13: \&\fIcommand\fRs in a particular \fIpackage\fR or in all installed packages if
michael@13: \&\fIpackage\fR is "\f(CW\*(C`all\*(C'\fR". Option \fB\-\-silent\fR can be used to explicitly
michael@13: disable progress messages on \f(CW\*(C`stderr\*(C'\fR. Option \fB\-\-verbose\fR can be used
michael@13: to explicitly enable progress messages on \f(CW\*(C`stderr\*(C'\fR. By default, \fBrc\fR
michael@13: automatically determines whether progress messages should be displayed
michael@13: or not depending on whether \f(CW\*(C`stderr\*(C'\fR is connected to a terminal device.
michael@13: Option \fB\-\-keep\fR can be used for debugging purposes to keep the
michael@428: temporary files were generated during internal processing. Option
michael@428: \&\fB\-\-define\fR can be used to on-the-fly re-define a configuration variable
michael@428: \&\fIname\fR with \fIvalue\fR.
michael@428: .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-p\fR|\fB\-\-print\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4
michael@428: .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-p\fR|\fB\-\-print\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4
michael@13: .IX Item "@l_prefix@/bin/openpkg rc -p|--print package command [command ...]"
michael@428: \&\fBRun-Command Printing.\fR 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 \f(CW\*(C`stdout\*(C'\fR.
michael@13: Use this for debugging or post-processing purposes.
michael@428: .ie n .IP "eval `\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-e\fR|\fB\-\-eval\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]`" 4
michael@428: .el .IP "eval `\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-e\fR|\fB\-\-eval\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]`" 4
michael@13: .IX Item "eval `@l_prefix@/bin/openpkg rc -e|--eval package command [command ...]`"
michael@428: \&\fBRun-Command Evaluation.\fR This is like the run-command execution
michael@13: (see above), but the resulting exported shell environment variables
michael@428: 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 \f(CW\*(C`stdout\*(C'\fR which then
michael@13: \&\*(L"sources\*(R" (and immediately removes) this temporary file. This is
michael@13: slightly different from printing the temporary script directly to
michael@13: \&\f(CW\*(C`stdout\*(C'\fR, because not all shell implementations like to "\fBeval\fR\*(L"
michael@13: large multi-line scripts. Hence, use this for executing the \*(R"\f(CW\*(C`env\*(C'\fR"
michael@13: run-commands within the current shell.
michael@428: .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-q\fR|\fB\-\-query\fR \fIvariable\fR [\fIvariable\fR ...]" 4
michael@428: .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-q\fR|\fB\-\-query\fR \fIvariable\fR [\fIvariable\fR ...]" 4
michael@13: .IX Item "@l_prefix@/bin/openpkg rc -q|--query variable [variable ...]"
michael@13: \&\fBConfiguration Variable Querying.\fR This queries the effective values
michael@13: (see \fBRUN-COMMAND \s-1CONFIGURATION\s0\fR section below) of one or more
michael@13: run-command configuration \fIvariable\fRs. Use this within a shell script
michael@13: to selectively query a particular variable.
michael@428: .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-c\fR|\fB\-\-config\fR" 4
michael@428: .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-c\fR|\fB\-\-config\fR" 4
michael@13: .IX Item "@l_prefix@/bin/openpkg rc -c|--config"
michael@13: \&\fBConfiguration Variable Summary.\fR This displays on \f(CW\*(C`stdout\*(C'\fR a
michael@13: three-column table showing the name, default and effective values of
michael@13: all run-command configuration variables. If \f(CW\*(C`stdout\*(C'\fR is connected to
michael@13: terminal device, variables where the default and effective values differ
michael@13: are shown in bold mode.
michael@428: .ie n .IP "\fB\fB@l_prefix\fB@/bin/openpkg rc\fR \fB\-h\fR|\fB\-\-help\fR" 4
michael@428: .el .IP "\fB\f(CB@l_prefix\fB@/bin/openpkg rc\fR \fB\-h\fR|\fB\-\-help\fR" 4
michael@13: .IX Item "@l_prefix@/bin/openpkg rc -h|--help"
michael@13: \&\fBRequesting Help.\fR This just displays a short summary of
michael@13: the usage for this program.
michael@13: .SH "FILES"
michael@13: .IX Header "FILES"
michael@428: .ie n .SS "RUN-COMMAND \s-1FILES\s0 (\*(C`@l_prefix@/bin/openpkg rc.d/rc.*\*(C')"
michael@428: .el .SS "RUN-COMMAND \s-1FILES\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.d/rc.*\*(C'\fP)"
michael@13: .IX Subsection "RUN-COMMAND FILES (@l_prefix@/bin/openpkg rc.d/rc.*)"
michael@13: The foundation of the \fBOpenPKG\fR run-command facility are the individual
michael@13: run-command files \f(CW\*(C`rc.*\*(C'\fR of the installed packages. They are all
michael@13: located in the directory \f(CW\*(C`@l_prefix@/bin/openpkg rc.d/\*(C'\fR and are named
michael@13: "\f(CW\*(C`rc.\*(C'\fR\fIpackage\fR\*(L". They consist of one or more sections, each starting
michael@13: with a section header \*(R"\f(CW\*(C`%\*(C'\fR\fIname\fR [\fIoptions\fR]" and following a \s-1GNU\s0
michael@13: Bash compatible shell script. There are three classes of sections:
michael@13: .IP "\fBSpecial Sections\fR" 4
michael@13: .IX Item "Special Sections"
michael@13: There are 2 sections which have a special meaning to the \fBrc\fR program
michael@13: and cannot be used for different purposes.
michael@13: .RS 4
michael@13: .ie n .IP "%config" 4
michael@13: .el .IP "\f(CW%config\fR" 4
michael@13: .IX Item "%config"
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: "\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIvariable\fR\f(CW\*(C`=\*(C'\fR\fIvalue\fR\*(L". Notice that in section
michael@13: \&\*(R"\f(CW%config\fR\*(L" of run-command file \*(R"\f(CW\*(C`rc.foo\*(C'\fR\*(L" the variables all have
michael@13: to be prefixed (by convention) with \*(R"\f(CW\*(C`foo_\*(C'\fR". It is allowed that the
michael@13: \&\fIvalue\fRs reference other variables defined before in the same section
michael@13: or from the "\f(CW%config\fR\*(L" section of the bootstrap package \*(R"\f(CW\*(C`openpkg\*(C'\fR".
michael@13: Additionally, by convention all lines have to be indented by 4 spaces.
michael@13: .Sp
michael@13: \&\s-1NOTICE:\s0 All sections of all run-command scripts see all \f(CW%config\fR
michael@13: sections of all packages.
michael@13: .ie n .IP "%common" 4
michael@13: .el .IP "\f(CW%common\fR" 4
michael@13: .IX Item "%common"
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: .RE
michael@13: .RS 4
michael@13: .RE
michael@13: .IP "\fBConventional Sections\fR" 4
michael@13: .IX Item "Conventional Sections"
michael@13: There are 9 sections which have no special meaning to the \fBrc\fR program,
michael@13: but are used in \fBOpenPKG\fR by convention for standard purposes. Hence,
michael@13: do not use them for arbitrary things instead.
michael@13: .Sp
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: .Sp
michael@13: A priority can be given for each section to control execution sequence
michael@13: if "\f(CW\*(C`all\*(C'\fR" 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: .Sp
michael@13: Output generated on \fIstdout\fR and \fIstderr\fR 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 \fIstderr\fR. If the section
michael@13: is tagged with option \fB\-o\fR, \fIstdout\fR messages are passed through
michael@13: verbatim, even if the section script exists with a zero return value.
michael@13: .RS 4
michael@428: .ie n .IP "%start [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .el .IP "\f(CW%start\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .IX Item "%start [-u user] [-p priority]"
michael@13: This section should start daemons or initialize components.
michael@13: It is especially executed by \fBOpenPKG\fR during system startup.
michael@428: .ie n .IP "%stop [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .el .IP "\f(CW%stop\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .IX Item "%stop [-u user] [-p priority]"
michael@13: This section should stop daemons or cleaning up components. It is
michael@13: especially executed by \fBOpenPKG\fR during system shutdown and package
michael@13: deinstallation.
michael@428: .ie n .IP "%restart [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .el .IP "\f(CW%restart\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .IX Item "%restart [-u user] [-p priority]"
michael@13: This section should restart daemons.
michael@13: It is especially executed by \fBOpenPKG\fR during package upgrades.
michael@428: .ie n .IP "\*(C`%status \-o\*(C' [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .el .IP "\f(CW\*(C`%status \-o\*(C'\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .IX Item "%status -o [-u user] [-p priority]"
michael@13: This section has to provide status information for a package
michael@13: by printing to \f(CW\*(C`stdout\*(C'\fR (hence the \fB\-o\fR option is always required),
michael@13: in Bourne-Shell syntax, the definition of three variables:
michael@13: .RS 4
michael@13: .ie n .IP "\fIpackage\fR\*(C`_enable\*(C'" 4
michael@13: .el .IP "\fIpackage\fR\f(CW\*(C`_enable\*(C'\fR" 4
michael@13: .IX Item "package_enable"
michael@428: 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: .ie n .IP "\fIpackage\fR\*(C`_usable\*(C'" 4
michael@13: .el .IP "\fIpackage\fR\f(CW\*(C`_usable\*(C'\fR" 4
michael@13: .IX Item "package_usable"
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: .ie n .IP "\fIpackage\fR\*(C`_active\*(C'" 4
michael@13: .el .IP "\fIpackage\fR\f(CW\*(C`_active\*(C'\fR" 4
michael@13: .IX Item "package_active"
michael@13: Whether package is active, i.e., whether it is already running.
michael@13: This variable has to be individually determined.
michael@13: .RE
michael@13: .RS 4
michael@13: .RE
michael@428: .ie n .IP "%monthly [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .el .IP "\f(CW%monthly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .IX Item "%monthly [-u user] [-p priority]"
michael@13: .PD 0
michael@428: .ie n .IP "%weekly [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .el .IP "\f(CW%weekly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .IX Item "%weekly [-u user] [-p priority]"
michael@428: .ie n .IP "%hourly [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .el .IP "\f(CW%hourly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .IX Item "%hourly [-u user] [-p priority]"
michael@428: .ie n .IP "%quarterly [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .el .IP "\f(CW%quarterly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
michael@13: .IX Item "%quarterly [-u user] [-p priority]"
michael@13: .PD
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: .ie n .IP "%env" 4
michael@13: .el .IP "\f(CW%env\fR" 4
michael@13: .IX Item "%env"
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: \&\fB\-\-eval\fR command line option.
michael@13: .RE
michael@13: .RS 4
michael@13: .RE
michael@13: .IP "\fBCustom Sections\fR" 4
michael@13: .IX Item "Custom Sections"
michael@13: All other sections are custom ones and can be fully individual to each
michael@13: package. Some often seen sections are \f(CW%reload\fR (just reload the
michael@13: configuration without full stop and start procedure), \f(CW%info\fR (output
michael@13: arbitrary information about package), etc.
michael@428: .ie n .SS "RUN-COMMAND \s-1CONFIGURATION\s0 (\*(C`@l_prefix@/bin/openpkg rc.conf\*(C')"
michael@428: .el .SS "RUN-COMMAND \s-1CONFIGURATION\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.conf\*(C'\fP)"
michael@13: .IX Subsection "RUN-COMMAND CONFIGURATION (@l_prefix@/bin/openpkg rc.conf)"
michael@13: The run-command configuration variables defined in the "\f(CW%config\fR"
michael@13: sections of all installed packages can be overridden by the
michael@13: administrator in the global file \f(CW\*(C`@l_prefix@/bin/openpkg rc.conf\*(C'\fR. This file is
michael@13: usually empty, but can be filled with Bourne-Shell compatible variable
michael@13: assignment statements like "\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIvariable\fR=\fIvalue\fR".
michael@428: .ie n .SS "RUN-COMMAND \s-1FUNCTIONS\s0 (\*(C`@l_prefix@/bin/openpkg rc.func\*(C')"
michael@428: .el .SS "RUN-COMMAND \s-1FUNCTIONS\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.func\*(C'\fP)"
michael@13: .IX Subsection "RUN-COMMAND FUNCTIONS (@l_prefix@/bin/openpkg rc.func)"
michael@13: The file \f(CW\*(C`@l_prefix@/bin/openpkg rc.func\*(C'\fR 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: .IP "\fBrcMsg\fR [\fB\-e\fR] [\fB\-w\fR] \fImessage\fR" 4
michael@13: .IX Item "rcMsg [-e] [-w] message"
michael@13: Print a message to the output device of the run-command caller. The
michael@13: message is printed to the captured \fIstderr\fR (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 "\f(CW\*(C`rc:\*(C'\fR". If option \fB\-e\fR is given, the
michael@13: prefix is "\f(CW\*(C`rc:ERROR:\*(C'\fR". If option \fB\-w\fR is given, the prefix is
michael@13: "\f(CW\*(C`rc:WARNING:\*(C'\fR".
michael@13: .IP "\fBrcPath\fR [\fB\-a\fR] [\fB\-r\fR] [\fB\-p\fR] [\fB\-e\fR] \fIvariable\fR \fIdir\fR [\fIdir\fR ...]" 4
michael@13: .IX Item "rcPath [-a] [-r] [-p] [-e] variable dir [dir ...]"
michael@13: Add (option \fB\-a\fR) or remove (option \fB\-r\fR) one or more \fIdir\fRectories
michael@13: to/from the colon-separated value of a \fIvar\fRable. By default, on
michael@13: addition, the directory is appended to the end, if option \fB\-p\fR is used
michael@13: the directory is prepended to the start. If option \fB\-e\fR is used, the
michael@13: directories are added only if they exist on the underlying filesystem.
michael@13: Use this function for conveniently manipulating \f(CW\*(C`PATH\*(C'\fR, \f(CW\*(C`MANPATH\*(C'\fR,
michael@13: \&\f(CW\*(C`INFOPATH\*(C'\fR, \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR and similar variables.
michael@13: .IP "\fBrcTmp\fR [\fB\-i\fR] [\fB\-f\fR] [\fB\-n\fR \fIname\fR] [\fB\-k\fR]" 4
michael@13: .IX Item "rcTmp [-i] [-f] [-n name] [-k]"
michael@13: Convenience interface to secure temporary file handling. Option \fB\-i\fR
michael@13: first has to be used to initialize a secure temporary directory (option
michael@13: \&\fB\-k\fR later will kill this again). Under option \fB\-f\fR you then can get
michael@13: reasonable temporary filenames under the created temporary directory. By
michael@13: default, the temporary filename is just "\f(CW\*(C`tmp\*(C'\fR", but can be specified
michael@13: with option \fB\-n\fR to be \fIname\fR.
michael@13: .IP "\fBrcService\fR \fIpackage\fR \fIstatus\fR \fIvalue\fR" 4
michael@13: .IX Item "rcService package status value"
michael@13: Convenience interface to checking the \f(CW%status\fR variables
michael@13: \&\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIstatus\fR which have to be provided by the \f(CW%config\fR (if
michael@13: \&\fIstatus\fR is "\f(CW\*(C`enable\*(C'\fR" this is enough) and \f(CW%status\fR (if \fIstatus\fR is
michael@13: "\f(CW\*(C`enable\*(C'\fR\*(L", \*(R"\f(CW\*(C`usable\*(C'\fR\*(L" and \*(R"\f(CW\*(C`active\*(C'\fR"). The \fBrcService\fR especially
michael@13: caches the resolving of the variable values. Returns 0 if the resolved
michael@13: value is \fIvalue\fR, else returns 1.
michael@13: .IP "\fBrcVarIsYes\fR \fIname\fR" 4
michael@13: .IX Item "rcVarIsYes name"
michael@13: Checks whether variable \fIname\fR has a value of "\f(CW\*(C`yes\*(C'\fR\*(L", \*(R"\f(CW\*(C`true\*(C'\fR\*(L",
michael@13: \&\*(R"\f(CW\*(C`on\*(C'\fR\*(L", or \*(R"\f(CW1\fR" (with arbitrary lower or upper case letters). Returns
michael@13: 0 if value is one of these positive ones, else returns 1.
michael@13: .SH "EXAMPLES"
michael@13: .IX Header "EXAMPLES"
michael@13: First, an example run-command script \f(CW\*(C`@l_prefix@/bin/openpkg rc.d/rc.foo\*(C'\fR for a
michael@13: fictional daemon package "\f(CW\*(C`foo\*(C'\fR":
michael@13: .PP
michael@13: .Vb 8
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@428: \&
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@428: \&        if [ \-f ${foo_pidfile} ]; then
michael@428: \&            kill \-$1 \`cat ${foo_pidfile}\`
michael@13: \&            return $?
michael@13: \&        else
michael@13: \&            return 1
michael@13: \&        fi
michael@13: \&    }
michael@428: \&
michael@13: \& %status
michael@13: \&     foo_usable="no"
michael@428: \&     if [ ".\`grep \*(Aq<<PASSWORD>>\*(Aq ${foo_cfgfile}\`" = . ]; then
michael@13: \&         foo_usable="yes"
michael@13: \&     fi
michael@13: \&     foo_active="no"
michael@428: \&     if [ \-f ${foo_pidfile} ]; then
michael@13: \&         foo_signal 0
michael@428: \&         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@428: \&
michael@13: \& %start
michael@13: \&     rcService foo enable yes || exit 0
michael@13: \&     rcService foo active yes && exit 0
michael@428: \&     @l_prefix@/sbin/foo \-\-listen ${foo_listen}
michael@428: \&
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@428: \&
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@428: \&
michael@13: \& %daily
michael@13: \&     rcService foo enable yes || exit 0
michael@428: \&     shtool rotate \-f \e
michael@428: \&         \-n ${foo_log_numfiles} \-s ${foo_log_minsize} \-d \e
michael@428: \&         \-z ${foo_log_complevel} \-o @l_rusr@ \-g @l_rgrp@ \-m 644 \e
michael@428: \&         \-P "${foo_log_prolog}" \-E "${foo_log_epilog}" \e
michael@13: \&         ${foo_logfile}
michael@428: \&
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: .Ve
michael@13: .PP
michael@13: Now, show all run-command configuration variables, their
michael@13: default values and their effective values of package "\f(CW\*(C`foo\*(C'\fR":
michael@13: .PP
michael@13: .Vb 1
michael@428: \& $ @l_prefix@/bin/openpkg rc \-\-config | grep "^foo_"
michael@13: .Ve
michael@13: .PP
michael@13: Override the default value of a run-command configuration
michael@13: variable \f(CW\*(C`foo_listen\*(C'\fR:
michael@13: .PP
michael@13: .Vb 1
michael@428: \& $ echo \*(Aqfoo_listen="192.168.0.1"\*(Aq >>@l_prefix@/bin/openpkg rc.conf
michael@13: .Ve
michael@13: .PP
michael@13: Stop and start from scratch the package "\f(CW\*(C`foo\*(C'\fR":
michael@13: .PP
michael@13: .Vb 1
michael@13: \& $ @l_prefix@/bin/openpkg rc foo stop start
michael@13: .Ve
michael@13: .PP
michael@13: Query the effective value of run-command configuration
michael@13: variable \f(CW\*(C`foo_enable\*(C'\fR in a script:
michael@13: .PP
michael@13: .Vb 1
michael@428: \& if [ ".\`@l_prefix@/bin/openpkg rc \-q foo_enable\`" = .yes ]; then ...
michael@13: .Ve
michael@13: .PP
michael@13: Import all environment settings from all (including "\f(CW\*(C`foo\*(C'\fR") installed
michael@13: packages into the current Bourne-Shell environment:
michael@13: .PP
michael@13: .Vb 2
michael@428: \& $ eval \`@l_prefix@/bin/openpkg rc \-\-eval all env\`
michael@13: \& $ echo $FOO_HOME
michael@13: .Ve
michael@13: .SH "SEE ALSO"
michael@13: .IX Header "SEE ALSO"
michael@13: \&\fBOpenPKG\fR http://www.openpkg.org/
michael@13: .SH "HISTORY"
michael@13: .IX Header "HISTORY"
michael@13: The \fBOpenPKG\fR run-command facility consisting of the scripts \f(CW\*(C`rc\*(C'\fR
michael@13: and \f(CW\*(C`rc.func\*(C'\fR were originally invented in November 2000 by Ralf S.
michael@13: Engelschall for \fBOpenPKG\fR. They were completely worked off from scratch
michael@13: in July 2003 for \fBOpenPKG 1.3\fR.
michael@13: .SH "AUTHOR"
michael@13: .IX Header "AUTHOR"
michael@13: .Vb 3
michael@13: \& Ralf S. Engelschall
michael@13: \& rse@engelschall.com
michael@13: \& www.engelschall.com
michael@13: .Ve