'\" t
.TH upstart-events 7 2011-03-24 upstart
.\"
.SH NAME
upstart-events \- Well-known Upstart events summary
.\"
.SH Event Summary

This manual page summarizes well-known events generated by Upstart
running both as the
.BR init (8)
daemon (process ID 1) and a Session Init (process that supervises a user
session).

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 tables, \fBTable 1\fP and \fBTable 2\fP, encode the
well-known system and session events respectively, along with the type
of each event (listed in \fBTable 3\fP), the emitter of the event (see
\fBTable 4\fP) and the approximate time at which the event could be
generated. Additionally, the \fINote\fP column indexes into \fBTable
5\fP for further details on a particular event.

\fBTable 6\fP shows job goals and possible state transitions. See the
.B status
command in
.BR initctl (8)
for further details.

Note that some events listed in
.B Table 1
.I may
be available to session jobs (depending on when the Session Init
starts). Those events that are available will be prefixed with
\fI:sys:\fR. See
.BR upstart\-event\-bridge (8)
for further details.

The \fIRef\fP (Reference) column is used to refer to individual
events succinctly in the \fITime\fP column.

Note that the \(aq<\(aq and \(aq>\(aq characters in the \fITime\fP column denote
that the event in the \fIEvent\fP column occurs respectively before or
after the event specified in the \fITime\fP column (for example, the
\fBmounting\fP(7) event occurs "at some time" after the \fBstartup\fP(7)
event, and the \fBvirtual\-filesystems\fP(7) event occurs after the last
\fBmounted\fP(7) event relating to a virtual filesystem has been emitted).

For further details on events, consult the manual pages and the system
job configuration files, usually located in \fI/etc/init\fP.
.\"

.\" Flush-left to allow table to be viewed on 80-col display without
.\" wrapping.
.nr old_po .po
.nr old_in .in
.po 0
.in 0
.sp 1
\fBTable 1: Well-Known System Events Summary.\fP
.TS
box, tab (@);
c | c | c | c | c | c
c | l | c | c | l | c.
Ref@Event@Type@Emit@Time@Note
=
  @\fBall\-swaps\fP@S@M@> (5)@
  @\fBcontrol\-alt\-delete\fP(7)@S@A@> (5)@A
  @container@S@C@> \fI/run\fP mounted@Q
  @dbus\-activation@S@B@> D\-Bus client request@
  @deconfiguring\-networking@H@V@< non-local IFs down@P
  @desktop\-session\-start@H@D@> \fBX\fP(7) session created@B
  @desktop\-shutdown@H@D@> \fBX\fP(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
  @file@S@K@> (1)@U
7@\fBfilesystem\fP@S@M@After last (1)@D
  @graphics\-device\-added@S@U@> (5)@C
  @\fBkeyboard\-request\fP(7)@S@A@> (5)@E
  @\fBlocal\-filesystems\fP(7)@S@M@> (6)@
  @login\-session\-start@H@D@< DM running@F
1@\fBmounted\fP(7)@H@M@> associated (2)@G
2@\fBmounting\fP(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@> \fI/run\fP mounted@Q
  @\fBpower\-\%status\-\%changed\fP(7)@S@I@> (5)@I
  @recovery@S@G@Boot (<5)@R
  @\fBremote\-\%filesystems\fP(7)@S@M@> (6)@
  @\fBrunlevel\fP(7)@M@T@> (7) + (8)@
  @\fBsocket\fP(7)@S@S@> socket connection@
5@\fBstartup\fP(7)@S@I@Boot@J
  @\fBstarted\fP(7)@S@I@> job started@K
  @\fBstarting\fP(7)@H@I@< job starts@K
 8@static\-network\-up@S@N@> last static IF up@
  @\fBstopped\fP(7)@S@I@> job stopped@K
  @\fBstopping\fP(7)@H@I@< job stops@K
  @T{
unmounted\-\:remote\-\:filesystems
T}@H@V@T{
> last remote FS unmounted
T}@L
6@\fBvirtual\-\:filesystems\fP(7)@S@M@> last virtual FS (1)@M
.TE
.po \n[old_po]
.in \n[old_in]
.P
Key:
  \(aqDM\(aq is an abbreviation for Display Manager.
  \(aqFS\(aq is an abbreviation for filesystem.
  \(aqIF\(aq is an abbreviation for Network Interface.

.\" Flush-left to allow table to be viewed on 80-col display without
.\" wrapping.
.nr old_po .po
.nr old_in .in
.po 0
.in 0
.sp 1
\fBTable 2: Well-Known User Events Summary.\fP
.TS
box, tab (@);
c | c | c | c | c | c
c | l | c | c | l | c.
Ref@Event@Type@Emit@Time@Note
=
 @\fBdesktop\-end\fP(7)@S@J@< (2)@
 @\fBdesktop\-start\fP(7)@H@J@> (3)@
 @file@S@K@> (1)@U
2@\fBsession\-end\fP(7)@M@I@< Session Init end@
1@\fBstartup\fP(7)@S@I@> Session Init start@J
 @:sys:*@S@E@> \fBupstart\-event\-bridge\fP(8) start@
 @:sys:restarted@S@E@> \fBupstart\-event\-bridge\fP(8) start@V
3@xsession@M@H@> (1)@T
.TE
.po \n[old_po]
.in \n[old_in]

.\"
.P
.sp 1
.nr old_po .po
.nr old_in .in
.po 0
.in 0
\fBTable 3: Event Types.\fP
.TS
box, tab (@);
c | l |l
c | l |l.
Ref@Event Type@Notes
=
H@Hook@T{
Blocking. Waits for events that \fBstart on\fP or \fBstop on\fP this
event.
T}
M@Method@Blocking task.
S@Signal@Non-blocking.
.TE
.po \n[old_po]
.in \n[old_in]

.\"
.P
.nr old_po .po
.nr old_in .in
.po 0
.in 0
.sp 1
\fBTable 4: Event Emitters.\fP
.TS
box, tab (@);
c | l |l
c | l |l.
Ref@Emitter@Notes
=
A@System Administrator (initiator)@Technically emitted by init(8).
B@\fBdbus\-daemon\fP(1)@Run with "\fI\-\-activation=upstart"\fP
C@container\-detect job@
D@Display Manager@e.g. lightdm/gdm/kdm/xdm.
E@\fBupstart\-event\-bridge\fP(8)@
F@\fBifup\fP(8) or \fBifdown\fP(8)@See \fI/etc/network/\fP.
G@bootloader or initramfs@
H@xsession\-init session job@
I@\fBinit\fP(8)@Either PID 1 or a Session Init.
J@job that starts desktop@gnome\-session job for Ubuntu.
K@\fBupstart\-file\-bridge\fP(8)@
M@\fBmountall\fP(8)@
N@network\-interface job@
S@\fBupstart\-socket\-bridge\fP(8)@
T@\fBtelinit\fP(8), \fBshutdown\fP(8)@
U@\fBupstart\-udev\-bridge\fP(8)@
V@System V init system@
X@failsafe job@
.TE
.po \n[old_po]
.in \n[old_in]

.\"
.P
.nr old_po .po
.nr old_in .in
.po 0
.in 0
\fBTable 5: Event Summary Notes.\fP
.TS
box, tab (@);
c | l
c | l.
Note@Detail
=
A@T{
Requires administrator to press Control-Alt-Delete key
combination on the console.
T}
B@Event generated when user performs graphical login.
C@T{
These are specific examples. \fBupstart\-udev\-bridge\fP(8) will emit
events which match the pattern, "\fIS\fP\-device\-\fIA\fP" where
\(aqS\(aq is the udev \fIsubsystem\fP and \(aqA\(aq is the udev \fIaction\fP. See
\fBudev\fP(7) and for further details. If you have sysfs
mounted, you can look in \fI/sys/class/\fP for possible values for subsystem.
T}
D@Note this is in the singular - there is no \(aqfilesystems\(aq event.
E@T{
Emitted when administrator presses Alt-UpArrow key combination on
the console.
T}
F@T{
Denotes Display Manager running (about to be displayed), but no users
logged in yet.
T}
G@Generated for each mount that completes successfully.
H@T{
Emitted when mount attempt for single entry from \fBfstab\fP(5)
for any filesystem type is about to begin.
T}
I@Emitted when Upstart receives the SIGPWR signal.
J@Initial event (system or Session Init).
K@T{
Although the events are emmitted by \fBinit\fP(8), the instigator may be
\fBinitctl\fP(8) if a System Administrator has manually started or
stopped a job.
T}
L@\fI/etc/init/umountnfs.sh\fP.
M@Emitted when all virtual filesystems (such as \fI/proc\fR) mounted.
N@T{
Emitted when the \fI\-\-dev\-wait\-time\fP timeout is exceeded for
\fBmountall\fP(8).  This defaults to 30 seconds.
T}
O@T{
Emitted when the \fIX\fP(7) display manager exits at shutdown or reboot, to
hand off to the shutdown splash manager.
T}
P@T{
Emitted by /etc/init.d/networking just prior to stopping all non-local
network interfaces.
T}
Q@T{
Either \(aqcontainer\(aq or \(aqnot-container\(aq is emitted (depending
on the environment), but not both.
T}
R@T{
Emitted by either the initramfs or bootloader (for example grub) as the \fIinitial\fP
event (rather than \fBstartup\fP(7)) to denote the system has booted into
recovery mode. If recovery was successful, the standard \fBstartup\fP(7)
event is \fIthen\fP emitted, allowing the system to boot as normal.
T}
S@T{
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.
T}
T@Only emitted for a graphical session.
U@See \fBfile\-event\fP(7).
V@T{
This is a pseudo-system event emitted directly by the
.BR upstart\-event\-bridge (8) "" .
T}
.TE
.po \n[old_po]
.in \n[old_in]

.\" ------------------------------------------------------------
.SH Job States

.\"
.P
.sp 1
.nr old_po .po
.nr old_in .in
.po 0
.in 0
\fBTable 6: Job Goals and State Transitions.\fP
.TS
box,tab(@);
c | c s
c | c s
c | c | c
c | l l.
              @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
.TE
.po \n[old_po]
.in \n[old_in]
.P
Key:
  (*) If there is a \fBscript\fP or \fBexec\fP section and this process is running,
  state will be \(aqpre\-stop\(aq, else it will be \(aqstopping\(aq.

.\" ------------------------------------------------------------
.SH Job Lifecycle
.\"
.\" ------------------------------
.SS Starting a Job

.nr step 1 1
.\"
.IP \n[step] 3
Initially the job is "at rest" with a goal of \(aqstop\(aq
and a state of \(aqwaiting\(aq (shown as \(aqstop/waiting\(aq by the
.BR initctl (8)
.B list
and
.B status
commands).
.\"
.IP \n+[step] 3
The goal is changed from \(aqstop\(aq to
\(aqstart\(aq indicating the job is attempting to start.
.\"
.IP \n+[step] 3
The state is changed from \(aqwaiting\(aq to
\(aqstarting\(aq.
.\"
.IP \n+[step] 3
The \fBstarting\fP(7) event is emitted denoting the job is
"about to start".
.\"
.IP \n+[step] 3
Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied
by this job starting are started (or stopped respectively).
.\"
.IP \n+[step] 3
The \fBstarting\fP(7) event completes.
.\"
.IP \n+[step] 3
The state is changed from \(aqstarting\(aq to \(aqpre\-start\(aq.
.\"
.IP \n+[step] 3
If the \fBpre\-start\fP stanza exists, the pre\-start process is
spawned.
.\"
.IP \n+[step] 3
If the pre\-start process fails, the goal is changed from
\(aqstart\(aq to \(aqstop\(aq, and the
.BR stopping(7)
and
.BR stopped(7)
events are emitted with appropriate variables set denoting the error.
.\"
.IP \n+[step] 3
Assuming the pre\-start did not fail or did not call "stop", the main
process is spawned.
.\"
.IP \n+[step] 3
The state is changed from \(aqpre\-start\(aq to \(aqspawned\(aq.
.\"
.IP \n+[step] 3
Upstart then ascertains the \fIfinal\fP PID for the job which may be a
descendent of the immediate child process if \fBexpect fork\fP or
\fBexpect daemon\fP has been specified.
.\"
.IP \n+[step] 3
The state is changed from \(aqspawned\(aq to \(aqpost\-start\(aq.
.\"
.IP \n+[step] 3
If the \fBpost\-start\fP stanza exists, the post\-start process is
spawned.
.\"
.IP \n+[step] 3
The state is changed from \(aqpost\-start\(aq to \(aqrunning\(aq.
.\"
.IP \n+[step] 3
The \fBstarted\fP(7) event is emitted.
.sp 1
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).
.\"
.IP \n+[step] 3
Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied
by this job being started are started (or stopped respectively).

.\" ------------------------------
.SS Stopping a Job

.nr step 1 1
.\"
.IP \n[step] 3
Assuming the job is fully running, it will have a goal of \(aqstart\(aq
and a state of \(aqrunning\(aq (shown as \(aqstart/running\(aq by the
.BR initctl (8)
.B list
and
.B status
commands).
.\"
.IP \n+[step] 3
The goal is changed from \(aqstart\(aq to \(aqstop\(aq indicating the
job is attempting to stop.
.\"
.IP \n+[step] 3
The state is changed from \(aqrunning\(aq to
\(aqpre\-stop\(aq.
.\"
.IP \n+[step] 3
If the \fBpre\-stop\fP stanza exists, the pre\-stop process is
spawned.
.\"
.IP \n+[step] 3
The state is changed from \(aqpre\-stop\(aq to \(aqstopping\(aq.
.\"
.IP \n+[step] 3
The \fBstopping\fP(7) event is emitted.
.\"
.IP \n+[step] 3
Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied by this
job stopping are started (or stopped respectively).
.\"
.IP \n+[step] 3
The main process is stopped:
.RS
.nr step2 1 1
.af step2 i
.IP \n[step2] 3
The signal specified by the
.B 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
.BR SIGTERM "."
.sp 1
See \fBsignal\fP(7) and \fBinit\fP(5).
.IP \n+[step2] 3
Upstart waits for up to "kill timeout" seconds (default 5 seconds) for
the process to end.
.IP \n+[step2] 3
If the process is still running after the timeout, a
.B SIGKILL
signal is sent to the process which cannot be ignored and will forcibly
stop the processes in the process group.
.RE
.\"
.IP \n+[step] 3
The state is changed from \(aqkilled\(aq to \(aqpost\-stop\(aq.
.\"
.IP \n+[step] 3
If the \fBpost\-stop\fP stanza exists, the post\-stop process is
spawned.
.\"
.IP \n+[step] 3
The state is changed from \(aqpost\-stop\(aq to \(aqwaiting\(aq.
.\"
.IP \n+[step] 3
The \fBstopped\fP(7) event is emitted.
.sp 1
When this event completes, the job is fully stopped.
.\"
.IP \n+[step] 3
Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied
by this job being stopped are started (or stopped respectively).

.SH AUTHOR
Manual page written by James Hunt
.RB < james.hunt@ubuntu.com >
.\"
.SH REPORTING BUGS
Report bugs at
.RB < https://launchpad.net/ubuntu/+source/upstart/+bugs >
.\"
.SH COPYRIGHT
Copyright \(co 2011-2013 Canonical Ltd.
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.SH SEE ALSO
.BR init (5)
.BR init (8)
.BR initctl (8)
.BR mountall (8)
.BR started (7)
.BR starting (7)
.BR stopped (7)
.BR stopping (7)
.BR telinit (8)
.BR upstart\-event\-bridge (8)