Provided by:
upstart_1.5-0ubuntu5_i386 
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
virtual-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.
┌────┬──────────────────────────┬──────┬──────┬────────────────────────┬──────┐
├────┼──────────────────────────┼──────┼──────┼────────────────────────┼──────┤
│ │ all-swaps │ S │ M │ > (5) │ │
│ │ control-alt-delete(7) │ S │ A │ > (5) │ A │
│ │ container │ S │ C │ > /run mounted │ Q │
│ │ desktop-session-start │ H │ D │ > X(7) session created │ B │
│ │ desktop-shutdown │ H │ D │ > X(7) session ended │ O │
│ 7 │ filesystem │ S │ M │ After last (1) │ D │
│ │ keyboard-request(7) │ S │ A │ > (5) │ E │
│ │ local-filesystems(7) │ S │ M │ > (6) │ │
│ 1 │ mounted(7) │ H │ M │ > associated (2) │ G │
│ 2 │ mounting(7) │ H │ M │ > (5) │ H │
│ │ not-container │ S │ C │ > /run mounted │ Q │
│ │ power-status-changed(7) │ S │ I │ > (5) │ I │
│ │ 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 │
│ │ stopped(7) │ S │ I │ > job stopped │ K │
│ │ stopping(7) │ H │ I │ < job stops │ K │
│ 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.
┌────┬────────────┬─────────────────────┐
├────┼────────────┼─────────────────────┤
│ │ │ events that start │
│ │ │ on or stop on this │
└────┴────────────┴─────────────────────┘
Table 3: Event Emitters.
┌────┬──────────────────────────────────┬─────────────────────────────────┐
├────┼──────────────────────────────────┼─────────────────────────────────┤
│ B │ dbus-daemon(1) │ Run with "--activation=upstart" │
│ F │ ifup(8) or ifdown(8) │ See /etc/network/. │
│ I │ init(8) │ │
│ M │ mountall(8) │ │
│ S │ upstart-socket-bridge(8) │ │
│ T │ telinit(8), shutdown(8) │ │
│ U │ upstart-udev-bridge(8) │ │
└────┴──────────────────────────────────┴─────────────────────────────────┘
Table 4: Event Summary Notes.
┌─────┬─────────────────────────────────────────────────────────────────┐
├─────┼─────────────────────────────────────────────────────────────────┤
│ 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 │
│ │ /sys/class/ for possible values for subsystem. │
│ H │ Emitted when mount attempt for single entry from fstab(5) for │
│ K │ Although the events are emmitted by init(8), the instigator may │
│ │ be initctl(8) if a System Administrator has manually started or │
│ 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 │
│ │ mountall(8). This defaults to 30 seconds. │
│ O │ Emitted when the X(7) display manager exits at shutdown or │
│ │ grub) as the initial event (rather than startup(7)) to denote │
│ │ successful, the standard startup(7) event is then emitted, │
└─────┴─────────────────────────────────────────────────────────────────┘
Job States
Table 5: Job Goals and State Transitions.
┌───────────────┬──────────────────────────────────────────┐
├───────────────┼───────────────┴──────────────────────────┤
└───────────────┴──────────────────────────────────────────┘
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 called "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
daemon 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
completed (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 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 PARTICULAR
PURPOSE.
SEE ALSO
init(5) init(8) initctl(8) mountall(8) started(7) starting(7)
stopped(7) stopping(7) telinit(8)