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