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