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 September 23, 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 enabled 383Return 0 if the service is enabled and 1 if it is not. 384This command does not print anything. 385.It Cm rcvar 386Display which 387.Xr rc.conf 5 388variables are used to control the startup of the service (if any). 389.El 390.Pp 391If 392.Va pidfile 393or 394.Va procname 395is set, also support: 396.Bl -tag -width ".Cm restart" -offset indent 397.It Cm poll 398Wait for the command to exit. 399.It Cm status 400Show the status of the process. 401.El 402.Pp 403Other supported commands are listed in the optional variable 404.Va extra_commands . 405.Pp 406.Ar argument 407may have one of the following prefixes which alters its operation: 408.Bl -tag -width ".Li force" -offset indent 409.It Li fast 410Skip the check for an existing running process, 411and sets 412.Va rc_fast Ns = Ns Li YES . 413.It Li force 414Skip the checks for 415.Va rcvar 416being set to 417.Dq Li YES , 418and sets 419.Va rc_force Ns = Ns Li YES . 420This ignores 421.Ar argument Ns Va _precmd 422returning non-zero, and ignores any of the 423.Va required_* 424tests failing, and always returns a zero exit status. 425.It Li one 426Skip the checks for 427.Va rcvar 428being set to 429.Dq Li YES , 430but performs all the other prerequisite tests. 431.It Li quiet 432Inhibits some verbose diagnostics. 433Currently, this includes messages 434.Qq Starting ${name} 435(as checked by 436.Ic check_startmsgs 437inside 438.Nm ) 439and errors about usage of services that are not enabled in 440.Xr rc.conf 5 . 441This prefix also sets 442.Va rc_quiet Ns = Ns Li YES . 443.Em Please, note: 444.Va rc_quiet 445is not intended to completely mask all debug and warning messages, 446but only certain small classes of them. 447.El 448.Pp 449.Ic run_rc_command 450uses the following shell variables to control its behaviour. 451Unless otherwise stated, these are optional. 452.Bl -tag -width ".Va procname" -offset indent 453.It Va name 454The name of this script. 455This is not optional. 456.It Va rcvar 457The value of 458.Va rcvar 459is checked with 460.Ic checkyesno 461to determine if this method should be run. 462.It Va command 463Full path to the command. 464Not required if 465.Ar argument Ns Va _cmd 466is defined for each supported keyword. 467Can be overridden by 468.Va ${name}_program . 469.It Va command_args 470Optional arguments and/or shell directives for 471.Va command . 472.It Va command_interpreter 473.Va command 474is started with: 475.Pp 476.Dl "#! command_interpreter [...]" 477.Pp 478which results in its 479.Xr ps 1 480command being: 481.Pp 482.Dl "command_interpreter [...] command" 483.Pp 484so use that string to find the PID(s) of the running command 485rather than 486.Va command . 487.It Va extra_commands 488Extra commands/keywords/arguments supported. 489.It Va pidfile 490Path to PID file. 491Used to determine the PID(s) of the running command. 492If 493.Va pidfile 494is set, use: 495.Pp 496.Dl "check_pidfile $pidfile $procname" 497.Pp 498to find the PID. 499Otherwise, if 500.Va command 501is set, use: 502.Pp 503.Dl "check_process $procname" 504.Pp 505to find the PID. 506.It Va procname 507Process name to check for. 508Defaults to the value of 509.Va command . 510.It Va required_dirs 511Check for the existence of the listed directories 512before running the 513.Cm start 514method. 515.It Va required_files 516Check for the readability of the listed files 517before running the 518.Cm start 519method. 520.It Va required_modules 521Ensure that the listed kernel modules are loaded 522before running the 523.Cm start 524method. 525This is done after invoking the commands from 526.Va start_precmd 527so that the missing modules are not loaded in vain 528if the preliminary commands indicate a error condition. 529A word in the list can have an optional 530.Dq Li : Ns Ar modname 531or 532.Dq Li ~ Ns Ar pattern 533suffix. 534The 535.Ar modname 536or 537.Ar pattern 538parameter is passed to 539.Ic load_kld 540through a 541.Fl m 542or 543.Fl e 544option, respectively. 545See the description of 546.Ic load_kld 547in this document for details. 548.It Va required_vars 549Perform 550.Ic checkyesno 551on each of the list variables 552before running the 553.Cm start 554method. 555.It Va ${name}_chdir 556Directory to 557.Ic cd 558to before running 559.Va command , 560if 561.Va ${name}_chroot 562is not provided. 563.It Va ${name}_chroot 564Directory to 565.Xr chroot 8 566to before running 567.Va command . 568Only supported after 569.Pa /usr 570is mounted. 571.It Va ${name}_flags 572Arguments to call 573.Va command 574with. 575This is usually set in 576.Xr rc.conf 5 , 577and not in the 578.Xr rc.d 8 579script. 580The environment variable 581.Sq Ev flags 582can be used to override this. 583.It Va ${name}_nice 584.Xr nice 1 585level to run 586.Va command 587as. 588Only supported after 589.Pa /usr 590is mounted. 591.It Va ${name}_program 592Full path to the command. 593Overrides 594.Va command 595if both are set, but has no effect if 596.Va command 597is unset. 598As a rule, 599.Va command 600should be set in the script while 601.Va ${name}_program 602should be set in 603.Xr rc.conf 5 . 604.It Va ${name}_user 605User to run 606.Va command 607as, using 608.Xr chroot 8 609if 610.Va ${name}_chroot 611is set, otherwise 612uses 613.Xr su 1 . 614Only supported after 615.Pa /usr 616is mounted. 617.It Va ${name}_group 618Group to run the chrooted 619.Va command 620as. 621.It Va ${name}_groups 622Comma separated list of supplementary groups to run the chrooted 623.Va command 624with. 625.It Ar argument Ns Va _cmd 626Shell commands which override the default method for 627.Ar argument . 628.It Ar argument Ns Va _precmd 629Shell commands to run just before running 630.Ar argument Ns Va _cmd 631or the default method for 632.Ar argument . 633If this returns a non-zero exit code, the main method is not performed. 634If the default method is being executed, this check is performed after 635the 636.Va required_* 637checks and process (non-)existence checks. 638.It Ar argument Ns Va _postcmd 639Shell commands to run if running 640.Ar argument Ns Va _cmd 641or the default method for 642.Ar argument 643returned a zero exit code. 644.It Va sig_stop 645Signal to send the processes to stop in the default 646.Cm stop 647method. 648Defaults to 649.Dv SIGTERM . 650.It Va sig_reload 651Signal to send the processes to reload in the default 652.Cm reload 653method. 654Defaults to 655.Dv SIGHUP . 656.El 657.Pp 658For a given method 659.Ar argument , 660if 661.Ar argument Ns Va _cmd 662is not defined, then a default method is provided by 663.Ic run_rc_command : 664.Bl -tag -width ".Sy Argument" -offset indent 665.It Sy Argument 666.Sy Default method 667.It Cm start 668If 669.Va command 670is not running and 671.Ic checkyesno Va rcvar 672succeeds, start 673.Va command . 674.It Cm stop 675Determine the PIDs of 676.Va command 677with 678.Ic check_pidfile 679or 680.Ic check_process 681(as appropriate), 682.Ic kill Va sig_stop 683those PIDs, and run 684.Ic wait_for_pids 685on those PIDs. 686.It Cm reload 687Similar to 688.Cm stop , 689except that it uses 690.Va sig_reload 691instead, and does not run 692.Ic wait_for_pids . 693Another difference from 694.Cm stop 695is that 696.Cm reload 697is not provided by default. 698It can be enabled via 699.Va extra_commands 700if appropriate: 701.Pp 702.Dl "extra_commands=reload" 703.It Cm restart 704Runs the 705.Cm stop 706method, then the 707.Cm start 708method. 709.It Cm status 710Show the PID of 711.Va command , 712or some other script specific status operation. 713.It Cm poll 714Wait for 715.Va command 716to exit. 717.It Cm rcvar 718Display which 719.Xr rc.conf 5 720variable is used (if any). 721This method always works, even if the appropriate 722.Xr rc.conf 5 723variable is set to 724.Dq Li NO . 725.El 726.Pp 727The following variables are available to the methods 728(such as 729.Ar argument Ns Va _cmd ) 730as well as after 731.Ic run_rc_command 732has completed: 733.Bl -tag -width ".Va rc_flags" -offset indent 734.It Va rc_arg 735Argument provided to 736.Ic run_rc_command , 737after fast and force processing has been performed. 738.It Va rc_flags 739Flags to start the default command with. 740Defaults to 741.Va ${name}_flags , 742unless overridden by the environment variable 743.Sq Ev flags . 744This variable may be changed by the 745.Ar argument Ns Va _precmd 746method. 747.It Va rc_pid 748PID of 749.Va command 750(if appropriate). 751.It Va rc_fast 752Not empty if 753.Dq Li fast 754prefix was used. 755.It Va rc_force 756Not empty if 757.Dq Li force 758prefix was used. 759.El 760.It Ic run_rc_script Ar file argument 761Start the script 762.Ar file 763with an argument of 764.Ar argument , 765and handle the return value from the script. 766.Pp 767Various shell variables are unset before 768.Ar file 769is started: 770.Bd -ragged -offset indent 771.Va name , 772.Va command , 773.Va command_args , 774.Va command_interpreter , 775.Va extra_commands , 776.Va pidfile , 777.Va rcvar , 778.Va required_dirs , 779.Va required_files , 780.Va required_vars , 781.Ar argument Ns Va _cmd , 782.Ar argument Ns Va _precmd . 783.Ar argument Ns Va _postcmd . 784.Ed 785.Pp 786The startup behaviour of 787.Ar file 788depends upon the following checks: 789.Bl -enum 790.It 791If 792.Ar file 793ends in 794.Pa .sh , 795it is sourced into the current shell. 796.It 797If 798.Ar file 799appears to be a backup or scratch file 800(e.g., with a suffix of 801.Pa ~ , # , .OLD , 802or 803.Pa .orig ) , 804ignore it. 805.It 806If 807.Ar file 808is not executable, ignore it. 809.It 810If the 811.Xr rc.conf 5 812variable 813.Va rc_fast_and_loose 814is empty, 815source 816.Ar file 817in a sub shell, 818otherwise source 819.Ar file 820into the current shell. 821.El 822.It Ic stop_boot Op Ar always 823Prevent booting to multiuser mode. 824If the 825.Va autoboot 826variable is set to 827.Ql yes , 828or 829.Ic checkyesno Ar always 830indicates a truth value, then a 831.Dv SIGTERM 832signal is sent to the parent 833process, which is assumed to be 834.Xr rc 8 . 835Otherwise, the shell exits with a non-zero status. 836.It Ic wait_for_pids Op Ar pid ... 837Wait until all of the provided 838.Ar pids 839do not exist any more, printing the list of outstanding 840.Ar pids 841every two seconds. 842.It Ic warn Ar message 843Display a warning message to 844.Va stderr 845and log it to the system log 846using 847.Xr logger 1 . 848The warning message consists of the script name 849(from 850.Va $0 ) , 851followed by 852.Dq Li ": WARNING: " , 853and then 854.Ar message . 855.El 856.Sh FILES 857.Bl -tag -width ".Pa /etc/rc.subr" -compact 858.It Pa /etc/rc.subr 859The 860.Nm 861file resides in 862.Pa /etc . 863.El 864.Sh SEE ALSO 865.Xr rc.conf 5 , 866.Xr rc 8 867.Sh HISTORY 868The 869.Nm 870script 871appeared in 872.Nx 1.3 . 873The 874.Xr rc.d 8 875support functions appeared in 876.Nx 1.5 . 877The 878.Nm 879script 880first appeared in 881.Fx 5.0 . 882