1.\" $NetBSD: rc.subr.8,v 1.18 2007/12/31 15:31:43 ad 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 Ar argument Ns Sy _cmd 489Shell commands which override the default method for 490.Ar argument . 491.It Ar argument Ns Sy _precmd 492Shell commands to run just before running 493.Ar argument Ns Sy _cmd 494or the default method for 495.Ar argument . 496If this returns a non-zero exit code, the main method is not performed. 497If the default method is being executed, this check is performed after 498the 499.Sy required_* 500checks and process (non-)existence checks. 501.It Ar argument Ns Sy _postcmd 502Shell commands to run if running 503.Ar argument Ns Sy _cmd 504or the default method for 505.Ar argument 506returned a zero exit code. 507.It Sy sig_stop 508Signal to send the processes to stop in the default 509.Sy stop 510method. 511Defaults to 512.Dv SIGTERM . 513.It Sy sig_reload 514Signal to send the processes to reload in the default 515.Sy reload 516method. 517Defaults to 518.Dv SIGHUP . 519.El 520.Pp 521For a given method 522.Ar argument , 523if 524.Ar argument Ns Sy _cmd 525is not defined, then a default method is provided by 526.Sy run_rc_command : 527.Bl -tag -width "argument" -offset indent 528.It Sy Argument 529.Sy Default method 530.It Sy start 531If 532.Sy command 533is not running and 534.Ic checkyesno Sy rcvar 535succeeds, start 536.Sy command . 537.It Sy stop 538Determine the PIDs of 539.Sy command 540with 541.Ic check_pidfile 542or 543.Ic check_process 544(as appropriate), 545.Ic kill Sy sig_stop 546those PIDs, and run 547.Ic wait_for_pids 548on those PIDs. 549.It Sy reload 550Similar to 551.Sy stop , 552except that it uses 553.Sy sig_reload 554instead, and doesn't run 555.Ic wait_for_pids . 556.It Sy restart 557Runs the 558.Sy stop 559method, then the 560.Sy start 561method. 562.It Sy status 563Show the PID of 564.Sy command , 565or some other script specific status operation. 566.It Sy poll 567Wait for 568.Sy command 569to exit. 570.It Sy rcvar 571Display which 572.Xr rc.conf 5 573variable is used (if any). 574This method always works, even if the appropriate 575.Xr rc.conf 5 576variable is set to 577.Sq NO . 578.El 579.Pp 580The following variables are available to the methods 581(such as 582.Ar argument Ns Sy _cmd ) 583as well as after 584.Ic run_rc_command 585has completed: 586.Bl -tag -width "rc_flags" -offset indent 587.It Sy rc_arg 588Argument provided to 589.Sy run_rc_command , 590after fast and force processing has been performed. 591.It Sy rc_flags 592Flags to start the default command with. 593Defaults to 594.Sy ${name}_flags , 595unless overridden by the environment variable 596.Sq Ev flags . 597This variable may be changed by the 598.Ar argument Ns Sy _precmd 599method. 600.It Sy rc_pid 601PID of 602.Sy command 603(if appropriate). 604.It Sy rc_fast 605Not empty if 606.Dq fast 607prefix was used. 608.It Sy rc_force 609Not empty if 610.Dq force 611prefix was used. 612.El 613.It Ic run_rc_script Ar file Ar argument 614Start the script 615.Ar file 616with an argument of 617.Ar argument , 618and handle the return value from the script. 619.Pp 620Various shell variables are unset before 621.Ar file 622is started: 623.Bd -ragged -offset indent 624.Sy name , 625.Sy command , 626.Sy command_args , 627.Sy command_interpreter , 628.Sy extra_commands , 629.Sy pidfile , 630.Sy rcvar , 631.Sy required_dirs , 632.Sy required_files , 633.Sy required_vars , 634.Ar argument Ns Sy _cmd , 635.Ar argument Ns Sy _precmd . 636.Ar argument Ns Sy _postcmd . 637.Ed 638.Pp 639The startup behaviour of 640.Ar file 641depends upon the following checks: 642.Bl -enum 643.It 644If 645.Ar file 646ends in 647.Pa .sh , 648it is sourced into the current shell. 649.It 650If 651.Ar file 652appears to be a backup or scratch file 653(e.g., with a suffix of 654.Sq ~ , 655.Sq # , 656.Sq .OLD , 657or 658.Sq .orig ) , 659ignore it. 660.It 661If 662.Ar file 663is not executable, ignore it. 664.It 665If the 666.Xr rc.conf 5 667variable 668.Sy rc_fast_and_loose 669is empty, 670source 671.Ar file 672in a sub shell, 673otherwise source 674.Ar file 675into the current shell. 676.El 677.It Ic stop_boot 678Prevent booting to multiuser mode. 679If the 680.Sy autoboot 681variable is 682.Sq yes , 683then a 684.Sy SIGTERM 685signal is sent to the parent 686process (which is assumed to be 687.Xr rc 8 ) . 688Otherwise, the shell exits with status 689.Li 1 . 690.It Ic wait_for_pids Op Ar pid Op Ar ... 691Wait until all of the provided 692.Ar pids 693don't exist any more, printing the list of outstanding 694.Ar pids 695every two seconds. 696.It Ic warn Ar message 697Display a warning message to 698.Em stderr 699and log it to the system log 700using 701.Xr logger 1 . 702The warning message consists of the script name 703(from 704.Sy $0 ) , 705followed by 706.Dq ": WARNING: " , 707and then 708.Ar message . 709.El 710.Sh FILES 711.Bl -tag -width /etc/rc.subr -compact 712.It Pa /etc/rc.subr 713The 714.Nm 715file resides in 716.Pa /etc . 717.El 718.Sh SEE ALSO 719.Xr rc.conf 5 , 720.Xr rc 8 721.Sh HISTORY 722.Nm 723appeared in 724.Nx 1.3 . 725The 726.Xr rc.d 8 727support functions appeared in 728.Nx 1.5 . 729