init(5)init(5)NAMEinit - Upstart init daemon job configuration
SYNOPSIS
/etc/init
DESCRIPTION
On startup, the Upstart init(8) daemon reads its job configuration from
the /etc/init directory, and watches for future changes using ino‐
tify(7).
Files in this directory must end in .conf and may also be present in
sub-directories.
Each file defines a single service or task, with the name taken from
its relative path within the directory without the extension. For
example a job defined in /etc/init/rc-sysinit.conf is named rc-sysinit,
while a job defined in /etc/init/net/apache.conf is named net/apache.
These files are plain text and should not be executable.
Format
Each line begins with a configuration stanza and continues until either
the end of the line or a line containing a closing stanza. Line breaks
within a stanza are permitted within single or double quotes, or if
preceeded by a blackslash.
Stanzas and their arguments are delimited by whitespace, which consists
of one or more space or tab characters which are otherwise ignored
unless placed within single or double quotes.
Comments begin with a `#' and continue until the end of the line.
Blank lines and lines consisting only of whitespace or comments are
ignored.
Process definition
The primary use of jobs is to define services or tasks to be run by the
init(8) daemon. Each job may have one or more different processes run
as part of its lifecycle, with the most common known as the main
process.
The main process is defined using either the exec or script stanzas,
only one of which is permitted. These specify the executable or shell
script that will be run when the job is considered to be running. Once
this process terminates, the job stop.
All processes are run with the full job environment available as envi‐
ronment variables in their process.
exec COMMAND [ ARG ]...
This stanza defines the process to be run as the name of an exe‐
cutable on the filesystem, and zero or more arguments to be
passed to it. Any special characters, e.g. quotes or `$' speci‐
fied will result in the entire command being passed to a shell
for expansion.
exec /usr/sbin/acpid -c $EVENTSDIR -s $SOCKET
script ... end script
This stanza defines the process to be run as a shell script that
will be executed using sh(1). The -e shell option is always
used, so any command that fails will terminate the script.
The script stanza appears on its own on a line, the script is
everything up until the first end script stanza appearing on its
own on a line.
script
dd bs=1 if=/proc/kmsg of=$KMSGSINK
exec /sbin/klogd -P $KMSGSINK
end script
There an additional four processes that may be run as part of the job's
lifecycle. These are specified as the process name, followed by an
exec or script stanza.
pre-start exec|script...
This process will be run after the job's starting(7) event has
finished, but before the main process is run. It is typically
used to prepare the environment, such as making necessary direc‐
tories.
post-start exec|script...
This process will be run before the job's started(7) event is
emitted, but after the main process has been spawned. It is
typically used to send necessary commands to the main process,
or to delay the started(7) event until the main process is ready
to receive clients.
pre-stop exec|script...
This process is run if the job is stopped by an event listed in
its stop on stanza or by the stop(8) command. It will be run
before the job's stopping(7) event is emitted and before the
main process is killed. It is typically used to send any neces‐
sary shutdown commands to the main process, and it may also call
the start(8) command without arguments to cancel the stop.
post-stop exec|script...
This process is run after the main process has been killed and
before the job's stopped(7) event is emitted. It is typically
used to clean up the environment, such as removing temporary
directories.
All of these process, including the main process, are optional. Ser‐
vices without a main process will appear to be running until they are
stopped, this is commonly used to define states such as runlevels.
It's quite permissable to have no main process, but to have pre-start
and post-stop processes for the state.
pre-start exec ifup -a
post-stop exec ifdown -a
Event definition
Jobs can be manually started and stopped at any time by a system admin‐
strator using the. start(8) and stop(8) tools, however it is far more
useful for jobs to be started and stopped automatically by the init(8)
daemon when necessary.
This is done by specifying which events should cause your job to be
started, and which cause your process to be stopped again.
The set of possible events is limitless, however there are a number of
standard events defined by the init(8) daemon and telinit(8) tools that
you will want to use.
When first started, the init(8) daemon will emit the startup(7) event.
This will activate jobs that implement System V compatibility and the
runlevel(7) event. As jobs are started and stopped, the init(8) daemon
will emit the starting(7), started(7), stopping(7) and stopped(7)
events on their behalf.
start on EVENT [[KEY=]VALUE]... [and|or...]
The start on stanza defines the set of events that will cause
the job to be automatically started. Each EVENT is given by its
name. Multiple events are permitted using the and & or opera‐
tors, and complex expressions may be performed with parentheses
(within which line breaks are permitted).
You may also match on the environment variables contained within
the event by specifying the KEY and expected VALUE. If you know
the order in which the variables are given to the event you may
omit the KEY.
VALUE may contain wildcard matches and globs as permitted by
fnmatch(3) and may expand the value of any variable defined with
the env stanza.
Negation is permitted by using != between the KEY and VALUE.
start on started gdm or started kdm
start on device-added SUBSYSTEM=tty DEVPATH=ttyS*
start on net-device-added INTERFACE!=lo
stop on EVENT [[KEY=]VALUE]... [and|or...]
The stop on stanza defines the set of events that will cause the
job to be automatically stopped. It has the same syntax as
start on
VALUE may additionally expand the value of any variable that
came from the job's start environment (either the event or the
command that started it).
stop on stopping gdm or stopping kdm
stop on device-removed DEVPATH=$DEVPATH
Job environment
Each job is run with the environment from the events or commands that
started it. In addition, you may define defaults in the job which may
be overridden later and specify which environment variables are
exported into the events generated for the job.
The special UPSTART_EVENTS environment variable contains the list of
events that started the job, it will not be present if the job was
started manually.
In addition, the pre-stop and post-stop scripts are run with the envi‐
ronment of the events or commands that stopped the job. THe
UPSTART_STOP_EVENTS environment variable contains the list of events
that stopped the job, it will not be present if the job was stopped
manually.
All jobs also contain the UPSTART_JOB and UPSTART_INSTANCE environment
variables, containing the name of the job and instance. These are
mostly used by the initctl(8) utility to default to acting on the job
the commands are called from.
env KEY[=VALUE]
Defines a default environment variable, the value of which may
be overriden by the event or command that starts the job. If no
value is given, then the value is taken from the init(8) dae‐
mon's own environment.
export KEY
Exports the value of an environment variable into the start‐
ing(7), started(7), stopping(7) and stopped(7) events for this
job.
Services, tasks and respawning
Jobs are services by default. This means that the act of starting the
job is considered to be finished when the job is running, and that even
exiting with a zero exit status means the service will be respawned.
task This stanza may be used to specify that the job is a task
instead. This means that the act of starting the job is not
considered to be finished until the job itself has been run and
stopped again, but that existing with a zero exit status means
the task has completed successfully and will not be respawned.
The start(8) command, and any starting(7) or stopping(7) events will
block only until a service is running or until a task has finished.
respawn
A service or task with this stanza will be automatically started
if it should stop abnormally. All reasons for a service stop‐
ping, except the stop(8) command itself, are considered abnor‐
mal. Tasks may exit with a zero exit status to prevent being
respawned.
respawn limit COUNT INTERVAL
Respawning is subject to a limit, if the job is respawned more
than COUNT times in INTERVAL seconds, it will be considered to
be having deeper problems and will be stopped.
This only applies to automatic respawns and not the restart(8)
command.
normal exit STATUS|SIGNAL...
Additional exit statuses or even signals may be added, if the
job process terminates with any of these it will not be consid‐
ered to have failed and will not be respawned.
normal exit 0 1 TERM HUP
Instances
By default, only one instance of any job is permitted to exist at one
time. Attempting to start a job when it's already starting or running
results in an error.
Multiple instances may be permitted by defining the names of those
instances. If an instance with the same name is not already starting
or running, a new instance will be started instead of returning an
error.
instance NAME
This stanza defines the names of instances, on its own its not
particularly useful since it would just define the name of the
single permitted instance, however NAME expands any variable
defined in the job's environment.
These will often be variables that you need to pass to the
process anyway, so are an excellent way to limit the instances.
instance $CONFFILE
exec /sbin/httpd -c $CONFFILE
instance $TTY
exec /sbin/getty -8 38300 $TTY
These jobs appear in the initctl(8) output with the instance
name in parentheses, and have the INSTANCE environment variable
set in their events.
Documentation
Upstart provides several stanzas useful for documentation and external
tools.
description DESCRIPTION
This stanza may contain a description of the job.
description "This does neat stuff"
author AUTHOR
This stanza may contain the author of the job, often used as a
contact for bug reports.
author "Scott James Remnant <scott@netsplit.com>"
version VERSION
This stanza may contain version information about the job, such
as revision control or package version number. It is not used
or interpreted by init(8) in any way.
version "$Id$"
emits EVENT...
All processes on the system are free to emit their own events by
using the initctl(8) tool, or by communicating directly with the
init(8) daemon.
This stanza allows a job to document in its job configuration
what events it emits itself, and may be useful for graphing pos‐
sible transitions.
Process environment
Many common adjustments to the process environment, such as resource
limits, may be configured directly in the job rather than having to
handle them yourself.
console output|owner
By default the standard input, output and error file descriptors
of jobs are connected to /dev/null
If this stanza is specified, they are connected to /dev/console
instead.
console owner is special, it not only connects the job to the
system console but sets the job to be the owner of the system
console, which means it will receive certain signals from the
kernel when special key combinations such as Control-C are
pressed.
umask UMASK
A common configuration is to set the file mode creation mask for
the process. UMASK should be an octal value for the mask, see
umask(2) for more details.
nice NICE
Another common configuration is to adjust the process's nice
value, see nice(1) for more details.
oom ADJUSTMENT|never
Normally the OOM killer regards all processes equally, this
stanza advises the kernel to treat this job differently.
ADJUSTMENT may be an integer value from -16 (very unlikely to be
killed by the OOM killer) up to 14 (very likely to be killed by
the OOM killer). It may also be the special value never to have
the job ignored by the OOM killer entirely.
chroot DIR
Runs the job's processes in a chroot(8) environment underneath
DIR
Note that DIR must have all the necessary system libraries for
the process to be run, often including /bin/sh
chdir DIR
Runs the job's processes with a working directory of DIR instead
of the root of the filesystem.
limit LIMIT SOFT|unlimited HARD|unlimited
Sets initial system resource limits for the job's processes.
LIMIT may be one of core, cpu, data, fsize, memlock, msgqueue,
nice, nofile, nproc, rss, rtprio, sigpending or stack.
Limits are specified as both a SOFT value and a HARD value, both
of which are integers. The special value unlimited may be spec‐
ified for either.
Miscellaneous
kill timeout INTERVAL
Specifies the interval between sending the job's main process
the SIGTERM and SIGKILL signals when stopping the running job.
expect stop
Specifies that the job's main process will raise the SIGSTOP
signal to indicate that it is ready. init(8) will wait for this
signal before running the job's post-start script, or consider‐
ing the job to be running.
init(8) will send the process the SIGCONT signal to allow it to
continue.
expect daemon
Specifies that the job's main process is a daemon, and will fork
twice after being run. init(8) will follow this daemonisation,
and will wait for this to occur before running the job's post-
start script or considering the job to be running.
Without this stanza init(8) is unable to supervise daemon pro‐
cesses and will believe them to have stopped as soon as they
daemonise on startup.
expect fork
Specifies that the job's main process will fork once after being
run. init(8) will follow this fork, and will wait for this to
occur before running the job's post-start script or considering
the job to be running.
Without this stanza init(8) is unable to supervise forking pro‐
cesses and will believe them to have stopped as soon as they
fork on startup.
SEE ALSOinit(8)sh(1)Upstart 2010-02-04 init(5)
