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