.\" $OpenBSD: rc.subr.8,v 1.17 2011/03/25 10:03:26 ajacoutot Exp $ .\" .\" Copyright (c) 2011 Robert Nagy, Antoine Jacoutot, Ingo Schwarze .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: March 25 2011 $ .Dt RC.SUBR 8 .Os .Sh NAME .Nm rc.subr .Nd daemon control scripts routines .Sh SYNOPSIS .Nm daemon Ns = Ns Ar path_to_executable .Nm .\& .Pa /etc/rc.d/rc.subr .Nm rc_cmd .Ar action .Sh DESCRIPTION Apart from a few notable exceptions, rc scripts must follow this naming policy: .Pp .Bl -enum -compact .It Use the same name as the .Nm daemon it is referring to. .It Dashes .Pq Sq - have to be converted to underscores .Pq Sq _ . .El .Pp Every script under .Pa /etc/rc.d follows this pattern: .Pp .Bl -enum -compact .It Define the .Va daemon variable. .It Define service-specific defaults for one or more .Va daemon_* variables (optional). .It Source .Nm , which defines default shell functions and variable values. .It Override the .Va pexp variable or any of the .Ic rc_* functions and set the .Va rc_bg or .Va rc_reload variables, if needed. .It Define an .Ic rc_pre and/or .Ic rc_post function, if needed. .It Call the .Ic rc_cmd function as .Dq "rc_cmd $1" . .El .Pp The following shell functions are defined by .Nm : .Bl -tag -width rc_reload .It Ic rc_cmd Ar action Run the .Ar action for the current .Nm rc.d script, based on the settings of various shell variables. .Ic rc_cmd is extremely flexible, and allows fully functional .Nm rc.d scripts to be implemented in a small amount of shell code. For a given .Ar action , if the .Ar rc_${action}() function is not defined, then a default function is provided by .Nm rc.subr . In addition actions can be disabled by setting the .Ar rc_${name} variable to .Ar NO . For example, if rc_reload=NO is set in the .Nm rc.d script, and .Ic rc_cmd is called for the reload action, an error will be raised. .Pp The .Ar action argument can be .Cm start , .Cm stop , .Cm reload , .Cm restart , or .Cm check : .Bl -tag -width restart .It Ic check Call .Fn rc_check . Return 0 if the daemon is running or 1 if it is not. .It Ic start Check that the service is running by calling .Fn rc_check . If it's not running, call .Fn rc_pre if it exists, then .Fn rc_start . .It Ic stop Check that the service is running by calling .Fn rc_check . If it is running, call .Fn rc_stop and wait up to 30 seconds for the daemon to properly shutdown. If successful, run .Fn rc_post if it exists. .It Ic restart Run the .Ar action agument .Cm stop , then if successful run .Cm start . .It Ic reload Check that the service is running by calling .Fn rc_check . If it is running, call .Fn rc_reload . .El .It Ic rc_check Send a .Dv NULL signal using .Xr pkill 1 on the regular expression given in the .Ar pexp variable. .It Ic rc_start Start the daemon. Defaults to: .Bd -literal -offset indent ${rcexec} "${daemon} ${daemon_flags} ${_bg}" .Ed .It Ic rc_stop Stop the daemon. Send a .Dv SIGKILL signal using .Xr pkill 1 on the regular expression given in the .Ar pexp variable. .It Ic rc_reload Send a .Dv SIGHUP signal using .Xr pkill 1 on the regular expression given in the .Ar pexp variable. One has to make sure that sending .Dv SIGHUP to a daemon will have the desired effect, i.e. that it will reload its configuration. .El .Sh ENVIRONMENT .Ic rc_cmd uses the following shell variables to control its behaviour. .Bl -tag -width "daemon_flags" .It Va daemon The path to the daemon. This variable is required. It is an error to source .Nm without defining .Va daemon first. .It Va daemon_flags Arguments to call the daemon with. .It Va daemon_user User to run the daemon as, using .Xr su 1 . .It Va daemon_class Login class to run the daemon with, using .Xr su 1 . This is a read only variable that gets set by .Nm rc.subr itself. It searches .Xr login.conf 5 for a login class that has the same name as the .Nm rc.d script itself and uses that. If no such login class exists then .Dq daemon will be used. .It Va pexp A regular expression to be passed to .Xr pkill 1 in order to find the desired process. By default this variable contains the .Va daemon and .Va daemon_flags variables. To override the default value, an .Nm rc.d script has to redefine this variable .Em after sourcing .Nm . .It Va rc_bg Can be set to .Cm YES in an .Nm rc.d script to force starting the daemon in background when using the default .Fn rc_start . .It Va rc_reload Can be set to .Cm NO in an .Nm rc.d script to disable the reload action if the respective daemon does not support reloading its configuration. The same is possible, but almost never useful, for other actions. .It Va rcexec Holds the full .Xr su 1 command used to run the daemon. Defaults to: .Pp .Dl "su -l -c ${daemon_class} -s /bin/sh ${daemon_user} -c" .El .Pp All .Va daemon_* variables are set in the following ways: .Bl -enum .It Global defaults are provided by .Nm : .Bd -literal -offset indent daemon_class=daemon daemon_flags="" daemon_user=root .Ed .It Service-specific defaults may be provided in the respective .Nm rc.d script .Em before sourcing .Nm , thus overriding the global defaults. .It As noted in .Xr rc.d 8 , site-specific values provided in .Xr rc.conf.local 8 for .Va daemon_flags and .Va daemon_user will override those defaults. .El .Sh FILES .Bl -tag -width Ds .It Pa /etc/rc.d/ Directory containing daemon control scripts. .It Pa /etc/rc.d/rc.subr Functions and variables used by .Nm rc.d scripts. .It Pa /usr/ports/infrastructure/templates/rc.template A sample .Nm rc.d script. .El .Sh SEE ALSO .Xr rc 8 , .Xr rc.conf 8 , .Xr rc.d 8 .Sh HISTORY The .Nm framework first appeared in .Ox 4.9 . .Sh AUTHORS .An -nosplit The .Nm framework was written by .An Robert Nagy Aq robert@openbsd.org , .An Antoine Jacoutot Aq ajacoutot@openbsd.org , and .An Ingo Schwarze Aq schwarze@openbsd.org .