Ubuntu Wiki

This page summarizes the changes to Upstart between the following releases:

• precise (12.04 running Upstart 1.5) to trusty (14.04, running Upstart 1.12.1)
• saucy (13.10, running Upstart 1.10) to trusty (14.04, running Upstart 1.12.1)

For full details, please refer to the following:

• init (5)

• init (8)

• initctl (8)

• upstart-events (7)

• The Upstart Cookbook

Change Summary

New Stanzas and Stanza Values

apparmor load

Loads the specified AppArmor Mandatory Access Control system profile into the kernel prior to starting the job. The main job process (as specified by exec or script) will be confined to this profile.

Syntax:

    apparmor load <profile-path>

Notes:

• - The <profile-path> must be an absolute path. - The job will fail if the profile does not exist, or the profile fails to load.

Example:

    apparmor load /etc/apparmor.d/usr.sbin.cupsd
    exec /usr/sbin/cupsd -F

apparmor switch

Run main job process with already-loaded AppArmor Mandatory Access Control system profile.

Syntax:

    apparmor switch <profile-name>

Notes:

• - The job will fail if the profile named does not exist, or is not already loaded.

Example:

    apparmor switch /usr/bin/cupsd
    exec /usr/sbin/cupsd -F

reload signal

Specifies the signal that will be sent to the jobs main process when the job needs to be reloaded (the default is SIGHUP).

The signal should be specified as a full name (for example SIGHUP) or a partial name (for example HUP). Note that it is possible to specify the signal as a number (for example, "1") although this should be avoided if at all possible since signal numbers may differ between systems.

Examples:

• - Full signal name

  •         reload signal SIGUSR1

  - Partial signal name

  •         reload signal USR1

New init options

WARNING: Under normal conditions, you should not need to specify any command-line options to Upstart.

--no-dbus

Stops Upstart running as PID 1 from connecting to the D-Bus system bus. This can be employed if users wish to disable the ability for Session Inits to have any knowledge of system-level events (propogated to Session Inits via the upstart-event-bridge_).

--user (Running a Session Init)

Runs Upstart as a Session Init.

See Session Init.

New Commands

upstart-monitor

Allows upstart events to be observed as they are emitted in a similar fashion to dbus-monitor. The tool is able to run either graphically (default) or in console mode (upstart-monitor --no-gui).

See the manpage for further details:

• upstart-monitor (8)

New initctl Commands

All the commands below apply only to Upstart running as a Session Init.

get-env (Session Init only)

Retrieve value of a job environment variable.

Example:

    $ initctl get-env foo
    bar

list-env (Session Init only)

Show all variables in the job environment table.

Note that all Session Jobs inherit the environment of their Session Init.

list-sessions (Session Init only)

Lists details of the running Session Inits. The format is:

    <session-init-pid> <private-dbus-address>

Note that <private-dbus-address> shows the value of the $SESSION_INIT variable set for all jobs in that Session Inits environment.

Example:

    $ initctl list-sessions
    3285 unix:abstract=/com/ubuntu/upstart-session/1000/3285

list-sessions (Session Init only)

reset-env (Session Init only)

Return the job environment table to its default values.

set-env (Session Init only)

Adds or updates a variable in the job environment table.

Example:

    $ initctl set-env foo='hello world'

unset-env (Session Init only)

Discards the specified variable from the job environment table.

Example:

    $ initctl unset-env foo

New Features

Session Init

Upstart can now run as a normal user process (whose PID is not 1) both as root or as a non-privileged user. This feature is employed to manage the graphical session listed in /etc/upstart-xsessions. See /etc/X11/Xsession.d/99upstart which starts a Session Init for a user.

Non-graphical logins are not supported by default. Once the users desktop session starts, they may use the usual set of Upstart commands (such as "initctl", "start", "stop") to control their own non-privileged / session-level Upstart jobs. This implies a small behavioural change: in precise, running for example "initctl list" as a non-privileged user would list all system jobs. However, in trusty this command will list all *Session* jobs. There are two methods for a non-privileged user to list all system jobs:

• - Method 1: Use sudo:

  •     $ sudo initctl list

  - Method 2: Use the --system option:

  •     $ initctl --system list

User jobs can be loaded from multiple locations. The default set of jobs started for a Session Init exist in /usr/share/upstart/sessions/*.conf" however the user may supplement these jobs by placing new jobs in $XDG_CONFIG_DIR/upstart (or "$HOME/.config/upstart/" if not set) or the now-deprecated "$HOME/.init/".

Note that the Session Init will accept the first job of a particular name it find when loading jobs from all the directories it considers. However, note that a user may create an override file with the same name prefix as a job in a directory higher up the search path to modify its behaviour. For example a user can modify "/usr/share/upstart/sessions/job.conf" by creating a file named "$HOME/.config/upstart/foo.override").

The Session Init automatically inherits all variables from the environment that it was run from, making these variables available to the Session Jobs. This behaviour can be modified with the user of the new initctl environment commands such as initctl unset-env.

The Session Init connects to the users D-Bus session bus. All jobs running within a Session Init environment have a UPSTART_SESSION environment variable set to the private D-Bus address the Session Init is listening on.

Log files for Session Jobs are written to "$XDG_CACHE_DIR" (or "`$HOME/.cache/upstart/" if not set).

Log files are rotated automatically using a job called rotate which runs soon after graphical login but can be run at any time as:

    $ start logrotate

Table 2 in upstart-events(7) now lists Session-specific events.

See the manual pages for further details (including the order in which job configuration files and override files are read):

• init (5)

• init (8)

• init-events (7)

Stateful re-exec

"telinit u" now performs a stateful re-exec of Upstart. This command is called automatically when either Upstart, or any of its dependent libraries are updated. This means that the running version of Upstart will now always match the latest installed version - no reboot is required and services are not interrupted.

Note further that the /usr/share/upstart/sessions/re-exec.conf Session Job handles automatically restarting all Session Inits as soon as the System Init has restarted.

D-Bus bridge

Bridge that allows Session Jobs to react to D-Bus changes.

Note that by default, two instances of this bridge are started per user to allow Session Jobs to react to changes on the D-Bus session bus and the D-Bus system bus.

Although this bridge can run at the system level, no instance of this bridge is started automatically since doing so may be undesirable in that it could expose system-level D-Bus messages to the Session Inits.

Example (start a job when a particular NameAcquired D-Bus signal is received):

    start on dbus SIGNAL=NameAcquired INTERFACE=org.freedesktop.DBus OBJPATH=/org/freedesktop/DBus SENDER=org.freedesktop.DBus ARG0=com.mycorp.foo

See the manual pages for further details:

• dbus-event (7)

• upstart-dbus-bridge (8)

DConf bridge (Session-Init only)

Bridge that allows Session Jobs to react to DConf database changes.

Example (start a job when the user allows remote access to their desktop):

    start on dconf TYPE=changed KEY=/desktop/gnome/remote-access/notify-on-connect VALUE=true

Note that this bridge is not part of the upstart package; it is in package upstart-dconf-bridge which is not installed by default.

See the manual pages for further details:

• dconf-event (7)

• upstart-dconf-bridge (8)

Event bridge

An instance of the upstart-event-bridge runs for each user logged in via a graphical desktop. This bridge proxies system-level events down to the users Session Init. This means all events emitted by a system job become visible to jobs running as the user.

To allow Session Jobs to distinguish between User Events and System Events, the upstart-event-bridge prefixes all system events with ":sys:". So for example, when the "foo" system job starts, at the system level the following event will be emitted:

    started JOB=foo

That event is visible to all System Jobs, but is invisible to Session Jobs. However, the following event will be emitted by the upstart-event-bridge to allow Session Jobs to react to the "foo" system job starting:

    :sys:started JOB=foo

See the manual page for further details:

• upstart-event-bridge (8)

File bridge

Upstart now provides a file bridge (upstart-file-bridge) which is a daemon started early in the boot process that allows jobs to react to file events. It uses inotify(7) and is available both for System Jobs and Session Jobs. The bridge emits the file event.

Syntax of file event:

    start on file FILE=PATH EVENT=TYPE [MATCH=PATH]

Example job using the file event that will run a program when a file matching the glob "/var/crash/*.crash" is created:

    start on file FILE=/var/crash/*.crash EVENT=create
    exec ...

See the manual pages for further details:

• file-event (7)

• upstart-file-bridge (8)

Local bridge

Specialist bridge that provides a bridge between local Unix sockets and Upstart. Currently only enabled and used on Ubuntu Touch. See the manual page for further details:

• upstart-local-bridge (8)

Initramfs-less boot

Upstart can now boot a system which does not use an initd/initramfs.

Apport Hook

Upstart now provides an apport hook (/usr/share/apport/package-hooks/upstart.py) that will collect the required data to help developers resolve the issue should either upstart crash or a user wish to report a bug on Upstart by running ubuntu-bug upstart.