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