1.\" $OpenBSD: rc.subr.8,v 1.18 2011/12/13 00:09:52 schwarze 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: December 13 2011 $ 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 45Use the same name as the 46.Nm daemon 47it is referring to. 48.It 49Dashes 50.Pq Sq - 51have to be converted to 52underscores 53.Pq Sq _ . 54.El 55.Pp 56Every script under 57.Pa /etc/rc.d 58follows this pattern: 59.Pp 60.Bl -enum -compact 61.It 62Define the 63.Va daemon 64variable. 65.It 66Define service-specific defaults for one or more 67.Va daemon_* 68variables (optional). 69.It 70Source 71.Nm , 72which defines default shell functions and variable values. 73.It 74Override the 75.Va pexp 76variable or any of the 77.Ic rc_* 78functions and set the 79.Va rc_bg 80or 81.Va rc_reload 82variables, if needed. 83.It 84Define an 85.Ic rc_pre 86and/or 87.Ic rc_post 88function, if needed. 89.It 90Call the 91.Ic rc_cmd 92function as 93.Dq "rc_cmd $1" . 94.El 95.Pp 96The following shell functions are defined by 97.Nm : 98.Bl -tag -width rc_reload 99.It Ic rc_cmd Ar action 100Run the 101.Ar action 102for the current 103.Nm rc.d 104script, based on the settings of various shell variables. 105.Ic rc_cmd 106is extremely flexible, and allows fully functional 107.Nm rc.d 108scripts to be implemented in a small amount of shell code. 109For a given 110.Ar action , 111if the 112.Ar rc_${action}() 113function is not defined, then a default function is provided by 114.Nm rc.subr . 115In addition actions can be disabled by setting the 116.Ar rc_${name} 117variable to 118.Ar NO . 119For example, if rc_reload=NO is set in the 120.Nm rc.d 121script, and 122.Ic rc_cmd 123is called for the reload action, an error will be raised. 124.Pp 125The 126.Ar action 127argument can be 128.Cm start , 129.Cm stop , 130.Cm reload , 131.Cm restart , 132or 133.Cm check : 134.Bl -tag -width restart 135.It Ic check 136Call 137.Fn rc_check . 138Return 0 if the daemon is running or 1 if it is not. 139.It Ic start 140Check that the service is running by calling 141.Fn rc_check . 142If it's not running, call 143.Fn rc_pre 144if it exists, then 145.Fn rc_start . 146.It Ic stop 147Check that the service is running by calling 148.Fn rc_check . 149If it is running, 150call 151.Fn rc_stop 152and wait up to 30 seconds for the daemon to properly shutdown. 153If successful, run 154.Fn rc_post 155if it exists. 156.It Ic restart 157Run the 158.Ar action 159agument 160.Cm stop , 161then if successful run 162.Cm start . 163.It Ic reload 164Check that the service is running by calling 165.Fn rc_check . 166If it is running, 167call 168.Fn rc_reload . 169.El 170.It Ic rc_check 171Send a 172.Dv NULL 173signal using 174.Xr pkill 1 175on the regular expression given in the 176.Ar pexp 177variable. 178.It Ic rc_start 179Start the daemon. 180Defaults to: 181.Bd -literal -offset indent 182${rcexec} "${daemon} ${daemon_flags} ${_bg}" 183.Ed 184.It Ic rc_stop 185Stop the daemon. 186Send a 187.Dv SIGKILL 188signal using 189.Xr pkill 1 190on the regular expression given in the 191.Ar pexp 192variable. 193.It Ic rc_reload 194Send a 195.Dv SIGHUP 196signal using 197.Xr pkill 1 198on the regular expression given in the 199.Ar pexp 200variable. 201One has to make sure that sending 202.Dv SIGHUP 203to a daemon will have the desired effect, 204i.e. that it will reload its configuration. 205.El 206.Sh ENVIRONMENT 207.Ic rc_cmd 208uses the following shell variables to control its behaviour. 209.Bl -tag -width "daemon_flags" 210.It Va daemon 211The path to the daemon, optionally followed by one or more 212whitespace separated arguments. 213Arguments included here are always used, even if 214.Va daemon_flags 215is empty. 216This variable is required. 217It is an error to source 218.Nm 219without defining 220.Va daemon 221first. 222.It Va daemon_flags 223Arguments to call the daemon with. 224.It Va daemon_user 225User to run the daemon as, using 226.Xr su 1 . 227.It Va daemon_class 228Login class to run the daemon with, using 229.Xr su 1 . 230This is a read only variable that gets set by 231.Nm rc.subr 232itself. 233It searches 234.Xr login.conf 5 235for a login class that has the same name as the 236.Nm rc.d 237script itself and uses that. 238If no such login class exists then 239.Dq daemon 240will be used. 241.It Va pexp 242A regular expression to be passed to 243.Xr pkill 1 244in order to find the desired process. 245By default this variable contains the 246.Va daemon 247and 248.Va daemon_flags 249variables. 250To override the default value, an 251.Nm rc.d 252script has to redefine this variable 253.Em after 254sourcing 255.Nm . 256.It Va rc_bg 257Can be set to 258.Cm YES 259in an 260.Nm rc.d 261script to force starting the daemon in background when using the default 262.Fn rc_start . 263.It Va rc_reload 264Can be set to 265.Cm NO 266in an 267.Nm rc.d 268script to disable the reload action if the respective daemon 269does not support reloading its configuration. 270The same is possible, but almost never useful, for other actions. 271.It Va rcexec 272Holds the full 273.Xr su 1 274command used to run the daemon. 275Defaults to: 276.Pp 277.Dl "su -l -c ${daemon_class} -s /bin/sh ${daemon_user} -c" 278.El 279.Pp 280All 281.Va daemon_* 282variables are set in the following ways: 283.Bl -enum 284.It 285Global defaults are provided by 286.Nm : 287.Bd -literal -offset indent 288daemon_class=daemon 289daemon_flags="" 290daemon_user=root 291.Ed 292.It 293Service-specific defaults may be provided in the respective 294.Nm rc.d 295script 296.Em before 297sourcing 298.Nm , 299thus overriding the global defaults. 300.It 301As noted in 302.Xr rc.d 8 , 303site-specific values provided in 304.Xr rc.conf.local 8 305for 306.Va daemon_flags 307and 308.Va daemon_user 309will override those defaults. 310.El 311.Sh FILES 312.Bl -tag -width Ds 313.It Pa /etc/rc.d/ 314Directory containing daemon control scripts. 315.It Pa /etc/rc.d/rc.subr 316Functions and variables used by 317.Nm rc.d 318scripts. 319.It Pa /usr/ports/infrastructure/templates/rc.template 320A sample 321.Nm rc.d 322script. 323.El 324.Sh SEE ALSO 325.Xr rc 8 , 326.Xr rc.conf 8 , 327.Xr rc.d 8 328.Sh HISTORY 329The 330.Nm 331framework 332first appeared in 333.Ox 4.9 . 334.Sh AUTHORS 335.An -nosplit 336The 337.Nm 338framework was written by 339.An Robert Nagy Aq robert@openbsd.org , 340.An Antoine Jacoutot Aq ajacoutot@openbsd.org , 341and 342.An Ingo Schwarze Aq schwarze@openbsd.org . 343