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