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.\" 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 January 6, 2004 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 successful, 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|one]" . 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.Bl -tag -width restart -offset indent 271.It Sy start 272Start the service. 273This should check that the service is to be started as specified by 274.Xr rc.conf 5 . 275Also checks if the service is already running and refuses to start if 276it is. 277This latter check is not performed by standard 278.Nx 279scripts if the system is starting directly to multi-user mode, to 280speed up the boot process. 281.It Sy stop 282If the service is to be started as specified by 283.Xr rc.conf 5 , 284stop the service. 285This should check that the service is running and complain if it's not. 286.It Sy restart 287Perform a 288.Sy stop 289then a 290.Sy start . 291Defaults to displaying the process ID of the program (if running). 292.It Sy rcvar 293Display which 294.Xr rc.conf 5 295variables are used to control the startup of the service (if any). 296.El 297.Pp 298If 299.Sy pidfile 300or 301.Sy procname 302is set, also support: 303.Bl -tag -width restart -offset indent 304.It Sy poll 305Wait for the command to exit. 306.It Sy status 307Show the status of the process. 308.El 309.Pp 310Other supported commands are listed in the optional variable 311.Sy extra_commands . 312.Pp 313.Ar argument 314may have one of the following prefixes which alters its operation: 315.Bl -tag -width "Prefix" -offset indent 316.It Sy fast 317Skip the check for an existing running process, 318and sets 319.Sy rc_fast=YES . 320.It Sy force 321Skip the checks for 322.Sy rcvar 323being set to yes, 324and sets 325.Sy rc_force=YES . 326This ignores 327.Ar argument Ns Sy _precmd 328returning non-zero, and ignores any of the 329.Sy required_* 330tests failing, and always returns a zero exit status. 331.It Sy one 332Skip the checks for 333.Sy rcvar 334being set to yes, but performs all the other prerequisite tests. 335.El 336.Pp 337.Ic run_rc_command 338uses the following shell variables to control its behaviour. 339Unless otherwise stated, these are optional. 340.Bl -tag -width procname -offset indent 341.It Sy name 342The name of this script. 343This is not optional. 344.It Sy rcvar 345The value of 346.Sy rcvar 347is checked with 348.Ic checkyesno 349to determine if this method should be run. 350.It Sy command 351Full path to the command. 352Not required if 353.Ar argument Ns Sy _cmd 354is defined for each supported keyword. 355.It Sy command_args 356Optional arguments and/or shell directives for 357.Sy command . 358.It Sy command_interpreter 359.Sy command 360is started with 361.Dl #! command_interpreter [...] 362which results in its 363.Xr ps 1 364command being 365.Dl command_interpreter [...] command 366so use that string to find the PID(s) of the running command 367rather than 368.Ql command . 369.It Sy extra_commands 370Extra commands/keywords/arguments supported. 371.It Sy pidfile 372Path to pid file. 373Used to determine the PID(s) of the running command. 374If 375.Sy pidfile 376is set, use 377.Dl check_pidfile $pidfile $procname 378to find the PID. 379Otherwise, if 380.Sy command 381is set, use 382.Dl check_process $procname 383to find the PID. 384.It Sy procname 385Process name to check for. 386Defaults to the value of 387.Sy command . 388.It Sy required_dirs 389Check for the existence of the listed directories 390before running the default start method. 391.It Sy required_files 392Check for the readability of the listed files 393before running the default start method. 394.It Sy required_vars 395Perform 396.Ic checkyesno 397on each of the list variables 398before running the default start method. 399.It Sy ${name}_chdir 400Directory to 401.Ic cd 402to before running 403.Sy command , 404if 405.Sy ${name}_chroot 406is not provided. 407.It Sy ${name}_chroot 408Directory to 409.Xr chroot 8 410to before running 411.Sy command . 412Only supported after 413.Pa /usr 414is mounted. 415.It Sy ${name}_flags 416Arguments to call 417.Sy command 418with. 419This is usually set in 420.Xr rc.conf 5 , 421and not in the 422.Xr rc.d 8 423script. 424The environment variable 425.Sq Ev flags 426can be used to override this. 427.It Sy ${name}_nice 428.Xr nice 1 429level to run 430.Sy command 431as. 432Only supported after 433.Pa /usr 434is mounted. 435.It Sy ${name}_user 436User to run 437.Sy command 438as, using 439.Xr chroot 8 . 440if 441.Sy ${name}_chroot 442is set, otherwise 443uses 444.Xr su 1 . 445Only supported after 446.Pa /usr 447is mounted. 448.It Sy ${name}_group 449Group to run the chrooted 450.Sy command 451as. 452.It Sy ${name}_groups 453Comma separated list of supplementary groups to run the chrooted 454.Sy command 455with. 456.It Sy ${name}_systrace 457Flags passed to 458.Xr systrace 1 , 459if it is used. 460Setting this variable enables systracing 461of the given program. The use of 462.Sq -a 463is 464recommended so that the boot process is not 465stalled. In order to pass no flags to 466systrace, set this variable to 467.Sq -- . 468.It Ar argument Ns Sy _cmd 469Shell commands which override the default method for 470.Ar argument . 471.It Ar argument Ns Sy _precmd 472Shell commands to run just before running 473.Ar argument Ns Sy _cmd 474or the default method for 475.Ar argument . 476If this returns a non-zero exit code, the main method is not performed. 477If the default method is being executed, this check is performed after 478the 479.Sy required_* 480checks and process (non-)existence checks. 481.It Ar argument Ns Sy _postcmd 482Shell commands to run if running 483.Ar argument Ns Sy _cmd 484or the default method for 485.Ar argument 486returned a zero exit code. 487.It Sy sig_stop 488Signal to send the processes to stop in the default 489.Sy stop 490method. 491Defaults to 492.Dv SIGTERM . 493.It Sy sig_reload 494Signal to send the processes to reload in the default 495.Sy reload 496method. 497Defaults to 498.Dv SIGHUP . 499.El 500.Pp 501For a given method 502.Ar argument , 503if 504.Ar argument Ns Sy _cmd 505is not defined, then a default method is provided by 506.Sy run_rc_command : 507.Bl -tag -width "argument" -offset indent 508.It Sy Argument 509.Sy Default method 510.It Sy start 511If 512.Sy command 513is not running and 514.Ic checkyesno Sy rcvar 515succeeds, start 516.Sy command . 517.It Sy stop 518Determine the PIDs of 519.Sy command 520with 521.Ic check_pidfile 522or 523.Ic check_process 524(as appropriate), 525.Ic kill Sy sig_stop 526those PIDs, and run 527.Ic wait_for_pids 528on those PIDs. 529.It Sy reload 530Similar to 531.Sy stop , 532except that it uses 533.Sy sig_reload 534instead, and doesn't run 535.Ic wait_for_pids . 536.It Sy restart 537Runs the 538.Sy stop 539method, then the 540.Sy start 541method. 542.It Sy status 543Show the PID of 544.Sy command , 545or some other script specific status operation. 546.It Sy poll 547Wait for 548.Sy command 549to exit. 550.It Sy rcvar 551Display which 552.Xr rc.conf 5 553variable is used (if any). 554This method always works, even if the appropriate 555.Xr rc.conf 5 556variable is set to 557.Sq NO . 558.El 559.Pp 560The following variables are available to the methods 561(such as 562.Ar argument Ns Sy _cmd ) 563as well as after 564.Ic run_rc_command 565has completed: 566.Bl -tag -width "rc_flags" -offset indent 567.It Sy rc_arg 568Argument provided to 569.Sy run_rc_command , 570after fast and force processing has been performed. 571.It Sy rc_flags 572Flasg to start the default command with. 573Defaults to 574.Sy ${name}_flags , 575unless overridden by the environment variable 576.Sq Ev flags . 577This variable may be changed by the 578.Ar argument Ns Sy _precmd 579method. 580.It Sy rc_pid 581PID of 582.Sy command 583(if appropriate). 584.It Sy rc_fast 585Not empty if 586.Dq fast 587prefix was used. 588.It Sy rc_force 589Not empty if 590.Dq force 591prefix was used. 592.El 593.It Ic run_rc_script Ar file Ar argument 594Start the script 595.Ar file 596with an argument of 597.Ar argument , 598and handle the return value from the script. 599.Pp 600Various shell variables are unset before 601.Ar file 602is started: 603.Bd -ragged -offset indent 604.Sy name , 605.Sy command , 606.Sy command_args , 607.Sy command_interpreter , 608.Sy extra_commands , 609.Sy pidfile , 610.Sy rcvar , 611.Sy required_dirs , 612.Sy required_files , 613.Sy required_vars , 614.Ar argument Ns Sy _cmd , 615.Ar argument Ns Sy _precmd . 616.Ar argument Ns Sy _postcmd . 617.Ed 618.Pp 619The startup behaviour of 620.Ar file 621depends upon the following checks: 622.Bl -enum 623.It 624If 625.Ar file 626ends in 627.Pa .sh , 628it is sourced into the current shell. 629.It 630If 631.Ar file 632appears to be a backup or scratch file 633(e.g., with a suffix of 634.Sq ~ , 635.Sq # , 636.Sq .OLD , 637or 638.Sq .orig ) , 639ignore it. 640.It 641If 642.Ar file 643is not executable, ignore it. 644.It 645If the 646.Xr rc.conf 5 647variable 648.Sy rc_fast_and_loose 649is empty, 650source 651.Ar file 652in a sub shell, 653otherwise source 654.Ar file 655into the current shell. 656.El 657.It Ic wait_for_pids Op Ar pid Op Ar ... 658Wait until all of the provided 659.Ar pids 660don't exist any more, printing the list of outstanding 661.Ar pids 662every two seconds. 663.It Ic warn Ar message 664Display a warning message to 665.Em stderr 666and log it to the system log 667using 668.Xr logger 1 . 669The warning message consists of the script name 670(from 671.Sy $0 ) , 672followed by 673.Dq ": WARNING: " , 674and then 675.Ar message . 676.El 677.Sh FILES 678.Bl -tag -width /etc/rc.subr -compact 679.It Pa /etc/rc.subr 680The 681.Nm 682file resides in 683.Pa /etc . 684.El 685.Sh SEE ALSO 686.Xr rc.conf 5 , 687.Xr rc 8 688.Sh HISTORY 689.Nm 690appeared in 691.Nx 1.3 . 692The 693.Xr rc.d 8 694support functions appeared in 695.Nx 1.5 . 696