.\" Copyright (C) 2000-2001  Richard Gooch
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.\" Richard Gooch may be reached by email at  rgooch@atnf.csiro.au
.\" The postal address is:
.\"   Richard Gooch, c/o ATNF, P. O. Box 76, Epping, N.S.W., 2121, Australia.
.\"
.\"	initctl.8		Richard Gooch	21-FEB-2001
.\"
.TH INITCTL 8 "21 Feb 2001" "Util-Linux Package"
.SH NAME
initctl \- utility to control simpleinit(8)
.SH SYNOPSIS
.B need
.RB [ \-r ]
.I service
.br
.B display-services
.br
.B provide
.I service
.SH OVERVIEW
The \fBinitctl\fP programme is designed to help improve the
robustness, scalability and readability of system boot scripts. It is
now possible to write a modularised set of boot scripts without the
complex and fragile numbered symlink scheme used in SysV-style boot
scripts. Each script can simply declare, using \fBneed\fP(8), what
must run before them.
.SH DESCRIPTION for need
The \fBneed\fP programme is a utility that tells \fBsimpleinit\fP(8)
to start a \fIservice\fP (usually a script in \fI/sbin/init.d\fP) and
will wait for the service to become available. If the service is
already available, it will not be started again.

The \fB-r\fP option is used to tell \fBsimpleinit\fP(8) to "roll back"
(stop) services up to (but not including) \fIservice\fP. If
\fIservice\fP is not specified, all services are stopped. The \fB-r\fP
option thus allows the system to be partially or wholly shut down in
an orderly fashion. The \fBshutdown\fP(8) programme still needs to be
run.

.SH DESCRIPTION for display-services
When invoked as \fBdisplay-services\fP it will write the list of
currently available services and the list of failed services to the
standard output.

.SH DESCRIPTION for provide
When invoked as \fBprovide\fP it tells \fBsimpleinit\fP(8) that the
parent (calling) process will be providing a service with name
\fIservice\fP. If the calling process exits successfully (status 0)
the service is deemed to be available. Only one instance of
\fIservice\fP may be started, so alternate providers will block and
may fail.

Using \fBprovide\fP it is possible to have multiple potential
providers for the same (generic) service (e.g. \fBsendmail\fP and
\fBqmail\fP both provide a \fBmta\fP service), where only one actually
provides the service. This may be used by service startup scripts
which check for configuration files.
.SH EXIT CODE
The exit code from \fBneed\fP is 0 if the service was successfully
started, 1 if the service failed badly, and 2 if the service is
unavailable (i.e. disabled in configuration files). These exit codes
reflect the exit codes from the service startup scripts.

The exit code from \fBneed -r\fP is 0 if the service was successfully
stopped, 1 if the service could not be stopped, and 2 if the service
was not available to start with. The service shutdown scripts may only
return 0 (for success) or 1 (for failure).

The exit code from \fBprovide\fP is 0 if the service may be provided,
1 if it may not, and 2 if the parent process is not a child of
init. It may block waiting for another provider which is initialising
the service.
.SH SIGNALS
\fBinitctl\fP(8) uses \fBSIGUSR1\fP, \fBSIGUSR2\fP and \fBSIGPOLL\fP
for communication with \fBsimpleinit\fP(8). Don't send these signals
to it.
.SH FILES
.PD 0
.TP 20
.BI /dev/initctl
This is the control FIFO, created by \fBsimpleinit\fP(8), which
\fBinitctl\fP(8) writes commands to.
.SH SEE ALSO
.BR simpleinit (8),
.BR init (8)
.PP
A more complete discussion of the new boot script system, based on
\fBneed\fP(8), is available from:
http://www.atnf.csiro.au/~rgooch/linux/boot-scripts/
.SH AUTHOR
Richard Gooch (rgooch@atnf.csiro.au)

.SH AVAILABILITY
The initctl command is part of the util-linux-ng package and is available from
ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.