| blob | 9d1e1d45d1a215689f5644c12be77c38005f61d4 |
1 .\" $NetBSD: rc.subr.8,v 1.24 2009/09/11 19:48:52 wiz Exp $
2 .\"
3 .\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Luke Mewburn.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd October 5, 2009
31 .Dt RC.SUBR 8
32 .Os
33 .Sh NAME
34 .Nm rc.subr
35 .Nd functions used by system shell scripts
36 .Sh SYNOPSIS
37 .Bl -item
38 .It
39 .Li . /etc/rc.subr
40 .It
41 .Ic backup_file Ar action Ar file Ar current Ar backup
42 .It
43 .Ic checkyesno Ar var
44 .It
45 .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
46 .It
47 .Ic check_process Ar procname Op Ar interpreter
48 .It
49 .Ic err Ar exitval Ar message
50 .It
51 .Ic load_rc_config Ar command
52 .It
53 .Ic load_rc_config_var Ar command Ar var
54 .It
55 .Ic mount_critical_filesystems Ar type
56 .It
57 .Ic no_rc_postprocess Ar command Op Ar arguments
58 .It
59 .Ic print_rc_metadata Ar string
60 .It
61 .Ic print_rc_normal Ar string
62 .It
63 .Ic rc_usage Ar command Op Ar ...
64 .It
65 .Ic reverse_list Ar item Op Ar ...
66 .It
67 .Ic run_rc_command Ar argument
68 .It
69 .Ic run_rc_script Ar file Ar argument
70 .It
71 .Ic stop_boot
72 .It
73 .Ic twiddle
74 .It
75 .Ic wait_for_pids Op Ar pid Op Ar ...
76 .It
77 .Ic warn Ar message
78 .It
79 .Ic yesno_to_truefalse Ar var
80 .El
81 .Sh DESCRIPTION
82 .Nm
83 contains commonly used shell script functions which are used by
84 various scripts such as
85 .Xr rc 8 ,
86 and the periodic system services which are controlled by
87 .Xr daily.conf 5 ,
88 .Xr monthly.conf 5 ,
89 .Xr security.conf 5 ,
90 and
91 .Xr weekly.conf 5 .
92 .Pp
93 The
94 .Nm
95 functions are accessed by sourcing
96 .Pa /etc/rc.subr
97 into the current shell.
98 .Pp
99 The following shell functions are available:
100 .Bl -tag -width 4n
101 .It Ic backup_file Ar action Ar file Ar current Ar backup
102 Make a backup copy of
103 .Ar file
104 into
105 .Ar current .
106 If the
107 .Xr rc.conf 5
108 variable
109 .Sy backup_uses_rcs
110 is
111 .Sq YES ,
112 use
113 .Xr rcs 1
114 to archive the previous version of
115 .Ar current ,
116 otherwise save the previous version of
117 .Ar current
118 as
119 .Ar backup .
120 .Pp
121 .Ar action
122 may be one of the following:
123 .Bl -tag -width remove
124 .It Sy add
125 .Ar file
126 is now being backed up by or possibly re-entered into this backup mechanism.
127 .Ar current
128 is created, and if necessary, the
129 .Xr rcs 1
130 files are created as well.
131 .It Sy update
132 .Ar file
133 has changed and needs to be backed up.
134 If
135 .Ar current
136 exists, it is copied to
137 .Ar backup
138 or checked into
139 .Xr rcs 1
140 (if the repository file is old),
141 and then
142 .Ar file
143 is copied to
144 .Ar current .
145 .It Sy remove
146 .Ar file
147 is no longer being tracked by this backup mechanism.
148 If
149 .Xr rcs 1
150 is being used, an empty file is checked in and
151 .Ar current
152 is removed,
153 otherwise
154 .Ar current
155 is moved to
156 .Ar backup .
157 .El
158 .It Ic checkyesno Ar var
159 Return 0 if
160 .Ar var
161 is defined to
162 .Sq YES ,
163 .Sq TRUE ,
164 .Sq ON ,
165 or
166 .Sq 1 .
167 Return 1 if
168 .Ar var
169 is defined to
170 .Sq NO ,
171 .Sq FALSE ,
172 .Sq OFF ,
173 or
174 .Sq 0 .
175 Otherwise, warn that
176 .Ar var
177 is not set correctly.
178 The values are case insensitive.
179 .Pp
180 Note that the warning message shown by this function when
181 .Ar var
182 is not set references a manual page where the user can find more information.
183 Its name is picked up from the
184 .Sy rcvar_manpage
185 variable.
186 .It Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
187 Parses the first word of the first line of
188 .Ar pidfile
189 for a PID, and ensures that the process with that PID
190 is running and its first argument matches
191 .Ar procname .
192 Prints the matching PID if successful, otherwise nothing.
193 If
194 .Ar interpreter
195 is provided, parse the first line of
196 .Ar procname ,
197 ensure that the line is of the form
198 .Dl #! interpreter [...]
199 and use
200 .Ar interpreter
201 with its optional arguments and
202 .Ar procname
203 appended as the process string to search for.
204 .It Ic check_process Ar procname Op Ar interpreter
205 Prints the PIDs of any processes that are running with a first
206 argument that matches
207 .Ar procname .
208 .Ar interpreter
209 is handled as per
210 .Ic check_pidfile .
211 .It Ic err Ar exitval Ar message
212 Display an error message to
213 .Em stderr ,
214 log it to the system log
215 using
216 .Xr logger 1 ,
217 and
218 .Cm exit
219 with an exit value of
220 .Ar exitval .
221 The error message consists of the script name
222 (from
223 .Sy $0 ) ,
224 followed by
225 .Dq ": ERROR: " ,
226 and then
227 .Ar message .
228 .It Ic load_rc_config Ar command
229 Source in the
230 .Xr rc.conf 5
231 configuration files for
232 .Ar command .
233 First,
234 .Pa /etc/rc.conf
235 is sourced if it has not yet been read in.
236 Then,
237 .Pa /etc/rc.conf.d/ Ns Ar command
238 is sourced if it is an existing file.
239 The latter may also contain other variable assignments to override
240 .Ic run_rc_command
241 arguments defined by the calling script, to provide an easy
242 mechanism for an administrator to override the behaviour of a given
243 .Xr rc.d 8
244 script without requiring the editing of that script.
245 .It Ic load_rc_config_var Ar command Ar var
246 Read the
247 .Xr rc.conf 5
248 variable
249 .Ar var
250 for
251 .Ar command
252 and set in the current shell, using
253 .Ic load_rc_config
254 in a sub-shell to prevent unwanted side effects from other variable
255 assignments.
256 .It Ic mount_critical_filesystems Ar type
257 Go through a list of critical file systems,
258 as found in the
259 .Xr rc.conf 5
260 variable
261 .Sy critical_filesystems_ Ns Ar type ,
262 mounting each one that
263 is not currently mounted.
264 .It Ic no_rc_postprocess Ar command Op Ar arguments
265 Execute the specified command with the specified arguments,
266 in such a way that its output bypasses the post-processor that
267 .Xr rc 8
268 uses for most commands.
269 This implies that the output will not appear in the
270 .Pa /var/run/rc.log
271 file, and will appear on the console regardless of the
272 value of
273 .Va rc_silent .
274 This is expected to be useful for interactive commands,
275 and this mechanism is automatically used by
276 .Ic run_rc_command
277 when a script contains the
278 .Xr rcorder 8
279 keyword
280 .Dq interactive .
281 .Pp
282 If invoked from a context that does not appear to be under the control of
283 .Xr rc 8 ,
284 then the command is executed without special treatment.
285 .It Ic print_rc_metadata Ar string
286 Print the specified
287 .Ar string
288 in such a way that it should be handled as meta-data by the
289 .Xr rc 8
290 post-processor.
291 If invoked from a context that does not appear to be under the control of
292 .Xr rc 8 ,
293 then the
294 .Ar string
295 is discarded.
296 .Pp
297 Any
298 .Xr rc.d 8
299 script may invoke this function with an argument that begins with
300 .Dq note: ,
301 followed by one line of arbitrary text;
302 the text will be logged by
303 .Xr rc 8
304 but will not be displayed on the console.
305 .Pp
306 The use of arguments that do not begin with
307 .Dq note:
308 is reserved for internal use by
309 .Xr rc 8
310 and
311 .Nm .
312 .It Ic print_rc_normal Ar string
313 Print the specified
314 .Ar string
315 in such a way that it should be handled as normal output by the
316 .Xr rc 8
317 post-processor.
318 If invoked from a context that does not appear to be under the control of
319 .Xr rc 8 ,
320 then the
321 .Ar string
322 is printed to standard output.
323 .Pp
324 Ths intent is that a script that is run via the
325 .Fn no_rc_postprocess
326 function (so its output would ordinarily be invisible to the post-processor)
327 can nevertheless arrange for the post-processor to see things printed with
328 .Fn print_rc_normal.
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|one]" .
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 .Bl -tag -width restart -offset indent
356 .It Sy start
357 Start the service.
358 This should check that the service is to be started as specified by
359 .Xr rc.conf 5 .
360 Also checks if the service is already running and refuses to start if
361 it is.
362 This latter check is not performed by standard
363 .Nx
364 scripts if the system is starting directly to multi-user mode, to
365 speed up the boot process.
366 .It Sy stop
367 If the service is to be started as specified by
368 .Xr rc.conf 5 ,
369 stop the service.
370 This should check that the service is running and complain if it's not.
371 .It Sy restart
372 Perform a
373 .Sy stop
374 then a
375 .Sy start .
376 Defaults to displaying the process ID of the program (if running).
377 .It Sy rcvar
378 Display which
379 .Xr rc.conf 5
380 variables are used to control the startup of the service (if any).
381 .El
382 .Pp
383 If
384 .Sy pidfile
385 or
386 .Sy procname
387 is set, also support:
388 .Bl -tag -width restart -offset indent
389 .It Sy poll
390 Wait for the command to exit.
391 .It Sy status
392 Show the status of the process.
393 .El
394 .Pp
395 Other supported commands are listed in the optional variable
396 .Sy extra_commands .
397 .Pp
398 .Ar argument
399 may have one of the following prefixes which alters its operation:
400 .Bl -tag -width "Prefix" -offset indent
401 .It Sy fast
402 Skip the check for an existing running process,
403 and sets
404 .Sy rc_fast=YES .
405 .It Sy force
406 Skip the checks for
407 .Sy rcvar
408 being set to yes,
409 and sets
410 .Sy rc_force=YES .
411 This ignores
412 .Ar argument Ns Sy _precmd
413 returning non-zero, and ignores any of the
414 .Sy required_*
415 tests failing, and always returns a zero exit status.
416 .It Sy one
417 Skip the checks for
418 .Sy rcvar
419 being set to yes, but performs all the other prerequisite tests.
420 .El
421 .Pp
422 .Ic run_rc_command
423 uses the following shell variables to control its behaviour.
424 Unless otherwise stated, these are optional.
425 .Bl -tag -width procname -offset indent
426 .It Sy name
427 The name of this script.
428 This is not optional.
429 .It Sy rcvar
430 The value of
431 .Sy rcvar
432 is checked with
433 .Ic checkyesno
434 to determine if this method should be run.
435 .It Sy rcvar_manpage
436 The manual page containing information about
437 .Sy rcvar .
438 It will be part of the warning message shown when
439 .Sy rcvar
440 is undefined.
441 Defaults to
442 .Xr rc.conf 5 .
443 .It Sy command
444 Full path to the command.
445 Not required if
446 .Ar argument Ns Sy _cmd
447 is defined for each supported keyword.
448 .It Sy command_args
449 Optional arguments and/or shell directives for
450 .Sy command .
451 .It Sy command_interpreter
452 .Sy command
453 is started with
454 .Dl #! command_interpreter [...]
455 which results in its
456 .Xr ps 1
457 command being
458 .Dl command_interpreter [...] command
459 so use that string to find the PID(s) of the running command
460 rather than
461 .Ql command .
462 .It Sy extra_commands
463 Extra commands/keywords/arguments supported.
464 .It Sy pidfile
465 Path to pid file.
466 Used to determine the PID(s) of the running command.
467 If
468 .Sy pidfile
469 is set, use
470 .Dl check_pidfile $pidfile $procname
471 to find the PID.
472 Otherwise, if
473 .Sy command
474 is set, use
475 .Dl check_process $procname
476 to find the PID.
477 .It Sy procname
478 Process name to check for.
479 Defaults to the value of
480 .Sy command .
481 .It Sy required_dirs
482 Check for the existence of the listed directories
483 before running the default start method.
484 .It Sy required_files
485 Check for the readability of the listed files
486 before running the default start method.
487 .It Sy required_vars
488 Perform
489 .Ic checkyesno
490 on each of the list variables
491 before running the default start method.
492 .It Sy ${name}_chdir
493 Directory to
494 .Ic cd
495 to before running
496 .Sy command ,
497 if
498 .Sy ${name}_chroot
499 is not provided.
500 .It Sy ${name}_chroot
501 Directory to
502 .Xr chroot 8
503 to before running
504 .Sy command .
505 Only supported after
506 .Pa /usr
507 is mounted.
508 .It Sy ${name}_env
509 List of additional or modified environment variables to set
510 when starting
511 .Sy command .
512 .It Sy ${name}_flags
513 Arguments to call
514 .Sy command
515 with.
516 This is usually set in
517 .Xr rc.conf 5 ,
518 and not in the
519 .Xr rc.d 8
520 script.
521 The environment variable
522 .Sq Ev flags
523 can be used to override this.
524 .It Sy ${name}_nice
525 .Xr nice 1
526 level to run
527 .Sy command
528 as.
529 Only supported after
530 .Pa /usr
531 is mounted.
532 .It Sy ${name}_user
533 User to run
534 .Sy command
535 as, using
536 .Xr chroot 8 .
537 if
538 .Sy ${name}_chroot
539 is set, otherwise
540 uses
541 .Xr su 1 .
542 Only supported after
543 .Pa /usr
544 is mounted.
545 .It Sy ${name}_group
546 Group to run the chrooted
547 .Sy command
548 as.
549 .It Sy ${name}_groups
550 Comma separated list of supplementary groups to run the chrooted
551 .Sy command
552 with.
553 .It Ar argument Ns Sy _cmd
554 Shell commands which override the default method for
555 .Ar argument .
556 .It Ar argument Ns Sy _precmd
557 Shell commands to run just before running
558 .Ar argument Ns Sy _cmd
559 or the default method for
560 .Ar argument .
561 If this returns a non-zero exit code, the main method is not performed.
562 If the default method is being executed, this check is performed after
563 the
564 .Sy required_*
565 checks and process (non-)existence checks.
566 .It Ar argument Ns Sy _postcmd
567 Shell commands to run if running
568 .Ar argument Ns Sy _cmd
569 or the default method for
570 .Ar argument
571 returned a zero exit code.
572 .It Sy sig_stop
573 Signal to send the processes to stop in the default
574 .Sy stop
575 method.
576 Defaults to
577 .Dv SIGTERM .
578 .It Sy sig_reload
579 Signal to send the processes to reload in the default
580 .Sy reload
581 method.
582 Defaults to
583 .Dv SIGHUP .
584 .El
585 .Pp
586 For a given method
587 .Ar argument ,
588 if
589 .Ar argument Ns Sy _cmd
590 is not defined, then a default method is provided by
591 .Sy run_rc_command :
592 .Bl -tag -width "argument" -offset indent
593 .It Sy Argument
594 .Sy Default method
595 .It Sy start
596 If
597 .Sy command
598 is not running and
599 .Ic checkyesno Sy rcvar
600 succeeds, start
601 .Sy command .
602 .It Sy stop
603 Determine the PIDs of
604 .Sy command
605 with
606 .Ic check_pidfile
607 or
608 .Ic check_process
609 (as appropriate),
610 .Ic kill Sy sig_stop
611 those PIDs, and run
612 .Ic wait_for_pids
613 on those PIDs.
614 .It Sy reload
615 Similar to
616 .Sy stop ,
617 except that it uses
618 .Sy sig_reload
619 instead, and doesn't run
620 .Ic wait_for_pids .
621 .It Sy restart
622 Runs the
623 .Sy stop
624 method, then the
625 .Sy start
626 method.
627 .It Sy status
628 Show the PID of
629 .Sy command ,
630 or some other script specific status operation.
631 .It Sy poll
632 Wait for
633 .Sy command
634 to exit.
635 .It Sy rcvar
636 Display which
637 .Xr rc.conf 5
638 variable is used (if any).
639 This method always works, even if the appropriate
640 .Xr rc.conf 5
641 variable is set to
642 .Sq NO .
643 .El
644 .Pp
645 The following variables are available to the methods
646 (such as
647 .Ar argument Ns Sy _cmd )
648 as well as after
649 .Ic run_rc_command
650 has completed:
651 .Bl -tag -width "rc_flags" -offset indent
652 .It Sy rc_arg
653 Argument provided to
654 .Sy run_rc_command ,
655 after fast and force processing has been performed.
656 .It Sy rc_flags
657 Flags to start the default command with.
658 Defaults to
659 .Sy ${name}_flags ,
660 unless overridden by the environment variable
661 .Sq Ev flags .
662 This variable may be changed by the
663 .Ar argument Ns Sy _precmd
664 method.
665 .It Sy rc_pid
666 PID of
667 .Sy command
668 (if appropriate).
669 .It Sy rc_fast
670 Not empty if
671 .Dq fast
672 prefix was used.
673 .It Sy rc_force
674 Not empty if
675 .Dq force
676 prefix was used.
677 .El
678 .It Ic run_rc_script Ar file Ar argument
679 Start the script
680 .Ar file
681 with an argument of
682 .Ar argument ,
683 and handle the return value from the script.
684 .Pp
685 Various shell variables are unset before
686 .Ar file
687 is started:
688 .Bd -ragged -offset indent
689 .Sy name ,
690 .Sy command ,
691 .Sy command_args ,
692 .Sy command_interpreter ,
693 .Sy extra_commands ,
694 .Sy pidfile ,
695 .Sy rcvar ,
696 .Sy required_dirs ,
697 .Sy required_files ,
698 .Sy required_vars ,
699 .Ar argument Ns Sy _cmd ,
700 .Ar argument Ns Sy _precmd .
701 .Ar argument Ns Sy _postcmd .
702 .Ed
703 .Pp
704 The startup behaviour of
705 .Ar file
706 depends upon the following checks:
707 .Bl -enum
708 .It
709 If
710 .Ar file
711 ends in
712 .Pa .sh ,
713 it is sourced into the current shell.
714 .It
715 If
716 .Ar file
717 appears to be a backup or scratch file
718 (e.g., with a suffix of
719 .Sq ~ ,
720 .Sq # ,
721 .Sq .OLD ,
722 or
723 .Sq .orig ) ,
724 ignore it.
725 .It
726 If
727 .Ar file
728 is not executable, ignore it.
729 .It
730 If the
731 .Xr rc.conf 5
732 variable
733 .Sy rc_fast_and_loose
734 is empty,
735 source
736 .Ar file
737 in a sub shell,
738 otherwise source
739 .Ar file
740 into the current shell.
741 .It
742 If
743 .Ar file
744 contains the
745 .Xr rcorder 8
746 keyword
747 .Dq interactive ,
748 then the command is executed using
749 .Ic no_rc_postprocess .
750 .El
751 .It Ic stop_boot
752 Prevent booting to multiuser mode.
753 If the
754 .Sy autoboot
755 variable is
756 .Sq yes ,
757 then a
758 .Sy SIGTERM
759 signal is sent to the parent
760 process (which is assumed to be
761 .Xr rc 8 ) .
762 Otherwise, the shell exits with status
763 .Li 1 .
764 .It Ic twiddle
765 Display one of the characters
766 .Sq \&/ , \&- , \&\e , \&| ,
767 followed by a backspace.
768 Repeated calls to this function will create the appearance of a spinning
769 symbol, as a different character is displayed on each call.
770 Output is to
771 .Pa /dev/tty ,
772 so this function may be useful even inside a script whose output
773 has been redirected.
774 .It Ic wait_for_pids Op Ar pid Op Ar ...
775 Wait until all of the provided
776 .Ar pids
777 don't exist any more, printing the list of outstanding
778 .Ar pids
779 every two seconds.
780 .It Ic warn Ar message
781 Display a warning message to
782 .Em stderr
783 and log it to the system log
784 using
785 .Xr logger 1 .
786 The warning message consists of the script name
787 (from
788 .Sy $0 ) ,
789 followed by
790 .Dq ": WARNING: " ,
791 and then
792 .Ar message .
793 .It Ic yesno_to_truefalse Ar var
794 Change the value of the specified variable from any of the
795 forms acceptable to the
796 .Ic checkyesno
797 function, to
798 .Dq true
799 or
800 .Dq false .
801 .El
802 .Sh FILES
803 .Bl -tag -width /etc/rc.subr -compact
804 .It Pa /etc/rc.subr
805 The
806 .Nm
807 file resides in
808 .Pa /etc .
809 .El
810 .Sh SEE ALSO
811 .Xr rc.conf 5 ,
812 .Xr rc 8
813 .Sh HISTORY
814 .Nm
815 appeared in
816 .Nx 1.3 .
817 The
818 .Xr rc.d 8
819 support functions appeared in
820 .Nx 1.5 .
821 Support for the
822 .Xr rc 8
823 post-processor appeared in
824 .Nx 6.0 .