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