Default location of system job configuration files.
Default location of user job configuration files.
On startup, the Upstart init(8) daemon reads its job configuration from
files in the /etc/init/ directory, and watches for future changes to
these files using inotify(7).
If D-Bus has been configured to allow non-privileged users to invoke
all Upstart D-Bus methods, Upstart is also able to manage User Jobs.
See User Jobs for further details.
To be considered by Upstart, files in this directory must have a recog-
nized suffix and may also be present in sub-directories. There are two
o Files ending in .conf are called configuration files, or simply
"conf files" for short. These are the primary vehicle for specify-
ing a job.
o Files ending in .override are called override files. If an over-
ride file is present, the stanzas it contains take precedence over
those equivalently named stanzas in the corresponding configuration
file contents for a particular job. The main use for override
files is to modify how a job will run without having to modify its
configuration file directly. See the section Override File Han-
dling below for further details.
A job can thus be defined by either:
o A single configuration file.
o A single configuration file and a single override file.
Unless explicitly stated otherwise, any reference to a jobs configura-
tion can refer both to a configuration file or an override file.
Each configuration file defines the template for a single service
(long-running process or daemon) or task (short-lived process).
Note that a configuration file is not itself a job: it is a description
of an environmenta job could be run in. A job is the runtime embodi-
ment of a configuration file.
The configuration file name as displayed by Upstart and associated
tooling is taken from its relative path within the directory without
the extension. For example a configuration file /etc/init/rc-
sysinit.conf is named rc-sysinit, while a configuration file
Any user can create user jobs, but that user can control only jobs they
Users are able to manage their jobs using the standard initctl(8)
Note that stanzas which manipulate resources limits may cause a job to
fail to start should the value provided to such a stanza attempt to
exceed the maximum value the users privilege level allows.
Note that a user job configuration file cannot have the same name as a
system job configuration file.
Upstart is able to manage jobs within a chroot(2). To control jobs
within the chroot environment, use the standard initctl(8) facility.
Note that it is not necessary to install D-Bus within the chroot (in
fact it is not recommended).
Note that User Jobs can be created within a chroot environment.
Configuration File 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.
If a stanza is duplicated, the last occurence will be used. Unrecog-
nized stanzas will generate parse errors, which will stop a job from
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
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
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 stops.
All processes are run with the full job environment available as envi-
ronment variables in their process.
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.
dd bs=1 if=/proc/kmsg of=$KMSGSINK
exec /sbin/klogd -P $KMSGSINK
There are 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.
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-
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.
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.
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
All of these processes, 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
is permissable to have no main process, but to have pre-start and
post-stop processes for the state.
pre-start exec ifup -a
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
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
manual This stanza will disregard any previously seen start on defini-
tion. By adding this stanza on any line below the start on def-
inition, it provides the ability to stop a job from being auto-
matically started. When specified, the only way to start such a
job is via start (8).
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
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.
Defines a default environment variable, the value of which may
be overriden by the event or command that starts the job. If
'KEY=VALUE' is specified, the variable KEY is given the value
VALUE. If only 'KEY' is given, then the value is taken from the
init(8) daemon's own environment.
Exports the value of an environment variable into the start-
ing(7), started(7), stopping(7) and stopped(7) events for this
job and to all resultant events (not just those relating to the
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 exiting 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.
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
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. Default COUNT is
10. Default INTERVAL is 5 seconds.
time. Attempting to start a job when it's already starting or running
results in an error. Note that a job is considered to be running if its
pre-start process is running.
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
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.
exec /sbin/httpd -c $CONFFILE
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.
Upstart provides several stanzas useful for documentation and external
This stanza may contain a description of the job.
description "This does neat stuff"
This stanza may contain the author of the job, often used as a
contact for bug reports.
author "Scott James Remnant <firstname.lastname@example.org>"
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.
All processes on the system are free to emit their own events by
and square brackets ('[' and ']')). Meta-characters are useful
to allow initctl(8) check-config to resolve a class of events,
such as those emitted by upstart-udev-bridge(8).
This stanza may contain the text used by initctl(8) usage com-
mand. This text may be also shown when commands start(8),
stop(8) or status(8) fail.
usage "tty DEV=ttyX - where X is console id"
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.
If none is specified, the jobs standard input, standard
output and standard error file descriptors are connected
to /dev/null. Any output generated by a job will be dis-
carded. This used to be the default prior to the intro-
duction of log in Upstart 1.4.
Only applies to system jobs: if specified by user jobs,
the job will be considered to have specified the value
For system jobs, if log is specified, standard input is
connected to /dev/null, and standard output and standard
error are connected to a pseudo-tty which logs all job
Output is logged to file /var/log/upstart/<job-log-file>.
If a job has specified instance, <job-log-file> will
equate to <job>-<instance>.log where '<instance>' is
replaced by the specific instance value and '<job>' is
replaced with the job name (job configuration file name,
without the extension). If instance is not specified,
<job-log-file> will be <job>.log where '<job>' is
replaced with the job name.
If log files already exist, they are appended to.
All slash ('/') characters in <job-log-file> are replaced
with underscore ('_') characters. For example, any output
from the 'wibble' instance of the 'foo/bar' job would be
encoded in file 'foo_bar-wibble.log' in the log file
directory. This gives the log file directory a flat
If the logger detects that the file it is about to write
to was deleted, it will re-open the file first.
Care should be taken if the log directory is a mount
point since any job that starts before that mount is
available and which produces output will then attempt to
write logs to the mount point, not to the mounted direc-
tory. This may give the impression that log data has not
been recorded. A strategy to handle this situation is to
ensure the mount point directory is not writeable such
that logs will only be written when the mount has suc-
ceeded (assuming the mount itself is writeable and has
Note that since log utilizes pseudo-ttys, your kernel
must support these. If it does not, the console value
will be modified automatically to none. Further, note
that it may be necessary to increase the number of avail-
able pty devices; see pty(7) for details.
Under Linux, full Unix 98 pty support requires that the
devpts filesystem be mounted.
If pty setup fails for any reason, an error message will
be displayed and the job's console value will be reset to
If output is specified, the standard input, standard out-
put and standard error file descriptors are connected to
The owner value 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.
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.
Another common configuration is to adjust the process's nice
value, see nice(1) for more details.
oom score 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 -999 (very unlikely to
be killed by the OOM killer) up to 1000 (very likely to be
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.
Changes to the user USERNAME before running any job process.
If this stanza is unspecified, all job processes will run as
root in the case of system jobs, and as the user in the case of
Note that system jobs using the setuid stanza are still system
jobs, and can not be controlled by an unprivileged user, even if
the setuid stanza specifies that user.
Changes to the group GROUPNAME before running any job process.
If this stanza is unspecified, the primary group of the user
specified in the setuid block is used for all job processes. If
both stanzas are unspecified, all job processes will run with
its group ID set to 0 in the case of system jobs, and as the
primary group of the user in the case of User Jobs.
Override File Handling
Override files allow a jobs environment to be changed without modifying
the jobs configuration file. Rules governing override files:
o If a job is embodied with only a configuration file, the contents of
this file define the job.
o If an override files exists where there is no existing cofiguration
file, the override file is ignored.
o If both a configuration file and an override file exist for a job and
both files are syntactically correct:
o stanzas in the override file will take precedence over stanzas
present in the corresponding configuration file.
o stanzas in the override file which are not present in the corre-
sponding configuration file will be honoured when the job runs.
o If both a configuration file and an override file exist for a job and
subsequently the override file is deleted, the configuration file is
automatically reloaded with the effect that any changes introduced by
kill signal SIGNAL
Specifies the stopping signal, SIGTERM by default, a job's main
process will receive when stopping the running job.
kill signal INT
kill timeout INTERVAL
Specifies the interval between sending the job's main process
the "stopping" (see above) and SIGKILL signals when stopping the
running job. Default is 5 seconds.
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
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.
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.
The use of symbolic links in job configuration file directories is not
supported since it can lead to unpredicable behaviour resulting from
broken or inaccessible links (such as would be caused by a link cross-
ing a filesystem boundary to a filesystem that has not yet been
The and and or operators allowed with start on and stop on do not work
intuitively: operands to the right of either operator are only evalu-
ated once and state information is then discarded. This can lead to
jobs with complex start on or stop on conditions not behaving as
System job configuration files.
System job override files.
User job configuration files. Note that you may make the direc-
tory $HOME/.init/ a symbolic link to $HOME/.config/upstart/.
User job override files.
Default location of system job output logs.
Manual page written by Scott James Remnant <email@example.com> and
James Hunt <firstname.lastname@example.org>.
Report bugs at <https://launchpad.net/upstart/+bugs>
Copyright (C) 2009-2011 Canonical Ltd.
This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
init(8) initctl(8) sh(1) upstart-events(7) pty(7)
Upstart 2011-05-12 init(5)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017
All Rights Reserved.