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