1.\" $OpenBSD: rc.subr.8,v 1.31 2016/04/26 18:30:22 jmc 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: April 26 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 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.Ic 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.Va rc_${action} 117variable to 118.Dq NO . 119For example, if 120.Dq rc_reload=NO 121is set in the 122.Nm rc.d 123script, and 124.Ic rc_cmd 125is called for the reload action, an error will be raised. 126Similarly, the special variable 127.Va rc_usercheck 128must be set to 129.Dq NO 130if the 131.Cm check 132.Ar action 133requires root privileges. 134.Pp 135The 136.Ar action 137argument can be 138.Cm start , 139.Cm stop , 140.Cm reload , 141.Cm restart , 142or 143.Cm check : 144.Bl -tag -width restart 145.It Ic check 146Call 147.Ic rc_check . 148Return 0 if the daemon is running or 1 if it is not. 149.It Ic start 150Check that the service is running by calling 151.Ic rc_check . 152If it's not running, call 153.Ic rc_pre 154if it exists, then 155.Ic rc_start . 156.It Ic stop 157Check that the service is running by calling 158.Ic rc_check . 159If it is running, 160call 161.Ic rc_stop 162and wait up to 30 seconds for the daemon to properly shutdown. 163If successful, run 164.Ic rc_post 165if it exists. 166.It Ic restart 167Run the 168.Ar action 169argument 170.Cm stop , 171then if successful run 172.Cm start . 173.It Ic reload 174Check that the service is running by calling 175.Ic rc_check . 176If it is running, 177call 178.Ic rc_reload . 179.El 180.It Ic rc_check 181Search for processes of the service with 182.Xr pgrep 1 183using the regular expression given in the 184.Va pexp 185variable. 186.It Ic rc_start 187Start the daemon. 188Defaults to: 189.Bd -literal -offset indent 190${rcexec} "${daemon} ${daemon_flags} ${_bg}" 191.Ed 192.It Ic rc_stop 193Stop the daemon. 194Send a 195.Dv SIGTERM 196signal using 197.Xr pkill 1 198on the regular expression given in the 199.Va pexp 200variable. 201.It Ic rc_reload 202Send a 203.Dv SIGHUP 204signal using 205.Xr pkill 1 206on the regular expression given in the 207.Va pexp 208variable. 209One has to make sure that sending 210.Dv SIGHUP 211to a daemon will have the desired effect, 212i.e. that it will reload its configuration. 213.El 214.Sh ENVIRONMENT 215.Ic rc_cmd 216uses the following shell variables to control its behaviour. 217.Bl -tag -width "daemon_timeout" 218.It Va daemon 219The path to the daemon, optionally followed by one or more 220whitespace separated arguments. 221Arguments included here are always used, even if 222.Va daemon_flags 223is empty. 224This variable is required. 225It is an error to source 226.Nm 227without defining 228.Va daemon 229first. 230.It Va daemon_class 231Login class to run the daemon with, using 232.Xr su 1 . 233This is a read only variable that gets set by 234.Nm rc.subr 235itself. 236It searches 237.Xr login.conf 5 238for a login class that has the same name as the 239.Nm rc.d 240script itself and uses that. 241If no such login class exists then 242.Dq daemon 243will be used. 244.It Va daemon_flags 245Arguments to call the daemon with. 246.It Va daemon_rtable 247Routing table to run the daemon under, using 248.Xr route 8 . 249.It Va daemon_timeout 250Maximum time in seconds to wait for the 251.Cm start 252(only if 253.Va rc_bg 254is set), 255.Cm stop 256and 257.Cm reload 258actions to return. 259This is only guaranteed with the default 260.Ic rc_start , 261.Ic rc_stop 262and 263.Ic rc_reload 264functions. 265.It Va daemon_user 266User to run the daemon as, using 267.Xr su 1 . 268.It Va pexp 269A regular expression to be passed to 270.Xr pgrep 1 271in order to find the desired process or to be passed to 272.Xr pkill 1 273to stop it. 274By default this variable contains the 275.Va daemon 276and 277.Va daemon_flags 278variables. 279To override the default value, an 280.Nm rc.d 281script has to redefine this variable 282.Em after 283sourcing 284.Nm . 285.It Va rc_bg 286Can be set to 287.Cm YES 288in an 289.Nm rc.d 290script to force starting the daemon in background when using the default 291.Ic rc_start . 292.It Va rc_reload 293Can be set to 294.Dq NO 295in an 296.Nm rc.d 297script to disable the reload action if the respective daemon 298does not support reloading its configuration. 299The same is possible, but almost never useful, for other actions. 300.It Va rc_usercheck 301Can be set to 302.Dq NO 303in an 304.Nm rc.d 305script, if the 306.Cm check 307action needs root privileges. 308.It Va rcexec 309Holds the full 310.Xr su 1 311command used to run the daemon. 312Defaults to: 313.Pp 314.Dl "su -l -c ${daemon_class} -s /bin/sh ${daemon_user} -c" 315.El 316If 317.Va daemon_rtable 318is set, the following 319.Xr route 8 320command is prepended to 321.Va rcexec : 322.Pp 323.Dl "route -T ${daemon_rtable}" 324.Pp 325All 326.Va daemon_* 327variables are set in the following ways: 328.Bl -enum 329.It 330Global defaults are provided by 331.Nm : 332.Bd -literal -offset indent 333daemon_class=daemon 334daemon_flags= 335daemon_rtable=0 336daemon_timeout=30 337daemon_user=root 338.Ed 339.It 340Service-specific defaults may be provided in the respective 341.Nm rc.d 342script 343.Em before 344sourcing 345.Nm , 346thus overriding the global defaults. 347.It 348As noted in 349.Xr rc.d 8 , 350site-specific values provided in 351.Xr rc.conf.local 8 352for 353.Va daemon_flags , 354.Va daemon_rtable , 355.Va daemon_timeout , 356and 357.Va daemon_user 358will override those defaults. 359.El 360.Sh FILES 361.Bl -tag -width Ds 362.It Pa /etc/rc.d/ 363Directory containing daemon control scripts. 364.It Pa /etc/rc.d/rc.subr 365Functions and variables used by 366.Nm rc.d 367scripts. 368.It Pa /usr/ports/infrastructure/templates/rc.template 369A sample 370.Nm rc.d 371script. 372.El 373.Sh SEE ALSO 374.Xr rc 8 , 375.Xr rc.conf 8 , 376.Xr rc.d 8 377.Sh HISTORY 378The 379.Nm 380framework 381first appeared in 382.Ox 4.9 . 383.Sh AUTHORS 384.An -nosplit 385The 386.Nm 387framework was written by 388.An Robert Nagy Aq Mt robert@openbsd.org , 389.An Antoine Jacoutot Aq Mt ajacoutot@openbsd.org , 390and 391.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 392