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