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.\" $FreeBSD$ 38.\" 39.Dd June 21, 2006 40.Dt RC.SUBR 8 41.Os 42.Sh NAME 43.Nm rc.subr 44.Nd functions used by system shell scripts 45.Sh SYNOPSIS 46.Bl -item -compact 47.It 48.Ic .\& Pa /etc/rc.subr 49.Pp 50.It 51.Ic backup_file Ar action Ar file Ar current Ar backup 52.It 53.Ic checkyesno Ar var 54.It 55.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter 56.It 57.Ic check_process Ar procname Op Ar interpreter 58.It 59.Ic debug Ar message 60.It 61.Ic err Ar exitval Ar message 62.It 63.Ic force_depend Ar name 64.It 65.Ic info Ar message 66.It 67.Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file 68.It 69.Ic load_rc_config Ar name 70.It 71.Ic load_rc_config_var Ar name Ar var 72.It 73.Ic mount_critical_filesystems Ar type 74.It 75.Ic rc_usage Ar command ... 76.It 77.Ic reverse_list Ar item ... 78.It 79.Ic run_rc_command Ar argument 80.It 81.Ic run_rc_script Ar file Ar argument 82.It 83.Ic set_rcvar Op Ar base 84.It 85.Ic wait_for_pids Op Ar pid ... 86.It 87.Ic warn Ar message 88.El 89.Sh DESCRIPTION 90The 91.Nm 92script 93contains commonly used shell script functions and variable 94definitions which are used by various scripts such as 95.Xr rc 8 . 96Scripts required by ports in 97.Pa /usr/local/etc/rc.d 98will also eventually 99be rewritten to make use of it. 100.Pp 101The 102.Nm 103functions were mostly imported from 104.Nx 105and it is intended that they remain synced between the 106two projects. 107With that in mind there are several variable 108definitions that can help in this regard. 109They are: 110.Bl -tag -width 4n 111.It Va OSTYPE 112Its value will be either 113.Qq Li FreeBSD 114or 115.Qq Li NetBSD , 116depending on which OS it is running on. 117.It Va SYSCTL 118The path to the 119.Xr sysctl 8 120command. 121.It Va SYSCTL_N 122The path and argument list to display only the 123.Xr sysctl 8 124values instead of a 125.Ar name Ns = Ns Ar value 126pair. 127.It Va SYSCTL_W 128The path and argument to write or modify 129.Xr sysctl 8 130values. 131.El 132.Pp 133The 134.Nm 135functions are accessed by sourcing 136.Pa /etc/rc.subr 137into the current shell. 138.Pp 139The following shell functions are available: 140.Bl -tag -width 4n 141.It Ic backup_file Ar action file current backup 142Make a backup copy of 143.Ar file 144into 145.Ar current . 146If the 147.Xr rc.conf 5 148variable 149.Va backup_uses_rcs 150is 151.Dq Li YES , 152use 153.Xr rcs 1 154to archive the previous version of 155.Ar current , 156otherwise save the previous version of 157.Ar current 158as 159.Ar backup . 160.Pp 161The 162.Ar action 163argument 164may be one of the following: 165.Bl -tag -width ".Cm remove" 166.It Cm add 167.Ar file 168is now being backed up by or possibly re-entered into this backup mechanism. 169.Ar current 170is created, and if necessary, the 171.Xr rcs 1 172files are created as well. 173.It Cm update 174.Ar file 175has changed and needs to be backed up. 176If 177.Ar current 178exists, it is copied to 179.Ar backup 180or checked into 181.Xr rcs 1 182(if the repository file is old), 183and then 184.Ar file 185is copied to 186.Ar current . 187.It Cm remove 188.Ar file 189is no longer being tracked by this backup mechanism. 190If 191.Xr rcs 1 192is being used, an empty file is checked in and 193.Ar current 194is removed, 195otherwise 196.Ar current 197is moved to 198.Ar backup . 199.El 200.It Ic checkyesno Ar var 201Return 0 if 202.Ar var 203is defined to 204.Dq Li YES , 205.Dq Li TRUE , 206.Dq Li ON , 207or 208.Ql 1 . 209Return 1 if 210.Ar var 211is defined to 212.Dq Li NO , 213.Dq Li FALSE , 214.Dq Li OFF , 215or 216.Ql 0 . 217Otherwise, warn that 218.Ar var 219is not set correctly. 220The values are case insensitive. 221.It Ic check_pidfile Ar pidfile procname Op Ar interpreter 222Parses the first word of the first line of 223.Ar pidfile 224for a PID, and ensures that the process with that PID 225is running and its first argument matches 226.Ar procname . 227Prints the matching PID if successful, otherwise nothing. 228If 229.Ar interpreter 230is provided, parse the first line of 231.Ar procname , 232ensure that the line is of the form: 233.Pp 234.Dl "#! interpreter [...]" 235.Pp 236and use 237.Ar interpreter 238with its optional arguments and 239.Ar procname 240appended as the process string to search for. 241.It Ic check_process Ar procname Op Ar interpreter 242Prints the PIDs of any processes that are running with a first 243argument that matches 244.Ar procname . 245.Ar interpreter 246is handled as per 247.Ic check_pidfile . 248.It Ic debug Ar message 249Display a debugging message to 250.Va stderr , 251log it to the system log using 252.Xr logger 1 , 253and 254return to the caller. 255The error message consists of the script name 256(from 257.Va $0 ) , 258followed by 259.Dq Li ": DEBUG: " , 260and then 261.Ar message . 262This function is intended to be used by developers 263as an aid to debugging scripts. 264It can be turned on or off 265by the 266.Xr rc.conf 5 267variable 268.Va rc_debug . 269.It Ic err Ar exitval message 270Display an error message to 271.Va stderr , 272log it to the system log 273using 274.Xr logger 1 , 275and 276.Ic exit 277with an exit value of 278.Ar exitval . 279The error message consists of the script name 280(from 281.Va $0 ) , 282followed by 283.Dq Li ": ERROR: " , 284and then 285.Ar message . 286.It Ic force_depend name 287Output an advisory message and force the 288.Ar name 289service to start. 290The 291.Ar name 292argument is the 293.Xr basename 1 294component of the path to the script, usually 295.Pa /etc/rc.d/name . 296If the script fails for any reason it will output a warning 297and return with a return value of 1. 298If it was successful 299it will return 0. 300.It Ic info Ar message 301Display an informational message to 302.Va stdout , 303and log it to the system log using 304.Xr logger 1 . 305The message consists of the script name 306(from 307.Va $0 ) , 308followed by 309.Dq Li ": INFO: " , 310and then 311.Ar message . 312The display of this informational output can be 313turned on or off by the 314.Xr rc.conf 5 315variable 316.Va rc_info . 317.It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file 318Load 319.Ar file 320as a kernel module unless it is already loaded. 321For the purpose of checking the module status, 322either the exact module name can be specified using 323.Fl m , 324or an 325.Xr egrep 1 326regular expression matching the module name can be supplied via 327.Fl e . 328By default, the module is assumed to have the same name as 329.Ar file , 330which is not always the case. 331.It Ic load_rc_config Ar name 332Source in the configuration files for 333.Ar name . 334First, 335.Pa /etc/defaults/rc.conf 336and 337.Pa /etc/rc.conf 338are sourced if they have not yet been read in. 339Then, 340.Va etcdir 341is set to 342.Pa /etc 343if 344.Va command Ap s 345prefix (or 346.Va ${name} Ns Va _program Ap s 347if it is defined) is 348.Pa / 349or 350.Pa /usr , 351otherwise 352.Va etcdir 353is set to 354.Pa ${prefix} Ns Pa /etc . 355Once those variables are set accordingly, 356.Pa /etc/rc.conf.d/ Ns Va ${name} 357is sourced if the file exists (but it is deprecated if 358.Va etcdir 359is different than 360.Pa /etc ) 361and then 362.Pa ${etcdir} Ns Pa /defaults/ Ns Va ${name} 363and 364.Va ${etcdir} Ns Pa /rc.conf.d/ Ns Va ${name} 365are sourced if these files exist. 366All these files may also contain other variable assignments to override 367.Ic run_rc_command 368arguments defined by the calling script, to provide an easy 369mechanism for an administrator to override the behaviour of a given 370.Xr rc.d 8 371script without requiring the editing of that script. 372.It Ic load_rc_config_var Ar name Ar var 373Read the 374.Xr rc.conf 5 375variable 376.Ar var 377for 378.Ar name 379and set in the current shell, using 380.Ic load_rc_config 381in a sub-shell to prevent unwanted side effects from other variable 382assignments. 383.It Ic mount_critical_filesystems Ar type 384Go through a list of critical file systems, 385as found in the 386.Xr rc.conf 5 387variable 388.Va critical_filesystems_ Ns Ar type , 389mounting each one that 390is not currently mounted. 391.It Ic rc_usage Ar command ... 392Print a usage message for 393.Va $0 , 394with 395.Ar commands 396being the list of valid arguments 397prefixed by 398.Sm off 399.Dq Bq Li fast | force | one . 400.Sm on 401.It Ic reverse_list Ar item ... 402Print the list of 403.Ar items 404in reverse order. 405.It Ic run_rc_command Ar argument 406Run the 407.Ar argument 408method for the current 409.Xr rc.d 8 410script, based on the settings of various shell variables. 411.Ic run_rc_command 412is extremely flexible, and allows fully functional 413.Xr rc.d 8 414scripts to be implemented in a small amount of shell code. 415.Pp 416.Ar argument 417is searched for in the list of supported commands, which may be one 418of: 419.Bl -tag -width ".Cm restart" -offset indent 420.It Cm start 421Start the service. 422This should check that the service is to be started as specified by 423.Xr rc.conf 5 . 424Also checks if the service is already running and refuses to start if 425it is. 426This latter check is not performed by standard 427.Fx 428scripts if the system is starting directly to multi-user mode, to 429speed up the boot process. 430.It Cm stop 431If the service is to be started as specified by 432.Xr rc.conf 5 , 433stop the service. 434This should check that the service is running and complain if it is not. 435.It Cm restart 436Perform a 437.Cm stop 438then a 439.Cm start . 440Defaults to displaying the process ID of the program (if running). 441.It Cm rcvar 442Display which 443.Xr rc.conf 5 444variables are used to control the startup of the service (if any). 445.El 446.Pp 447If 448.Va pidfile 449or 450.Va procname 451is set, also support: 452.Bl -tag -width ".Cm restart" -offset indent 453.It Cm poll 454Wait for the command to exit. 455.It Cm status 456Show the status of the process. 457.El 458.Pp 459Other supported commands are listed in the optional variable 460.Va extra_commands . 461.Pp 462.Ar argument 463may have one of the following prefixes which alters its operation: 464.Bl -tag -width ".Li force" -offset indent 465.It Li fast 466Skip the check for an existing running process, 467and sets 468.Va rc_fast Ns = Ns Li YES . 469.It Li force 470Skip the checks for 471.Va rcvar 472being set to 473.Dq Li YES , 474and sets 475.Va rc_force Ns = Ns Li YES . 476This ignores 477.Ar argument Ns Va _precmd 478returning non-zero, and ignores any of the 479.Va required_* 480tests failing, and always returns a zero exit status. 481.It Li one 482Skip the checks for 483.Va rcvar 484being set to 485.Dq Li YES , 486but performs all the other prerequisite tests. 487.El 488.Pp 489.Ic run_rc_command 490uses the following shell variables to control its behaviour. 491Unless otherwise stated, these are optional. 492.Bl -tag -width ".Va procname" -offset indent 493.It Va name 494The name of this script. 495This is not optional. 496.It Va rcvar 497The value of 498.Va rcvar 499is checked with 500.Ic checkyesno 501to determine if this method should be run. 502.It Va command 503Full path to the command. 504Not required if 505.Ar argument Ns Va _cmd 506is defined for each supported keyword. 507Can be overridden by 508.Va ${name}_program . 509.It Va command_args 510Optional arguments and/or shell directives for 511.Va command . 512.It Va command_interpreter 513.Va command 514is started with: 515.Pp 516.Dl "#! command_interpreter [...]" 517.Pp 518which results in its 519.Xr ps 1 520command being: 521.Pp 522.Dl "command_interpreter [...] command" 523.Pp 524so use that string to find the PID(s) of the running command 525rather than 526.Va command . 527.It Va extra_commands 528Extra commands/keywords/arguments supported. 529.It Va pidfile 530Path to PID file. 531Used to determine the PID(s) of the running command. 532If 533.Va pidfile 534is set, use: 535.Pp 536.Dl "check_pidfile $pidfile $procname" 537.Pp 538to find the PID. 539Otherwise, if 540.Va command 541is set, use: 542.Pp 543.Dl "check_process $procname" 544.Pp 545to find the PID. 546.It Va procname 547Process name to check for. 548Defaults to the value of 549.Va command . 550.It Va required_dirs 551Check for the existence of the listed directories 552before running the default start method. 553.It Va required_files 554Check for the readability of the listed files 555before running the default start method. 556.It Va required_vars 557Perform 558.Ic checkyesno 559on each of the list variables 560before running the default start method. 561.It Va ${name}_chdir 562Directory to 563.Ic cd 564to before running 565.Va command , 566if 567.Va ${name}_chroot 568is not provided. 569.It Va ${name}_chroot 570Directory to 571.Xr chroot 8 572to before running 573.Va command . 574Only supported after 575.Pa /usr 576is mounted. 577.It Va ${name}_flags 578Arguments to call 579.Va command 580with. 581This is usually set in 582.Xr rc.conf 5 , 583and not in the 584.Xr rc.d 8 585script. 586The environment variable 587.Sq Ev flags 588can be used to override this. 589.It Va ${name}_nice 590.Xr nice 1 591level to run 592.Va command 593as. 594Only supported after 595.Pa /usr 596is mounted. 597.It Va ${name}_program 598Full path to the command. 599Overrides 600.Va command 601if both are set, but has no effect if 602.Va command 603is unset. 604As a rule, 605.Va command 606should be set in the script while 607.Va ${name}_program 608should be set in 609.Xr rc.conf 5 . 610.It Va ${name}_user 611User to run 612.Va command 613as, using 614.Xr chroot 8 . 615if 616.Va ${name}_chroot 617is set, otherwise 618uses 619.Xr su 1 . 620Only supported after 621.Pa /usr 622is mounted. 623.It Va ${name}_group 624Group to run the chrooted 625.Va command 626as. 627.It Va ${name}_groups 628Comma separated list of supplementary groups to run the chrooted 629.Va command 630with. 631.It Ar argument Ns Va _cmd 632Shell commands which override the default method for 633.Ar argument . 634.It Ar argument Ns Va _precmd 635Shell commands to run just before running 636.Ar argument Ns Va _cmd 637or the default method for 638.Ar argument . 639If this returns a non-zero exit code, the main method is not performed. 640If the default method is being executed, this check is performed after 641the 642.Va required_* 643checks and process (non-)existence checks. 644.It Ar argument Ns Va _postcmd 645Shell commands to run if running 646.Ar argument Ns Va _cmd 647or the default method for 648.Ar argument 649returned a zero exit code. 650.It Va sig_stop 651Signal to send the processes to stop in the default 652.Cm stop 653method. 654Defaults to 655.Dv SIGTERM . 656.It Va sig_reload 657Signal to send the processes to reload in the default 658.Cm reload 659method. 660Defaults to 661.Dv SIGHUP . 662.El 663.Pp 664For a given method 665.Ar argument , 666if 667.Ar argument Ns Va _cmd 668is not defined, then a default method is provided by 669.Ic run_rc_command : 670.Bl -tag -width ".Sy Argument" -offset indent 671.It Sy Argument 672.Sy Default method 673.It Cm start 674If 675.Va command 676is not running and 677.Ic checkyesno Va rcvar 678succeeds, start 679.Va command . 680.It Cm stop 681Determine the PIDs of 682.Va command 683with 684.Ic check_pidfile 685or 686.Ic check_process 687(as appropriate), 688.Ic kill Va sig_stop 689those PIDs, and run 690.Ic wait_for_pids 691on those PIDs. 692.It Cm reload 693Similar to 694.Cm stop , 695except that it uses 696.Va sig_reload 697instead, and does not run 698.Ic wait_for_pids . 699Another difference from 700.Cm stop 701is that 702.Cm reload 703is not provided by default. 704It can be enabled via 705.Va extra_commands 706if appropriate: 707.Pp 708.Dl "extra_commands=reload" 709.It Cm restart 710Runs the 711.Cm stop 712method, then the 713.Cm start 714method. 715.It Cm status 716Show the PID of 717.Va command , 718or some other script specific status operation. 719.It Cm poll 720Wait for 721.Va command 722to exit. 723.It Cm rcvar 724Display which 725.Xr rc.conf 5 726variable is used (if any). 727This method always works, even if the appropriate 728.Xr rc.conf 5 729variable is set to 730.Dq Li NO . 731.El 732.Pp 733The following variables are available to the methods 734(such as 735.Ar argument Ns Va _cmd ) 736as well as after 737.Ic run_rc_command 738has completed: 739.Bl -tag -width ".Va rc_flags" -offset indent 740.It Va rc_arg 741Argument provided to 742.Ic run_rc_command , 743after fast and force processing has been performed. 744.It Va rc_flags 745Flags to start the default command with. 746Defaults to 747.Va ${name}_flags , 748unless overridden by the environment variable 749.Sq Ev flags . 750This variable may be changed by the 751.Ar argument Ns Va _precmd 752method. 753.It Va rc_pid 754PID of 755.Va command 756(if appropriate). 757.It Va rc_fast 758Not empty if 759.Dq Li fast 760prefix was used. 761.It Va rc_force 762Not empty if 763.Dq Li force 764prefix was used. 765.El 766.It Ic run_rc_script Ar file argument 767Start the script 768.Ar file 769with an argument of 770.Ar argument , 771and handle the return value from the script. 772.Pp 773Various shell variables are unset before 774.Ar file 775is started: 776.Bd -ragged -offset indent 777.Va name , 778.Va command , 779.Va command_args , 780.Va command_interpreter , 781.Va extra_commands , 782.Va pidfile , 783.Va rcvar , 784.Va required_dirs , 785.Va required_files , 786.Va required_vars , 787.Ar argument Ns Va _cmd , 788.Ar argument Ns Va _precmd . 789.Ar argument Ns Va _postcmd . 790.Ed 791.Pp 792The startup behaviour of 793.Ar file 794depends upon the following checks: 795.Bl -enum 796.It 797If 798.Ar file 799ends in 800.Pa .sh , 801it is sourced into the current shell. 802.It 803If 804.Ar file 805appears to be a backup or scratch file 806(e.g., with a suffix of 807.Pa ~ , # , .OLD , 808or 809.Pa .orig ) , 810ignore it. 811.It 812If 813.Ar file 814is not executable, ignore it. 815.It 816If the 817.Xr rc.conf 5 818variable 819.Va rc_fast_and_loose 820is empty, 821source 822.Ar file 823in a sub shell, 824otherwise source 825.Ar file 826into the current shell. 827.El 828.It Ic set_rcvar Op Ar base 829Set the variable name required to start a service. 830In 831.Fx 832a daemon is usually controlled by an 833.Xr rc.conf 5 834variable consisting of a daemon's name postfixed by the string 835.Dq Li "_enable" . 836This is not the case in 837.Nx . 838When the following line is included in a script: 839.Pp 840.Dl "rcvar=`set_rcvar`" 841.Pp 842this function will use the value of the 843.Va $name 844variable, which should be defined by the calling script, 845to construct the appropriate 846.Xr rc.conf 5 847knob. 848If the 849.Ar base 850argument is set it will use 851.Ar base 852instead of 853.Va $name . 854.It Ic wait_for_pids Op Ar pid ... 855Wait until all of the provided 856.Ar pids 857do not exist any more, printing the list of outstanding 858.Ar pids 859every two seconds. 860.It Ic warn Ar message 861Display a warning message to 862.Va stderr 863and log it to the system log 864using 865.Xr logger 1 . 866The warning message consists of the script name 867(from 868.Va $0 ) , 869followed by 870.Dq Li ": WARNING: " , 871and then 872.Ar message . 873.El 874.Sh FILES 875.Bl -tag -width ".Pa /etc/rc.subr" -compact 876.It Pa /etc/rc.subr 877The 878.Nm 879file resides in 880.Pa /etc . 881.El 882.Sh SEE ALSO 883.Xr rc.conf 5 , 884.Xr rc 8 885.Sh HISTORY 886The 887.Nm 888script 889appeared in 890.Nx 1.3 . 891The 892.Xr rc.d 8 893support functions appeared in 894.Nx 1.5 . 895The 896.Nm 897script 898first appeared in 899.Fx 5.0 . 900