upstart man
man upstart
nit(8) init(8)
NAME
init - Upstart process management daemon
SYNOPSIS
init [OPTION]...
DESCRIPTION
init is the parent of all processes on the system, it is executed by the kernel and is responsible for starting all other processes; it is
the parent of all processes whose natural parents have died and it is responsible for reaping those when they die.
Processes managed by init are known as jobs and are defined by files in the /etc/init directory. See init(5) for more details on configur�
ing Upstart.
Events
init(8) is an event-based init daemon. This means that jobs will be automatically started and stopped by changes that occur to the system
state, including as a result of jobs starting and stopping.
This is different to dependency-based init daemons which start a specified set of goal jobs, and resolve the order in which they should be
started and other jobs required by iterating their dependencies.
For more information on starting and stopping jobs, as well as emitting events that will automatically start and stop jobs, see the manual
page for the initctl(8) tool.
The primary event is the startup(7) event, emitted when the daemon has finished loading its configuration. Other useful events are the
starting(7), started(7), stopping(7) and stopped(7) events emitted as jobs change state.
See upstart-events(7) for a summary of well-known events.
System V compatibility
The Upstart init(8) daemon does not keep track of runlevels itself, instead they are implemented entirely by its userspace tools. The event
emitted to signify a change of runlevel is the runlevel(7) event. For more information see its manual page.
OPTIONS
Options are passed to init(8) by placing them on the kernel command-line.
--confdir directory
Read job configuration files from a directory other than /etc/init.
--default-console value
Default value for jobs that do not specify a 'console' stanza. This could be used for example to set the default to 'none' but still
honour jobs that specify explicitly 'console log'. See init(5) for all possible values of console.
--logdir directory
Write job output log files to a directory other than /var/log/upstart.
--no-log
Disable logging of job output. Note that jobs specifying 'console log' will be treated as if they had specified 'console none'. See
init(5) for further details.
--no-sessions
Disable user and chroot sessions.
--no-startup-event
Suppress emission of the initial startup event. This option should only be used for testing since it will stop the init(8) daemon
from starting any jobs automatically.
--session
Connect to the D-Bus session bus. This should only be used for testing.
--startup-event event
Specify a different initial startup event from the standard startup(7).
--verbose
Outputs verbose messages about job state changes and event emissions to the system console or log, useful for debugging boot.
NOTES
init is not normally executed by a user process, and expects to have a process id of 1. If this is not the case, it will actually execute
telinit(8) and pass all arguments to that. See that manual page for further details.
FILES
/etc/init.conf
/etc/init/*.conf
$HOME/.init/
AUTHOR
Written by Scott James Remnant <scott@netsplit.com>
REPORTING BUGS
Report bugs at <https://launchpad.net/upstart/+bugs>
COPYRIGHT
Copyright © 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 PARTICU�
LAR PURPOSE.
SEE ALSO
control-alt-delete(7) init(5) initctl(8) runlevel(7) startup(7) starting(7) started(7) stopping(7) stopped(7) telinit(8) upstart-events(7)
Upstart 2011-04-06 init(8)
man 5 init
init(5) init(5)
NAME
init - Upstart init daemon job configuration
SYNOPSIS
/etc/init/
Default location of system job configuration files.
$HOME/.init/
Default location of user job configuration files.
DESCRIPTION
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 recognized suffix and may also be present in sub-directories. There are
two recognized suffixes:
· Files ending in .conf are called configuration files, or simply "conf files" for short. These are the primary vehicle for specifying a
job.
· Files ending in .override are called override files. If an override 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 Handling below for
further details.
A job can thus be defined by either:
· A single configuration file.
· A single configuration file and a single override file.
Unless explicitly stated otherwise, any reference to a jobs configuration 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 embod‐
iment 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
/etc/init/net/apache.conf is named net/apache. Since override files only modify the way a configuration file is interpreted, they are not
named.
Configuration files are plain text and should not be executable.
User Jobs
A User Job is a job configuration file created by a non-privileged user in their $HOME/.init/ directory. Job configuration files in this
directory have the same syntax as system job configuration files. Files in this directory will be read and an inotify(7) watch created the
first time a user runs initctl(8).
Any user can create user jobs, but that user can control only jobs they create.
Users are able to manage their jobs using the standard initctl(8) facility.
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.
Chroot Support
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. Unrecognized stanzas will generate parse errors, which will stop a job from run‐
ning.
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 stops.
All processes are run with the full job environment available as environment variables in their process.
exec COMMAND [ ARG ]...
This stanza defines the process to be run as the name of an executable on the filesystem, and zero or more arguments to be passed to
it. Any special characters, e.g. quotes or `$' specified 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 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.
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 directories.
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 necessary 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 processes, including the main process, are optional. Services 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
post-stop exec ifdown -a
Event definition
Jobs can be manually started and stopped at any time by a system adminstrator 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 operators, 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
manual This stanza will disregard any previously seen start on definition. By adding this stanza on any line below the start on definition,
it provides the ability to stop a job from being automatically started. When specified, the only way to start such a job is via
start (8).
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 environment 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
´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.
export KEY
Exports the value of an environment variable into the starting(7), started(7), stopping(7) and stopped(7) events for this job and to
all resultant events (not just those relating to the current 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 exiting with a zero exit status means the task has com‐
pleted 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 stopping,
except the stop(8) command itself, are considered abnormal. 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 hav‐
ing deeper problems and will be stopped. Default COUNT is 10. Default INTERVAL is 5 seconds.
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 considered 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. 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 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 possible
transitions.
The initctl(8) check-config command attempts to use this stanza to resolve events.
EVENT can be either a literal string or a string including shell wildcard meta-characters (asterisk ('*'), question mark ('?'), 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).
usage USAGE
This stanza may contain the text used by initctl(8) usage command. 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"
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 none|log|output|owner
none
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 discarded. This used to be the default prior to the introduction of log in Upstart 1.4.
log
Only applies to system jobs: if specified by user jobs, the job will be considered to have specified the value none.
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.
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 structure.
If the directory for system jobs does not exist, job output for each job will be cached until the job finishes. Thus, the boot
process must ensure that the directory is available as soon as possible since any job that finishes before a writeable disk is
available will not be able to take advantage of this facility.
If it is not possible to write to any log file due to lack of disk space, the job will be considered to have specified a con‐
sole value of none and all subsequent job output will be discarded.
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 directory. 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 write‐
able such that logs will only be written when the mount has succeeded (assuming the mount itself is writeable and has suffi‐
cient space).
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 available 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 none.
output
If output is specified, the standard input, standard output and standard error file descriptors are connected to /dev/console.
owner
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.
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 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 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 specified
for either.
setuid USERNAME
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 user
jobs.
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.
setgid GROUPNAME
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:
· If a job is embodied with only a configuration file, the contents of this file define the job.
· If an override files exists where there is no existing cofiguration file, the override file is ignored.
· If both a configuration file and an override file exist for a job and both files are syntactically correct:
· stanzas in the override file will take precedence over stanzas present in the corresponding configuration file.
· stanzas in the override file which are not present in the corresponding configuration file will be honoured when the job runs.
· 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 the override file are undone and the configuration file alone now
defines the job.
· If both a configuration file and an override file exist for a job and subsequently the configuration file is deleted, a new instance of
the job can no longer be started (since without a corresponding configuration file an override file is ignored).
· If both a configuration file and an override file exist for a job and any of the contents of the override file are invalid, the override
file is ignored and only the contents of the configuration file are considered.
Miscellaneous
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 run‐
ning job. Default is 5 seconds.
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 considering 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 processes 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 processes and will believe them to have stopped as soon as they fork on
startup.
RESTRICTIONS
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 crossing a filesystem boundary to a filesystem that has not yet been
mounted).
BUGS
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
expected when restarted. For example, if a job encodes the following condition:
start on A and (B or C)
When 'A' and 'B' become true, the condition is satisfied so the job will be run. However, if the job ends and subsequently 'A' and 'C'
become true, the job will not be re-run even though the condtion is satisfied. Avoid using complex conditions with jobs which need to be
restarted.
FILES
/etc/init/*.conf
System job configuration files.
/etc/init/*.override
System job override files.
$HOME/.init/*.conf
User job configuration files. Note that you may make the directory $HOME/.init/ a symbolic link to $HOME/.config/upstart/.
$HOME/.init/*.override
User job override files.
/var/log/upstart/*.log
Default location of system job output logs.
AUTHOR
Manual page written by Scott James Remnant <scott@netsplit.com> and James Hunt <james.hunt@canonical.com>.
REPORTING BUGS
Report bugs at <https://launchpad.net/upstart/+bugs>
COPYRIGHT
Copyright © 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 PARTICU‐
LAR PURPOSE.
SEE ALSO
init(8) initctl(8) sh(1) upstart-events(7) pty(7)
Upstart 2011-05-12 init(5)
man upstart-events
upstart-events(7) upstart-events(7)
NAME
upstart-events - Well-known Upstart events summary
Event Summary
This manual page summarizes well-known events generated by the Upstart init(8) daemon. It is not an exhaustive list of all possible events,
but rather details a standard set of events expected to be generated on any Ubuntu system running Upstart.
The primary table, Table 1, encodes the well-known events, along with the type of each event (listed in Table 2), the emitter of the event
(see Table 3) and the approximate time at which the event could be generated. Additionally, the Note column indexes into Table 4 for further
details on a particular event.
The Ref (Reference) column is used to refer to individual events succinctly in the Time column.
Note that the '<' and '>' characters in the Time column denote that the event in the Event column occurs respectively before or after the
event specified in the Time column (for example, the mounting(7) event occurs "at some time" after the startup(7) event, and the vir‐
tual-filesystems(7) event occurs after the last mounted(7) event relating to a virtual filesystem has been emitted).
For further details on events, consult the manual pages and the job configuration files, usually located in /etc/init.
Table 1: Well-Known Event Summary.
┌────┬──────────────────────────┬──────┬──────┬────────────────────────┬──────┐
│Ref │ Event │ Type │ Emit │ Time │ Note │
├────┼──────────────────────────┼──────┼──────┼────────────────────────┼──────┤
│ │ all-swaps │ S │ M │ > (5) │ │
│ │ control-alt-delete(7) │ S │ A │ > (5) │ A │
│ │ container │ S │ C │ > /run mounted │ Q │
│ │ dbus-activation │ S │ B │ > D-Bus client request │ │
│ │ deconfiguring-networking │ H │ V │ < non-local IFs down │ P │
│ │ desktop-session-start │ H │ D │ > X(7) session created │ B │
│ │ desktop-shutdown │ H │ D │ > X(7) session ended │ O │
│ │ device-not-ready │ H │ M │ > (2) │ N │
│ │ drm-device-added │ S │ U │ > (5) │ C │
│ │ failsafe-boot │ S │ X │ > (7) and local IF │ S │
│ 7 │ filesystem │ S │ M │ After last (1) │ D │
│ │ graphics-device-added │ S │ U │ > (5) │ C │
│ │ keyboard-request(7) │ S │ A │ > (5) │ E │
│ │ local-filesystems(7) │ S │ M │ > (6) │ │
│ │ login-session-start │ H │ D │ < DM running │ F │
│ 1 │ mounted(7) │ H │ M │ > associated (2) │ G │
│ 2 │ mounting(7) │ H │ M │ > (5) │ H │
│ 3 │ net-device-added │ S │ U │ > (5) │ C │
│ │ net-device-changed │ S │ U │ > (5) │ C │
│ │ net-device-down │ S │ F │ < (4) │ C │
│ 4 │ net-device-removed │ S │ U │ > (5) │ C │
│ │ net-device-up │ S │ F,N │ > (3) │ C │
│ │ not-container │ S │ C │ > /run mounted │ Q │
│ │ power-status-changed(7) │ S │ I │ > (5) │ I │
│ │ recovery │ S │ G │ Boot (<5) │ R │
│ │ remote-filesystems(7) │ S │ M │ > (6) │ │
│ │ runlevel(7) │ M │ T │ > (7) + (8) │ │
│ │ socket(7) │ S │ S │ > socket connection │ │
│ 5 │ startup(7) │ S │ I │ Boot │ J │
│ │ started(7) │ S │ I │ > job started │ K │
│ │ starting(7) │ H │ I │ < job starts │ K │
│ 8 │ static-network-up │ S │ N │ > last static IF up │ │
│ │ stopped(7) │ S │ I │ > job stopped │ K │
│ │ stopping(7) │ H │ I │ < job stops │ K │
│ │ unmounted-remote- │ H │ V │ > last remote FS │ L │
│ │ filesystems │ │ │ unmounted │ │
│ 6 │ virtual-filesystems(7) │ S │ M │ > last virtual FS (1) │ M │
└────┴──────────────────────────┴──────┴──────┴────────────────────────┴──────┘
Key:
'DM' is an abbreviation for Display Manager.
'FS' is an abbreviation for filesystem.
'IF' is an abbreviation for Network Interface.
Table 2: Event Types.
┌────┬────────────┬───────────────────────────────────────┐
│Ref │ Event Type │ Notes │
├────┼────────────┼───────────────────────────────────────┤
│ H │ Hook │ Blocking. Waits for events that start │
│ │ │ on or stop on this event. │
│ M │ Method │ Blocking task. │
│ S │ Signal │ Non-blocking. │
└────┴────────────┴───────────────────────────────────────┘
Table 3: Event Emitters.
┌────┬──────────────────────────────────┬─────────────────────────────────┐
│Ref │ Emitter │ Notes │
├────┼──────────────────────────────────┼─────────────────────────────────┤
│ A │ System Administrator (initiator) │ Technically emitted by init(8). │
│ B │ dbus-daemon(1) │ Run with "--activation=upstart" │
│ C │ container-detect job │ │
│ D │ Display Manager │ e.g. lightdm/gdm/kdm/xdm. │
│ F │ ifup(8) or ifdown(8) │ See /etc/network/. │
│ G │ bootloader or initramfs │ │
│ I │ init(8) │ │
│ M │ mountall(8) │ │
│ N │ network-interface job │ │
│ S │ upstart-socket-bridge(8) │ │
│ T │ telinit(8), shutdown(8) │ │
│ U │ upstart-udev-bridge(8) │ │
│ V │ System V init system │ │
│ X │ failsafe job │ │
└────┴──────────────────────────────────┴─────────────────────────────────┘
Table 4: Event Summary Notes.
┌─────┬─────────────────────────────────────────────────────────────────┐
│Note │ Detail │
├─────┼─────────────────────────────────────────────────────────────────┤
│ A │ Requires administrator to press Control-Alt-Delete key combina‐ │
│ │ tion on the console. │
│ B │ Event generated when user performs graphical login. │
│ C │ These are specific examples. upstart-udev-bridge(8) will emit │
│ │ events which match the pattern, "S-device-A" where 'S' is the │
│ │ udev subsystem and 'A' is the udev action. See udev(7) and for │
│ │ further details. If you have sysfs mounted, you can look in │
│ │ /sys/class/ for possible values for subsystem. │
│ D │ Note this is in the singular - there is no 'filesystems' event. │
│ E │ Emitted when administrator presses Alt-UpArrow key combination │
│ │ on the console. │
│ F │ Denotes Display Manager running (about to be displayed), but no │
│ │ users logged in yet. │
│ G │ Generated for each mount that completes successfully. │
│ H │ Emitted when mount attempt for single entry from fstab(5) for │
│ │ any filesystem type is about to begin. │
│ I │ Emitted when Upstart receives the SIGPWR signal. │
│ J │ Initial event. │
│ K │ Although the events are emmitted by init(8), the instigator may │
│ │ be initctl(8) if a System Administrator has manually started or │
│ │ stopped a job. │
│ L │ /etc/init/umountnfs.sh. │
│ M │ Emitted when all virtual filesystems (such as /proc) mounted. │
│ N │ Emitted when the --dev-wait-time timeout is exceeded for moun‐ │
│ │ tall(8). This defaults to 30 seconds. │
│ O │ Emitted when the X(7) display manager exits at shutdown or │
│ │ reboot, to hand off to the shutdown splash manager. │
│ P │ Emitted by /etc/init.d/networking just prior to stopping all │
│ │ non-local network interfaces. │
│ Q │ Either 'container' or 'not-container' is emitted (depending on │
│ │ the environment), but not both. │
│ R │ Emitted by either the initramfs or bootloader (for example │
│ │ grub) as the initial event (rather than startup(7)) to denote │
│ │ the system has booted into recovery mode. If recovery was suc‐ │
│ │ cessful, the standard startup(7) event is then emitted, allow‐ │
│ │ ing the system to boot as normal. │
│ S │ Emitted to indicate the system has failed to boot within the │
│ │ expected time. This event will trigger other jobs to forcibly │
│ │ attempt to bring the system into a usable state. │
└─────┴─────────────────────────────────────────────────────────────────┘
Job States
Table 5: Job Goals and State Transitions.
┌───────────────┬──────────────────────────────────────────┐
│ │ Goal │
│ ├───────────────┬──────────────────────────┤
│Current State │ start │ stop │
├───────────────┼───────────────┴──────────────────────────┤
│waiting │ starting n/a │
│starting │ pre-start stopping │
│pre-start │ spawned stopping │
│spawned │ post-start stopping │
│post-start │ running stopping │
│running │ stopping pre-stop / stopping (*) │
│pre-stop │ running stopping │
│stopping │ killed killed │
│killed │ post-stop post-stop │
│post-stop │ starting waiting │
└───────────────┴──────────────────────────────────────────┘
Key:
(*) If there is a script or exec section and this process is running,
state will be 'pre-stop', else it will be 'stopping'.
Job Lifecycle
Starting a Job
1 Initially the job is "at rest" with a goal of 'stop' and a state of 'waiting' (shown as 'stop/waiting' by the initctl(8) list and status
commands).
2 The goal is changed from 'stop' to 'start' indicating the job is attempting to start.
3 The state is changed from 'waiting' to 'starting'.
4 The starting(7) event is emitted denoting the job is "about to start".
5 Any jobs whose 'start on' (or 'stop on') condition would be satisfied by this job starting are started (or stopped respectively).
6 The starting(7) event completes.
7 The state is changed from 'starting' to 'pre-start'.
8 If the pre-start stanza exists, the pre-start process is spawned.
9 If the pre-start process fails, the goal is changed from 'start' to 'stop', and the stopping(7) and stopped(7) events are emitted with
appropriate variables set denoting the error.
10 Assuming the pre-start did not fail or did not call "stop", the main process is spawned.
11 The state is changed from 'pre-start' to 'spawned'.
12 Upstart then ascertains the final PID for the job which may be a descendent of the immediate child process if expect fork or expect dae‐
mon has been specified.
13 The state is changed from 'spawned' to 'post-start'.
14 If the post-start stanza exists, the post-start process is spawned.
15 The state is changed from 'post-start' to 'running'.
16 The started(7) event is emitted.
For services, when this event completes the main process will now be fully running. If the job refers to a task, it will now have com‐
pleted (successfully or otherwise).
17 Any jobs whose 'start on' (or 'stop on') condition would be satisfied by this job being started are started (or stopped respectively).
Stopping a Job
1 Assuming the job is fully running, it will have a goal of 'start' and a state of 'running' (shown as 'start/running' by the initctl(8)
list and status commands).
2 The goal is changed from 'start' to 'stop' indicating the job is attempting to stop.
3 The state is changed from 'running' to 'pre-stop'.
4 If the pre-stop stanza exists, the pre-stop process is spawned.
5 The state is changed from 'pre-stop' to 'stopping'.
6 The stopping(7) event is emitted.
7 Any jobs whose 'start on' (or 'stop on') condition would be satisfied by this job stopping are started (or stopped respectively).
8 The main process is stopped:
i The signal specified by the kill signal stanza is sent to the process group of the main process (such that all processes belonging to
the jobs main process are killed). By default this signal is SIGTERM.
See signal(7) and init(5).
ii Upstart waits for up to "kill timeout" seconds (default 5 seconds) for the process to end.
iii
If the process is still running after the timeout, a SIGKILL signal is sent to the process which cannot be ignored and will forcibly
stop the processes in the process group.
9 The state is changed from 'killed' to 'post-stop'.
10 If the post-stop stanza exists, the post-stop process is spawned.
11 The state is changed from 'post-stop' to 'waiting'.
12 The stopped(7) event is emitted.
When this event completes, the job is fully stopped.
13 Any jobs whose 'start on' (or 'stop on') condition would be satisfied by this job being stopped are started (or stopped respectively).
AUTHOR
Manual page written by James Hunt <james.hunt@ubuntu.com>
REPORTING BUGS
Report bugs at <https://launchpad.net/ubuntu/+source/upstart/+bugs>
COPYRIGHT
Copyright © 2011-2012 Canonical Ltd.
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICU‐
LAR PURPOSE.
SEE ALSO
init(5) init(8) initctl(8) mountall(8) started(7) starting(7) stopped(7) stopping(7) telinit(8)
upstart 2011-03-24 upstart-events(7)
