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