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