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