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