1.\" $OpenBSD: rc.subr.8,v 1.32 2016/09/07 13:12:42 ajacoutot Exp $ 2.\" 3.\" Copyright (c) 2011 Robert Nagy, Antoine Jacoutot, Ingo Schwarze 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: September 7 2016 $ 28.Dt RC.SUBR 8 29.Os 30.Sh NAME 31.Nm rc.subr 32.Nd daemon control scripts routines 33.Sh SYNOPSIS 34.Nm daemon Ns = Ns Ar path_to_executable 35.Nm .\& 36.Pa /etc/rc.d/rc.subr 37.Nm rc_cmd 38.Ar action 39.Sh DESCRIPTION 40Apart from a few notable exceptions, rc scripts must follow this 41naming policy: 42.Pp 43.Bl -enum -compact 44.It 45When possible, use the same name as the 46.Nm daemon 47it is referring to. 48.It 49It must follow 50.Xr ksh 1 51variable naming: begin with an alphabetic or underscore character, followed by 52one or more alphanumeric or underscore characters. 53Dashes 54.Pq Sq - 55have to be converted to 56underscores 57.Pq Sq _ . 58.El 59.Pp 60Every script under 61.Pa /etc/rc.d 62follows this pattern: 63.Pp 64.Bl -enum -compact 65.It 66Define the 67.Va daemon 68variable. 69.It 70Define service-specific defaults for one or more 71.Va daemon_* 72variables (optional). 73.It 74Source 75.Nm , 76which defines default shell functions and variable values. 77.It 78Override the 79.Va pexp 80variable or any of the 81.Ic rc_* 82functions and set the 83.Va rc_bg 84or 85.Va rc_reload 86variables, if needed. 87.It 88Define an 89.Ic rc_pre 90and/or 91.Ic rc_post 92function, if needed. 93.It 94Call the 95.Ic rc_cmd 96function as 97.Dq "rc_cmd $1" . 98.El 99.Pp 100The following shell functions are defined by 101.Nm : 102.Bl -tag -width rc_reload 103.It Ic rc_cmd Ar action 104Run the 105.Ar action 106for the current 107.Nm rc.d 108script, based on the settings of various shell variables. 109.Ic rc_cmd 110is extremely flexible, and allows fully functional 111.Nm rc.d 112scripts to be implemented in a small amount of shell code. 113For a given 114.Ar action , 115if the 116.Ic rc_${action} 117function is not defined, then a default function is provided by 118.Nm rc.subr . 119In addition actions can be disabled by setting the 120.Va rc_${action} 121variable to 122.Dq NO . 123For example, if 124.Dq rc_reload=NO 125is set in the 126.Nm rc.d 127script, and 128.Ic rc_cmd 129is called for the reload action, an error will be raised. 130Similarly, the special variable 131.Va rc_usercheck 132must be set to 133.Dq NO 134if the 135.Cm check 136.Ar action 137requires root privileges. 138.Pp 139The 140.Ar action 141argument can be 142.Cm start , 143.Cm stop , 144.Cm reload , 145.Cm restart , 146or 147.Cm check : 148.Bl -tag -width restart 149.It Ic check 150Call 151.Ic rc_check . 152Return 0 if the daemon is running or 1 if it is not. 153.It Ic start 154Check that the service is running by calling 155.Ic rc_check . 156If it's not running, call 157.Ic rc_pre 158if it exists, then 159.Ic rc_start . 160.It Ic stop 161Check that the service is running by calling 162.Ic rc_check . 163If it is running, 164call 165.Ic rc_stop 166and wait up to 30 seconds for the daemon to properly shutdown. 167If successful, run 168.Ic rc_post 169if it exists. 170.It Ic restart 171Run the 172.Ar action 173argument 174.Cm stop , 175then if successful run 176.Cm start . 177.It Ic reload 178Check that the service is running by calling 179.Ic rc_check . 180If it is running, 181call 182.Ic rc_reload . 183.El 184.It Ic rc_check 185Search for processes of the service with 186.Xr pgrep 1 187using the regular expression given in the 188.Va pexp 189variable. 190.It Ic rc_start 191Start the daemon. 192Defaults to: 193.Bd -literal -offset indent 194${rcexec} "${daemon} ${daemon_flags} ${_bg}" 195.Ed 196.It Ic rc_stop 197Stop the daemon. 198Send a 199.Dv SIGTERM 200signal using 201.Xr pkill 1 202on the regular expression given in the 203.Va pexp 204variable. 205.It Ic rc_reload 206Send a 207.Dv SIGHUP 208signal using 209.Xr pkill 1 210on the regular expression given in the 211.Va pexp 212variable. 213One has to make sure that sending 214.Dv SIGHUP 215to a daemon will have the desired effect, 216i.e. that it will reload its configuration. 217.El 218.Sh ENVIRONMENT 219.Ic rc_cmd 220uses the following shell variables to control its behaviour. 221.Bl -tag -width "daemon_timeout" 222.It Va daemon 223The path to the daemon, optionally followed by one or more 224whitespace separated arguments. 225Arguments included here are always used, even if 226.Va daemon_flags 227is empty. 228This variable is required. 229It is an error to source 230.Nm 231without defining 232.Va daemon 233first. 234.It Va daemon_class 235Login class to run the daemon with, using 236.Xr su 1 . 237This is a read only variable that gets set by 238.Nm rc.subr 239itself. 240It searches 241.Xr login.conf 5 242for a login class that has the same name as the 243.Nm rc.d 244script itself and uses that. 245If no such login class exists then 246.Dq daemon 247will be used. 248.It Va daemon_flags 249Arguments to call the daemon with. 250.It Va daemon_rtable 251Routing table to run the daemon under, using 252.Xr route 8 . 253.It Va daemon_timeout 254Maximum time in seconds to wait for the 255.Cm start 256(only if 257.Va rc_bg 258is set), 259.Cm stop 260and 261.Cm reload 262actions to return. 263This is only guaranteed with the default 264.Ic rc_start , 265.Ic rc_stop 266and 267.Ic rc_reload 268functions. 269.It Va daemon_user 270User to run the daemon as, using 271.Xr su 1 . 272.It Va pexp 273A regular expression to be passed to 274.Xr pgrep 1 275in order to find the desired process or to be passed to 276.Xr pkill 1 277to stop it. 278By default this variable contains the 279.Va daemon 280and 281.Va daemon_flags 282variables. 283To override the default value, an 284.Nm rc.d 285script has to redefine this variable 286.Em after 287sourcing 288.Nm . 289.It Va rc_bg 290Can be set to 291.Cm YES 292in an 293.Nm rc.d 294script to force starting the daemon in background when using the default 295.Ic rc_start . 296.It Va rc_reload 297Can be set to 298.Dq NO 299in an 300.Nm rc.d 301script to disable the reload action if the respective daemon 302does not support reloading its configuration. 303The same is possible, but almost never useful, for other actions. 304.It Va rc_usercheck 305Can be set to 306.Dq NO 307in an 308.Nm rc.d 309script, if the 310.Cm check 311action needs root privileges. 312.It Va rcexec 313Holds the full 314.Xr su 1 315command used to run the daemon. 316Defaults to: 317.Pp 318.Dl "su -l -c ${daemon_class} -s /bin/sh ${daemon_user} -c" 319.El 320If 321.Va daemon_rtable 322is set, the following 323.Xr route 8 324command is prepended to 325.Va rcexec : 326.Pp 327.Dl "route -T ${daemon_rtable}" 328.Pp 329All 330.Va daemon_* 331variables are set in the following ways: 332.Bl -enum 333.It 334Global defaults are provided by 335.Nm : 336.Bd -literal -offset indent 337daemon_class=daemon 338daemon_flags= 339daemon_rtable=0 340daemon_timeout=30 341daemon_user=root 342.Ed 343.It 344Service-specific defaults may be provided in the respective 345.Nm rc.d 346script 347.Em before 348sourcing 349.Nm , 350thus overriding the global defaults. 351.It 352As noted in 353.Xr rc.d 8 , 354site-specific values provided in 355.Xr rc.conf.local 8 356for 357.Va daemon_flags , 358.Va daemon_rtable , 359.Va daemon_timeout , 360and 361.Va daemon_user 362will override those defaults. 363.El 364.Sh FILES 365.Bl -tag -width Ds 366.It Pa /etc/rc.d/ 367Directory containing daemon control scripts. 368.It Pa /etc/rc.d/rc.subr 369Functions and variables used by 370.Nm rc.d 371scripts. 372.It Pa /usr/ports/infrastructure/templates/rc.template 373A sample 374.Nm rc.d 375script. 376.El 377.Sh SEE ALSO 378.Xr rc 8 , 379.Xr rc.conf 8 , 380.Xr rc.d 8 381.Sh HISTORY 382The 383.Nm 384framework 385first appeared in 386.Ox 4.9 . 387.Sh AUTHORS 388.An -nosplit 389The 390.Nm 391framework was written by 392.An Robert Nagy Aq Mt robert@openbsd.org , 393.An Antoine Jacoutot Aq Mt ajacoutot@openbsd.org , 394and 395.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 396