1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/rc.8 Tue Jan 06 23:40:39 2009 +0100
1.3 @@ -0,0 +1,533 @@
1.4 +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
1.5 +.\"
1.6 +.\" Standard preamble:
1.7 +.\" ========================================================================
1.8 +.de Sh \" Subsection heading
1.9 +.br
1.10 +.if t .Sp
1.11 +.ne 5
1.12 +.PP
1.13 +\fB\\$1\fR
1.14 +.PP
1.15 +..
1.16 +.de Sp \" Vertical space (when we can't use .PP)
1.17 +.if t .sp .5v
1.18 +.if n .sp
1.19 +..
1.20 +.de Vb \" Begin verbatim text
1.21 +.ft CW
1.22 +.nf
1.23 +.ne \\$1
1.24 +..
1.25 +.de Ve \" End verbatim text
1.26 +.ft R
1.27 +.fi
1.28 +..
1.29 +.\" Set up some character translations and predefined strings. \*(-- will
1.30 +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
1.31 +.\" double quote, and \*(R" will give a right double quote. | will give a
1.32 +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
1.33 +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
1.34 +.\" expand to `' in nroff, nothing in troff, for use with C<>.
1.35 +.tr \(*W-|\(bv\*(Tr
1.36 +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
1.37 +.ie n \{\
1.38 +. ds -- \(*W-
1.39 +. ds PI pi
1.40 +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
1.41 +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
1.42 +. ds L" ""
1.43 +. ds R" ""
1.44 +. ds C`
1.45 +. ds C'
1.46 +'br\}
1.47 +.el\{\
1.48 +. ds -- \|\(em\|
1.49 +. ds PI \(*p
1.50 +. ds L" ``
1.51 +. ds R" ''
1.52 +'br\}
1.53 +.\"
1.54 +.\" If the F register is turned on, we'll generate index entries on stderr for
1.55 +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
1.56 +.\" entries marked with X<> in POD. Of course, you'll have to process the
1.57 +.\" output yourself in some meaningful fashion.
1.58 +.if \nF \{\
1.59 +. de IX
1.60 +. tm Index:\\$1\t\\n%\t"\\$2"
1.61 +..
1.62 +. nr % 0
1.63 +. rr F
1.64 +.\}
1.65 +.\"
1.66 +.\" For nroff, turn off justification. Always turn off hyphenation; it makes
1.67 +.\" way too many mistakes in technical documents.
1.68 +.hy 0
1.69 +.if n .na
1.70 +.\"
1.71 +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
1.72 +.\" Fear. Run. Save yourself. No user-serviceable parts.
1.73 +. \" fudge factors for nroff and troff
1.74 +.if n \{\
1.75 +. ds #H 0
1.76 +. ds #V .8m
1.77 +. ds #F .3m
1.78 +. ds #[ \f1
1.79 +. ds #] \fP
1.80 +.\}
1.81 +.if t \{\
1.82 +. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
1.83 +. ds #V .6m
1.84 +. ds #F 0
1.85 +. ds #[ \&
1.86 +. ds #] \&
1.87 +.\}
1.88 +. \" simple accents for nroff and troff
1.89 +.if n \{\
1.90 +. ds ' \&
1.91 +. ds ` \&
1.92 +. ds ^ \&
1.93 +. ds , \&
1.94 +. ds ~ ~
1.95 +. ds /
1.96 +.\}
1.97 +.if t \{\
1.98 +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
1.99 +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
1.100 +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
1.101 +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
1.102 +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
1.103 +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
1.104 +.\}
1.105 +. \" troff and (daisy-wheel) nroff accents
1.106 +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
1.107 +.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
1.108 +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
1.109 +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
1.110 +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
1.111 +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
1.112 +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
1.113 +.ds ae a\h'-(\w'a'u*4/10)'e
1.114 +.ds Ae A\h'-(\w'A'u*4/10)'E
1.115 +. \" corrections for vroff
1.116 +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
1.117 +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
1.118 +. \" for low resolution devices (crt and lpr)
1.119 +.if \n(.H>23 .if \n(.V>19 \
1.120 +\{\
1.121 +. ds : e
1.122 +. ds 8 ss
1.123 +. ds o a
1.124 +. ds d- d\h'-1'\(ga
1.125 +. ds D- D\h'-1'\(hy
1.126 +. ds th \o'bp'
1.127 +. ds Th \o'LP'
1.128 +. ds ae ae
1.129 +. ds Ae AE
1.130 +.\}
1.131 +.rm #[ #] #H #V #F C
1.132 +.\" ========================================================================
1.133 +.\"
1.134 +.IX Title "RC 8"
1.135 +.TH RC 8 "OpenPKG" "RC(8)" "OpenPKG"
1.136 +.SH "NAME"
1.137 +\&\fB@l_prefix@/bin/openpkg rc\fR \- OpenPKG Run\-Command Processor
1.138 +.SH "SYNOPSIS"
1.139 +.IX Header "SYNOPSIS"
1.140 +\&\fB@l_prefix@/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] \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]
1.141 +.PP
1.142 +\&\fB@l_prefix@/bin/openpkg rc\fR \fB\-p\fR|\fB\-\-print\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]
1.143 +.PP
1.144 +eval `\fB@l_prefix@/bin/openpkg rc\fR \fB\-e\fR|\fB\-\-eval\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]`
1.145 +.PP
1.146 +\&\fB@l_prefix@/bin/openpkg rc\fR \fB\-q\fR|\fB\-\-query\fR \fIvariable\fR [\fIvariable\fR ...]
1.147 +.PP
1.148 +\&\fB@l_prefix@/bin/openpkg rc\fR \fB\-c\fR|\fB\-\-config\fR
1.149 +.PP
1.150 +\&\fB@l_prefix@/bin/openpkg rc\fR \fB\-h\fR|\fB\-\-help\fR
1.151 +.SH "DESCRIPTION"
1.152 +.IX Header "DESCRIPTION"
1.153 +The \fB@l_prefix@/bin/openpkg rc\fR program is the run-command (rc) processor
1.154 +of the \fBOpenPKG\fR instance \f(CW\*(C`@l_prefix@\*(C'\fR. It allows querying the rc
1.155 +configuration variables and the execution of rc command scripts of one
1.156 +or more installed \fBOpenPKG\fR packages. The implemented run-command
1.157 +facility is partly modeled after the classical \s-1UNIX\s0(tm) System V
1.158 +run-command facility plus ideas taken from the FreeBSD and NetBSD
1.159 +run-command facilities. It mainly merges the classical startup/shutdown
1.160 +procedures with periodical procedures into a single approach.
1.161 +.SH "USAGE"
1.162 +.IX Header "USAGE"
1.163 +.IP "\fB@l_prefix@/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] \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4
1.164 +.IX Item "@l_prefix@/bin/openpkg rc [-s|--silent] [-v|--verbose] [-d|--debug] [-k|--keep] package command [command ...]"
1.165 +\&\fBRun-Command Execution.\fR This executes one or more specified
1.166 +\&\fIcommand\fRs in a particular \fIpackage\fR or in all installed packages if
1.167 +\&\fIpackage\fR is "\f(CW\*(C`all\*(C'\fR". Option \fB\-\-silent\fR can be used to explicitly
1.168 +disable progress messages on \f(CW\*(C`stderr\*(C'\fR. Option \fB\-\-verbose\fR can be used
1.169 +to explicitly enable progress messages on \f(CW\*(C`stderr\*(C'\fR. By default, \fBrc\fR
1.170 +automatically determines whether progress messages should be displayed
1.171 +or not depending on whether \f(CW\*(C`stderr\*(C'\fR is connected to a terminal device.
1.172 +Option \fB\-\-keep\fR can be used for debugging purposes to keep the
1.173 +temporary files were generated during internal processing.
1.174 +.IP "\fB@l_prefix@/bin/openpkg rc\fR \fB\-p\fR|\fB\-\-print\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]" 4
1.175 +.IX Item "@l_prefix@/bin/openpkg rc -p|--print package command [command ...]"
1.176 +\&\fBRun-Command Printing.\fR This is like the run-command execution (see
1.177 +above), but instead of immediately executing all involved individual
1.178 +run-command scripts, they are concatenated (but with all configuration
1.179 +parts reduced to a single configuration part) and printed to \f(CW\*(C`stdout\*(C'\fR.
1.180 +Use this for debugging or post-processing purposes.
1.181 +.IP "eval `\fB@l_prefix@/bin/openpkg rc\fR \fB\-e\fR|\fB\-\-eval\fR \fIpackage\fR \fIcommand\fR [\fIcommand\fR ...]`" 4
1.182 +.IX Item "eval `@l_prefix@/bin/openpkg rc -e|--eval package command [command ...]`"
1.183 +\&\fBRun-Command Evaluation.\fR This is like the run-command execution
1.184 +(see above), but the resulting exported shell environment variables
1.185 +are output to a temporary file as a (Bourne\-Shell or C\-Shell syntax)
1.186 +shell script, suitable for evaluation within the shell environment
1.187 +of the caller. A one-line script is printed to \f(CW\*(C`stdout\*(C'\fR which then
1.188 +\&\*(L"sources\*(R" (and immediately removes) this temporary file. This is
1.189 +slightly different from printing the temporary script directly to
1.190 +\&\f(CW\*(C`stdout\*(C'\fR, because not all shell implementations like to "\fBeval\fR\*(L"
1.191 +large multi-line scripts. Hence, use this for executing the \*(R"\f(CW\*(C`env\*(C'\fR"
1.192 +run-commands within the current shell.
1.193 +.IP "\fB@l_prefix@/bin/openpkg rc\fR \fB\-q\fR|\fB\-\-query\fR \fIvariable\fR [\fIvariable\fR ...]" 4
1.194 +.IX Item "@l_prefix@/bin/openpkg rc -q|--query variable [variable ...]"
1.195 +\&\fBConfiguration Variable Querying.\fR This queries the effective values
1.196 +(see \fBRUN-COMMAND \s-1CONFIGURATION\s0\fR section below) of one or more
1.197 +run-command configuration \fIvariable\fRs. Use this within a shell script
1.198 +to selectively query a particular variable.
1.199 +.IP "\fB@l_prefix@/bin/openpkg rc\fR \fB\-c\fR|\fB\-\-config\fR" 4
1.200 +.IX Item "@l_prefix@/bin/openpkg rc -c|--config"
1.201 +\&\fBConfiguration Variable Summary.\fR This displays on \f(CW\*(C`stdout\*(C'\fR a
1.202 +three-column table showing the name, default and effective values of
1.203 +all run-command configuration variables. If \f(CW\*(C`stdout\*(C'\fR is connected to
1.204 +terminal device, variables where the default and effective values differ
1.205 +are shown in bold mode.
1.206 +.IP "\fB@l_prefix@/bin/openpkg rc\fR \fB\-h\fR|\fB\-\-help\fR" 4
1.207 +.IX Item "@l_prefix@/bin/openpkg rc -h|--help"
1.208 +\&\fBRequesting Help.\fR This just displays a short summary of
1.209 +the usage for this program.
1.210 +.SH "FILES"
1.211 +.IX Header "FILES"
1.212 +.ie n .Sh "RUN-COMMAND \s-1FILES\s0 (\*(C`@l_prefix@/bin/openpkg rc.d/rc.*\*(C')"
1.213 +.el .Sh "RUN-COMMAND \s-1FILES\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.d/rc.*\*(C'\fP)"
1.214 +.IX Subsection "RUN-COMMAND FILES (@l_prefix@/bin/openpkg rc.d/rc.*)"
1.215 +The foundation of the \fBOpenPKG\fR run-command facility are the individual
1.216 +run-command files \f(CW\*(C`rc.*\*(C'\fR of the installed packages. They are all
1.217 +located in the directory \f(CW\*(C`@l_prefix@/bin/openpkg rc.d/\*(C'\fR and are named
1.218 +"\f(CW\*(C`rc.\*(C'\fR\fIpackage\fR\*(L". They consist of one or more sections, each starting
1.219 +with a section header \*(R"\f(CW\*(C`%\*(C'\fR\fIname\fR [\fIoptions\fR]" and following a \s-1GNU\s0
1.220 +Bash compatible shell script. There are three classes of sections:
1.221 +.IP "\fBSpecial Sections\fR" 4
1.222 +.IX Item "Special Sections"
1.223 +There are 2 sections which have a special meaning to the \fBrc\fR program
1.224 +and cannot be used for different purposes.
1.225 +.RS 4
1.226 +.ie n .IP "%config" 4
1.227 +.el .IP "\f(CW%config\fR" 4
1.228 +.IX Item "%config"
1.229 +This section has to consist of run-command configuration
1.230 +variable default settings in Bourne-Shell syntax only, i.e.,
1.231 +it has to contain one or more lines, each of exactly the form
1.232 +"\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIvariable\fR\f(CW\*(C`=\*(C'\fR\fIvalue\fR\*(L". Notice that in section
1.233 +\&\*(R"\f(CW%config\fR\*(L" of run-command file \*(R"\f(CW\*(C`rc.foo\*(C'\fR\*(L" the variables all have
1.234 +to be prefixed (by convention) with \*(R"\f(CW\*(C`foo_\*(C'\fR". It is allowed that the
1.235 +\&\fIvalue\fRs reference other variables defined before in the same section
1.236 +or from the "\f(CW%config\fR\*(L" section of the bootstrap package \*(R"\f(CW\*(C`openpkg\*(C'\fR".
1.237 +Additionally, by convention all lines have to be indented by 4 spaces.
1.238 +.Sp
1.239 +\&\s-1NOTICE:\s0 All sections of all run-command scripts see all \f(CW%config\fR
1.240 +sections of all packages.
1.241 +.ie n .IP "%common" 4
1.242 +.el .IP "\f(CW%common\fR" 4
1.243 +.IX Item "%common"
1.244 +This section can consist of an arbitrary shell script
1.245 +which is automatically prepended to the shell scripts
1.246 +of all other sections on execution. It is usually used
1.247 +to define common and local variables and functions.
1.248 +.RE
1.249 +.RS 4
1.250 +.RE
1.251 +.IP "\fBConventional Sections\fR" 4
1.252 +.IX Item "Conventional Sections"
1.253 +There are 9 sections which have no special meaning to the \fBrc\fR program,
1.254 +but are used in \fBOpenPKG\fR by convention for standard purposes. Hence,
1.255 +do not use them for arbitrary things instead.
1.256 +.Sp
1.257 +Throughout these sections it is possible to specify the user to be
1.258 +switched to before the code is executed.
1.259 +.Sp
1.260 +A priority can be given for each section to control execution sequence
1.261 +if "\f(CW\*(C`all\*(C'\fR" packages are given. Higher priority leads to earlier
1.262 +starting and later stopping. The priority is a number where low numbers
1.263 +mean high priority (numerically sorted for starting). If omitted, the
1.264 +priority defaults to 500.
1.265 +.Sp
1.266 +Output generated on \fIstdout\fR and \fIstderr\fR is captured and normally
1.267 +suppressed. In case the sections script exits with a non-zero return
1.268 +value, the intercepted messages are consolidated, reformatted with a
1.269 +surrounding ASCII-art border and printed to \fIstderr\fR. If the section
1.270 +is tagged with option \fB\-o\fR, \fIstdout\fR messages are passed through
1.271 +verbatim, even if the section script exists with a zero return value.
1.272 +.RS 4
1.273 +.ie n .IP "%start\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority]" 4
1.274 +.el .IP "\f(CW%start\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
1.275 +.IX Item "%start [-u user] [-p priority]"
1.276 +This section should start daemons or initialize components.
1.277 +It is especially executed by \fBOpenPKG\fR during system startup.
1.278 +.ie n .IP "%stop\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority]" 4
1.279 +.el .IP "\f(CW%stop\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
1.280 +.IX Item "%stop [-u user] [-p priority]"
1.281 +This section should stop daemons or cleaning up components. It is
1.282 +especially executed by \fBOpenPKG\fR during system shutdown and package
1.283 +deinstallation.
1.284 +.ie n .IP "%restart\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority]" 4
1.285 +.el .IP "\f(CW%restart\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
1.286 +.IX Item "%restart [-u user] [-p priority]"
1.287 +This section should restart daemons.
1.288 +It is especially executed by \fBOpenPKG\fR during package upgrades.
1.289 +.ie n .IP "\*(C`%status \-o\*(C'\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority]" 4
1.290 +.el .IP "\f(CW\*(C`%status \-o\*(C'\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
1.291 +.IX Item "%status -o [-u user] [-p priority]"
1.292 +This section has to provide status information for a package
1.293 +by printing to \f(CW\*(C`stdout\*(C'\fR (hence the \fB\-o\fR option is always required),
1.294 +in Bourne-Shell syntax, the definition of three variables:
1.295 +.RS 4
1.296 +.ie n .IP "\fIpackage\fR\*(C`_enable\*(C'" 4
1.297 +.el .IP "\fIpackage\fR\f(CW\*(C`_enable\*(C'\fR" 4
1.298 +.IX Item "package_enable"
1.299 +Whether package is enabled, i.e., whether it accepts run\-commands. This
1.300 +variable just has to be printed, because is already set in current
1.301 +script environment.
1.302 +.ie n .IP "\fIpackage\fR\*(C`_usable\*(C'" 4
1.303 +.el .IP "\fIpackage\fR\f(CW\*(C`_usable\*(C'\fR" 4
1.304 +.IX Item "package_usable"
1.305 +Whether package is usable, i.e., whether it is already correctly
1.306 +configured, etc. This variable has to be individually determined.
1.307 +.ie n .IP "\fIpackage\fR\*(C`_active\*(C'" 4
1.308 +.el .IP "\fIpackage\fR\f(CW\*(C`_active\*(C'\fR" 4
1.309 +.IX Item "package_active"
1.310 +Whether package is active, i.e., whether it is already running.
1.311 +This variable has to be individually determined.
1.312 +.RE
1.313 +.RS 4
1.314 +.RE
1.315 +.ie n .IP "%monthly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority]" 4
1.316 +.el .IP "\f(CW%monthly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
1.317 +.IX Item "%monthly [-u user] [-p priority]"
1.318 +.PD 0
1.319 +.ie n .IP "%weekly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority]" 4
1.320 +.el .IP "\f(CW%weekly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
1.321 +.IX Item "%weekly [-u user] [-p priority]"
1.322 +.ie n .IP "%hourly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority]" 4
1.323 +.el .IP "\f(CW%hourly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
1.324 +.IX Item "%hourly [-u user] [-p priority]"
1.325 +.ie n .IP "%quarterly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority]" 4
1.326 +.el .IP "\f(CW%quarterly\fR [\fB\-u\fR \fIuser\fR] [\fB\-p\fR \fIpriority\fR]" 4
1.327 +.IX Item "%quarterly [-u user] [-p priority]"
1.328 +.PD
1.329 +These sections should perform periodical tasks for a package and
1.330 +are executed on a monthly, weekly, hourly or quarterly basis.
1.331 +.ie n .IP "%env" 4
1.332 +.el .IP "\f(CW%env\fR" 4
1.333 +.IX Item "%env"
1.334 +This section is intended to export one or more environment variables
1.335 +which are imported into the shell environment of the caller through the
1.336 +\&\fB\-\-eval\fR command line option.
1.337 +.RE
1.338 +.RS 4
1.339 +.RE
1.340 +.IP "\fBCustom Sections\fR" 4
1.341 +.IX Item "Custom Sections"
1.342 +All other sections are custom ones and can be fully individual to each
1.343 +package. Some often seen sections are \f(CW%reload\fR (just reload the
1.344 +configuration without full stop and start procedure), \f(CW%info\fR (output
1.345 +arbitrary information about package), etc.
1.346 +.ie n .Sh "RUN-COMMAND \s-1CONFIGURATION\s0 (\*(C`@l_prefix@/bin/openpkg rc.conf\*(C')"
1.347 +.el .Sh "RUN-COMMAND \s-1CONFIGURATION\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.conf\*(C'\fP)"
1.348 +.IX Subsection "RUN-COMMAND CONFIGURATION (@l_prefix@/bin/openpkg rc.conf)"
1.349 +The run-command configuration variables defined in the "\f(CW%config\fR"
1.350 +sections of all installed packages can be overridden by the
1.351 +administrator in the global file \f(CW\*(C`@l_prefix@/bin/openpkg rc.conf\*(C'\fR. This file is
1.352 +usually empty, but can be filled with Bourne-Shell compatible variable
1.353 +assignment statements like "\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIvariable\fR=\fIvalue\fR".
1.354 +.ie n .Sh "RUN-COMMAND \s-1FUNCTIONS\s0 (\*(C`@l_prefix@/bin/openpkg rc.func\*(C')"
1.355 +.el .Sh "RUN-COMMAND \s-1FUNCTIONS\s0 (\f(CW\*(C`@l_prefix@/bin/openpkg rc.func\*(C'\fP)"
1.356 +.IX Subsection "RUN-COMMAND FUNCTIONS (@l_prefix@/bin/openpkg rc.func)"
1.357 +The file \f(CW\*(C`@l_prefix@/bin/openpkg rc.func\*(C'\fR is prepended to the scripts of all
1.358 +executed run-command sections and provides reusable functions.
1.359 +Currently the following functions are defined:
1.360 +.IP "\fBrcMsg\fR [\fB\-e\fR] [\fB\-w\fR] \fImessage\fR" 4
1.361 +.IX Item "rcMsg [-e] [-w] message"
1.362 +Print a message to the output device of the run-command caller. The
1.363 +message is printed to the captured \fIstderr\fR (but are visible to
1.364 +the caller of the run-command script only if the script fails). All
1.365 +messages are prefixed with "\f(CW\*(C`rc:\*(C'\fR". If option \fB\-e\fR is given, the
1.366 +prefix is "\f(CW\*(C`rc:ERROR:\*(C'\fR". If option \fB\-w\fR is given, the prefix is
1.367 +"\f(CW\*(C`rc:WARNING:\*(C'\fR".
1.368 +.IP "\fBrcPath\fR [\fB\-a\fR] [\fB\-r\fR] [\fB\-p\fR] [\fB\-e\fR] \fIvariable\fR \fIdir\fR [\fIdir\fR ...]" 4
1.369 +.IX Item "rcPath [-a] [-r] [-p] [-e] variable dir [dir ...]"
1.370 +Add (option \fB\-a\fR) or remove (option \fB\-r\fR) one or more \fIdir\fRectories
1.371 +to/from the colon-separated value of a \fIvar\fRable. By default, on
1.372 +addition, the directory is appended to the end, if option \fB\-p\fR is used
1.373 +the directory is prepended to the start. If option \fB\-e\fR is used, the
1.374 +directories are added only if they exist on the underlying filesystem.
1.375 +Use this function for conveniently manipulating \f(CW\*(C`PATH\*(C'\fR, \f(CW\*(C`MANPATH\*(C'\fR,
1.376 +\&\f(CW\*(C`INFOPATH\*(C'\fR, \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR and similar variables.
1.377 +.IP "\fBrcTmp\fR [\fB\-i\fR] [\fB\-f\fR] [\fB\-n\fR \fIname\fR] [\fB\-k\fR]" 4
1.378 +.IX Item "rcTmp [-i] [-f] [-n name] [-k]"
1.379 +Convenience interface to secure temporary file handling. Option \fB\-i\fR
1.380 +first has to be used to initialize a secure temporary directory (option
1.381 +\&\fB\-k\fR later will kill this again). Under option \fB\-f\fR you then can get
1.382 +reasonable temporary filenames under the created temporary directory. By
1.383 +default, the temporary filename is just "\f(CW\*(C`tmp\*(C'\fR", but can be specified
1.384 +with option \fB\-n\fR to be \fIname\fR.
1.385 +.IP "\fBrcService\fR \fIpackage\fR \fIstatus\fR \fIvalue\fR" 4
1.386 +.IX Item "rcService package status value"
1.387 +Convenience interface to checking the \f(CW%status\fR variables
1.388 +\&\fIpackage\fR\f(CW\*(C`_\*(C'\fR\fIstatus\fR which have to be provided by the \f(CW%config\fR (if
1.389 +\&\fIstatus\fR is "\f(CW\*(C`enable\*(C'\fR" this is enough) and \f(CW%status\fR (if \fIstatus\fR is
1.390 +"\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
1.391 +caches the resolving of the variable values. Returns 0 if the resolved
1.392 +value is \fIvalue\fR, else returns 1.
1.393 +.IP "\fBrcVarIsYes\fR \fIname\fR" 4
1.394 +.IX Item "rcVarIsYes name"
1.395 +Checks whether variable \fIname\fR has a value of "\f(CW\*(C`yes\*(C'\fR\*(L", \*(R"\f(CW\*(C`true\*(C'\fR\*(L",
1.396 +\&\*(R"\f(CW\*(C`on\*(C'\fR\*(L", or \*(R"\f(CW1\fR" (with arbitrary lower or upper case letters). Returns
1.397 +0 if value is one of these positive ones, else returns 1.
1.398 +.SH "EXAMPLES"
1.399 +.IX Header "EXAMPLES"
1.400 +First, an example run-command script \f(CW\*(C`@l_prefix@/bin/openpkg rc.d/rc.foo\*(C'\fR for a
1.401 +fictional daemon package "\f(CW\*(C`foo\*(C'\fR":
1.402 +.PP
1.403 +.Vb 8
1.404 +\& %config
1.405 +\& foo_enable="${openpkg_rc_def}"
1.406 +\& foo_listen="127.0.0.1"
1.407 +\& foo_log_prolog="true"
1.408 +\& foo_log_epilog="true"
1.409 +\& foo_log_numfiles="10"
1.410 +\& foo_log_minsize="1M"
1.411 +\& foo_log_complevel="9"
1.412 +.Ve
1.413 +.PP
1.414 +.Vb 13
1.415 +\& %common
1.416 +\& foo_homedir="@l_prefix@/share/foo"
1.417 +\& foo_cfgfile="@l_prefix@/etc/foo/foo.cfg"
1.418 +\& foo_pidfile="@l_prefix@/var/foo/foo.pid"
1.419 +\& foo_logfile="@l_prefix@/var/foo/foo.log"
1.420 +\& foo_signal () {
1.421 +\& if [ -f ${foo_pidfile} ]; then
1.422 +\& kill -$1 `cat ${foo_pidfile}`
1.423 +\& return $?
1.424 +\& else
1.425 +\& return 1
1.426 +\& fi
1.427 +\& }
1.428 +.Ve
1.429 +.PP
1.430 +.Vb 15
1.431 +\& %status
1.432 +\& foo_usable="no"
1.433 +\& if [ ".`grep '<<PASSWORD>>' ${foo_cfgfile}`" = . ]; then
1.434 +\& foo_usable="yes"
1.435 +\& fi
1.436 +\& foo_active="no"
1.437 +\& if [ -f ${foo_pidfile} ]; then
1.438 +\& foo_signal 0
1.439 +\& if [ $? -eq 0 ]; then
1.440 +\& foo_active="yes"
1.441 +\& fi
1.442 +\& fi
1.443 +\& echo "foo_enable=${foo_enable}"
1.444 +\& echo "foo_usable=${foo_usable}"
1.445 +\& echo "foo_active=${foo_active}"
1.446 +.Ve
1.447 +.PP
1.448 +.Vb 4
1.449 +\& %start
1.450 +\& rcService foo enable yes || exit 0
1.451 +\& rcService foo active yes && exit 0
1.452 +\& @l_prefix@/sbin/foo --listen ${foo_listen}
1.453 +.Ve
1.454 +.PP
1.455 +.Vb 4
1.456 +\& %stop
1.457 +\& rcService foo enable yes || exit 0
1.458 +\& rcService foo active yes || exit 0
1.459 +\& foo_signal TERM
1.460 +.Ve
1.461 +.PP
1.462 +.Vb 4
1.463 +\& %restart
1.464 +\& rcService foo enable yes || exit 0
1.465 +\& rcService foo active yes || exit 0
1.466 +\& rc foo stop start
1.467 +.Ve
1.468 +.PP
1.469 +.Vb 7
1.470 +\& %daily
1.471 +\& rcService foo enable yes || exit 0
1.472 +\& shtool rotate -f \e
1.473 +\& -n ${foo_log_numfiles} -s ${foo_log_minsize} -d \e
1.474 +\& -z ${foo_log_complevel} -o @l_rusr@ -g @l_rgrp@ -m 644 \e
1.475 +\& -P "${foo_log_prolog}" -E "${foo_log_epilog}" \e
1.476 +\& ${foo_logfile}
1.477 +.Ve
1.478 +.PP
1.479 +.Vb 5
1.480 +\& %env
1.481 +\& if rcService foo enable yes; then
1.482 +\& FOO_HOME="$foo_homedir"
1.483 +\& export FOO_HOME
1.484 +\& fi
1.485 +.Ve
1.486 +.PP
1.487 +Now, show all run-command configuration variables, their
1.488 +default values and their effective values of package "\f(CW\*(C`foo\*(C'\fR":
1.489 +.PP
1.490 +.Vb 1
1.491 +\& $ @l_prefix@/bin/openpkg rc --config | grep "^foo_"
1.492 +.Ve
1.493 +.PP
1.494 +Override the default value of a run-command configuration
1.495 +variable \f(CW\*(C`foo_listen\*(C'\fR:
1.496 +.PP
1.497 +.Vb 1
1.498 +\& $ echo 'foo_listen="192.168.0.1"' >>@l_prefix@/bin/openpkg rc.conf
1.499 +.Ve
1.500 +.PP
1.501 +Stop and start from scratch the package "\f(CW\*(C`foo\*(C'\fR":
1.502 +.PP
1.503 +.Vb 1
1.504 +\& $ @l_prefix@/bin/openpkg rc foo stop start
1.505 +.Ve
1.506 +.PP
1.507 +Query the effective value of run-command configuration
1.508 +variable \f(CW\*(C`foo_enable\*(C'\fR in a script:
1.509 +.PP
1.510 +.Vb 1
1.511 +\& if [ ".`@l_prefix@/bin/openpkg rc -q foo_enable`" = .yes ]; then ...
1.512 +.Ve
1.513 +.PP
1.514 +Import all environment settings from all (including "\f(CW\*(C`foo\*(C'\fR") installed
1.515 +packages into the current Bourne-Shell environment:
1.516 +.PP
1.517 +.Vb 2
1.518 +\& $ eval `@l_prefix@/bin/openpkg rc --eval all env`
1.519 +\& $ echo $FOO_HOME
1.520 +.Ve
1.521 +.SH "SEE ALSO"
1.522 +.IX Header "SEE ALSO"
1.523 +\&\fBOpenPKG\fR http://www.openpkg.org/
1.524 +.SH "HISTORY"
1.525 +.IX Header "HISTORY"
1.526 +The \fBOpenPKG\fR run-command facility consisting of the scripts \f(CW\*(C`rc\*(C'\fR
1.527 +and \f(CW\*(C`rc.func\*(C'\fR were originally invented in November 2000 by Ralf S.
1.528 +Engelschall for \fBOpenPKG\fR. They were completely worked off from scratch
1.529 +in July 2003 for \fBOpenPKG 1.3\fR.
1.530 +.SH "AUTHOR"
1.531 +.IX Header "AUTHOR"
1.532 +.Vb 3
1.533 +\& Ralf S. Engelschall
1.534 +\& rse@engelschall.com
1.535 +\& www.engelschall.com
1.536 +.Ve
