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