upstart-events(1) Well-known Upstart events summary

Event Summary

This manual page summarizes well-known events generated by Upstart running both as the 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, Table 1 and Table 2, encode the well-known system and session events respectively, along with the type of each event (listed in Table 3), the emitter of the event (see Table 4) and the approximate time at which the event could be generated. Additionally, the Note column indexes into Table 5 for further details on a particular event.

Table 6 shows job goals and possible state transitions. See the status command in initctl(8) for further details.

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

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 system job configuration files, usually located in /etc/init.

Table 1: Well-Known System Events Summary.

RefEventTypeEmitTimeNote



  
all-swapsSM> (5)

  
control-alt-delete(7)SA> (5)A

  
containerSC> /run mountedQ

  
dbus-activationSB> D-Bus client request

  
deconfiguring-networkingHV< non-local IFs downP

  
desktop-session-startHD> X(7) session createdB

  
desktop-shutdownHD> X(7) session endedO

  
device-not-readyHM> (2)N

  
drm-device-addedSU> (5)C

  
failsafe-bootSX> (7) and local IFS

  
fileSK> (1)U
7filesystemSMAfter last (1)D

  
graphics-device-addedSU> (5)C

  
keyboard-request(7)SA> (5)E

  
local-filesystems(7)SM> (6)

  
login-session-startHD< DM runningF
1mounted(7)HM> associated (2)G
2mounting(7)HM> (5)H
3net-device-addedSU> (5)C

  
net-device-changedSU> (5)C

  
net-device-downSF< (4)C
4net-device-removedSU> (5)C

  
net-device-upSF,N> (3)C

  
not-containerSC> /run mountedQ

  
power-status-changed(7)SI> (5)I

  
recoverySGBoot (<5)R

  
remote-filesystems(7)SM> (6)

  
runlevel(7)MT> (7) + (8)

  
socket(7)SS> socket connection
5startup(7)SIBootJ

  
started(7)SI> job startedK

  
starting(7)HI< job startsK

 8
static-network-upSN> last static IF up

  
stopped(7)SI> job stoppedK

  
stopping(7)HI< job stopsK

  
unmounted-:remote-:filesystems HV > last remote FS unmounted L
6virtual-:filesystems(7)SM> 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: Well-Known User Events Summary.

RefEventTypeEmitTimeNote



 
desktop-end(7)SJ< (2)

 
desktop-start(7)HJ> (3)

 
fileSK> (1)U
2session-end(7)MI< Session Init end
1startup(7)SI> Session Init startJ

 
:sys:*SE> upstart-event-bridge(8) start

 
:sys:restartedSE> upstart-event-bridge(8) startV
3xsessionMH> (1)T

Table 3: Event Types.

RefEvent TypeNotes


HHook Blocking. Waits for events that start on or stop on this event.
MMethodBlocking task.
SSignalNon-blocking.

Table 4: Event Emitters.

RefEmitterNotes


ASystem Administrator (initiator)Technically emitted by init(8).
Bdbus-daemon(1)Run with "--activation=upstart"
Ccontainer-detect job
DDisplay Managere.g. lightdm/gdm/kdm/xdm.
Eupstart-event-bridge(8)
Fifup(8) or ifdown(8)See /etc/network/.
Gbootloader or initramfs
Hxsession-init session job
Iinit(8)Either PID 1 or a Session Init.
Jjob that starts desktopgnome-session job for Ubuntu.
Kupstart-file-bridge(8)
Mmountall(8)
Nnetwork-interface job
Supstart-socket-bridge(8)
Ttelinit(8), shutdown(8)
Uupstart-udev-bridge(8)
VSystem V init system
Xfailsafe job

Table 5: Event Summary Notes.

NoteDetail


A Requires administrator to press Control-Alt-Delete key combination on the console.
BEvent 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.
DNote 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.
GGenerated 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.
IEmitted when Upstart receives the SIGPWR signal.
JInitial event (system or Session Init).
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.
MEmitted 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 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 successful, the standard startup(7) event is then emitted, allowing 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.
TOnly emitted for a graphical session.
USee file-event(7).
V This is a pseudo-system event emitted directly by the upstart-event-bridge(8).

Job States

Table 6: 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

step]
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).
step]
The goal is changed from 'stop' to 'start' indicating the job is attempting to start.
step]
The state is changed from 'waiting' to 'starting'.
step]
The starting(7) event is emitted denoting the job is "about to start".
step]
Any jobs whose 'start on' (or 'stop on') condition would be satisfied by this job starting are started (or stopped respectively).
step]
The starting(7) event completes.
step]
The state is changed from 'starting' to 'pre-start'.
step]
If the pre-start stanza exists, the pre-start process is spawned.
step]
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.
step]
Assuming the pre-start did not fail or did not call "stop", the main process is spawned.
step]
The state is changed from 'pre-start' to 'spawned'.
step]
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.
step]
The state is changed from 'spawned' to 'post-start'.
step]
If the post-start stanza exists, the post-start process is spawned.
step]
The state is changed from 'post-start' to 'running'.
step]
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).

step]
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

step]
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).
step]
The goal is changed from 'start' to 'stop' indicating the job is attempting to stop.
step]
The state is changed from 'running' to 'pre-stop'.
step]
If the pre-stop stanza exists, the pre-stop process is spawned.
step]
The state is changed from 'pre-stop' to 'stopping'.
step]
The stopping(7) event is emitted.
step]
Any jobs whose 'start on' (or 'stop on') condition would be satisfied by this job stopping are started (or stopped respectively).
step]
The main process is stopped:
step2]
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).

step2]
Upstart waits for up to "kill timeout" seconds (default 5 seconds) for the process to end.
step2]
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.
step]
The state is changed from 'killed' to 'post-stop'.
step]
If the post-stop stanza exists, the post-stop process is spawned.
step]
The state is changed from 'post-stop' to 'waiting'.
step]
The stopped(7) event is emitted.

When this event completes, the job is fully stopped.

step]
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 <[email protected]>

REPORTING BUGS

Report bugs at <https://launchpad.net/ubuntu/+source/upstart/+bugs>

COPYRIGHT

Copyright © 2011-2013 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.