Provided by: upstart_1.3-0ubuntu10_i386 bug

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.


+----+-------------------------+------+------+------------------------+------+
|Ref |          Event          | Type | Emit |          Time          | Note |
+----+-------------------------+------+------+------------------------+------+
|    | all-swaps               |  S   |  M   | > (5)                  |      |
|    | control-alt-delete(7)   |  S   |  A   | > (5)                  |  A   |
|    | dbus-activation         |  S   |  B   | > D-Bus client request |      |
|    | device-not-ready        |  H   |  M   | > (2)                  |  N   |
|    | desktop-session-start   |  H   |  D   | > X(7) session created |  B   |
|    | desktop-shutdown        |  H   |  D   | > X(7) session ended   |  O   |
|    | drm-device-added        |  S   |  U   | > (5)                  |  C   |
|    | filesystem              |  S   |  M   | After last (1)         |  D   |
|    | graphics-device-added   |  S   |  U   | > (5)                  |  C   |
|    | keyboard-request(7)     |  S   |  A   | > (5)                  |  E   |
|    | local-filesystems(7)    |  S   |  M   | > (6)                  |      |
|    | login-session-start     |  H   |  D   | < DM running           |  F   |
| 1  | mounted(7)              |  H   |  M   | > associated (2)       |  G   |
| 2  | mounting(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   |
|    | power-status-changed(7) |  S   |  I   | > (5)                  |  I   |
|    | remote-filesystems(7)   |  S   |  M   | > (6)                  |      |
|    | runlevel(7)             |  M   |  T   | > (5)                  |      |
|    | 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   |
|    | unmounted-remote-       |  H   |  V   | >   last   remote   FS |  L   |
|    | filesystems             |      |      | unmounted              |      |
| 6  | virtual-filesystems(7)  |  S   |  M   | > last virtual FS (1)  |  M   |
+----+-------------------------+------+------+------------------------+------+
       Key:
         'FS' is an abbreviation for filesystem.
         'DM' is an abbreviation for Display Manager.

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


+----+----------------------------------+---------------------------------+
|Ref | Emitter                          | Notes                           |
+----+----------------------------------+---------------------------------+
| A  | System Administrator (initiator) | Technically emitted by init(8). |
| B  | dbus-daemon(1)                   | Run with "--activation=upstart" |
| D  | Display Manager                  | e.g. lightdm/gdm/kdm/xdm.       |
| F  | ifup(8) or ifdown(8)             | See /etc/network/.              |
| I  | init(8)                          |                                 |
| M  | mountall(8)                      |                                 |
| N  | network-interface job            |                                 |
| S  | upstart-socket-bridge(8)         |                                 |
| T  | telinit(8), shutdown(8)          |                                 |
| U  | upstart-udev-bridge(8)           |                                 |
| V  | System V init system             |                                 |
+----+----------------------------------+---------------------------------+

Table 4: 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) 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.                  |
| 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) for |
|     | any filesystem type is about to begin.                          |
| I   | Emitted when Upstart receives the SIGPWR signal.                |
| J   | Initial event.                                                  |
| 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.                                         |
| 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 |
|     | reboot, to hand off to the shutdown splash manager.             |
+-----+-----------------------------------------------------------------+

Job lifecycle

   Starting a Job
       1  Upstart emits the starting(7) event denoting the job  is  "about  to
          start". The starting(7) event completes.

       2  If the pre-start stanza exists, the pre-start process is spawned.

       3  Upstart spawns the main process.

          It  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.

       4  If the post-start stanza exists, the post-start process is spawned.

       5  Upstart emits the started(7) event.

          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.

   Stopping a Job
       1  If the pre-stop stanza exists, the pre-stop process is spawned.

       2  The main process is stopped:

          i  The SIGTERM signal is sent to the main process.

             See signal(7).

          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  is
             sent to the process.

       3  Upstart emits the stopping(7) event.

       4  If the post-stop stanza exists, the post-stop process is spawned.

       5  Upstart emits the stopped(7) event.

          When this event completes, the job is fully stopped.

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 (C) 2011 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) telinit(8)