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