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