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.\" $DragonFly: src/share/man/man8/rc.subr.8,v 1.5 2008/01/15 21:35:46 swildner Exp $ 4.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Luke Mewburn. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd January 15, 2008 39.Dt RC.SUBR 8 40.Os 41.Sh NAME 42.Nm rc.subr 43.Nd functions used by system shell scripts 44.Sh SYNOPSIS 45.Bl -item 46.It 47.Li . /etc/rc.subr 48.It 49.Ic backup_file Ar action Ar file Ar current Ar backup 50.It 51.Ic checkyesno Ar var 52.It 53.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter 54.It 55.Ic check_process Ar procname Op Ar interpreter 56.It 57.Ic debug Ar message 58.It 59.Ic err Ar exitval Ar message 60.It 61.Ic force_depend Ar name 62.It 63.Ic info Ar message 64.It 65.Ic load_rc_config Ar command 66.It 67.Ic mount_critical_filesystems Ar type 68.It 69.Ic rc_usage Ar command Op Ar ... 70.It 71.Ic reverse_list Ar item Op Ar ... 72.It 73.Ic run_rc_command Ar argument 74.It 75.Ic run_rc_script Ar file Ar argument 76.It 77.Ic set_rcvar Op Ar base 78.It 79.Ic wait_for_pids Op Ar pid Op Ar ... 80.It 81.Ic warn Ar message 82.El 83.Sh DESCRIPTION 84.Nm 85contains commonly used shell script functions and variable 86definitions which are used by various scripts such as 87.Xr rc 8 . 88Scripts required by ports in 89.Pa /usr/local/etc/rc.d 90will also eventually 91be rewritten to make use of it. 92.Pp 93The 94.Nm 95functions were mostly imported from 96.Nx 97and it is intended that they remain synced between the 98two projects. With that in mind there are several variable 99definitions that can help in this regard. They are: 100.Bl -tag -width 4n 101.It Ic OSTYPE 102Its value will be either 103.Dx Ns , 104.Fx Ns , 105or 106.Nx , 107depending on which OS it is running on. 108.It Ic SYSCTL 109The path to the 110.Xr sysctl 8 111command. 112.It Ic SYSCTL_N 113The path and argument list to display only the 114.Xr sysctl 8 115values instead of a name=value pair. 116.It Ic SYSCTL_W 117The path and argument to write or modify 118.Xr sysctl 8 119values. 120.El 121.Pp 122The 123.Nm 124functions are accessed by sourcing 125.Pa /etc/rc.subr 126into the current shell. 127.Pp 128The following shell functions are available: 129.Bl -tag -width 4n 130.It Xo 131.Ic backup_file Ar action Ar file Ar current Ar backup 132.Xc 133Make a backup copy of 134.Ar file 135into 136.Ar current . 137If the 138.Xr rc.conf 5 139variable 140.Sy backup_uses_rcs 141is 142.Sq YES , 143use 144.Xr rcs 1 145to archive the previous version of 146.Ar current , 147otherwise save the previous version of 148.Ar current 149as 150.Ar backup . 151.Pp 152.Ar action 153may be one of the following: 154.Bl -tag -width remove 155.It Sy add 156.Ar file 157is now being backed up by or possibly re-entered into this backup mechanism. 158.Ar current 159is created, and if necessary, the 160.Xr rcs 1 161files are created as well. 162.It Sy update 163.Ar file 164has changed and needs to be backed up. 165If 166.Ar current 167exists, it is copied to 168.Ar backup 169or checked into 170.Xr rcs 1 171(if the repository file is old), 172and then 173.Ar file 174is copied to 175.Ar current . 176.It Sy remove 177.Ar file 178is no longer being tracked by this backup mechanism. 179If 180.Xr rcs 1 181is being used, an empty file is checked in and 182.Ar current 183is removed, 184otherwise 185.Ar current 186is moved to 187.Ar backup . 188.El 189.It Ic checkyesno Ar var 190Return 0 if 191.Ar var 192is defined to 193.Sq YES , 194.Sq TRUE , 195.Sq ON , 196or 197.Sq 1 . 198Return 1 if 199.Ar var 200is defined to 201.Sq NO , 202.Sq FALSE , 203.Sq OFF , 204or 205.Sq 0 . 206Otherwise, warn that 207.Ar var 208is not set correctly. 209The values are case insensitive. 210.It Xo 211.Ic check_pidfile 212.Ar pidfile 213.Ar procname 214.Op Ar interpreter 215.Xc 216Parses the first word of the first line of 217.Ar pidfile 218for a PID, and ensures that the process with that PID 219is running and its first argument matches 220.Ar procname . 221Prints the matching PID if successful, otherwise nothing. 222If 223.Ar interpreter 224is provided, parse the first line of 225.Ar procname , 226ensure that the line is of the form 227.Dl #! interpreter [...] 228and use 229.Ar interpreter 230with its optional arguments and 231.Ar procname 232appended as the process string to search for. 233.It Ic check_process Ar procname Op Ar interpreter 234Prints the PIDs of any processes that are running with a first 235argument that matches 236.Ar procname . 237.Ar interpreter 238is handled as per 239.Ic check_pidfile . 240.It Ic debug Ar message 241Display a debugging message to 242.Em stderr , 243log it to the system log using 244.Xr logger 1 , 245and 246return to the caller. 247The error message consists of the script name 248(from 249.Sy $0 ) , 250followed by 251.Dq ": DEBUG: " , 252and then 253.Ar message . 254This function is intended to be used by developers 255as an aid to debugging scripts. It can be turned on or off 256by the 257.Xr rc.conf 5 258variable 259.Va rc_debug . 260.It Ic err Ar exitval Ar message 261Display an error message to 262.Em stderr , 263log it to the system log 264using 265.Xr logger 1 , 266and 267.Cm exit 268with an exit value of 269.Ar exitval . 270The error message consists of the script name 271(from 272.Sy $0 ) , 273followed by 274.Dq ": ERROR: " , 275and then 276.Ar message . 277.It Ic force_depend name 278Output an advisory message and force the 279.Ar name 280service to start. The 281.Ar name 282argument is the 283.Xr basename 1 , 284component of the path to the script, usually 285.Em /etc/rc.d/name . 286If the script fails for any reason it will output a warning 287and return with a return value of 1. If it was successful 288it will return 0. 289.It Ic info Ar message 290Display an informational message to 291.Em stdout , 292and log it to the system log using 293.Xr logger 1 . 294The message consists of the script name 295(from 296.Sy $0 ) , 297followed by 298.Dq ": INFO: " , 299and then 300.Ar message . 301The display of this informational output can be 302turned on or off by the 303.Xr rc.conf 5 304variable 305.Va rc_info . 306.It Ic load_rc_config Ar command 307Source in the configuration files for 308.Ar command . 309First, 310.Pa /etc/rc.conf 311is sourced if it has not yet been read in. 312Then, 313.Pa /etc/rc.conf.d/ Ns Ar command 314is sourced if it is an existing file. 315The latter may also contain other variable assignments to override 316.Ic run_rc_command 317arguments defined by the calling script, to provide an easy 318mechanism for an administrator to override the behaviour of a given 319.Xr rc.d 8 320script without requiring the editing of that script. 321.It Ic mount_critical_filesystems Ar type 322Go through a list of critical file systems, 323as found in the 324.Xr rc.conf 5 325variable 326.Sy critical_filesystems_ Ns Ar type , 327mounting each one that 328is not currently mounted. 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]" . 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.Dl start stop restart rcvar 356as well as any word listed in the optional variable 357.Sy extra_commands . 358If 359.Sy pidfile 360or 361.Sy procname 362is set, also allow: 363.Dl status poll 364.Pp 365.Ar argument 366may have one of the following prefixes which alters its operation: 367.Bl -tag -width "Prefix" -offset indent -compact 368.It Sy Prefix 369.Sy Operation 370.It Li fast 371Skip the check for an existing running process, 372and sets 373.Sy rc_fast=YES . 374.It Li force 375Skip the checks for 376.Sy rcvar 377being set to yes, 378and sets 379.Sy rc_force=YES . 380This ignores 381.Ar argument Ns Sy _precmd 382returning non-zero, and ignores any of the 383.Sy required_* 384tests failing . 385.El 386.Pp 387.Ic run_rc_command 388uses the following shell variables to control its behaviour. 389Unless otherwise stated, these are optional. 390.Bl -tag -width procname -offset indent 391.It Sy name 392The name of this script. 393This is not optional. 394.It Sy rcvar 395The value of 396.Sy rcvar 397is checked with 398.Ic checkyesno 399to determine if this method should be run. 400.It Sy command 401Full path to the command. 402Not required if 403.Ar argument Ns Sy _cmd 404is defined for each supported keyword. 405.It Sy command_args 406Optional arguments and/or shell directives for 407.Sy command . 408.It Sy command_interpreter 409.Sy command 410is started with 411.Dl #! command_interpreter [...] 412which results in its 413.Xr ps 1 414command being 415.Dl command_interpreter [...] command 416so use that string to find the PID(s) of the running command 417rather than 418.Ql command . 419.It Sy extra_commands 420Extra commands/keywords/arguments supported. 421.It Sy pidfile 422Path to pid file. 423Used to determine the PID(s) of the running command. 424If 425.Sy pidfile 426is set, use 427.Dl check_pidfile $pidfile $procname 428to find the PID. 429Otherwise, if 430.Sy command 431is set, use 432.Dl check_process $procname 433to find the PID. 434.It Sy procname 435Process name to check for. 436Defaults to the value of 437.Sy command . 438.It Sy required_dirs 439Check for the existence of the listed directories 440before running the default start method. 441.It Sy required_files 442Check for the readability of the listed files 443before running the default start method. 444.It Sy required_vars 445Perform 446.Ic checkyesno 447on each of the list variables 448before running the default start method. 449.It Sy ${name}_chdir 450Directory to 451.Ic cd 452to before running 453.Sy command , 454if 455.Sy ${name}_chroot 456is not provided. 457.It Sy ${name}_chroot 458Directory to 459.Xr chroot 8 460to before running 461.Sy command . 462Only supported after 463.Pa /usr 464is mounted. 465.It Sy ${name}_flags 466Arguments to call 467.Sy command 468with. 469This is usually set in 470.Xr rc.conf 5 , 471and not in the 472.Xr rc.d 8 473script. 474The environment variable 475.Sq Ev flags 476can be used to override this. 477.It Sy ${name}_nice 478.Xr nice 1 479level to run 480.Sy command 481as. 482Only supported after 483.Pa /usr 484is mounted. 485.It Sy ${name}_user 486User to run 487.Sy command 488as, using 489.Xr chroot 8 . 490if 491.Sy ${name}_chroot 492is set, otherwise 493uses 494.Xr su 1 . 495Only supported after 496.Pa /usr 497is mounted. 498.It Sy ${name}_group 499Group to run the chrooted 500.Sy command 501as. 502.It Sy ${name}_groups 503Comma separated list of supplementary groups to run the chrooted 504.Sy command 505with. 506.It Ar argument Ns Sy _cmd 507Shell commands which override the default method for 508.Ar argument . 509.It Ar argument Ns Sy _precmd 510Shell commands to run just before running 511.Ar argument Ns Sy _cmd 512or the default method for 513.Ar argument . 514If this returns a non-zero exit code, the main method is not performed. 515If the default method is being executed, this check is performed after 516the 517.Sy required_* 518checks and process (non-)existence checks. 519.It Ar argument Ns Sy _postcmd 520Shell commands to run if running 521.Ar argument Ns Sy _cmd 522or the default method for 523.Ar argument 524returned a zero exit code. 525.It Sy sig_stop 526Signal to send the processes to stop in the default 527.Sy stop 528method. 529Defaults to 530.Dv SIGTERM . 531.It Sy sig_reload 532Signal to send the processes to reload in the default 533.Sy reload 534method. 535Defaults to 536.Dv SIGHUP . 537.El 538.Pp 539For a given method 540.Ar argument , 541if 542.Ar argument Ns Sy _cmd 543is not defined, then a default method is provided by 544.Sy run_rc_command : 545.Bl -tag -width "argument" -offset indent 546.It Sy Argument 547.Sy Default method 548.It Sy start 549If 550.Sy command 551is not running and 552.Ic checkyesno Sy rcvar 553succeeds, start 554.Sy command . 555.It Sy stop 556Determine the PIDs of 557.Sy command 558with 559.Ic check_pidfile 560or 561.Ic check_process 562(as appropriate), 563.Ic kill Sy sig_stop 564those PIDs, and run 565.Ic wait_for_pids 566on those PIDs. 567.It Sy reload 568Similar to 569.Sy stop , 570except that it uses 571.Sy sig_reload 572instead, and doesn't run 573.Ic wait_for_pids . 574.It Sy restart 575Runs the 576.Sy stop 577method, then the 578.Sy start 579method. 580.It Sy status 581Show the PID of 582.Sy command , 583or some other script specific status operation. 584.It Sy poll 585Wait for 586.Sy command 587to exit. 588.It Sy rcvar 589Display which 590.Xr rc.conf 5 591variable is used (if any). 592This method always works, even if the appropriate 593.Xr rc.conf 5 594variable is set to 595.Sq NO . 596.El 597.Pp 598The following variables are available to the methods 599(such as 600.Ar argument Ns Sy _cmd ) 601as well as after 602.Ic run_rc_command 603has completed: 604.Bl -tag -width "rc_flags" -offset indent 605.It Sy rc_arg 606Argument provided to 607.Sy run_rc_command , 608after fast and force processing has been performed. 609.It Sy rc_flags 610Flags to start the default command with. 611Defaults to 612.Sy ${name}_flags , 613unless overridden by the environment variable 614.Sq Ev flags . 615This variable may be changed by the 616.Ar argument Ns Sy _precmd 617method. 618.It Sy rc_pid 619PID of 620.Sy command 621(if appropriate). 622.It Sy rc_fast 623Not empty if 624.Dq fast 625prefix was used. 626.It Sy rc_force 627Not empty if 628.Dq force 629prefix was used. 630.El 631.It Ic run_rc_script Ar file Ar argument 632Start the script 633.Ar file 634with an argument of 635.Ar argument , 636and handle the return value from the script. 637.Pp 638Various shell variables are unset before 639.Ar file 640is started: 641.Bd -ragged -offset indent 642.Sy name , 643.Sy command , 644.Sy command_args , 645.Sy command_interpreter , 646.Sy extra_commands , 647.Sy pidfile , 648.Sy rcvar , 649.Sy required_dirs , 650.Sy required_files , 651.Sy required_vars , 652.Ar argument Ns Sy _cmd , 653.Ar argument Ns Sy _precmd . 654.Ar argument Ns Sy _postcmd . 655.Ed 656.Pp 657The startup behaviour of 658.Ar file 659depends upon the following checks: 660.Bl -enum 661.It 662If 663.Ar file 664ends in 665.Pa .sh , 666it is sourced into the current shell. 667.It 668If 669.Ar file 670appears to be a backup or scratch file 671(e.g., with a suffix of 672.Sq ~ , 673.Sq # , 674.Sq .OLD , 675or 676.Sq .orig ) , 677ignore it. 678.It 679If 680.Ar file 681is not executable, ignore it. 682.It 683If the 684.Xr rc.conf 5 685variable 686.Sy rc_fast_and_loose 687is empty, 688source 689.Ar file 690in a sub shell, 691otherwise source 692.Ar file 693into the current shell. 694.El 695.It Ic set_rcvar Op Ar base 696Set the variable name required to start a service. In 697.Dx 698a daemon is usually controlled by an 699.Xr rc.conf 5 700variable consisting of a daemon's name postfixed by the string 701.Sy "_enable" 702(this postfix can be omitted as in 703.Nx ) . 704When the following line is included in a script 705.Pp 706.Dl rcvar=`set_rcvar` 707.Pp 708This function will use the value of the 709.Sy $name 710variable, which should be defined by the calling script, to construct the appropriate 711.Xr rc.conf 5 712knob. If the 713.Ar base 714argument is set it will use 715.Ar base 716instead of 717.Sy $name . 718.It Ic wait_for_pids Op Ar pid Op Ar ... 719Wait until all of the provided 720.Ar pids 721don't exist any more, printing the list of outstanding 722.Ar pids 723every two seconds. 724.It Ic warn Ar message 725Display a warning message to 726.Em stderr 727and log it to the system log 728using 729.Xr logger 1 . 730The warning message consists of the script name 731(from 732.Sy $0 ) , 733followed by 734.Dq ": WARNING: " , 735and then 736.Ar message . 737.El 738.Sh FILES 739.Bl -tag -width /etc/rc.subr -compact 740.It Pa /etc/rc.subr 741The 742.Nm 743file resides in 744.Pa /etc . 745.El 746.Sh SEE ALSO 747.Xr rc.conf 5 , 748.Xr rc 8 749.Sh HISTORY 750.Nm 751appeared in 752.Nx 1.3 . 753The 754.Xr rc.d 8 755support functions appeared in 756.Nx 1.5 . 757.Nm 758first appeared in 759.Fx 5.0 . 760