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 an 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 Va ${name}_env 527A list of environment variables to run 528.Va command 529with. 530This will be passed as arguments to 531.Xr env 1 532utility. 533.It Sy ${name}_flags 534Arguments to call 535.Sy command 536with. 537This is usually set in 538.Xr rc.conf 5 , 539and not in the 540.Xr rc.d 8 541script. 542The environment variable 543.Sq Ev flags 544can be used to override this. 545.It Sy ${name}_nice 546.Xr nice 1 547level to run 548.Sy command 549as. 550Only supported after 551.Pa /usr 552is mounted. 553.It Sy ${name}_user 554User to run 555.Sy command 556as, using 557.Xr chroot 8 . 558if 559.Sy ${name}_chroot 560is set, otherwise 561uses 562.Xr su 1 . 563Only supported after 564.Pa /usr 565is mounted. 566.It Sy ${name}_group 567Group to run the chrooted 568.Sy command 569as. 570.It Sy ${name}_groups 571Comma separated list of supplementary groups to run the chrooted 572.Sy command 573with. 574.It Va ${name}_prepend 575Commands to be prepended to 576.Va command . 577This is a generic version of 578.Va ${name}_env 579or 580.Va ${name}_nice . 581.It Ar argument Ns Sy _cmd 582Shell commands which override the default method for 583.Ar argument . 584.It Ar argument Ns Sy _precmd 585Shell commands to run just before running 586.Ar argument Ns Sy _cmd 587or the default method for 588.Ar argument . 589If this returns a non-zero exit code, the main method is not performed. 590If the default method is being executed, this check is performed after 591the 592.Sy required_* 593checks and process (non-)existence checks. 594.It Ar argument Ns Sy _postcmd 595Shell commands to run if running 596.Ar argument Ns Sy _cmd 597or the default method for 598.Ar argument 599returned a zero exit code. 600.It Sy sig_stop 601Signal to send the processes to stop in the default 602.Sy stop 603method. 604Defaults to 605.Dv SIGTERM . 606.It Sy sig_reload 607Signal to send the processes to reload in the default 608.Sy reload 609method. 610Defaults to 611.Dv SIGHUP . 612.El 613.Pp 614For a given method 615.Ar argument , 616if 617.Ar argument Ns Sy _cmd 618is not defined, then a default method is provided by 619.Sy run_rc_command : 620.Bl -tag -width "argument" -offset indent 621.It Sy Argument 622.Sy Default method 623.It Sy start 624If 625.Sy command 626is not running and 627.Ic checkyesno Sy rcvar 628succeeds, start 629.Sy command . 630.It Sy stop 631Determine the PIDs of 632.Sy command 633with 634.Ic check_pidfile 635or 636.Ic check_process 637(as appropriate), 638.Ic kill Sy sig_stop 639those PIDs, and run 640.Ic wait_for_pids 641on those PIDs. 642.It Sy reload 643Similar to 644.Sy stop , 645except that it uses 646.Sy sig_reload 647instead, and doesn't run 648.Ic wait_for_pids . 649.It Sy restart 650Runs the 651.Sy stop 652method, then the 653.Sy start 654method. 655.It Sy status 656Show the PID of 657.Sy command , 658or some other script specific status operation. 659.It Sy poll 660Wait for 661.Sy command 662to exit. 663.It Sy rcvar 664Display which 665.Xr rc.conf 5 666variable is used (if any). 667This method always works, even if the appropriate 668.Xr rc.conf 5 669variable is set to 670.Sq NO . 671.El 672.Pp 673The following variables are available to the methods 674(such as 675.Ar argument Ns Sy _cmd ) 676as well as after 677.Ic run_rc_command 678has completed: 679.Bl -tag -width "rc_flags" -offset indent 680.It Sy rc_arg 681Argument provided to 682.Sy run_rc_command , 683after fast and force processing has been performed. 684.It Sy rc_flags 685Flags to start the default command with. 686Defaults to 687.Sy ${name}_flags , 688unless overridden by the environment variable 689.Sq Ev flags . 690This variable may be changed by the 691.Ar argument Ns Sy _precmd 692method. 693.It Sy rc_pid 694PID of 695.Sy command 696(if appropriate). 697.It Sy rc_fast 698Not empty if 699.Dq fast 700prefix was used. 701.It Sy rc_force 702Not empty if 703.Dq force 704prefix was used. 705.El 706.It Ic run_rc_script Ar file Ar argument 707Start the script 708.Ar file 709with an argument of 710.Ar argument , 711and handle the return value from the script. 712.Pp 713Various shell variables are unset before 714.Ar file 715is started: 716.Bd -ragged -offset indent 717.Sy name , 718.Sy command , 719.Sy command_args , 720.Sy command_interpreter , 721.Sy extra_commands , 722.Sy pidfile , 723.Sy rcvar , 724.Sy required_dirs , 725.Sy required_files , 726.Sy required_vars , 727.Ar argument Ns Sy _cmd , 728.Ar argument Ns Sy _precmd . 729.Ar argument Ns Sy _postcmd . 730.Ed 731.Pp 732The startup behaviour of 733.Ar file 734depends upon the following checks: 735.Bl -enum 736.It 737If 738.Ar file 739ends in 740.Pa .sh , 741it is sourced into the current shell. 742.It 743If 744.Ar file 745appears to be a backup or scratch file 746(e.g., with a suffix of 747.Sq ~ , 748.Sq # , 749.Sq .OLD , 750or 751.Sq .orig ) , 752ignore it. 753.It 754If 755.Ar file 756is not executable, ignore it. 757.It 758If the 759.Xr rc.conf 5 760variable 761.Sy rc_fast_and_loose 762is empty, 763source 764.Ar file 765in a sub shell, 766otherwise source 767.Ar file 768into the current shell. 769.El 770.It Ic set_rcvar Op Ar base 771Set the variable name required to start a service. In 772.Dx 773a daemon is usually controlled by an 774.Xr rc.conf 5 775variable consisting of a daemon's name optionally postfixed by the string 776.Sy "_enable" . 777When the following line is included in a script 778.Pp 779.Dl rcvar=`set_rcvar` 780.Pp 781This function will use the value of the 782.Sy $name 783variable, which should be defined by the calling script, to construct the appropriate 784.Xr rc.conf 5 785knob. If the 786.Ar base 787argument is set it will use 788.Ar base 789instead of 790.Sy $name . 791.It Ic wait_for_pids Op Ar pid Op Ar ... 792Wait until all of the provided 793.Ar pids 794don't exist any more, printing the list of outstanding 795.Ar pids 796every two seconds. 797.It Ic warn Ar message 798Display a warning message to 799.Em stderr 800and log it to the system log 801using 802.Xr logger 1 . 803The warning message consists of the script name 804(from 805.Sy $0 ) , 806followed by 807.Dq ": WARNING: " , 808and then 809.Ar message . 810.El 811.Sh FILES 812.Bl -tag -width /etc/rc.subr -compact 813.It Pa /etc/rc.subr 814The 815.Nm 816file resides in 817.Pa /etc . 818.El 819.Sh SEE ALSO 820.Xr rc.conf 5 , 821.Xr rc 8 822.Sh HISTORY 823.Nm 824appeared in 825.Nx 1.3 . 826The 827.Xr rc.d 8 828support functions appeared in 829.Nx 1.5 . 830.Nm 831first appeared in 832.Fx 5.0 . 833