---
name: "upstart-events"
section: "7"
platform: "linux"
package: "upstart"
version: "1.11-5"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/upstart-events"
---

# upstart-events(7)

Well-known Upstart events summary

## NAME

upstart-events - Well-known Upstart events summary

## Event Summary

This manual page summarizes well-known events generated by Upstart running both as the [**init**(8)](/init/8.md) 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)](/initctl/8.md) 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)](/upstart-event-bridge/8.md) 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)](/mounting/7.md) event occurs "at some time" after the [**startup**(7)](/startup/7.md) event, and the [**virtual-filesystems**(7)](/virtual-filesystems/7.md) event occurs after the last [**mounted**(7)](/mounted/7.md) 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.**

| | | | | | |
| --- | --- | --- | --- | --- | --- |
| Ref | Event | Type | Emit | Time | Note |
|  | **all-swaps** | S | M | \> (5) |  |
|  | [**control-alt-delete**(7)](/control-alt-delete/7.md) | 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)](/X/7.md) session created | B |
|  | desktop-shutdown | H | D | \> [**X**(7)](/X/7.md) 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 | **filesystem** | S | M | After last (1) | D |
|  | graphics-device-added | S | U | \> (5) | C |
|  | [**keyboard-request**(7)](/keyboard-request/7.md) | S | A | \> (5) | E |
|  | [**local-filesystems**(7)](/local-filesystems/7.md) | S | M | \> (6) |  |
|  | login-session-start | H | D | \< DM running | F |
| 1 | [**mounted**(7)](/mounted/7.md) | H | M | \> associated (2) | G |
| 2 | [**mounting**(7)](/mounting/7.md) | 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)](/power-status-changed/7.md) | S | I | \> (5) | I |
|  | recovery | S | G | Boot (\<5) | R |
|  | [**remote-filesystems**(7)](/remote-filesystems/7.md) | S | M | \> (6) |  |
|  | [**runlevel**(7)](/runlevel/7.md) | M | T | \> (7) + (8) |  |
|  | [**socket**(7)](/socket/7.md) | S | S | \> socket connection |  |
| 5 | [**startup**(7)](/startup/7.md) | S | I | Boot | J |
|  | [**started**(7)](/started/7.md) | S | I | \> job started | K |
|  | [**starting**(7)](/starting/7.md) | H | I | \< job starts | K |
| 8 | static-network-up | S | N | \> last static IF up |  |
|  | [**stopped**(7)](/stopped/7.md) | S | I | \> job stopped | K |
|  | [**stopping**(7)](/stopping/7.md) | H | I | \< job stops | K |
|  | unmounted-remote-filesystems | H | V | \> last remote FS unmounted | L |
| 6 | [**virtual-filesystems**(7)](/virtual-filesystems/7.md) | 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: Well-Known User Events Summary.**

| | | | | | |
| --- | --- | --- | --- | --- | --- |
| Ref | Event | Type | Emit | Time | Note |
|  | **desktop-end**(7) | S | J | \< (2) |  |
|  | **desktop-start**(7) | H | J | \> (3) |  |
|  | file | S | K | \> (1) | U |
| 2 | [**session-end**(7)](/session-end/7.md) | M | I | \< Session Init end |  |
| 1 | [**startup**(7)](/startup/7.md) | S | I | \> Session Init start | J |
|  | :sys:\* | S | E | \> [**upstart-event-bridge**(8)](/upstart-event-bridge/8.md) start |  |
|  | :sys:restarted | S | E | \> [**upstart-event-bridge**(8)](/upstart-event-bridge/8.md) start | V |
| 3 | xsession | M | H | \> (1) | T |

**Table 3: 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 4: Event Emitters.**

| | | |
| --- | --- | --- |
| Ref | Emitter | Notes |
| A | System Administrator (initiator) | Technically emitted by [init(8)](/init/8.md). |
| B | [**dbus-daemon**(1)](/dbus-daemon/1.md) | Run with "*--activation=upstart"* |
| C | container-detect job |  |
| D | Display Manager | e.g. lightdm/gdm/kdm/xdm. |
| E | [**upstart-event-bridge**(8)](/upstart-event-bridge/8.md) |  |
| F | [**ifup**(8)](/ifup/8.md) or [**ifdown**(8)](/ifdown/8.md) | See */etc/network/*. |
| G | bootloader or initramfs |  |
| H | xsession-init session job |  |
| I | [**init**(8)](/init/8.md) | Either PID 1 or a Session Init. |
| J | job that starts desktop | gnome-session job for Ubuntu. |
| K | [**upstart-file-bridge**(8)](/upstart-file-bridge/8.md) |  |
| M | [**mountall**(8)](/mountall/8.md) |  |
| N | network-interface job |  |
| S | [**upstart-socket-bridge**(8)](/upstart-socket-bridge/8.md) |  |
| T | [**telinit**(8)](/telinit/8.md), [**shutdown**(8)](/shutdown/8.md) |  |
| U | [**upstart-udev-bridge**(8)](/upstart-udev-bridge/8.md) |  |
| V | System V init system |  |
| X | failsafe job |  |

**Table 5: Event Summary Notes.**

| | |
| --- | --- |
| Note | Detail |
| A | Requires administrator to press Control-Alt-Delete key combination on the console. |
| B | Event generated when user performs graphical login. |
| C | These are specific examples. [**upstart-udev-bridge**(8)](/upstart-udev-bridge/8.md) 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)](/udev/7.md) 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)](/fstab/5.md) for any filesystem type is about to begin. |
| I | Emitted when Upstart receives the SIGPWR signal. |
| J | Initial event (system or Session Init). |
| K | Although the events are emmitted by [**init**(8)](/init/8.md), the instigator may be [**initctl**(8)](/initctl/8.md) 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 [**mountall**(8)](/mountall/8.md). This defaults to 30 seconds. |
| O | Emitted when the [*X*(7)](/X/7.md) 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)](/startup/7.md)) to denote the system has booted into recovery mode. If recovery was successful, the standard [**startup**(7)](/startup/7.md) 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. |
| T | Only emitted for a graphical session. |
| U | See [**file-event**(7)](/file-event/7.md). |
| V | This is a pseudo-system event emitted directly by the [**upstart-event-bridge**(8)](/upstart-event-bridge/8.md). |

## 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

- 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)](/initctl/8.md) **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)](/starting/7.md) 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)](/starting/7.md) 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)](/stopping/7.md)** and **[stopped(7)](/stopped/7.md)** 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 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)](/started/7.md) 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)](/initctl/8.md) **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)](/stopping/7.md) 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:

  - 1

    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)](/signal/7.md) and [**init**(5)](/init/5.md).

  - 2

    Upstart waits for up to "kill timeout" seconds (default 5 seconds) for the process to end.

  - 3

    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)](/stopped/7.md) 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-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.

## SEE ALSO

[**init**(5)](/init/5.md) [**init**(8)](/init/8.md) [**initctl**(8)](/initctl/8.md) [**mountall**(8)](/mountall/8.md) [**started**(7)](/started/7.md) [**starting**(7)](/starting/7.md) [**stopped**(7)](/stopped/7.md) [**stopping**(7)](/stopping/7.md) [**telinit**(8)](/telinit/8.md) [**upstart-event-bridge**(8)](/upstart-event-bridge/8.md)