1.\" $NetBSD: rc.subr.8,v 1.8 2002/04/18 11:14:33 lukem 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 Ar argument Ns Sy _cmd 422Shell commands which override the default method for 423.Ar argument . 424.It Ar argument Ns Sy _precmd 425Shell commands to run just before running 426.Ar argument Ns Sy _cmd 427or the default method for 428.Ar argument . 429If this returns a non-zero exit code, the main method is not performed. 430If the default method is being executed, this check is performed after 431the 432.Sy required_* 433checks and process (non-)existence checks. 434.It Ar argument Ns Sy _postcmd 435Shell commands to run if running 436.Ar argument Ns Sy _cmd 437or the default method for 438.Ar argument 439returned a zero exit code. 440.It Sy sig_stop 441Signal to send the processes to stop in the default 442.Sy stop 443method. 444Defaults to 445.Dv SIGTERM . 446.It Sy sig_reload 447Signal to send the processes to reload in the default 448.Sy reload 449method. 450Defaults to 451.Dv SIGHUP . 452.El 453.Pp 454For a given method 455.Ar argument , 456if 457.Ar argument Ns Sy _cmd 458is not defined, then a default method is provided by 459.Sy run_rc_command : 460.Bl -tag -width "argument" -offset indent 461.It Sy Argument 462.Sy Default method 463.It Sy start 464If 465.Sy command 466is not running and 467.Ic checkyesno Sy rcvar 468succeeds, start 469.Sy command . 470.It Sy stop 471Determine the PIDs of 472.Sy command 473with 474.Ic check_pidfile 475or 476.Ic check_process 477(as appropriate), 478.Ic kill Sy sig_stop 479those PIDs, and run 480.Ic wait_for_pids 481on those PIDs. 482.It Sy reload 483Similar to 484.Sy stop , 485except that it uses 486.Sy sig_reload 487instead, and doesn't run 488.Ic wait_for_pids . 489.It Sy restart 490Runs the 491.Sy stop 492method, then the 493.Sy start 494method. 495.It Sy status 496Show the PID of 497.Sy command , 498or some other script specific status operation. 499.It Sy poll 500Wait for 501.Sy command 502to exit. 503.It Sy rcvar 504Display which 505.Xr rc.conf 5 506variable is used (if any). 507This method always works, even if the appropriate 508.Xr rc.conf 5 509variable is set to 510.Sq NO . 511.El 512.Pp 513The following variables are available to the methods 514(such as 515.Ar argument Ns Sy _cmd ) 516as well as after 517.Ic run_rc_command 518has completed: 519.Bl -tag -width "rc_flags" -offset indent 520.It Sy rc_arg 521Argument provided to 522.Sy run_rc_command , 523after fast and force processing has been performed. 524.It Sy rc_flags 525Flasg to start the default command with. 526Defaults to 527.Sy ${name}_flags , 528unless overridden by the environment variable 529.Sq Ev flags . 530This variable may be changed by the 531.Ar argument Ns Sy _precmd 532method. 533.It Sy rc_pid 534PID of 535.Sy command 536(if appropriate). 537.It Sy rc_fast 538Not empty if 539.Dq fast 540prefix was used. 541.It Sy rc_force 542Not empty if 543.Dq force 544prefix was used. 545.El 546.It Ic run_rc_script Ar file Ar argument 547Start the script 548.Ar file 549with an argument of 550.Ar argument , 551and handle the return value from the script. 552.Pp 553Various shell variables are unset before 554.Ar file 555is started: 556.Bd -ragged -offset indent 557.Sy name , 558.Sy command , 559.Sy command_args , 560.Sy command_interpreter , 561.Sy extra_commands , 562.Sy pidfile , 563.Sy rcvar , 564.Sy required_dirs , 565.Sy required_files , 566.Sy required_vars , 567.Ar argument Ns Sy _cmd , 568.Ar argument Ns Sy _precmd . 569.Ar argument Ns Sy _postcmd . 570.Ed 571.Pp 572The startup behaviour of 573.Ar file 574depends upon the following checks: 575.Bl -enum 576.It 577If 578.Ar file 579ends in 580.Pa .sh , 581it is sourced into the current shell. 582.It 583If 584.Ar file 585appears to be a backup or scratch file 586(e.g., with a suffix of 587.Sq ~ , 588.Sq # , 589.Sq .OLD , 590or 591.Sq .orig ) , 592ignore it. 593.It 594If 595.Ar file 596is not executable, ignore it. 597.It 598If the 599.Xr rc.conf 5 600variable 601.Sy rc_fast_and_loose 602is empty, 603source 604.Ar file 605in a sub shell, 606otherwise source 607.Ar file 608into the current shell. 609.El 610.It Ic wait_for_pids Op Ar pid Op Ar ... 611Wait until all of the provided 612.Ar pids 613don't exist any more, printing the list of outstanding 614.Ar pids 615every two seconds. 616.It Ic warn Ar message 617Display a warning message to 618.Em stderr 619and log it to the system log 620using 621.Xr logger 1 . 622The warning message consists of the script name 623(from 624.Sy $0 ) , 625followed by 626.Dq ": WARNING: " , 627and then 628.Ar message . 629.El 630.Sh FILES 631.Bl -tag -width /etc/rc.subr -compact 632.It Pa /etc/rc.subr 633The 634.Nm 635file resides in 636.Pa /etc . 637.El 638.Sh SEE ALSO 639.Xr rc.conf 5 , 640.Xr rc 8 641.Sh HISTORY 642.Nm 643appeared in 644.Nx 1.3 . 645The 646.Xr rc.d 8 647support functions appeared in 648.Nx 1.5 . 649