aboutsummaryrefslogtreecommitdiff
path: root/src/genrc.8
blob: 00522eedbe884c6d649b4eaa1749533fcefee32f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
.\" This file is part of genrc.
.\" Copyright (C) 2018 Sergey Poznyakoff.
.\"
.\" Genrc is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" Genrc is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with genrc.  If not, see <http://www.gnu.org/licenses/>. 
.TH GENRC 8 "May 17, 2018" "GENRC" "Genrc User Manual"
.SH NAME
genrc \- generic system initialization script helper
.SH SYNOPSIS
.nh
.na
\fBgenrc\fR\
 [\fB\-hv\fR]\
 [\fB\-F\fR \fIPIDFILE\fR]\
 [\fB\-P\fR \fISOURCE\fR]\
 [\fB\-c\fR \fICOMMAND\fR]\
 [\fB\-g\fR \fIGROUP\fR[,\fIGROUP\fR...]]\
 [\fB\-p\fR \fIPROGRAM\fR]\
 [\fB\-t\fR \fISECONDS\fR]\
 [\fB\-u\fR \fIUSER\fR]\
 [\fB\-\-command=\fICOMMAND\fR]\
 [\fB\-\-create\-pidfile=\fIPIDFILE\fR]\
 [\fB\-\-group=\fIGROUP\fR[,\fIGROUP\fR...]]\
 [\fB\-\-help\fR]\
 [\fB\-\-no\-reload\fR]\
 [\fB\-\-pid\-from=\fISOURCE\fR]\
 [\fB\-\-pidfile=\fIPIDFILE\fR]\
 [\fB\-\-program=\fIPROGRAM\fR]\
 [\fB\-\-sentinel\fR]\
 [\fB\-\-signal\-reload=\fISIG\fR]\
 [\fB\-\-signal\-stop=\fISIG\fR]\
 [\fB\-\-timeout=\fISECONDS\fR]\
 [\fB\-\-user=\fIUSER\fR]\
 [\fB\-\-usage\fR]\
 [\fB\-\-verbose\fR]\
 {\
 \fBstart\fR\
 |\
 \fBstop\fR\
 |\
 \fBrestart\fR\
 |\
 \fBreload\fR\
 |\
 \fBstatus\fR\
 }
.ad
.hy
.SH DESCRIPTION
.B genrc
is a generic helper program for writing system initialization
scripts. Depending on the operation mode, it starts, stops,
reconfigures or displays the status of a specific program.
.PP
The operation mode of the program is set by its only mandatory
argument. Other program settings are specified via the command
line options or environment variables. Most options have a
corresponding environment variable. For example, the command line
of the program to be run is given by the \fB\-\-command\fR option,
or by the \fBGENRC_COMMAND\fR environment variable. If both the
variable is set and the option is supplied, the later takes precedence
over the former.
.PP
The \fB\-\-program\fR option or the \fBGENRC_PROGRAM\fR environment
variable supplies the name of the program, which is used to determine
whether the program is already running. If not supplied, the first
word (in the shell sense) from \fICOMMAND\fR is used.
.PP
If \fB\-\-program\fR is given, but \fB\-\-command\fR is not, its value
will be used as the command to run.
.PP
The program operation modes are:
.SS start
If given \fBstart\fR argument, \fBgenrc\fR runs the supplier
command. Before, it checks if the program is not already running and
refuses to start its second copy if so.
.PP
It is supposed that the program to be run will detach from the
controlling terminal and continue running in the background (i.e. it
is a \fIdaemon\fR, in UNIX sense). If it is not the case, use the
\fB\-\-sentinel\fR option. With this option, \fBgenrc\fR will start
the command and will become daemon itself, controlling the execution
of the program. It will exit when the command terminates. So long as
the command runs, \fBgenrc\fR will pipe its standard output and error
to syslog facility \fBdaemon\fR. The standard output will be logged
with the priority \fBinfo\fR and the error with the priority
\fBerr\fR.
.PP
If the \fB\-\-create\-pidfile=\fIFILENAME\fR option is given together with
\fB\-\-sentinel\fR, the PID of the subsidiary command will be stored
in \fIFILE\fR. The file will be unlinked after the subsidiary command
terminates. Unless the \fB\-\-pid\-from\fR option is given,
\fB\-\-pid\-from=FILE:\fIFILENAME\fR will be assumed.
.SS status
In \fBstatus\fR mode \fBgenrc\fR verifies if the \fICOMMAND\fR is
already running and outputs its status on the standard output. To this
effect, it uses an abstraction called \fIPID source\fR, which allows
it to determine the PID of the program by its name of command line.
.PP
The default PID source is the Linux \fB/proc\fR filesystem (or, if it
is not available, the output of \fBps -ef\fR), which is scanned for
the name of the program (given by \fB\-\-program\fR or
\fB\-\-command\fR options). 
.PP
The source to use can be supplied with the \fB\-\-pid\-from\fR option
(or the \fB\-\-pidfile option, which is equivalent to
\fB\-\-pid\-from=FILE:\fR). See the section \fBPID SOURCES\fR for a
detailed discussion of available sources.
.SS stop
In the \fBstop\fR mode \fBgenrc\fR stops the command by sending it
\fBSIGTERM\fR (or another signal as supplied with the
\fB\-\-signal\-stop\fR option). If the PID source returns multiple
PIDs, by default only parent PID is selected. However, \fBgenrc\fR can
be instructed to signal all PIDs instead (see the \fBa\fR flag in the
description of \fBPROC\fR or \fBPS\fR PID source).
.PP
After sending the signal, the program will wait for all processes to
terminate. It will report error if they don't terminate within 5
seconds. This timeout can be changed using the \fB\-\-timeout\fR
option.
.SS restart
Restarts the program. It is equivalent to running
.B genrc stop
immediately followed by
.BR "genrc start" .
.SS reload
Attempt to reload (or reconfigure) the program by sending it the
\fBSIGHUP\fR signal (or another signal, as given with the
\fB\-\-signal\-reload\fR option). The \fB\-\-no\-reload\fR or
\fB\-\-signal\-reload=0\fR option disables this behavior, making
this mode equivalent to
.BR "genrc restart" .
.SH EXAMPLE
Following is a sample \fBrc.ntpd\fR file for Slackware:
.sp
.EX
#! /bin/sh
PIDFILE=/var/run/ntpd.pid
exec /sbin/genrc \\
     \-\-command="/usr/sbin/ntpd \-g \-p $PIDFILE" \\
     \-\-no\-reload \\
     \-\-signal\-stop=SIGHUP \\
     \-\-pid\-from="FILE:$PIDFILE" "$@"
.EE
.SH OPTIONS
.TP
\fB\-c\fR, \fB\-\-command=\fICOMMAND\fR
Command line to run.
.TP
\fB\-\-create\-pidfile=\fINAME\fR
When used together with \fB\-\-sentinel\fR, the PID of the command
being run will be stored in file \fINAME\fR. The
\fB\-\-pid\-from=FILE:\fINAME\fR will be assumed, unless the
\fB\-\-pid\-from\fR is given explicitly (or the \fBGENRC_PID_FROM\fR
variable is set). 
.TP
\fB\-F\fR, \fB\-\-pidfile=\fINAME\fR
Name of the PID file (same as \fB\-\-pid\-from=FILE:\fINAME\fR)
.TP
\fB\-h\fR, \fB\-\-help\fR
Display a short help list.
.TP
\fB\-g\fR, \fB\-\-group=\fIGROUP\fR[,\fIGROUP\fR...]
Run program with this \fIGROUP\fR privileges. If the argument is a
list of groups, the first group becomes the principal, and the
rest of them supplementary groups. Each \fIGROUP\fR is either a group
name or a numeric group number prefixed with a plus sign. Whatever
notation is used, it must exist in the system group database.

See also the \fB\-\-user\fR option.
.TP
\fB\-\-no\-reload\fR
Makes \fBreload\fR equivalent to \fBrestart\fR.
.TP
\fB\-p\fR, \fB\-\-program=\fIPROGRAM\fR
Name of the program to run.
.TP
\fB\-P\fR, \fB\-\-pid\-from=\fISOURCE\fR
Where to look for PIDs of the running programs.
.TP
\fB\-\-sentinel\fR
\fIPROGRAM\fR runs in foreground; disconnect from the controlling
terminal, run it and act as a sentinel.
.TP
\fB\-\-signal\-reload=\fISIG\fR
Signal to send on reload (default: \fBSIGHUP\fR). Setting it to 0 is
equivalent to \fB\-\-no\-reload\fR.
.TP
\fB\-\-signal\-stop=\fISIG\fR
Signal to send in order to terminate the program (default:
\fBSIGTERM\fR).
.TP
\fB\-t\fR, \fB\-\-timeout=\fISECONDS\fR
Time to wait for the program to start up or terminate.
.TP
\fB\-\-usage\fR
Display a short usage summary.
.TP
\fB\-u\fR, \fB\-\-user=\fIUSER\fR
Run with this user privileges. The argument is either a login
name or a numeric UID prefixed with the plus sign. Whatever form is
used, it must correspond to a valid user from the system user
database.

Unless \fB\-\-group\fR option is also given, the primary and
supplementary groups of \fIUSER\fR will be used.
.TP
\fB\-\-version\fR
Display program version and exit.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Print verbose messages (e.g. "Starting \fIPROGNAME\fR").
.SH PID SOURCES
.TP
\fBFILE:\fIFILENAME\fR
Read PID from the file \fIFILENAME\fR.
.TP
\fBCONFIG:\fILANG\fB:\fIFILENAME\fB:\fIFQRN\fR
Name of the PID file is stored in relation \fIFQRN\fR of the configuration
file \fIFILENAME\fR, written in language \fILANG\fR. Recognizable
\fILANG\fR values are:
.RS
.TP
.B BIND
ISC BIND configuration file.
.TP
.B DHCPD
ISC DHCPD configuration file.
.TP
.B GIT
Git-style configuration file.
.TP
.B GRECS
GRECS-style configuration file. This is a generalization of a
structured configuration file format.
.TP
.B META1
META1 configuration file.
.TP
.B PATH
Configuration specified as fully-qualified keyword-value pairs
(similar to \fB.Xdefaults\fR).
.RE
.TP
\fBGREP:\fIFILE\fB:s/\fIRX\fB/\fIREPL\fB/[\fIFLAGS\fR][\fB;\fR...]
Grep for the first line in \fIFILE\fR that matches \fIRX\fR. If found, process
replace the matched portion according to \fIREPL\fR and \fIFLAGS\fR. Use
the resulting string as PID. More sed expressions can be supplied,
separated with semicolons.
.TP
\fBPROC\fR[\fB:\fR[\fIEXE\fR][\fB:\fIFLAGS\fR]]
Look for matching program in \fB/proc/\fIPID\fB/*\fR. If \fIEXE\fR is
not supplied or empty, program name from \fB\-\-program\fR will be
used. \fIFLAGS\fR are:
.RS
.TP
.B e
exact match
.TP
.B g
glob pattern match
.TP
.B x
extended POSIX regexp match (default)
.TP
.B p
PCRE match
.TP
.B i
case-insensitive match
.TP
.B c
match entire command line
.TP
.B r
match real executable name (instead of argv0)
.TP
.B a
signal all matching PIDs
.RE
.TP
\fBPS:\fR[\fB:\fR[\fIEXE\fR][:\fIFLAGS\fR]]
Look for matching program in the output of \fBps \-ef\fR. \fIEXE\fR
and \fIFLAGS\fR are as described above.
.SH ENVIRONMENT
Influential environment variables and corresponding options:
.sp
.nf
.ta 5n 35n
.ul
	Variable	Option
	\fBGENRC_COMMAND=\fICOMMAND\fR	\fB\-\-command=\fICOMMAND\fR
	\fBGENRC_PROGRAM=\fINAME\fR	\fB\-\-program=\fINAME\fR
	\fBGENRC_PID_FROM=\fISOURCE\fR	\fB\-\-pid\-from=\fISOURCE\fR
	\fBGENRC_TIMEOUT=\fISECONDS\fR	\fB\-\-timeout=\fISECONDS\fR
	\fBGENRC_SENTINEL=1\fR	\fB\-\-sentinel\fR
	\fBGENRC_CREATE_PIDFILE=\fINAME\fR	\fB\-\-create\-pidfile=\fINAME\fR
	\fBGENRC_USER=\fINAME\fR	\fB\-\-user=\fINAME\fR
	\fBGENRC_GROUP=\fIGROUPS\fR	\fB\-\-group=\fIGROUPS\fR	
.fi
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray@gnu.org>.
.SH COPYRIGHT
Copyright \(co 2018 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.