1.\" $NetBSD: rc.subr.8,v 1.9 2002/07/08 16:14:55 atatat Exp $ 2.\" 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 April 18, 2002 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 err Ar exitval Ar message 57.It 58.Ic load_rc_config Ar command 59.It 60.Ic mount_critical_filesystems Ar type 61.It 62.Ic rc_usage Ar command Op Ar ... 63.It 64.Ic reverse_list Ar item Op Ar ... 65.It 66.Ic run_rc_command Ar argument 67.It 68.Ic run_rc_script Ar file Ar argument 69.It 70.Ic wait_for_pids Op Ar pid Op Ar ... 71.It 72.Ic warn Ar message 73.El 74.Sh DESCRIPTION 75.Nm 76contains commonly used shell script functions which are used by 77various scripts such as 78.Xr rc 8 , 79and the periodic system services which are controlled by 80.Xr daily.conf 5 , 81.Xr monthly.conf 5 , 82.Xr security.conf 5 , 83and 84.Xr weekly.conf 5 . 85.Pp 86The 87.Nm 88functions are accessed by sourcing 89.Pa /etc/rc.subr 90into the current shell. 91.Pp 92The following shell functions are available: 93.Bl -tag -width 4n 94.It Xo 95.Ic backup_file Ar action Ar file Ar current Ar backup 96.Xc 97Make a backup copy of 98.Ar file 99into 100.Ar current . 101If the 102.Xr rc.conf 5 103variable 104.Sy backup_uses_rcs 105is 106.Sq YES , 107use 108.Xr rcs 1 109to archive the previous version of 110.Ar current , 111otherwise save the previous version of 112.Ar current 113as 114.Ar backup . 115.Pp 116.Ar action 117may be one of the following: 118.Bl -tag -width remove 119.It Sy add 120.Ar file 121is now being backed up by or possibly re-entered into this backup mechanism. 122.Ar current 123is created, and if necessary, the 124.Xr rcs 1 125files are created as well. 126.It Sy update 127.Ar file 128has changed and needs to be backed up. 129If 130.Ar current 131exists, it is copied to 132.Ar backup 133or checked into 134.Xr rcs 1 135(if the repository file is old), 136and then 137.Ar file 138is copied to 139.Ar current . 140.It Sy remove 141.Ar file 142is no longer being tracked by this backup mechanism. 143If 144.Xr rcs 1 145is being used, an empty file is checked in and 146.Ar current 147is removed, 148otherwise 149.Ar current 150is moved to 151.Ar backup . 152.El 153.It Ic checkyesno Ar var 154Return 0 if 155.Ar var 156is defined to 157.Sq YES , 158.Sq TRUE , 159.Sq ON , 160or 161.Sq 1 . 162Return 1 if 163.Ar var 164is defined to 165.Sq NO , 166.Sq FALSE , 167.Sq OFF , 168or 169.Sq 0 . 170Otherwise, warn that 171.Ar var 172is not set correctly. 173The values are case insensitive. 174.It Xo 175.Ic check_pidfile 176.Ar pidfile 177.Ar procname 178.Op Ar interpreter 179.Xc 180Parses the first word of the first line of 181.Ar pidfile 182for a PID, and ensures that the process with that PID 183is running and its first argument matches 184.Ar procname . 185Prints the matching PID if successfull, otherwise nothing. 186If 187.Ar interpreter 188is provided, parse the first line of 189.Ar procname , 190ensure that the line is of the form 191.Dl #! interpreter [...] 192and use 193.Ar interpreter 194with its optional arguments and 195.Ar procname 196appended as the process string to search for. 197.It Ic check_process Ar procname Op Ar interpreter 198Prints the PIDs of any processes that are running with a first 199argument that matches 200.Ar procname . 201.Ar interpreter 202is handled as per 203.Ic check_pidfile . 204.It Ic err Ar exitval Ar message 205Display an error message to 206.Em stderr , 207log it to the system log 208using 209.Xr logger 1 , 210and 211.Cm exit 212with an exit value of 213.Ar exitval . 214The error message consists of the script name 215(from 216.Sy $0 ) , 217followed by 218.Dq ": ERROR: " , 219and then 220.Ar message . 221.It Ic load_rc_config Ar command 222Source in the configuration files for 223.Ar command . 224First, 225.Pa /etc/rc.conf 226is sourced if it has not yet been read in. 227Then, 228.Pa /etc/rc.conf.d/ Ns Ar command 229is sourced if it is an existing file. 230The latter may also contain other variable assignments to override 231.Ic run_rc_command 232arguments defined by the calling script, to provide an easy 233mechanism for an administrator to override the behaviour of a given 234.Xr rc.d 8 235script without requiring the editing of that script. 236.It Ic mount_critical_filesystems Ar type 237Go through a list of critical file systems, 238as found in the 239.Xr rc.conf 5 240variable 241.Sy critical_filesystems_ Ns Ar type , 242mounting each one that 243is not currently mounted. 244.It Ic rc_usage Ar command Op Ar ... 245Print a usage message for 246.Sy $0 , 247with 248.Ar commands 249being the list of valid arguments 250prefixed by 251.Dq "[fast|force]" . 252.It Ic reverse_list Ar item Op Ar ... 253Print the list of 254.Ar items 255in reverse order. 256.It Ic run_rc_command Ar argument 257Run the 258.Ar argument 259method for the current 260.Xr rc.d 8 261script, based on the settings of various shell variables. 262.Ic run_rc_command 263is extremely flexible, and allows fully functional 264.Xr rc.d 8 265scripts to be implemented in a small amount of shell code. 266.Pp 267.Ar argument 268is searched for in the list of supported commands, which may be one 269of: 270.Dl start stop restart rcvar 271as well as any word listed in the optional variable 272.Sy extra_commands . 273If 274.Sy pidfile 275or 276.Sy procname 277is set, also allow: 278.Dl status poll 279.Pp 280.Ar argument 281may have one of the following prefixes which alters its operation: 282.Bl -tag -width "Prefix" -offset indent -compact 283.It Sy Prefix 284.Sy Operation 285.It Li fast 286Skip the check for an existing running process, 287and sets 288.Sy rc_fast=YES . 289.It Li force 290Skip the checks for 291.Sy rcvar 292being set to yes, 293and sets 294.Sy rc_force=YES . 295This ignores 296.Ar argument Ns Sy _precmd 297returning non-zero, and ignores any of the 298.Sy required_* 299tests failing . 300.El 301.Pp 302.Ic run_rc_command 303uses the following shell variables to control its behaviour. 304Unless otherwise stated, these are optional. 305.Bl -tag -width procname -offset indent 306.It Sy name 307The name of this script. 308This is not optional. 309.It Sy rcvar 310The value of 311.Sy rcvar 312is checked with 313.Ic checkyesno 314to determine if this method should be run. 315.It Sy command 316Full path to the command. 317Not required if 318.Ar argument Ns Sy _cmd 319is defined for each supported keyword. 320.It Sy command_args 321Optional arguments and/or shell directives for 322.Sy command . 323.It Sy command_interpreter 324.Sy command 325is started with 326.Dl #! command_interpreter [...] 327which results in its 328.Xr ps 1 329command being 330.Dl command_interpreter [...] command 331so use that string to find the PID(s) of the running command 332rather than 333.Ql command . 334.It Sy extra_commands 335Extra commands/keywords/arguments supported. 336.It Sy pidfile 337Path to pid file. 338Used to determine the PID(s) of the running command. 339If 340.Sy pidfile 341is set, use 342.Dl check_pidfile $pidfile $procname 343to find the PID. 344Otherwise, if 345.Sy command 346is set, use 347.Dl check_process $procname 348to find the PID. 349.It Sy procname 350Process name to check for. 351Defaults to the value of 352.Sy command . 353.It Sy required_dirs 354Check for the existence of the listed directories 355before running the default start method. 356.It Sy required_files 357Check for the readability of the listed files 358before running the default start method. 359.It Sy required_vars 360Perform 361.Ic checkyesno 362on each of the list variables 363before running the default start method. 364.It Sy ${name}_chdir 365Directory to 366.Ic cd 367to before running 368.Sy command , 369if 370.Sy ${name}_chroot 371is not provided. 372.It Sy ${name}_chroot 373Directory to 374.Xr chroot 8 375to before running 376.Sy command . 377Only supported after 378.Pa /usr 379is mounted. 380.It Sy ${name}_flags 381Arguments to call 382.Sy command 383with. 384This is usually set in 385.Xr rc.conf 5 , 386and not in the 387.Xr rc.d 8 388script. 389The environment variable 390.Sq Ev flags 391can be used to override this. 392.It Sy ${name}_nice 393.Xr nice 1 394level to run 395.Sy command 396as. 397Only supported after 398.Pa /usr 399is mounted. 400.It Sy ${name}_user 401User to run 402.Sy command 403as, using 404.Xr chroot 8 . 405if 406.Sy ${name}_chroot 407is set, otherwise 408uses 409.Xr su 1 . 410Only supported after 411.Pa /usr 412is mounted. 413.It Sy ${name}_group 414Group to run the chrooted 415.Sy command 416as. 417.It Sy ${name}_groups 418Comma separated list of supplementary groups to run the chrooted 419.Sy command 420with. 421.It Sy ${name}_systrace 422Flags passed to 423.Xr systrace 1 , 424if it is used. 425Setting this variable enables systracing 426of the given program. The use of 427.Sq -a 428is 429recommended so that the boot process is not 430stalled. In order to pass no flags to 431systrace, set this variable to 432.Sq -- . 433.It Ar argument Ns Sy _cmd 434Shell commands which override the default method for 435.Ar argument . 436.It Ar argument Ns Sy _precmd 437Shell commands to run just before running 438.Ar argument Ns Sy _cmd 439or the default method for 440.Ar argument . 441If this returns a non-zero exit code, the main method is not performed. 442If the default method is being executed, this check is performed after 443the 444.Sy required_* 445checks and process (non-)existence checks. 446.It Ar argument Ns Sy _postcmd 447Shell commands to run if running 448.Ar argument Ns Sy _cmd 449or the default method for 450.Ar argument 451returned a zero exit code. 452.It Sy sig_stop 453Signal to send the processes to stop in the default 454.Sy stop 455method. 456Defaults to 457.Dv SIGTERM . 458.It Sy sig_reload 459Signal to send the processes to reload in the default 460.Sy reload 461method. 462Defaults to 463.Dv SIGHUP . 464.El 465.Pp 466For a given method 467.Ar argument , 468if 469.Ar argument Ns Sy _cmd 470is not defined, then a default method is provided by 471.Sy run_rc_command : 472.Bl -tag -width "argument" -offset indent 473.It Sy Argument 474.Sy Default method 475.It Sy start 476If 477.Sy command 478is not running and 479.Ic checkyesno Sy rcvar 480succeeds, start 481.Sy command . 482.It Sy stop 483Determine the PIDs of 484.Sy command 485with 486.Ic check_pidfile 487or 488.Ic check_process 489(as appropriate), 490.Ic kill Sy sig_stop 491those PIDs, and run 492.Ic wait_for_pids 493on those PIDs. 494.It Sy reload 495Similar to 496.Sy stop , 497except that it uses 498.Sy sig_reload 499instead, and doesn't run 500.Ic wait_for_pids . 501.It Sy restart 502Runs the 503.Sy stop 504method, then the 505.Sy start 506method. 507.It Sy status 508Show the PID of 509.Sy command , 510or some other script specific status operation. 511.It Sy poll 512Wait for 513.Sy command 514to exit. 515.It Sy rcvar 516Display which 517.Xr rc.conf 5 518variable is used (if any). 519This method always works, even if the appropriate 520.Xr rc.conf 5 521variable is set to 522.Sq NO . 523.El 524.Pp 525The following variables are available to the methods 526(such as 527.Ar argument Ns Sy _cmd ) 528as well as after 529.Ic run_rc_command 530has completed: 531.Bl -tag -width "rc_flags" -offset indent 532.It Sy rc_arg 533Argument provided to 534.Sy run_rc_command , 535after fast and force processing has been performed. 536.It Sy rc_flags 537Flasg to start the default command with. 538Defaults to 539.Sy ${name}_flags , 540unless overridden by the environment variable 541.Sq Ev flags . 542This variable may be changed by the 543.Ar argument Ns Sy _precmd 544method. 545.It Sy rc_pid 546PID of 547.Sy command 548(if appropriate). 549.It Sy rc_fast 550Not empty if 551.Dq fast 552prefix was used. 553.It Sy rc_force 554Not empty if 555.Dq force 556prefix was used. 557.El 558.It Ic run_rc_script Ar file Ar argument 559Start the script 560.Ar file 561with an argument of 562.Ar argument , 563and handle the return value from the script. 564.Pp 565Various shell variables are unset before 566.Ar file 567is started: 568.Bd -ragged -offset indent 569.Sy name , 570.Sy command , 571.Sy command_args , 572.Sy command_interpreter , 573.Sy extra_commands , 574.Sy pidfile , 575.Sy rcvar , 576.Sy required_dirs , 577.Sy required_files , 578.Sy required_vars , 579.Ar argument Ns Sy _cmd , 580.Ar argument Ns Sy _precmd . 581.Ar argument Ns Sy _postcmd . 582.Ed 583.Pp 584The startup behaviour of 585.Ar file 586depends upon the following checks: 587.Bl -enum 588.It 589If 590.Ar file 591ends in 592.Pa .sh , 593it is sourced into the current shell. 594.It 595If 596.Ar file 597appears to be a backup or scratch file 598(e.g., with a suffix of 599.Sq ~ , 600.Sq # , 601.Sq .OLD , 602or 603.Sq .orig ) , 604ignore it. 605.It 606If 607.Ar file 608is not executable, ignore it. 609.It 610If the 611.Xr rc.conf 5 612variable 613.Sy rc_fast_and_loose 614is empty, 615source 616.Ar file 617in a sub shell, 618otherwise source 619.Ar file 620into the current shell. 621.El 622.It Ic wait_for_pids Op Ar pid Op Ar ... 623Wait until all of the provided 624.Ar pids 625don't exist any more, printing the list of outstanding 626.Ar pids 627every two seconds. 628.It Ic warn Ar message 629Display a warning message to 630.Em stderr 631and log it to the system log 632using 633.Xr logger 1 . 634The warning message consists of the script name 635(from 636.Sy $0 ) , 637followed by 638.Dq ": WARNING: " , 639and then 640.Ar message . 641.El 642.Sh FILES 643.Bl -tag -width /etc/rc.subr -compact 644.It Pa /etc/rc.subr 645The 646.Nm 647file resides in 648.Pa /etc . 649.El 650.Sh SEE ALSO 651.Xr rc.conf 5 , 652.Xr rc 8 653.Sh HISTORY 654.Nm 655appeared in 656.Nx 1.3 . 657The 658.Xr rc.d 8 659support functions appeared in 660.Nx 1.5 . 661