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

.\" 	$OpenBSD: rc.subr.8,v 1.4 2011/01/16 14:59:19 jmc Exp $
.\"
.\" Copyright (c) 2010 Robert Nagy and Antoine Jacoutot
.\" 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 AUTHOR ``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 AUTHOR 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: January 16 2011 $
.Dt RC.SUBR 8
.Os
.Sh NAME
.Nm rc.subr ,
.Nm rc.d
.Nd functions used by rc.d scripts
.Sh SYNOPSIS
.Nm .\&
.Pa /etc/rc.d/rc.subr
.Nm rc_cmd
.Ar argument
.Sh DESCRIPTION
The
.Nm
script contains commonly used shell script functions and variable
definitions which are used by various
.Nm rc.d
scripts.
.Pp
The
.Nm
functions are accessed by sourcing
.Pa /etc/rc.d/rc.subr
into the current shell.
.Pp
The following shell functions are available:
.Bl -tag -width 4n
.It Ic rc_cmd Ar argument
Run the
.Ar argument
method 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 method
.Ar argument ,
if the
.Ar rc_${argument}()
function is not defined, then a default method is provided by
.Nm rc.subr .
In addition methods 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 with the reload argument, an error will be raised.
.Pp
.Ar argument
is searched for in the list of supported commands, which may be one
of:
.Bl -tag -width ".Cm restart" -offset indent
.It Cm start
Start the service.
It checks if the service is already running by calling
.Ar rc_check
and refuses to start if it is.
In addition if the
.Fn rc_pre
function exists, it is called before
starting the daemon.
.It Cm stop
It checks that the service is running by calling
.Ar rc_check
and if it's not, no action is taken.
In addition if the
.Fn rc_post
function exists, it is called right
after the daemon has been stopped.
.It Cm reload
Find the process using
.Xr pkill 1
with the regular expression as specified in the
.Ar pexp
variable and send a
.Dv SIGHUP
signal.
One has to make sure that sending
.Dv SIGHUP
to a daemon will have the desired effect,
which is reloading the configuration files.
.It Cm restart
Perform a
.Cm stop
then a
.Cm start .
.It Cm check
Return 0 if the daemon is running or 1 if it is not.
.El
.El
.Pp
.Ic rc_cmd
uses the following shell variables to control its behaviour.
.Bl -tag -width ".Va procname" -offset indent
.It Va daemon
The path to the daemon.
.It Va daemon_flags
Arguments to call
.Va daemon
with.
This is usually set in
.Xr rc.conf 8 ,
and not in the
.Nm rc.d
script except when there is a sane default value specified.
.Ar ${name}_flags
can be used in
.Xr rc.conf 8
to override this.
.It Va daemon_user
User to run
.Va daemon
as, using
.Xr su 1 .
This defaults to root unless specified by the
.Ar daemon_user
variable in the
.Nm rc.d
script or the
.Ar ${name}_user
variable in
.Xr rc.conf 8 .
.It Va daemon_class
Login class to run the
.Va 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 daemon_shell
Shell to run the
.Va daemon
in, using
.Xr su 1 .
This defaults to
.Pa /bin/sh
unless specified by the
.Ar daemon_shell
variable in the
.Nm rc.d
script or the
.Ar ${name}_shell
variable in
.Xr rc.conf 8 .
.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.
.El
.Sh FILES
.Bl -tag -width ".Pa /etc/rc.d/rc.subr" -compact
.It Pa /etc/rc.d/rc.subr
The
.Nm
file resides in
.Pa /etc/rc.d .
.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
.Sh HISTORY
The
.Nm
script
first appeared in
.Ox 4.9 .
.Sh AUTHORS
.An -nosplit
The
.Nm rc.subr
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 .