Add rc.subr to our list of most informative manpages
[dragonfly.git] / share / man / man8 / rc.subr.8
1 .\"     $NetBSD: rc.subr.8,v 1.9 2002/07/08 16:14:55 atatat Exp $
2 .\"     $FreeBSD: src/share/man/man8/rc.subr.8,v 1.3 2003/04/22 05:13:55 dougb Exp $
3 .\"     $DragonFly: src/share/man/man8/rc.subr.8,v 1.1 2003/08/01 04:36:57 rob Exp $
4 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
5 .\" All rights reserved.
6 .\"
7 .\" This code is derived from software contributed to The NetBSD Foundation
8 .\" by Luke Mewburn.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\"    notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\"    notice, this list of conditions and the following disclaimer in the
17 .\"    documentation and/or other materials provided with the distribution.
18 .\" 3. All advertising materials mentioning features or use of this software
19 .\"    must display the following acknowledgement:
20 .\"     This product includes software developed by the NetBSD
21 .\"     Foundation, Inc. and its contributors.
22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
23 .\"    contributors may be used to endorse or promote products derived
24 .\"    from this software without specific prior written permission.
25 .\"
26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36 .\" POSSIBILITY OF SUCH DAMAGE.
37 .\"
38 .Dd April 18, 2002
39 .Dt RC.SUBR 8
40 .Os
41 .Sh NAME
42 .Nm rc.subr
43 .Nd functions used by system shell scripts
44 .Sh SYNOPSIS
45 .Bl -item
46 .It
47 .Li . /etc/rc.subr
48 .It
49 .Ic backup_file Ar action Ar file Ar current Ar backup
50 .It
51 .Ic checkyesno Ar var
52 .It
53 .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
54 .It
55 .Ic check_process Ar procname Op Ar interpreter
56 .It
57 .Ic debug Ar message
58 .It
59 .Ic err Ar exitval Ar message
60 .It
61 .Ic force_depend Ar name
62 .It
63 .Ic info Ar message
64 .It
65 .Ic load_rc_config Ar command
66 .It
67 .Ic mount_critical_filesystems Ar type
68 .It
69 .Ic rc_usage Ar command Op Ar ...
70 .It
71 .Ic reverse_list Ar item Op Ar ...
72 .It
73 .Ic run_rc_command Ar argument
74 .It
75 .Ic run_rc_script Ar file Ar argument
76 .It
77 .Ic set_rcvar Op Ar base
78 .It
79 .Ic wait_for_pids Op Ar pid Op Ar ...
80 .It
81 .Ic warn Ar message
82 .El
83 .Sh DESCRIPTION
84 .Nm
85 contains commonly used shell script functions and variable
86 definitions which are used by various scripts such as
87 .Xr rc 8 .
88 Scripts required by ports in
89 .Pa /usr/local/etc/rc.d
90 will also eventually
91 be rewritten to make use of it.
92 .Pp
93 The
94 .Nm
95 functions were mostly imported from
96 .Nx
97 and it is intended that they remain synced between the
98 two projects. With that in mind there are several variable
99 definitions that can help in this regard. They are:
100 .Bl -tag -width 4n
101 .It Ic OSTYPE
102 Its value will be either
103 .Fx
104 or
105 .Nx ,
106 depending on which OS it is running on.
107 .It Ic SYSCTL
108 The path to the
109 .Xr sysctl 8
110 command.
111 .It Ic SYSCTL_N
112 The path and argument list to display only the
113 .Xr sysctl 8
114 values instead of a name=value pair.
115 .It Ic SYSCTL_W
116 The path and argument to write or modify
117 .Xr sysctl 8
118 values.
119 .El
120 .Pp
121 The
122 .Nm
123 functions are accessed by sourcing
124 .Pa /etc/rc.subr
125 into the current shell.
126 .Pp
127 The following shell functions are available:
128 .Bl -tag -width 4n
129 .It Xo
130 .Ic backup_file Ar action Ar file Ar current Ar backup
131 .Xc
132 Make a backup copy of
133 .Ar file
134 into
135 .Ar current .
136 If the
137 .Xr rc.conf 5
138 variable
139 .Sy backup_uses_rcs
140 is
141 .Sq YES ,
142 use
143 .Xr rcs 1
144 to archive the previous version of
145 .Ar current ,
146 otherwise save the previous version of
147 .Ar current
148 as
149 .Ar backup .
150 .Pp
151 .Ar action
152 may be one of the following:
153 .Bl -tag -width remove
154 .It Sy add
155 .Ar file
156 is now being backed up by or possibly re-entered into this backup mechanism.
157 .Ar current
158 is created, and if necessary, the
159 .Xr rcs 1
160 files are created as well.
161 .It Sy update
162 .Ar file
163 has changed and needs to be backed up.
164 If
165 .Ar current
166 exists, it is copied to
167 .Ar backup
168 or checked into
169 .Xr rcs 1
170 (if the repository file is old),
171 and then
172 .Ar file
173 is copied to
174 .Ar current .
175 .It Sy remove
176 .Ar file
177 is no longer being tracked by this backup mechanism.
178 If
179 .Xr rcs 1
180 is being used, an empty file is checked in and
181 .Ar current
182 is removed,
183 otherwise
184 .Ar current
185 is moved to
186 .Ar backup .
187 .El
188 .It Ic checkyesno Ar var
189 Return 0 if
190 .Ar var
191 is defined to
192 .Sq YES ,
193 .Sq TRUE ,
194 .Sq ON ,
195 or
196 .Sq 1 .
197 Return 1 if
198 .Ar var
199 is defined to
200 .Sq NO ,
201 .Sq FALSE ,
202 .Sq OFF ,
203 or
204 .Sq 0 .
205 Otherwise, warn that
206 .Ar var
207 is not set correctly.
208 The values are case insensitive.
209 .It Xo
210 .Ic check_pidfile
211 .Ar pidfile
212 .Ar procname
213 .Op Ar interpreter
214 .Xc
215 Parses the first word of the first line of
216 .Ar pidfile
217 for a PID, and ensures that the process with that PID
218 is running and its first argument matches
219 .Ar procname .
220 Prints the matching PID if successfull, otherwise nothing.
221 If
222 .Ar interpreter
223 is provided, parse the first line of
224 .Ar procname ,
225 ensure that the line is of the form
226 .Dl #! interpreter [...]
227 and use
228 .Ar interpreter
229 with its optional arguments and
230 .Ar procname
231 appended as the process string to search for.
232 .It Ic check_process Ar procname Op Ar interpreter
233 Prints the PIDs of any processes that are running with a first
234 argument that matches
235 .Ar procname .
236 .Ar interpreter
237 is handled as per
238 .Ic check_pidfile .
239 .It Ic debug Ar message
240 Display a debugging message to
241 .Em stderr ,
242 log it to the system log using
243 .Xr logger 1 ,
244 and
245 return to the caller.
246 The error message consists of the script name
247 (from
248 .Sy $0 ) ,
249 followed by
250 .Dq ": DEBUG: " ,
251 and then
252 .Ar message .
253 This function is intended to be used by developers
254 as an aid to debugging scripts. It can be turned on or off
255 by the
256 .Xr rc.conf 5
257 variable
258 .Em rc_debug .
259 .It Ic err Ar exitval Ar message
260 Display an error message to
261 .Em stderr ,
262 log it to the system log
263 using
264 .Xr logger 1 ,
265 and
266 .Cm exit
267 with an exit value of
268 .Ar exitval .
269 The error message consists of the script name
270 (from
271 .Sy $0 ) ,
272 followed by
273 .Dq ": ERROR: " ,
274 and then
275 .Ar message .
276 .It Ic force_depend name
277 Output an advisory message and force the
278 .Ar name
279 service to start. The
280 .Ar name
281 argument is the
282 .Xr basename 1 ,
283 component of the path to the script, usually
284 .Em /etc/rc.d/name .
285 If the script fails for any reason it will output a warning
286 and return with a return value of 1. If it was successful
287 it will return 0.
288 .It Ic info Ar message
289 Display an informational message to
290 .Em stdout ,
291 and log it to the system log using
292 .Xr logger 1 .
293 The message consists of the script name
294 (from
295 .Sy $0 ) ,
296 followed by
297 .Dq ": INFO: " ,
298 and then
299 .Ar message .
300 The display of this informational output can be
301 turned on or off by the
302 .Xr rc.conf 5
303 variable
304 .Em rc_info .
305 .It Ic load_rc_config Ar command
306 Source in the configuration files for
307 .Ar command .
308 First,
309 .Pa /etc/rc.conf
310 is sourced if it has not yet been read in.
311 Then,
312 .Pa /etc/rc.conf.d/ Ns Ar command
313 is sourced if it is an existing file.
314 The latter may also contain other variable assignments to override
315 .Ic run_rc_command
316 arguments defined by the calling script, to provide an easy
317 mechanism for an administrator to override the behaviour of a given
318 .Xr rc.d 8
319 script without requiring the editing of that script.
320 .It Ic mount_critical_filesystems Ar type
321 Go through a list of critical file systems,
322 as found in the
323 .Xr rc.conf 5
324 variable
325 .Sy critical_filesystems_ Ns Ar type ,
326 mounting each one that
327 is not currently mounted.
328 .It Ic rc_usage Ar command Op Ar ...
329 Print a usage message for
330 .Sy $0 ,
331 with
332 .Ar commands
333 being the list of valid arguments
334 prefixed by
335 .Dq "[fast|force]" .
336 .It Ic reverse_list Ar item Op Ar ...
337 Print the list of
338 .Ar items
339 in reverse order.
340 .It Ic run_rc_command Ar argument
341 Run the
342 .Ar argument
343 method for the current
344 .Xr rc.d 8
345 script, based on the settings of various shell variables.
346 .Ic run_rc_command
347 is extremely flexible, and allows fully functional
348 .Xr rc.d 8
349 scripts to be implemented in a small amount of shell code.
350 .Pp
351 .Ar argument
352 is searched for in the list of supported commands, which may be one
353 of:
354 .Dl start stop restart rcvar
355 as well as any word listed in the optional variable
356 .Sy extra_commands .
357 If
358 .Sy pidfile
359 or
360 .Sy procname
361 is set, also allow:
362 .Dl status poll
363 .Pp
364 .Ar argument
365 may have one of the following prefixes which alters its operation:
366 .Bl -tag -width "Prefix" -offset indent -compact
367 .It Sy Prefix
368 .Sy Operation
369 .It Li fast
370 Skip the check for an existing running process,
371 and sets
372 .Sy rc_fast=YES .
373 .It Li force
374 Skip the checks for
375 .Sy rcvar
376 being set to yes,
377 and sets
378 .Sy rc_force=YES .
379 This ignores
380 .Ar argument Ns Sy _precmd
381 returning non-zero, and ignores any of the
382 .Sy required_*
383 tests failing .
384 .El
385 .Pp
386 .Ic run_rc_command
387 uses the following shell variables to control its behaviour.
388 Unless otherwise stated, these are optional.
389 .Bl -tag -width procname -offset indent
390 .It Sy name
391 The name of this script.
392 This is not optional.
393 .It Sy rcvar
394 The value of
395 .Sy rcvar
396 is checked with
397 .Ic checkyesno
398 to determine if this method should be run.
399 .It Sy command
400 Full path to the command.
401 Not required if
402 .Ar argument Ns Sy _cmd
403 is defined for each supported keyword.
404 .It Sy command_args
405 Optional arguments and/or shell directives for
406 .Sy command .
407 .It Sy command_interpreter
408 .Sy command
409 is started with
410 .Dl #! command_interpreter [...]
411 which results in its
412 .Xr ps 1
413 command being
414 .Dl command_interpreter [...] command
415 so use that string to find the PID(s) of the running command
416 rather than
417 .Ql command .
418 .It Sy extra_commands
419 Extra commands/keywords/arguments supported.
420 .It Sy pidfile
421 Path to pid file.
422 Used to determine the PID(s) of the running command.
423 If
424 .Sy pidfile
425 is set, use
426 .Dl check_pidfile $pidfile $procname
427 to find the PID.
428 Otherwise, if
429 .Sy command
430 is set, use
431 .Dl check_process $procname
432 to find the PID.
433 .It Sy procname
434 Process name to check for.
435 Defaults to the value of
436 .Sy command .
437 .It Sy required_dirs
438 Check for the existence of the listed directories
439 before running the default start method.
440 .It Sy required_files
441 Check for the readability of the listed files
442 before running the default start method.
443 .It Sy required_vars
444 Perform
445 .Ic checkyesno
446 on each of the list variables
447 before running the default start method.
448 .It Sy ${name}_chdir
449 Directory to
450 .Ic cd
451 to before running
452 .Sy command ,
453 if
454 .Sy ${name}_chroot
455 is not provided.
456 .It Sy ${name}_chroot
457 Directory to
458 .Xr chroot 8
459 to before running
460 .Sy command .
461 Only supported after
462 .Pa /usr
463 is mounted.
464 .It Sy ${name}_flags
465 Arguments to call
466 .Sy command
467 with.
468 This is usually set in
469 .Xr rc.conf 5 ,
470 and not in the
471 .Xr rc.d 8
472 script.
473 The environment variable
474 .Sq Ev flags
475 can be used to override this.
476 .It Sy ${name}_nice
477 .Xr nice 1
478 level to run
479 .Sy command
480 as.
481 Only supported after
482 .Pa /usr
483 is mounted.
484 .It Sy ${name}_user
485 User to run
486 .Sy command
487 as, using
488 .Xr chroot 8 .
489 if
490 .Sy ${name}_chroot
491 is set, otherwise
492 uses
493 .Xr su 1 .
494 Only supported after
495 .Pa /usr
496 is mounted.
497 .It Sy ${name}_group
498 Group to run the chrooted
499 .Sy command
500 as.
501 .It Sy ${name}_groups
502 Comma separated list of supplementary groups to run the chrooted
503 .Sy command
504 with.
505 .It Ar argument Ns Sy _cmd
506 Shell commands which override the default method for
507 .Ar argument .
508 .It Ar argument Ns Sy _precmd
509 Shell commands to run just before running
510 .Ar argument Ns Sy _cmd
511 or the default method for
512 .Ar argument .
513 If this returns a non-zero exit code, the main method is not performed.
514 If the default method is being executed, this check is performed after
515 the
516 .Sy required_*
517 checks and process (non-)existence checks.
518 .It Ar argument Ns Sy _postcmd
519 Shell commands to run if running
520 .Ar argument Ns Sy _cmd
521 or the default method for
522 .Ar argument
523 returned a zero exit code.
524 .It Sy sig_stop
525 Signal to send the processes to stop in the default
526 .Sy stop
527 method.
528 Defaults to
529 .Dv SIGTERM .
530 .It Sy sig_reload
531 Signal to send the processes to reload in the default
532 .Sy reload
533 method.
534 Defaults to
535 .Dv SIGHUP .
536 .El
537 .Pp
538 For a given method
539 .Ar argument ,
540 if
541 .Ar argument Ns Sy _cmd
542 is not defined, then a default method is provided by
543 .Sy run_rc_command :
544 .Bl -tag -width "argument" -offset indent
545 .It Sy Argument
546 .Sy Default method
547 .It Sy start
548 If
549 .Sy command
550 is not running and
551 .Ic checkyesno Sy rcvar
552 succeeds, start
553 .Sy command .
554 .It Sy stop
555 Determine the PIDs of
556 .Sy command
557 with
558 .Ic check_pidfile
559 or
560 .Ic check_process
561 (as appropriate),
562 .Ic kill Sy sig_stop
563 those PIDs, and run
564 .Ic wait_for_pids
565 on those PIDs.
566 .It Sy reload
567 Similar to
568 .Sy stop ,
569 except that it uses
570 .Sy sig_reload
571 instead, and doesn't run
572 .Ic wait_for_pids .
573 .It Sy restart
574 Runs the
575 .Sy stop
576 method, then the
577 .Sy start
578 method.
579 .It Sy status
580 Show the PID of
581 .Sy command ,
582 or some other script specific status operation.
583 .It Sy poll
584 Wait for
585 .Sy command
586 to exit.
587 .It Sy rcvar
588 Display which
589 .Xr rc.conf 5
590 variable is used (if any).
591 This method always works, even if the appropriate
592 .Xr rc.conf 5
593 variable is set to
594 .Sq NO .
595 .El
596 .Pp
597 The following variables are available to the methods
598 (such as
599 .Ar argument Ns Sy _cmd )
600 as well as after
601 .Ic run_rc_command
602 has completed:
603 .Bl -tag -width "rc_flags" -offset indent
604 .It Sy rc_arg
605 Argument provided to
606 .Sy run_rc_command ,
607 after fast and force processing has been performed.
608 .It Sy rc_flags
609 Flags to start the default command with.
610 Defaults to
611 .Sy ${name}_flags ,
612 unless overridden by the environment variable
613 .Sq Ev flags .
614 This variable may be changed by the
615 .Ar argument Ns Sy _precmd
616 method.
617 .It Sy rc_pid
618 PID of
619 .Sy command
620 (if appropriate).
621 .It Sy rc_fast
622 Not empty if
623 .Dq fast
624 prefix was used.
625 .It Sy rc_force
626 Not empty if
627 .Dq force
628 prefix was used.
629 .El
630 .It Ic run_rc_script Ar file Ar argument
631 Start the script
632 .Ar file
633 with an argument of
634 .Ar argument ,
635 and handle the return value from the script.
636 .Pp
637 Various shell variables are unset before
638 .Ar file
639 is started:
640 .Bd -ragged -offset indent
641 .Sy name ,
642 .Sy command ,
643 .Sy command_args ,
644 .Sy command_interpreter ,
645 .Sy extra_commands ,
646 .Sy pidfile ,
647 .Sy rcvar ,
648 .Sy required_dirs ,
649 .Sy required_files ,
650 .Sy required_vars ,
651 .Ar argument Ns Sy _cmd ,
652 .Ar argument Ns Sy _precmd .
653 .Ar argument Ns Sy _postcmd .
654 .Ed
655 .Pp
656 The startup behaviour of
657 .Ar file
658 depends upon the following checks:
659 .Bl -enum
660 .It
661 If
662 .Ar file
663 ends in
664 .Pa .sh ,
665 it is sourced into the current shell.
666 .It
667 If
668 .Ar file
669 appears to be a backup or scratch file
670 (e.g., with a suffix of
671 .Sq ~ ,
672 .Sq # ,
673 .Sq .OLD ,
674 or
675 .Sq .orig ) ,
676 ignore it.
677 .It
678 If
679 .Ar file
680 is not executable, ignore it.
681 .It
682 If the
683 .Xr rc.conf 5
684 variable
685 .Sy rc_fast_and_loose
686 is empty,
687 source
688 .Ar file
689 in a sub shell,
690 otherwise source
691 .Ar file
692 into the current shell.
693 .El
694 .It Ic set_rcvar Op Ar base
695 Set the variable name required to start a service. In
696 .Fx
697 a daemon is usually controlled by an
698 .Xr rc.conf 5
699 variable consisting of a daemon's name postfixed by the string
700 .Sy "_enable" .
701 This is not the case in
702 .Nx .
703 When the following line is included in a script
704 .Pp
705 .Dl rcvar=`set_rcvar`
706 .Pp
707 This function will use the value of the
708 .Sy $name
709 variable, which should be defined by the calling script, to construct the appropriate
710 .Xr rc.conf 5
711 knob. If the
712 .Ar base
713 argument is set it will use
714 .Ar base
715 instead of
716 .Sy $name .
717 .It Ic wait_for_pids Op Ar pid Op Ar ...
718 Wait until all of the provided
719 .Ar pids
720 don't exist any more, printing the list of outstanding
721 .Ar pids
722 every two seconds.
723 .It Ic warn Ar message
724 Display a warning message to
725 .Em stderr
726 and log it to the system log
727 using
728 .Xr logger 1 .
729 The warning message consists of the script name
730 (from
731 .Sy $0 ) ,
732 followed by
733 .Dq ": WARNING: " ,
734 and then
735 .Ar message .
736 .El
737 .Sh FILES
738 .Bl -tag -width /etc/rc.subr -compact
739 .It Pa /etc/rc.subr
740 The
741 .Nm
742 file resides in
743 .Pa /etc .
744 .El
745 .Sh SEE ALSO
746 .Xr rc.conf 5 ,
747 .Xr rc 8
748 .Sh HISTORY
749 .Nm
750 appeared in
751 .Nx 1.3 .
752 The
753 .Xr rc.d 8
754 support functions appeared in
755 .Nx 1.5 .
756 .Nm
757 first appeared in
758 .Fx 5.0 .