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