1.\" $OpenBSD: rc.subr.8,v 1.37 2020/02/21 00:47:21 kn 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: February 21 2020 $ 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}" 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.Cm stop 257and 258.Cm reload 259actions to return. 260This is only guaranteed with the default 261.Ic rc_start , 262.Ic rc_stop 263and 264.Ic rc_reload 265functions. 266.It Va daemon_user 267User to run the daemon as, using 268.Xr su 1 . 269.It Va pexp 270A regular expression to be passed to 271.Xr pgrep 1 272in order to find the desired process or to be passed to 273.Xr pkill 1 274to stop it. 275By default this variable contains the 276.Va daemon 277and 278.Va daemon_flags 279variables. 280To override the default value, an 281.Nm rc.d 282script has to redefine this variable 283.Em after 284sourcing 285.Nm . 286.It Va rc_bg 287Can be set to 288.Cm YES 289in an 290.Nm rc.d 291script to force starting the daemon in background when using the default 292.Ic rc_start . 293.It Va rc_reload 294Can be set to 295.Dq NO 296in an 297.Nm rc.d 298script to disable the reload action if the respective daemon 299does not support reloading its configuration. 300The same is possible, but almost never useful, for other actions. 301.It Va rc_usercheck 302Can be set to 303.Dq NO 304in an 305.Nm rc.d 306script, if the 307.Cm check 308action needs root privileges. 309.It Va rcexec 310Holds the full 311.Xr su 1 312command used to run the daemon. 313Defaults to: 314.Pp 315.Dl "su -l -c ${daemon_class} -s /bin/sh ${daemon_user} -c" 316.El 317If 318.Va daemon_rtable 319is set, the following 320.Xr route 8 321command is prepended to 322.Va rcexec : 323.Pp 324.Dl "route -T ${daemon_rtable} exec" 325.Pp 326All 327.Va daemon_* 328variables are set in the following ways: 329.Bl -enum 330.It 331Global defaults are provided by 332.Nm : 333.Bd -literal -offset indent 334daemon_class=daemon 335daemon_flags= 336daemon_rtable=0 337daemon_timeout=30 338daemon_user=root 339.Ed 340.It 341Service-specific defaults may be provided in the respective 342.Nm rc.d 343script 344.Em before 345sourcing 346.Nm , 347thus overriding the global defaults. 348.It 349As noted in 350.Xr rc.d 8 , 351site-specific values provided in 352.Xr rc.conf.local 8 353for 354.Va daemon_flags , 355.Va daemon_rtable , 356.Va daemon_timeout , 357and 358.Va daemon_user 359will override those defaults. 360.El 361.Sh FILES 362.Bl -tag -width Ds 363.It Pa /etc/rc.d/ 364Directory containing daemon control scripts. 365.It Pa /etc/rc.d/rc.subr 366Functions and variables used by 367.Nm rc.d 368scripts. 369.It Pa /usr/ports/infrastructure/templates/rc.template 370A sample 371.Nm rc.d 372script. 373.El 374.Sh SEE ALSO 375.Xr rc 8 , 376.Xr rc.conf 8 , 377.Xr rc.d 8 378.Sh HISTORY 379The 380.Nm 381framework 382first appeared in 383.Ox 4.9 . 384.Sh AUTHORS 385.An -nosplit 386The 387.Nm 388framework was written by 389.An Robert Nagy Aq Mt robert@openbsd.org , 390.An Antoine Jacoutot Aq Mt ajacoutot@openbsd.org , 391and 392.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 393