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 February 22, 2006 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. 452Can be overridden by 453.Va ${name}_program . 454.It Va command_args 455Optional arguments and/or shell directives for 456.Va command . 457.It Va command_interpreter 458.Va command 459is started with: 460.Pp 461.Dl "#! command_interpreter [...]" 462.Pp 463which results in its 464.Xr ps 1 465command being: 466.Pp 467.Dl "command_interpreter [...] command" 468.Pp 469so use that string to find the PID(s) of the running command 470rather than 471.Va command . 472.It Va extra_commands 473Extra commands/keywords/arguments supported. 474.It Va pidfile 475Path to PID file. 476Used to determine the PID(s) of the running command. 477If 478.Va pidfile 479is set, use: 480.Pp 481.Dl "check_pidfile $pidfile $procname" 482.Pp 483to find the PID. 484Otherwise, if 485.Va command 486is set, use: 487.Pp 488.Dl "check_process $procname" 489.Pp 490to find the PID. 491.It Va procname 492Process name to check for. 493Defaults to the value of 494.Va command . 495.It Va required_dirs 496Check for the existence of the listed directories 497before running the default start method. 498.It Va required_files 499Check for the readability of the listed files 500before running the default start method. 501.It Va required_vars 502Perform 503.Ic checkyesno 504on each of the list variables 505before running the default start method. 506.It Va ${name}_chdir 507Directory to 508.Ic cd 509to before running 510.Va command , 511if 512.Va ${name}_chroot 513is not provided. 514.It Va ${name}_chroot 515Directory to 516.Xr chroot 8 517to before running 518.Va command . 519Only supported after 520.Pa /usr 521is mounted. 522.It Va ${name}_flags 523Arguments to call 524.Va command 525with. 526This is usually set in 527.Xr rc.conf 5 , 528and not in the 529.Xr rc.d 8 530script. 531The environment variable 532.Sq Ev flags 533can be used to override this. 534.It Va ${name}_nice 535.Xr nice 1 536level to run 537.Va command 538as. 539Only supported after 540.Pa /usr 541is mounted. 542.It Va ${name}_program 543Full path to the command. 544Overrides 545.Va command 546if both are set, but has no effect if 547.Va command 548is unset. 549As a rule, 550.Va command 551should be set in the script while 552.Va ${name}_program 553should be set in 554.Xr rc.conf 5 . 555.It Va ${name}_user 556User to run 557.Va command 558as, using 559.Xr chroot 8 . 560if 561.Va ${name}_chroot 562is set, otherwise 563uses 564.Xr su 1 . 565Only supported after 566.Pa /usr 567is mounted. 568.It Va ${name}_group 569Group to run the chrooted 570.Va command 571as. 572.It Va ${name}_groups 573Comma separated list of supplementary groups to run the chrooted 574.Va command 575with. 576.It Ar argument Ns Va _cmd 577Shell commands which override the default method for 578.Ar argument . 579.It Ar argument Ns Va _precmd 580Shell commands to run just before running 581.Ar argument Ns Va _cmd 582or the default method for 583.Ar argument . 584If this returns a non-zero exit code, the main method is not performed. 585If the default method is being executed, this check is performed after 586the 587.Va required_* 588checks and process (non-)existence checks. 589.It Ar argument Ns Va _postcmd 590Shell commands to run if running 591.Ar argument Ns Va _cmd 592or the default method for 593.Ar argument 594returned a zero exit code. 595.It Va sig_stop 596Signal to send the processes to stop in the default 597.Cm stop 598method. 599Defaults to 600.Dv SIGTERM . 601.It Va sig_reload 602Signal to send the processes to reload in the default 603.Cm reload 604method. 605Defaults to 606.Dv SIGHUP . 607.El 608.Pp 609For a given method 610.Ar argument , 611if 612.Ar argument Ns Va _cmd 613is not defined, then a default method is provided by 614.Ic run_rc_command : 615.Bl -tag -width ".Sy Argument" -offset indent 616.It Sy Argument 617.Sy Default method 618.It Cm start 619If 620.Va command 621is not running and 622.Ic checkyesno Va rcvar 623succeeds, start 624.Va command . 625.It Cm stop 626Determine the PIDs of 627.Va command 628with 629.Ic check_pidfile 630or 631.Ic check_process 632(as appropriate), 633.Ic kill Va sig_stop 634those PIDs, and run 635.Ic wait_for_pids 636on those PIDs. 637.It Cm reload 638Similar to 639.Cm stop , 640except that it uses 641.Va sig_reload 642instead, and does not run 643.Ic wait_for_pids . 644Another difference from 645.Cm stop 646is that 647.Cm reload 648is not provided by default. 649It can be enabled via 650.Va extra_commands 651if appropriate: 652.Pp 653.Dl "extra_commands=reload" 654.It Cm restart 655Runs the 656.Cm stop 657method, then the 658.Cm start 659method. 660.It Cm status 661Show the PID of 662.Va command , 663or some other script specific status operation. 664.It Cm poll 665Wait for 666.Va command 667to exit. 668.It Cm rcvar 669Display which 670.Xr rc.conf 5 671variable is used (if any). 672This method always works, even if the appropriate 673.Xr rc.conf 5 674variable is set to 675.Dq Li NO . 676.El 677.Pp 678The following variables are available to the methods 679(such as 680.Ar argument Ns Va _cmd ) 681as well as after 682.Ic run_rc_command 683has completed: 684.Bl -tag -width ".Va rc_flags" -offset indent 685.It Va rc_arg 686Argument provided to 687.Ic run_rc_command , 688after fast and force processing has been performed. 689.It Va rc_flags 690Flags to start the default command with. 691Defaults to 692.Va ${name}_flags , 693unless overridden by the environment variable 694.Sq Ev flags . 695This variable may be changed by the 696.Ar argument Ns Va _precmd 697method. 698.It Va rc_pid 699PID of 700.Va command 701(if appropriate). 702.It Va rc_fast 703Not empty if 704.Dq Li fast 705prefix was used. 706.It Va rc_force 707Not empty if 708.Dq Li force 709prefix was used. 710.El 711.It Ic run_rc_script Ar file argument 712Start the script 713.Ar file 714with an argument of 715.Ar argument , 716and handle the return value from the script. 717.Pp 718Various shell variables are unset before 719.Ar file 720is started: 721.Bd -ragged -offset indent 722.Va name , 723.Va command , 724.Va command_args , 725.Va command_interpreter , 726.Va extra_commands , 727.Va pidfile , 728.Va rcvar , 729.Va required_dirs , 730.Va required_files , 731.Va required_vars , 732.Ar argument Ns Va _cmd , 733.Ar argument Ns Va _precmd . 734.Ar argument Ns Va _postcmd . 735.Ed 736.Pp 737The startup behaviour of 738.Ar file 739depends upon the following checks: 740.Bl -enum 741.It 742If 743.Ar file 744ends in 745.Pa .sh , 746it is sourced into the current shell. 747.It 748If 749.Ar file 750appears to be a backup or scratch file 751(e.g., with a suffix of 752.Pa ~ , # , .OLD , 753or 754.Pa .orig ) , 755ignore it. 756.It 757If 758.Ar file 759is not executable, ignore it. 760.It 761If the 762.Xr rc.conf 5 763variable 764.Va rc_fast_and_loose 765is empty, 766source 767.Ar file 768in a sub shell, 769otherwise source 770.Ar file 771into the current shell. 772.El 773.It Ic set_rcvar Op Ar base 774Set the variable name required to start a service. 775In 776.Fx 777a daemon is usually controlled by an 778.Xr rc.conf 5 779variable consisting of a daemon's name postfixed by the string 780.Dq Li "_enable" . 781This is not the case in 782.Nx . 783When the following line is included in a script: 784.Pp 785.Dl "rcvar=`set_rcvar`" 786.Pp 787this function will use the value of the 788.Va $name 789variable, which should be defined by the calling script, 790to construct the appropriate 791.Xr rc.conf 5 792knob. 793If the 794.Ar base 795argument is set it will use 796.Ar base 797instead of 798.Va $name . 799.It Ic wait_for_pids Op Ar pid ... 800Wait until all of the provided 801.Ar pids 802do not exist any more, printing the list of outstanding 803.Ar pids 804every two seconds. 805.It Ic warn Ar message 806Display a warning message to 807.Va stderr 808and log it to the system log 809using 810.Xr logger 1 . 811The warning message consists of the script name 812(from 813.Va $0 ) , 814followed by 815.Dq Li ": WARNING: " , 816and then 817.Ar message . 818.El 819.Sh FILES 820.Bl -tag -width ".Pa /etc/rc.subr" -compact 821.It Pa /etc/rc.subr 822The 823.Nm 824file resides in 825.Pa /etc . 826.El 827.Sh SEE ALSO 828.Xr rc.conf 5 , 829.Xr rc 8 830.Sh HISTORY 831The 832.Nm 833script 834appeared in 835.Nx 1.3 . 836The 837.Xr rc.d 8 838support functions appeared in 839.Nx 1.5 . 840The 841.Nm 842script 843first appeared in 844.Fx 5.0 . 845