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