path: root/share/man/man8/rc.subr.8

.\" 	$OpenBSD: rc.subr.8,v 1.9 2011/03/05 12:56:33 schwarze 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 5 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
.Va dashes
have to be converted to
.Va underscores .
.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
or
.Va rc_reload
variables
or any of the
.Ic rc_*
functions, 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_restart
.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 ,
each running one of the functions described below.
.It Ic rc_start
Check whether the service is already running by calling
.Ar rc_check ,
If it's not running, call
.Fn rc_pre
if it exists, then start the daemon.
.It Ic rc_stop
Check that the service is running by calling
.Ar rc_check .
If it is running, stop the daemon,
then call
.Fn rc_post
if it exists.
.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,
that is, that it will reload its configuration.
.It Ic rc_restart
Perform a
.Cm stop
then a
.Cm start .
.It Ic rc_check
Return 0 if the daemon is running or 1 if it is not.
.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 daemon will be used.
.It Va pexp
A regular expression to be passed to
.Xr pgrep 1
or
.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_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 the
.Dv SIGHUP
signal to reload its configuration.
The same is possible, but almost never useful, for other actions.
.It Va rcexec
Holds the full
.Xr su 1
arguments used to run the daemon.
Defaults to:
.Va 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 .