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