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