3 .\" The DragonFly Project. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in
13 .\" the documentation and/or other materials provided with the
15 .\" 3. Neither the name of The DragonFly Project nor the names of its
16 .\" contributors may be used to endorse or promote products derived
17 .\" from this software without specific, prior written permission.
19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .Nd build an environment and monitor/maintain a service or command
43 .Op arguments-to-directive
46 is a program which can build, monitor, and manage a simple environment
47 and execute a command within that environment.
50 system call to round-up all processes and sub-processes created under the
52 It can detect when the specific command or the command and all processes
53 exit and perform some action, and it can do a few relatively simple support
54 functions to terminate, restart, or terminate/re-initiate.
56 The following options are available:
57 .Bl -tag -width indent
59 Debug mode. Additional debug output is printed.
63 Foreground mode. Instead of fork/detaching the service, the service itself
64 runs in the foreground when the
66 directive is specified. The pid will not be printed in this case.
68 Display quick help for directives and exit.
70 Specify the directory to store pidfiles and sockets in, and to search
72 If not specified, the default is
76 no pidfile will be created or maintained. The
78 specification is not recommended except in combination with
82 Specify the restart delay and enable automatic restarts if the original
83 command under management exits, even if other processes are still present.
84 This option also modifies the behavior of the
86 service command, causing it to kill only the main process under management.
87 Any forked children will be left intact.
88 This option is exclusive with
91 Specify the restart delay and enable automatic restarts if all processes
92 under management exit.
93 This option also modifies the behavior of the
95 service command, causing it to kill all processes under management.
96 This option is exclusive with
99 Causes the service demon itself to exit if the service being monitored
101 Specify as an option to the left of the
109 to indicate what is considered a dead service (some or all of the processes).
110 If neither is specified,
112 is assumed. If specified, the timeout is irrelevant as there will be no
115 This option also issues a
117 directive before exiting. That is, it will still ensure that all processes
118 running under the service, either direct or indirect, are dead before the
119 service itself exits.
121 Causes the service demon to issue a
123 command after stopping or killing a service.
125 When stopping processes under management, specify the amount of time
126 allowed to elapse after sending a SIGTERM before sending a SIGKILL.
127 If 0 is specified, only SIGKILL will be sent.
128 The default is 10 seconds.
130 Set the uid and gid of the command to execute based on the user.
131 The uid or username must exist in the password file.
132 The gid may be overridden by the
137 The service demon itself is not affected.
139 Specified when initializing a new service, has no effect for other directives.
140 Cannot be overridden in
145 Set the gid of the command to execute.
146 This will override the user's gid set via the
149 The service demon itself is not affected.
151 Specified when initializing a new service, has no effect for other directives.
152 Cannot be overridden in
156 .It Fl G Ar group-list
157 Set the group-list of the command to execute. The service demon itself is not
159 This will completely override all other assumed or specified GIDs.
161 Specified when initializing a new service, has no effect for other directives.
162 Cannot be overridden in
167 Set the logfile path for the command.
168 If not specified, no logfile will be created.
169 However, the service monitor will still keep track of the last ~8KB or
170 so of stdout/stderr output.
172 Specified when initializing a new service, has no effect for other directives.
174 May be used in combination with
178 to automatically mount /dev in a chroot or jail.
179 It will be left mounted through stops and starts and will be unmounted
184 Specified when initializing a new service, has no effect for other directives.
185 .It Fl c Ar directory
186 Chroot into the specified directory when executing or re-executing the
187 command. The service itself stays outside the chroot.
190 is also specified, the service will automatically mount /dev in the chroot
191 if it does not already exist and unmount it when the service exits. The
192 mount remains in place when the service is stopped.
194 Specified when initializing a new service, has no effect for other directives.
195 Cannot be overridden in
199 .It Fl j Ar directory
200 Create a jail and operate in a manner similar to a chroot.
201 .It Fl k Ar jail-spec
202 Additional specification for the jail. See below.
208 to adjust what shows up in a ps command, to make process lists easier to
210 .It Fl F Ar restarts:pertimo
211 Specify failure timing.
212 If a service is automatically restarted more than the specified number
213 within the specified period, the service is considered to be in a failed
214 state when it next dies and will no longer be restarted.
216 The situation will be syslogged and an email will be sent to
218 with a description of the problem if the service is running as root.
219 If the service is running as a user, the email is sent to the user.
220 The system operator should generally setup a mail alias to point
222 to the desired destination.
224 This feature is disabled by default.
225 If you only specify the restart count the rate will default to
227 Specify as an option to the left of the
230 .It Ar directive Op arguments-to-directive
231 Specify a directive (see below).
233 Specify a label to name or locate the service.
234 Note that most directives allow a label prefix to be specified, affecting
236 If your label is postfixed by a number, you should use a fixed-width
237 0-fill field for the number or risk some confusion.
240 All timeouts and delays are specified in seconds.
248 directive, the service will not automatically restart if the underlying
249 processes exit. The service demon will remain intact unless
254 always creates a pid file in the pid directory named
255 .Pa service.<label>.pid
256 and maintains an open descriptor with an active exclusive
259 Scripts can determine whether the service demon itself is running or not
262 utility, or may use the convenient
264 directive and check the exit code to get more detailed status.
265 In addition, a service socket is created in the pid directory named
266 .Pa service.<label>.sk
269 uses to communicate with a running service demon.
271 Note that the service demon itself will not exit when the executed command
272 exits unless you have used the
280 Some RC services, such as sendmail, may maintain multiple service processes
281 and name each one with a postfix to the label.
282 By specifying just the prefix, your directives will affect all matching
285 For build systems the
287 option is typically used, sometimes with the
289 option, and allowed to default to just waiting for the original command
291 This will cause the service demon to then kill any remaining hanger-ons
294 .Bl -tag -width indent
295 .It Ar init Ar label Ar exec-command Op arguments
296 Start a new service with the specified label.
297 This command will fail if the label is already in-use.
298 This command will detach a new service demon, create a pidfile, and
299 output the pid of the new service demon to stdout before returning.
303 is a single word and not an absolute or relative path, the system
304 command path will be searched for the command.
306 Start a service that has been stopped.
307 The label can be a wildcard prefix so, for example, if there are
308 three sendmail services (sendmail01, sendmail02, sendmail03), then
309 the label 'sendmail' will operate on all three.
311 If the service is already running, this directive will be a NOP.
313 Stop a running service by sending a TERM signal and later a KILL signal
314 if necessry, to some or all processes
315 running under the service. The processes signaled depend on the original
319 options specified when the service was initiated.
320 These options, along with
322 may also be specified in this directive to override
323 (but not permanently change) the original options.
325 The service demon itself remains intact.
327 This is a short-hand for
330 It will kill all sub-processes of the service regardless of whether
334 was used in the original
340 operation, sleep for a few seconds based on the original
344 options, and then execute the
347 These options, along with
349 may also be specified in this directive to override
350 (but not permanently change) the original options.
354 operation but override prior options and terminate ALL processes
355 running under the service.
356 The service demon itself then terminates and must be init'd again
359 This function will also remove any stale pid and socket files.
363 operation but override prior options and terminate ALL processes
364 running under the service.
365 Also force the delay to 0, bypassing SIGTERM and causing SIGKILL to be
367 The service demon itself then terminates and must be init'd again
370 This function will also remove any stale pid and socket files.
372 List a subset of labels and their status.
373 If no label is specified, all active labels are listed.
375 Print the status of a particular label, exit with a 0 status if
376 the service exists and is still considered to be running.
377 Exit with 1 if the service exists but is considered to be stopped.
378 Exit with 2 if the service does not exist.
379 If multiple labels match, the worst condition found becomes the exit code.
381 Scripts that use this feature can conveniently use the
383 directive to start any matching service that is considered stopped.
384 The directive is a NOP for services that are considered to be running.
386 The service demon monitors stdout/stderr output from programs it runs
387 continuously and will remember the last ~8KB or so, which can be
388 dumped via this directive.
390 This works the same as
392 but continues to monitor and dump the output until you ^C.
393 In order to avoid potentially stalling the service under management,
394 gaps may occur if the monitor is unable to keep up with the log
397 This works similarly to
399 but dumps fewer lines of log history before dovetailing into
400 continuous monitoring.
401 .It Ar logfile Ar label Op path
402 Re-open, set, or change the logfile path for the monitor,
403 creating a new logfile if necessary.
404 The logfile is created by the parent monitor (the one not running in
405 a chroot or jail or as a particular user or group).
406 This way the service under management cannot modify or destroy it.
408 It is highly recommended that you specify an absolute path when
409 changing the logfile.
410 If you wish to disable the logfile, set it to /dev/null.
411 Disabling the logfile does not prevent you from viewing the
412 last ~8KB and/or monitoring any logged data.
414 Display quick help for directives.
417 Description of nominal operation
420 .Sh JAIL-SPECIFICATIONS
421 A simple jail just chroots into a directory, possibly mounts /dev, and
422 allows all current IP bindings to be used.
423 The service demon itself does not run in the jail, but will keep the
428 operations by leaving a forked process intact inside.
429 If the jail is destroyed, the service demon will re-create it if necessary
433 option may be used to specify additional parameters.
434 Parameters are comma-delimited with no spaces.
435 Values may be specified in the name=value format.
437 .Fl k Ar clean,ip=1.2.3.4,ip=5.6.7.8
438 .Bl -tag -width indent
440 The jail is handed a clean environment, similar to what
444 The jail is allowed to bind to the specified IP address. This option may
445 be specified multiple times.
448 Generally speaking signals should not be sent to a service demon.
449 Instead, the command should be run with an appropriate directive to
450 adjust running behavior.
451 However, the service demon will act on signals as follows:
452 .Bl -tag -width indent
454 The service demon will execute the
458 The service demon will execute the
465 utility first appeared in