'\" t
.TH init 8 2011-01-11 "Upstart-Events"
.\"
.SH NAME
upstart-events \- Well-known Upstart events summary
.\"
.SH Event Summary

The first table below summarizes well-known \fBUpstart\fP(8) events. It
is not therefore comprehensive, but details a standard set of events
expetected to be generated on any system running Upstart.

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 \fPmounting\fP(7)
event occurs "at some time" after the \fPstartup\fP(7) event.

For further details on events, consult the manual pages and the job
configuration files, usually located in \fI/etc/init\fP.
.\"
.TS
box, tab (@);
l | l | l | l
l | c | l | l.
Event@Emitter@Time@Notes
=
\fBstartup\fP(7)@I@Boot@(A)
\fBmounting\fP(7)@M@> \fBstartup\fP@(B)
\fBmounted\fP(7)@M@> associated \fBmounting\fP@(C)
\fBvirtual-filesystems\fP(7)@M@> last virtual FS \fBmounted\fP@(D)
\fBlocal-filesystems\fP(7)@M@> \fBvirtual-filesystems\fP@
\fBremote-filesystems\fP(7)@M@> \fBvirtual-filesystems\fP@
\fBfilesystem\fP@M@After last \fPmounted\fP@(E)
\fBall-swaps\fP@M@> \fBstartup\fP@
\fBcontrol-alt-delete\fP(7)@A@> \fBstartup\fP@(F)
\fBkeyboard-request\fP(7)@A@> \fBstartup\fP@(G)
\fBpower-status-changed\fP(7)@I@> \fBstartup\fP@(H)
\fBrunlevel\fP(7)@R@> \fBstartup\fP@
login-session-start@D@< Display Manager running@(I)
desktop-session-start@D@> \fBX\fP(7) session created@(J)
net-device-added@U@> \fBstartup\fP@(K)
net-device-changed@U@> \fBstartup\fP@(K)
net-device-removed@U@> \fBstartup\fP@(K)
net-device-up@F,N@> net-device-added@
net-device-down@F@< net-device-removed@
\fBstarting\fP(7)@I@< job starts@(L)
\fBstarted\fP(7)@I@> job started@(L)
\fBstopping\fP(7)@I@< job stops@(L)
\fBstopped\fP(7)@I@> job stop@(L)
.TE
.sp 1
Key: \'FS\' is an abbreviation for filesystem.
.\"
.P
The following tables refer to the primary table above.
.\"
.TS
box, tab (@);
l | l
l | l.
Reference@Emitter
=
A@System Administrator
D@Display Manager (e.g. gdm/kdm/xdm)
F@\fBifup\fP(8) or \fBifdown\fP(8)
I@\fBinit\fP(8)
M@\fBmountall\fP(8)
N@network-interface job
R@\fBrunlevel\fP(8)
U@\fBupstart-udev-bridge\fP(8)
.TE
.P

.TS
box, tab (@);
l | l
l | l.
Note@Detail
=
(A)@Initial event.
(B)@T{
Emitted when mount attempt for single entry from \fBfstab\fP(5)
for any filesystem type is about to begin.
T}
(C)@Generated for each mount that completes successfully.
(D)@Emitted when all virtual filesystems (such as \fI/proc\fR) mounted.
(E)@Note this is in the singular - there is no \'filesystems\' event.
(F)@T{
Requires administrator to press Control-Alt-Delete key
combination on the console.
T}
(G)@T{
Emitted when administrator presses Alt-UpArrow key combination on
the console.
T}
(H)@Emitted when Upstart receives the SIGPWR signal.
(I)@T{
Denotes Display Manager running (about to be displayed), but no users
logged in yet.
T}

(J)@Event generated when user performs graphical login.
(K)@T{
These are specific examples. \fBupstart-udev-bridge\fP(8) will
emit events which match the pattern, "\fIS\fP-device-\fIA\fP" where
\'S\' is the udev \fIsubsystem\fP and \'A\' is the udev
\fIaction\fP. See \fBudev\fP(7) for further details.
T}
(L)@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}
.TE

.SH Job lifecycle
.\"
.SS Starting a Job
.nr step 1 1
.IP \n[step] 3
Upstart emits the \fBstarting\fP(7) event denoting the job is
"about to start". The \fBstarting\fP(7) event completes.
.IP \n+[step] 3
If the \fBpre-start\fP stanza exists, the pre-start process is
spawned.
.IP \n+[step] 3
Upstart spawns the main process.
.sp
It 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
If the \fBpost-start\fP stanza exists, the post-start process is
spawned.
.IP \n+[step] 3
Upstart emits the \fBstarted\fP(7) event.
.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.

.SS Stopping a Job

.nr step 1 1
.IP \n[step] 3
If the \fBpre-stop\fP stanza exists, the pre-stop process is
spawned.
.IP \n+[step] 3
The main process is stopped:
.RS
.nr step2 1 1
.af step2 i
.IP \n[step2] 3
The SIGTERM signal is sent to the main process.
.sp 1
See \fBsignal\fP(7).
.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 SIGKILL is sent to the process.
.RE
.IP \n+[step] 3
Upstart emits the \fBstopping\fP(7) event.
.IP \n+[step] 3
If the \fBpost-stop\fP stanza exists, the post-stop process is
spawned.
.IP \n+[step] 3
Upstart emits the \fBstopped\fP(7) event.
.sp 1
When this event completes, the job is fully stopped.

.SH AUTHOR
Manual page written by James Hunt
.RB < james.hunt@canonical.com >
.\"
.SH REPORTING BUGS
Report bugs at
.RB < https://launchpad.net/upstart/+bugs >
.\"
.SH COPYRIGHT
Copyright \(co 2011 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 telinit (8)
