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 May 18, 2007 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.Sy Note : 222.Ar var 223should be a variable name, not its value; 224.Ic checkyesno 225will expand the variable by itself. 226.It Ic check_pidfile Ar pidfile procname Op Ar interpreter 227Parses the first word of the first line of 228.Ar pidfile 229for a PID, and ensures that the process with that PID 230is running and its first argument matches 231.Ar procname . 232Prints the matching PID if successful, otherwise nothing. 233If 234.Ar interpreter 235is provided, parse the first line of 236.Ar procname , 237ensure that the line is of the form: 238.Pp 239.Dl "#! interpreter [...]" 240.Pp 241and use 242.Ar interpreter 243with its optional arguments and 244.Ar procname 245appended as the process string to search for. 246.It Ic check_process Ar procname Op Ar interpreter 247Prints the PIDs of any processes that are running with a first 248argument that matches 249.Ar procname . 250.Ar interpreter 251is handled as per 252.Ic check_pidfile . 253.It Ic debug Ar message 254Display a debugging message to 255.Va stderr , 256log it to the system log using 257.Xr logger 1 , 258and 259return to the caller. 260The error message consists of the script name 261(from 262.Va $0 ) , 263followed by 264.Dq Li ": DEBUG: " , 265and then 266.Ar message . 267This function is intended to be used by developers 268as an aid to debugging scripts. 269It can be turned on or off 270by the 271.Xr rc.conf 5 272variable 273.Va rc_debug . 274.It Ic err Ar exitval message 275Display an error message to 276.Va stderr , 277log it to the system log 278using 279.Xr logger 1 , 280and 281.Ic exit 282with an exit value of 283.Ar exitval . 284The error message consists of the script name 285(from 286.Va $0 ) , 287followed by 288.Dq Li ": ERROR: " , 289and then 290.Ar message . 291.It Ic force_depend Ar name 292Output an advisory message and force the 293.Ar name 294service to start. 295The 296.Ar name 297argument is the 298.Xr basename 1 299component of the path to the script, usually 300.Pa /etc/rc.d/name . 301If the script fails for any reason it will output a warning 302and return with a return value of 1. 303If it was successful 304it will return 0. 305.It Ic info Ar message 306Display an informational message to 307.Va stdout , 308and log it to the system log using 309.Xr logger 1 . 310The message consists of the script name 311(from 312.Va $0 ) , 313followed by 314.Dq Li ": INFO: " , 315and then 316.Ar message . 317The display of this informational output can be 318turned on or off by the 319.Xr rc.conf 5 320variable 321.Va rc_info . 322.It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file 323Load 324.Ar file 325as a kernel module unless it is already loaded. 326For the purpose of checking the module status, 327either the exact module name can be specified using 328.Fl m , 329or an 330.Xr egrep 1 331regular expression matching the module name can be supplied via 332.Fl e . 333By default, the module is assumed to have the same name as 334.Ar file , 335which is not always the case. 336.It Ic load_rc_config Ar name 337Source in the configuration files for 338.Ar name . 339First, 340.Pa /etc/rc.conf 341is sourced if it has not yet been read in. 342Then, 343.Pa /etc/rc.conf.d/ Ns Ar name 344is sourced if it is an existing file. 345The latter may also contain other variable assignments to override 346.Ic run_rc_command 347arguments defined by the calling script, to provide an easy 348mechanism for an administrator to override the behaviour of a given 349.Xr rc.d 8 350script without requiring the editing of that script. 351.It Ic load_rc_config_var Ar name Ar var 352Read the 353.Xr rc.conf 5 354variable 355.Ar var 356for 357.Ar name 358and set in the current shell, using 359.Ic load_rc_config 360in a sub-shell to prevent unwanted side effects from other variable 361assignments. 362.It Ic mount_critical_filesystems Ar type 363Go through a list of critical file systems, 364as found in the 365.Xr rc.conf 5 366variable 367.Va critical_filesystems_ Ns Ar type , 368mounting each one that 369is not currently mounted. 370.It Ic rc_usage Ar command ... 371Print a usage message for 372.Va $0 , 373with 374.Ar commands 375being the list of valid arguments 376prefixed by 377.Sm off 378.Dq Bq Li fast | force | one . 379.Sm on 380.It Ic reverse_list Ar item ... 381Print the list of 382.Ar items 383in reverse order. 384.It Ic run_rc_command Ar argument 385Run the 386.Ar argument 387method for the current 388.Xr rc.d 8 389script, based on the settings of various shell variables. 390.Ic run_rc_command 391is extremely flexible, and allows fully functional 392.Xr rc.d 8 393scripts to be implemented in a small amount of shell code. 394.Pp 395.Ar argument 396is searched for in the list of supported commands, which may be one 397of: 398.Bl -tag -width ".Cm restart" -offset indent 399.It Cm start 400Start the service. 401This should check that the service is to be started as specified by 402.Xr rc.conf 5 . 403Also checks if the service is already running and refuses to start if 404it is. 405This latter check is not performed by standard 406.Fx 407scripts if the system is starting directly to multi-user mode, to 408speed up the boot process. 409.It Cm stop 410If the service is to be started as specified by 411.Xr rc.conf 5 , 412stop the service. 413This should check that the service is running and complain if it is not. 414.It Cm restart 415Perform a 416.Cm stop 417then a 418.Cm start . 419Defaults to displaying the process ID of the program (if running). 420.It Cm rcvar 421Display which 422.Xr rc.conf 5 423variables are used to control the startup of the service (if any). 424.El 425.Pp 426If 427.Va pidfile 428or 429.Va procname 430is set, also support: 431.Bl -tag -width ".Cm restart" -offset indent 432.It Cm poll 433Wait for the command to exit. 434.It Cm status 435Show the status of the process. 436.El 437.Pp 438Other supported commands are listed in the optional variable 439.Va extra_commands . 440.Pp 441.Ar argument 442may have one of the following prefixes which alters its operation: 443.Bl -tag -width ".Li force" -offset indent 444.It Li fast 445Skip the check for an existing running process, 446and sets 447.Va rc_fast Ns = Ns Li YES . 448.It Li force 449Skip the checks for 450.Va rcvar 451being set to 452.Dq Li YES , 453and sets 454.Va rc_force Ns = Ns Li YES . 455This ignores 456.Ar argument Ns Va _precmd 457returning non-zero, and ignores any of the 458.Va required_* 459tests failing, and always returns a zero exit status. 460.It Li one 461Skip the checks for 462.Va rcvar 463being set to 464.Dq Li YES , 465but performs all the other prerequisite tests. 466.El 467.Pp 468.Ic run_rc_command 469uses the following shell variables to control its behaviour. 470Unless otherwise stated, these are optional. 471.Bl -tag -width ".Va procname" -offset indent 472.It Va name 473The name of this script. 474This is not optional. 475.It Va rcvar 476The value of 477.Va rcvar 478is checked with 479.Ic checkyesno 480to determine if this method should be run. 481.It Va command 482Full path to the command. 483Not required if 484.Ar argument Ns Va _cmd 485is defined for each supported keyword. 486Can be overridden by 487.Va ${name}_program . 488.It Va command_args 489Optional arguments and/or shell directives for 490.Va command . 491.It Va command_interpreter 492.Va command 493is started with: 494.Pp 495.Dl "#! command_interpreter [...]" 496.Pp 497which results in its 498.Xr ps 1 499command being: 500.Pp 501.Dl "command_interpreter [...] command" 502.Pp 503so use that string to find the PID(s) of the running command 504rather than 505.Va command . 506.It Va extra_commands 507Extra commands/keywords/arguments supported. 508.It Va pidfile 509Path to PID file. 510Used to determine the PID(s) of the running command. 511If 512.Va pidfile 513is set, use: 514.Pp 515.Dl "check_pidfile $pidfile $procname" 516.Pp 517to find the PID. 518Otherwise, if 519.Va command 520is set, use: 521.Pp 522.Dl "check_process $procname" 523.Pp 524to find the PID. 525.It Va procname 526Process name to check for. 527Defaults to the value of 528.Va command . 529.It Va required_dirs 530Check for the existence of the listed directories 531before running the 532.Cm start 533method. 534.It Va required_files 535Check for the readability of the listed files 536before running the 537.Cm start 538method. 539.It Va required_modules 540Ensure that the listed kernel modules are loaded 541before running the 542.Cm start 543method. 544This is done after invoking the commands from 545.Va start_precmd 546so that the missing modules are not loaded in vain 547if the preliminary commands indicate a error condition. 548A word in the list can have an optional 549.Dq Li : Ns Ar modname 550or 551.Dq Li ~ Ns Ar pattern 552suffix. 553The 554.Ar modname 555or 556.Ar pattern 557parameter is passed to 558.Ic load_kld 559through a 560.Fl m 561or 562.Fl e 563option, respectively. 564See the description of 565.Ic load_kld 566in this document for details. 567.It Va required_vars 568Perform 569.Ic checkyesno 570on each of the list variables 571before running the 572.Cm start 573method. 574.It Va ${name}_chdir 575Directory to 576.Ic cd 577to before running 578.Va command , 579if 580.Va ${name}_chroot 581is not provided. 582.It Va ${name}_chroot 583Directory to 584.Xr chroot 8 585to before running 586.Va command . 587Only supported after 588.Pa /usr 589is mounted. 590.It Va ${name}_flags 591Arguments to call 592.Va command 593with. 594This is usually set in 595.Xr rc.conf 5 , 596and not in the 597.Xr rc.d 8 598script. 599The environment variable 600.Sq Ev flags 601can be used to override this. 602.It Va ${name}_nice 603.Xr nice 1 604level to run 605.Va command 606as. 607Only supported after 608.Pa /usr 609is mounted. 610.It Va ${name}_program 611Full path to the command. 612Overrides 613.Va command 614if both are set, but has no effect if 615.Va command 616is unset. 617As a rule, 618.Va command 619should be set in the script while 620.Va ${name}_program 621should be set in 622.Xr rc.conf 5 . 623.It Va ${name}_user 624User to run 625.Va command 626as, using 627.Xr chroot 8 628if 629.Va ${name}_chroot 630is set, otherwise 631uses 632.Xr su 1 . 633Only supported after 634.Pa /usr 635is mounted. 636.It Va ${name}_group 637Group to run the chrooted 638.Va command 639as. 640.It Va ${name}_groups 641Comma separated list of supplementary groups to run the chrooted 642.Va command 643with. 644.It Ar argument Ns Va _cmd 645Shell commands which override the default method for 646.Ar argument . 647.It Ar argument Ns Va _precmd 648Shell commands to run just before running 649.Ar argument Ns Va _cmd 650or the default method for 651.Ar argument . 652If this returns a non-zero exit code, the main method is not performed. 653If the default method is being executed, this check is performed after 654the 655.Va required_* 656checks and process (non-)existence checks. 657.It Ar argument Ns Va _postcmd 658Shell commands to run if running 659.Ar argument Ns Va _cmd 660or the default method for 661.Ar argument 662returned a zero exit code. 663.It Va sig_stop 664Signal to send the processes to stop in the default 665.Cm stop 666method. 667Defaults to 668.Dv SIGTERM . 669.It Va sig_reload 670Signal to send the processes to reload in the default 671.Cm reload 672method. 673Defaults to 674.Dv SIGHUP . 675.El 676.Pp 677For a given method 678.Ar argument , 679if 680.Ar argument Ns Va _cmd 681is not defined, then a default method is provided by 682.Ic run_rc_command : 683.Bl -tag -width ".Sy Argument" -offset indent 684.It Sy Argument 685.Sy Default method 686.It Cm start 687If 688.Va command 689is not running and 690.Ic checkyesno Va rcvar 691succeeds, start 692.Va command . 693.It Cm stop 694Determine the PIDs of 695.Va command 696with 697.Ic check_pidfile 698or 699.Ic check_process 700(as appropriate), 701.Ic kill Va sig_stop 702those PIDs, and run 703.Ic wait_for_pids 704on those PIDs. 705.It Cm reload 706Similar to 707.Cm stop , 708except that it uses 709.Va sig_reload 710instead, and does not run 711.Ic wait_for_pids . 712Another difference from 713.Cm stop 714is that 715.Cm reload 716is not provided by default. 717It can be enabled via 718.Va extra_commands 719if appropriate: 720.Pp 721.Dl "extra_commands=reload" 722.It Cm restart 723Runs the 724.Cm stop 725method, then the 726.Cm start 727method. 728.It Cm status 729Show the PID of 730.Va command , 731or some other script specific status operation. 732.It Cm poll 733Wait for 734.Va command 735to exit. 736.It Cm rcvar 737Display which 738.Xr rc.conf 5 739variable is used (if any). 740This method always works, even if the appropriate 741.Xr rc.conf 5 742variable is set to 743.Dq Li NO . 744.El 745.Pp 746The following variables are available to the methods 747(such as 748.Ar argument Ns Va _cmd ) 749as well as after 750.Ic run_rc_command 751has completed: 752.Bl -tag -width ".Va rc_flags" -offset indent 753.It Va rc_arg 754Argument provided to 755.Ic run_rc_command , 756after fast and force processing has been performed. 757.It Va rc_flags 758Flags to start the default command with. 759Defaults to 760.Va ${name}_flags , 761unless overridden by the environment variable 762.Sq Ev flags . 763This variable may be changed by the 764.Ar argument Ns Va _precmd 765method. 766.It Va rc_pid 767PID of 768.Va command 769(if appropriate). 770.It Va rc_fast 771Not empty if 772.Dq Li fast 773prefix was used. 774.It Va rc_force 775Not empty if 776.Dq Li force 777prefix was used. 778.El 779.It Ic run_rc_script Ar file argument 780Start the script 781.Ar file 782with an argument of 783.Ar argument , 784and handle the return value from the script. 785.Pp 786Various shell variables are unset before 787.Ar file 788is started: 789.Bd -ragged -offset indent 790.Va name , 791.Va command , 792.Va command_args , 793.Va command_interpreter , 794.Va extra_commands , 795.Va pidfile , 796.Va rcvar , 797.Va required_dirs , 798.Va required_files , 799.Va required_vars , 800.Ar argument Ns Va _cmd , 801.Ar argument Ns Va _precmd . 802.Ar argument Ns Va _postcmd . 803.Ed 804.Pp 805The startup behaviour of 806.Ar file 807depends upon the following checks: 808.Bl -enum 809.It 810If 811.Ar file 812ends in 813.Pa .sh , 814it is sourced into the current shell. 815.It 816If 817.Ar file 818appears to be a backup or scratch file 819(e.g., with a suffix of 820.Pa ~ , # , .OLD , 821or 822.Pa .orig ) , 823ignore it. 824.It 825If 826.Ar file 827is not executable, ignore it. 828.It 829If the 830.Xr rc.conf 5 831variable 832.Va rc_fast_and_loose 833is empty, 834source 835.Ar file 836in a sub shell, 837otherwise source 838.Ar file 839into the current shell. 840.El 841.It Ic stop_boot Op Ar always 842Prevent booting to multiuser mode. 843If the 844.Va autoboot 845variable is set to 846.Ql yes , 847or 848.Ic checkyesno Ar always 849indicates a truth value, then a 850.Dv SIGTERM 851signal is sent to the parent 852process, which is assumed to be 853.Xr rc 8 . 854Otherwise, the shell exits with a non-zero status. 855.It Ic set_rcvar Op Ar base 856Set the variable name required to start a service. 857In 858.Fx 859a daemon is usually controlled by an 860.Xr rc.conf 5 861variable consisting of a daemon's name postfixed by the string 862.Dq Li "_enable" . 863This is not the case in 864.Nx . 865When the following line is included in a script: 866.Pp 867.Dl "rcvar=`set_rcvar`" 868.Pp 869this function will use the value of the 870.Va $name 871variable, which should be defined by the calling script, 872to construct the appropriate 873.Xr rc.conf 5 874knob. 875If the 876.Ar base 877argument is set it will use 878.Ar base 879instead of 880.Va $name . 881.It Ic wait_for_pids Op Ar pid ... 882Wait until all of the provided 883.Ar pids 884do not exist any more, printing the list of outstanding 885.Ar pids 886every two seconds. 887.It Ic warn Ar message 888Display a warning message to 889.Va stderr 890and log it to the system log 891using 892.Xr logger 1 . 893The warning message consists of the script name 894(from 895.Va $0 ) , 896followed by 897.Dq Li ": WARNING: " , 898and then 899.Ar message . 900.El 901.Sh FILES 902.Bl -tag -width ".Pa /etc/rc.subr" -compact 903.It Pa /etc/rc.subr 904The 905.Nm 906file resides in 907.Pa /etc . 908.El 909.Sh SEE ALSO 910.Xr rc.conf 5 , 911.Xr rc 8 912.Sh HISTORY 913The 914.Nm 915script 916appeared in 917.Nx 1.3 . 918The 919.Xr rc.d 8 920support functions appeared in 921.Nx 1.5 . 922The 923.Nm 924script 925first appeared in 926.Fx 5.0 . 927