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 February 4, 2016 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}_oomprotect 608.Xr protect 1 609.Va command 610from being killed when swap space is exhausted. 611If 612.Em YES 613is used, no child processes are protected. 614If 615.Em ALL , 616protect all child processes. 617.It Va ${name}_program 618Full path to the command. 619Overrides 620.Va command 621if both are set, but has no effect if 622.Va command 623is unset. 624As a rule, 625.Va command 626should be set in the script while 627.Va ${name}_program 628should be set in 629.Xr rc.conf 5 . 630.It Va ${name}_user 631User to run 632.Va command 633as, using 634.Xr chroot 8 635if 636.Va ${name}_chroot 637is set, otherwise 638uses 639.Xr su 1 . 640Only supported after 641.Pa /usr 642is mounted. 643.It Va ${name}_group 644Group to run the chrooted 645.Va command 646as. 647.It Va ${name}_groups 648Comma separated list of supplementary groups to run the chrooted 649.Va command 650with. 651.It Va ${name}_prepend 652Commands to be prepended to 653.Va command . 654This is a generic version of 655.Va ${name}_env , 656.Va ${name}_fib , 657or 658.Va ${name}_nice . 659.It Ar argument Ns Va _cmd 660Shell commands which override the default method for 661.Ar argument . 662.It Ar argument Ns Va _precmd 663Shell commands to run just before running 664.Ar argument Ns Va _cmd 665or the default method for 666.Ar argument . 667If this returns a non-zero exit code, the main method is not performed. 668If the default method is being executed, this check is performed after 669the 670.Va required_* 671checks and process (non-)existence checks. 672.It Ar argument Ns Va _postcmd 673Shell commands to run if running 674.Ar argument Ns Va _cmd 675or the default method for 676.Ar argument 677returned a zero exit code. 678.It Va sig_stop 679Signal to send the processes to stop in the default 680.Cm stop 681method. 682Defaults to 683.Dv SIGTERM . 684.It Va sig_reload 685Signal to send the processes to reload in the default 686.Cm reload 687method. 688Defaults to 689.Dv SIGHUP . 690.El 691.Pp 692For a given method 693.Ar argument , 694if 695.Ar argument Ns Va _cmd 696is not defined, then a default method is provided by 697.Ic run_rc_command : 698.Bl -tag -width ".Sy Argument" -offset indent 699.It Sy Argument 700.Sy Default method 701.It Cm start 702If 703.Va command 704is not running and 705.Ic checkyesno Va rcvar 706succeeds, start 707.Va command . 708.It Cm stop 709Determine the PIDs of 710.Va command 711with 712.Ic check_pidfile 713or 714.Ic check_process 715(as appropriate), 716.Ic kill Va sig_stop 717those PIDs, and run 718.Ic wait_for_pids 719on those PIDs. 720.It Cm reload 721Similar to 722.Cm stop , 723except that it uses 724.Va sig_reload 725instead, and does not run 726.Ic wait_for_pids . 727Another difference from 728.Cm stop 729is that 730.Cm reload 731is not provided by default. 732It can be enabled via 733.Va extra_commands 734if appropriate: 735.Pp 736.Dl "extra_commands=reload" 737.It Cm restart 738Runs the 739.Cm stop 740method, then the 741.Cm start 742method. 743.It Cm status 744Show the PID of 745.Va command , 746or some other script specific status operation. 747.It Cm poll 748Wait for 749.Va command 750to exit. 751.It Cm rcvar 752Display which 753.Xr rc.conf 5 754variable is used (if any). 755This method always works, even if the appropriate 756.Xr rc.conf 5 757variable is set to 758.Dq Li NO . 759.El 760.Pp 761The following variables are available to the methods 762(such as 763.Ar argument Ns Va _cmd ) 764as well as after 765.Ic run_rc_command 766has completed: 767.Bl -tag -width ".Va rc_flags" -offset indent 768.It Va rc_arg 769Argument provided to 770.Ic run_rc_command , 771after fast and force processing has been performed. 772.It Va rc_flags 773Flags to start the default command with. 774Defaults to 775.Va ${name}_flags , 776unless overridden by the environment variable 777.Sq Ev flags . 778This variable may be changed by the 779.Ar argument Ns Va _precmd 780method. 781.It Va rc_pid 782PID of 783.Va command 784(if appropriate). 785.It Va rc_fast 786Not empty if 787.Dq Li fast 788prefix was used. 789.It Va rc_force 790Not empty if 791.Dq Li force 792prefix was used. 793.El 794.It Ic run_rc_script Ar file argument 795Start the script 796.Ar file 797with an argument of 798.Ar argument , 799and handle the return value from the script. 800.Pp 801Various shell variables are unset before 802.Ar file 803is started: 804.Bd -ragged -offset indent 805.Va name , 806.Va command , 807.Va command_args , 808.Va command_interpreter , 809.Va extra_commands , 810.Va pidfile , 811.Va rcvar , 812.Va required_dirs , 813.Va required_files , 814.Va required_vars , 815.Ar argument Ns Va _cmd , 816.Ar argument Ns Va _precmd . 817.Ar argument Ns Va _postcmd . 818.Ed 819.Pp 820The startup behaviour of 821.Ar file 822depends upon the following checks: 823.Bl -enum 824.It 825If 826.Ar file 827ends in 828.Pa .sh , 829it is sourced into the current shell. 830.It 831If 832.Ar file 833appears to be a backup or scratch file 834(e.g., with a suffix of 835.Pa ~ , # , .OLD , 836or 837.Pa .orig ) , 838ignore it. 839.It 840If 841.Ar file 842is not executable, ignore it. 843.It 844If the 845.Xr rc.conf 5 846variable 847.Va rc_fast_and_loose 848is empty, 849source 850.Ar file 851in a sub shell, 852otherwise source 853.Ar file 854into the current shell. 855.El 856.It Ic stop_boot Op Ar always 857Prevent booting to multiuser mode. 858If the 859.Va autoboot 860variable is set to 861.Ql yes , 862or 863.Ic checkyesno Ar always 864indicates a truth value, then a 865.Dv SIGTERM 866signal is sent to the parent 867process, which is assumed to be 868.Xr rc 8 . 869Otherwise, the shell exits with a non-zero status. 870.It Ic wait_for_pids Op Ar pid ... 871Wait until all of the provided 872.Ar pids 873do not exist any more, printing the list of outstanding 874.Ar pids 875every two seconds. 876.It Ic warn Ar message 877Display a warning message to 878.Va stderr 879and log it to the system log 880using 881.Xr logger 1 . 882The warning message consists of the script name 883(from 884.Va $0 ) , 885followed by 886.Dq Li ": WARNING: " , 887and then 888.Ar message . 889.El 890.Sh FILES 891.Bl -tag -width ".Pa /etc/rc.subr" -compact 892.It Pa /etc/rc.subr 893The 894.Nm 895file resides in 896.Pa /etc . 897.El 898.Sh SEE ALSO 899.Xr rc.conf 5 , 900.Xr rc 8 901.Sh HISTORY 902The 903.Nm 904script 905appeared in 906.Nx 1.3 . 907The 908.Xr rc.d 8 909support functions appeared in 910.Nx 1.5 . 911The 912.Nm 913script 914first appeared in 915.Fx 5.0 . 916