1.\" $NetBSD: rc.subr.8,v 1.25 2009/10/05 09:57:18 apb 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 5, 2009 31.Dt RC.SUBR 8 32.Os 33.Sh NAME 34.Nm rc.subr 35.Nd functions used by system shell scripts 36.Sh SYNOPSIS 37.Bl -item 38.It 39.Li . /etc/rc.subr 40.It 41.Ic backup_file Ar action Ar file Ar current Ar backup 42.It 43.Ic checkyesno Ar var 44.It 45.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter 46.It 47.Ic check_process Ar procname Op Ar interpreter 48.It 49.Ic err Ar exitval Ar message 50.It 51.Ic load_rc_config Ar command 52.It 53.Ic load_rc_config_var Ar command Ar var 54.It 55.Ic mount_critical_filesystems Ar type 56.It 57.Ic no_rc_postprocess Ar command Op Ar arguments 58.It 59.Ic print_rc_metadata Ar string 60.It 61.Ic print_rc_normal Ar string 62.It 63.Ic rc_usage Ar command Op Ar ... 64.It 65.Ic reverse_list Ar item Op Ar ... 66.It 67.Ic run_rc_command Ar argument 68.It 69.Ic run_rc_script Ar file Ar argument 70.It 71.Ic stop_boot 72.It 73.Ic twiddle 74.It 75.Ic wait_for_pids Op Ar pid Op Ar ... 76.It 77.Ic warn Ar message 78.It 79.Ic yesno_to_truefalse Ar var 80.El 81.Sh DESCRIPTION 82.Nm 83contains commonly used shell script functions which are used by 84various scripts such as 85.Xr rc 8 , 86and the periodic system services which are controlled by 87.Xr daily.conf 5 , 88.Xr monthly.conf 5 , 89.Xr security.conf 5 , 90and 91.Xr weekly.conf 5 . 92.Pp 93The 94.Nm 95functions are accessed by sourcing 96.Pa /etc/rc.subr 97into the current shell. 98.Pp 99The following shell functions are available: 100.Bl -tag -width 4n 101.It Ic backup_file Ar action Ar file Ar current Ar backup 102Make a backup copy of 103.Ar file 104into 105.Ar current . 106If the 107.Xr rc.conf 5 108variable 109.Sy backup_uses_rcs 110is 111.Sq YES , 112use 113.Xr rcs 1 114to archive the previous version of 115.Ar current , 116otherwise save the previous version of 117.Ar current 118as 119.Ar backup . 120.Pp 121.Ar action 122may be one of the following: 123.Bl -tag -width remove 124.It Sy add 125.Ar file 126is now being backed up by or possibly re-entered into this backup mechanism. 127.Ar current 128is created, and if necessary, the 129.Xr rcs 1 130files are created as well. 131.It Sy update 132.Ar file 133has changed and needs to be backed up. 134If 135.Ar current 136exists, it is copied to 137.Ar backup 138or checked into 139.Xr rcs 1 140(if the repository file is old), 141and then 142.Ar file 143is copied to 144.Ar current . 145.It Sy remove 146.Ar file 147is no longer being tracked by this backup mechanism. 148If 149.Xr rcs 1 150is being used, an empty file is checked in and 151.Ar current 152is removed, 153otherwise 154.Ar current 155is moved to 156.Ar backup . 157.El 158.It Ic checkyesno Ar var 159Return 0 if 160.Ar var 161is defined to 162.Sq YES , 163.Sq TRUE , 164.Sq ON , 165or 166.Sq 1 . 167Return 1 if 168.Ar var 169is defined to 170.Sq NO , 171.Sq FALSE , 172.Sq OFF , 173or 174.Sq 0 . 175Otherwise, warn that 176.Ar var 177is not set correctly. 178The values are case insensitive. 179.Pp 180Note that the warning message shown by this function when 181.Ar var 182is not set references a manual page where the user can find more information. 183Its name is picked up from the 184.Sy rcvar_manpage 185variable. 186.It Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter 187Parses the first word of the first line of 188.Ar pidfile 189for a PID, and ensures that the process with that PID 190is running and its first argument matches 191.Ar procname . 192Prints the matching PID if successful, otherwise nothing. 193If 194.Ar interpreter 195is provided, parse the first line of 196.Ar procname , 197ensure that the line is of the form 198.Dl #! interpreter [...] 199and use 200.Ar interpreter 201with its optional arguments and 202.Ar procname 203appended as the process string to search for. 204.It Ic check_process Ar procname Op Ar interpreter 205Prints the PIDs of any processes that are running with a first 206argument that matches 207.Ar procname . 208.Ar interpreter 209is handled as per 210.Ic check_pidfile . 211.It Ic err Ar exitval Ar message 212Display an error message to 213.Em stderr , 214log it to the system log 215using 216.Xr logger 1 , 217and 218.Cm exit 219with an exit value of 220.Ar exitval . 221The error message consists of the script name 222(from 223.Sy $0 ) , 224followed by 225.Dq ": ERROR: " , 226and then 227.Ar message . 228.It Ic load_rc_config Ar command 229Source in the 230.Xr rc.conf 5 231configuration files for 232.Ar command . 233First, 234.Pa /etc/rc.conf 235is sourced if it has not yet been read in. 236Then, 237.Pa /etc/rc.conf.d/ Ns Ar command 238is sourced if it is an existing file. 239The latter may also contain other variable assignments to override 240.Ic run_rc_command 241arguments defined by the calling script, to provide an easy 242mechanism for an administrator to override the behaviour of a given 243.Xr rc.d 8 244script without requiring the editing of that script. 245.It Ic load_rc_config_var Ar command Ar var 246Read the 247.Xr rc.conf 5 248variable 249.Ar var 250for 251.Ar command 252and set in the current shell, using 253.Ic load_rc_config 254in a sub-shell to prevent unwanted side effects from other variable 255assignments. 256.It Ic mount_critical_filesystems Ar type 257Go through a list of critical file systems, 258as found in the 259.Xr rc.conf 5 260variable 261.Sy critical_filesystems_ Ns Ar type , 262mounting each one that 263is not currently mounted. 264.It Ic no_rc_postprocess Ar command Op Ar arguments 265Execute the specified command with the specified arguments, 266in such a way that its output bypasses the post-processor that 267.Xr rc 8 268uses for most commands. 269This implies that the output will not appear in the 270.Pa /var/run/rc.log 271file, and will appear on the console regardless of the 272value of 273.Va rc_silent . 274This is expected to be useful for interactive commands, 275and this mechanism is automatically used by 276.Ic run_rc_command 277when a script contains the 278.Xr rcorder 8 279keyword 280.Dq interactive . 281.Pp 282If invoked from a context that does not appear to be under the control of 283.Xr rc 8 , 284then the command is executed without special treatment. 285.It Ic print_rc_metadata Ar string 286Print the specified 287.Ar string 288in such a way that it should be handled as meta-data by the 289.Xr rc 8 290post-processor. 291If invoked from a context that does not appear to be under the control of 292.Xr rc 8 , 293then the 294.Ar string 295is discarded. 296.Pp 297Any 298.Xr rc.d 8 299script may invoke this function with an argument that begins with 300.Dq note: , 301followed by one line of arbitrary text; 302the text will be logged by 303.Xr rc 8 304but will not be displayed on the console. 305.Pp 306The use of arguments that do not begin with 307.Dq note: 308is reserved for internal use by 309.Xr rc 8 310and 311.Nm . 312.It Ic print_rc_normal Ar string 313Print the specified 314.Ar string 315in such a way that it should be handled as normal output by the 316.Xr rc 8 317post-processor. 318If invoked from a context that does not appear to be under the control of 319.Xr rc 8 , 320then the 321.Ar string 322is printed to standard output. 323.Pp 324Ths intent is that a script that is run via the 325.Fn no_rc_postprocess 326function (so its output would ordinarily be invisible to the post-processor) 327can nevertheless arrange for the post-processor to see things printed with 328.Fn print_rc_normal. 329.It Ic rc_usage Ar command Op Ar ... 330Print a usage message for 331.Sy $0 , 332with 333.Ar commands 334being the list of valid arguments 335prefixed by 336.Dq "[fast|force|one]" . 337.It Ic reverse_list Ar item Op Ar ... 338Print the list of 339.Ar items 340in reverse order. 341.It Ic run_rc_command Ar argument 342Run the 343.Ar argument 344method for the current 345.Xr rc.d 8 346script, based on the settings of various shell variables. 347.Ic run_rc_command 348is extremely flexible, and allows fully functional 349.Xr rc.d 8 350scripts to be implemented in a small amount of shell code. 351.Pp 352.Ar argument 353is searched for in the list of supported commands, which may be one 354of: 355.Bl -tag -width restart -offset indent 356.It Sy start 357Start the service. 358This should check that the service is to be started as specified by 359.Xr rc.conf 5 . 360Also checks if the service is already running and refuses to start if 361it is. 362This latter check is not performed by standard 363.Nx 364scripts if the system is starting directly to multi-user mode, to 365speed up the boot process. 366.It Sy stop 367If the service is to be started as specified by 368.Xr rc.conf 5 , 369stop the service. 370This should check that the service is running and complain if it's not. 371.It Sy restart 372Perform a 373.Sy stop 374then a 375.Sy start . 376Defaults to displaying the process ID of the program (if running). 377.It Sy rcvar 378Display which 379.Xr rc.conf 5 380variables are used to control the startup of the service (if any). 381.El 382.Pp 383If 384.Sy pidfile 385or 386.Sy procname 387is set, also support: 388.Bl -tag -width restart -offset indent 389.It Sy poll 390Wait for the command to exit. 391.It Sy status 392Show the status of the process. 393.El 394.Pp 395Other supported commands are listed in the optional variable 396.Sy extra_commands . 397.Pp 398.Ar argument 399may have one of the following prefixes which alters its operation: 400.Bl -tag -width "Prefix" -offset indent 401.It Sy fast 402Skip the check for an existing running process, 403and sets 404.Sy rc_fast=YES . 405.It Sy force 406Skip the checks for 407.Sy rcvar 408being set to yes, 409and sets 410.Sy rc_force=YES . 411This ignores 412.Ar argument Ns Sy _precmd 413returning non-zero, and ignores any of the 414.Sy required_* 415tests failing, and always returns a zero exit status. 416.It Sy one 417Skip the checks for 418.Sy rcvar 419being set to yes, but performs all the other prerequisite tests. 420.El 421.Pp 422.Ic run_rc_command 423uses the following shell variables to control its behaviour. 424Unless otherwise stated, these are optional. 425.Bl -tag -width procname -offset indent 426.It Sy name 427The name of this script. 428This is not optional. 429.It Sy rcvar 430The value of 431.Sy rcvar 432is checked with 433.Ic checkyesno 434to determine if this method should be run. 435.It Sy rcvar_manpage 436The manual page containing information about 437.Sy rcvar . 438It will be part of the warning message shown when 439.Sy rcvar 440is undefined. 441Defaults to 442.Xr rc.conf 5 . 443.It Sy command 444Full path to the command. 445Not required if 446.Ar argument Ns Sy _cmd 447is defined for each supported keyword. 448.It Sy command_args 449Optional arguments and/or shell directives for 450.Sy command . 451.It Sy command_interpreter 452.Sy command 453is started with 454.Dl #! command_interpreter [...] 455which results in its 456.Xr ps 1 457command being 458.Dl command_interpreter [...] command 459so use that string to find the PID(s) of the running command 460rather than 461.Ql command . 462.It Sy extra_commands 463Extra commands/keywords/arguments supported. 464.It Sy pidfile 465Path to pid file. 466Used to determine the PID(s) of the running command. 467If 468.Sy pidfile 469is set, use 470.Dl check_pidfile $pidfile $procname 471to find the PID. 472Otherwise, if 473.Sy command 474is set, use 475.Dl check_process $procname 476to find the PID. 477.It Sy procname 478Process name to check for. 479Defaults to the value of 480.Sy command . 481.It Sy required_dirs 482Check for the existence of the listed directories 483before running the default start method. 484.It Sy required_files 485Check for the readability of the listed files 486before running the default start method. 487.It Sy required_vars 488Perform 489.Ic checkyesno 490on each of the list variables 491before running the default start method. 492.It Sy ${name}_chdir 493Directory to 494.Ic cd 495to before running 496.Sy command , 497if 498.Sy ${name}_chroot 499is not provided. 500.It Sy ${name}_chroot 501Directory to 502.Xr chroot 8 503to before running 504.Sy command . 505Only supported after 506.Pa /usr 507is mounted. 508.It Sy ${name}_env 509List of additional or modified environment variables to set 510when starting 511.Sy command . 512.It Sy ${name}_flags 513Arguments to call 514.Sy command 515with. 516This is usually set in 517.Xr rc.conf 5 , 518and not in the 519.Xr rc.d 8 520script. 521The environment variable 522.Sq Ev flags 523can be used to override this. 524.It Sy ${name}_nice 525.Xr nice 1 526level to run 527.Sy command 528as. 529Only supported after 530.Pa /usr 531is mounted. 532.It Sy ${name}_user 533User to run 534.Sy command 535as, using 536.Xr chroot 8 . 537if 538.Sy ${name}_chroot 539is set, otherwise 540uses 541.Xr su 1 . 542Only supported after 543.Pa /usr 544is mounted. 545.It Sy ${name}_group 546Group to run the chrooted 547.Sy command 548as. 549.It Sy ${name}_groups 550Comma separated list of supplementary groups to run the chrooted 551.Sy command 552with. 553.It Ar argument Ns Sy _cmd 554Shell commands which override the default method for 555.Ar argument . 556.It Ar argument Ns Sy _precmd 557Shell commands to run just before running 558.Ar argument Ns Sy _cmd 559or the default method for 560.Ar argument . 561If this returns a non-zero exit code, the main method is not performed. 562If the default method is being executed, this check is performed after 563the 564.Sy required_* 565checks and process (non-)existence checks. 566.It Ar argument Ns Sy _postcmd 567Shell commands to run if running 568.Ar argument Ns Sy _cmd 569or the default method for 570.Ar argument 571returned a zero exit code. 572.It Sy sig_stop 573Signal to send the processes to stop in the default 574.Sy stop 575method. 576Defaults to 577.Dv SIGTERM . 578.It Sy sig_reload 579Signal to send the processes to reload in the default 580.Sy reload 581method. 582Defaults to 583.Dv SIGHUP . 584.El 585.Pp 586For a given method 587.Ar argument , 588if 589.Ar argument Ns Sy _cmd 590is not defined, then a default method is provided by 591.Sy run_rc_command : 592.Bl -tag -width "argument" -offset indent 593.It Sy Argument 594.Sy Default method 595.It Sy start 596If 597.Sy command 598is not running and 599.Ic checkyesno Sy rcvar 600succeeds, start 601.Sy command . 602.It Sy stop 603Determine the PIDs of 604.Sy command 605with 606.Ic check_pidfile 607or 608.Ic check_process 609(as appropriate), 610.Ic kill Sy sig_stop 611those PIDs, and run 612.Ic wait_for_pids 613on those PIDs. 614.It Sy reload 615Similar to 616.Sy stop , 617except that it uses 618.Sy sig_reload 619instead, and doesn't run 620.Ic wait_for_pids . 621.It Sy restart 622Runs the 623.Sy stop 624method, then the 625.Sy start 626method. 627.It Sy status 628Show the PID of 629.Sy command , 630or some other script specific status operation. 631.It Sy poll 632Wait for 633.Sy command 634to exit. 635.It Sy rcvar 636Display which 637.Xr rc.conf 5 638variable is used (if any). 639This method always works, even if the appropriate 640.Xr rc.conf 5 641variable is set to 642.Sq NO . 643.El 644.Pp 645The following variables are available to the methods 646(such as 647.Ar argument Ns Sy _cmd ) 648as well as after 649.Ic run_rc_command 650has completed: 651.Bl -tag -width "rc_flags" -offset indent 652.It Sy rc_arg 653Argument provided to 654.Sy run_rc_command , 655after fast and force processing has been performed. 656.It Sy rc_flags 657Flags to start the default command with. 658Defaults to 659.Sy ${name}_flags , 660unless overridden by the environment variable 661.Sq Ev flags . 662This variable may be changed by the 663.Ar argument Ns Sy _precmd 664method. 665.It Sy rc_pid 666PID of 667.Sy command 668(if appropriate). 669.It Sy rc_fast 670Not empty if 671.Dq fast 672prefix was used. 673.It Sy rc_force 674Not empty if 675.Dq force 676prefix was used. 677.El 678.It Ic run_rc_script Ar file Ar argument 679Start the script 680.Ar file 681with an argument of 682.Ar argument , 683and handle the return value from the script. 684.Pp 685Various shell variables are unset before 686.Ar file 687is started: 688.Bd -ragged -offset indent 689.Sy name , 690.Sy command , 691.Sy command_args , 692.Sy command_interpreter , 693.Sy extra_commands , 694.Sy pidfile , 695.Sy rcvar , 696.Sy required_dirs , 697.Sy required_files , 698.Sy required_vars , 699.Ar argument Ns Sy _cmd , 700.Ar argument Ns Sy _precmd . 701.Ar argument Ns Sy _postcmd . 702.Ed 703.Pp 704The startup behaviour of 705.Ar file 706depends upon the following checks: 707.Bl -enum 708.It 709If 710.Ar file 711ends in 712.Pa .sh , 713it is sourced into the current shell. 714.It 715If 716.Ar file 717appears to be a backup or scratch file 718(e.g., with a suffix of 719.Sq ~ , 720.Sq # , 721.Sq .OLD , 722or 723.Sq .orig ) , 724ignore it. 725.It 726If 727.Ar file 728is not executable, ignore it. 729.It 730If the 731.Xr rc.conf 5 732variable 733.Sy rc_fast_and_loose 734is empty, 735source 736.Ar file 737in a sub shell, 738otherwise source 739.Ar file 740into the current shell. 741.It 742If 743.Ar file 744contains the 745.Xr rcorder 8 746keyword 747.Dq interactive , 748then the command is executed using 749.Ic no_rc_postprocess . 750.El 751.It Ic stop_boot 752Prevent booting to multiuser mode. 753If the 754.Sy autoboot 755variable is 756.Sq yes , 757then a 758.Sy SIGTERM 759signal is sent to the parent 760process (which is assumed to be 761.Xr rc 8 ) . 762Otherwise, the shell exits with status 763.Li 1 . 764.It Ic twiddle 765Display one of the characters 766.Sq \&/ , \&- , \&\e , \&| , 767followed by a backspace. 768Repeated calls to this function will create the appearance of a spinning 769symbol, as a different character is displayed on each call. 770Output is to 771.Pa /dev/tty , 772so this function may be useful even inside a script whose output 773has been redirected. 774.It Ic wait_for_pids Op Ar pid Op Ar ... 775Wait until all of the provided 776.Ar pids 777don't exist any more, printing the list of outstanding 778.Ar pids 779every two seconds. 780.It Ic warn Ar message 781Display a warning message to 782.Em stderr 783and log it to the system log 784using 785.Xr logger 1 . 786The warning message consists of the script name 787(from 788.Sy $0 ) , 789followed by 790.Dq ": WARNING: " , 791and then 792.Ar message . 793.It Ic yesno_to_truefalse Ar var 794Change the value of the specified variable from any of the 795forms acceptable to the 796.Ic checkyesno 797function, to 798.Dq true 799or 800.Dq false . 801.El 802.Sh FILES 803.Bl -tag -width /etc/rc.subr -compact 804.It Pa /etc/rc.subr 805The 806.Nm 807file resides in 808.Pa /etc . 809.El 810.Sh SEE ALSO 811.Xr rc.conf 5 , 812.Xr rc 8 813.Sh HISTORY 814.Nm 815appeared in 816.Nx 1.3 . 817The 818.Xr rc.d 8 819support functions appeared in 820.Nx 1.5 . 821Support for the 822.Xr rc 8 823post-processor appeared in 824.Nx 6.0 . 825