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