Ubuntu Wiki

This page forms part of the Ubuntu 14.04 (Trusty Tahr) release notes. It 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

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 (User Sessions)

Upstart can now run as a normal user process (whose PID is not 1) both as root or as a non-privileged user by passing the --user option. This feature is employed to supervise a user's desktop session (technically those sessions listed in /etc/upstart-xsessions). The Session Init is started /etc/X11/Xsession.d/99upstart which starts a Session Init for a user.

Upstart is now used to supervise a user's desktop session. To see details of the running Upstart session, either echo $UPSTART_SESSION to see the D-Bus address the Session Init process is listening to, or run the following command which lists the process id of the Upstart session along with the value of $UPSTART_SESSION:

$ initctl list-sessions

The normal suite of Upstart commands is available (such as initctl, start, and stop) to allow the user to control their own non-privileged / session-level Upstart jobs. For example, to list all session jobs, run:

$ initctl list

To list system jobs from within a user session, run one of the following two commands:

$ initctl --system list
$ sudo initctl list

Note that this is behavioural change since in Precise running for example "initctl list" as a non-privileged user would list all system jobs.

Session jobs are read from /usr/share/upstart/sessions/ and $XDG_CONFIG_HOME/upstart/ (or $HOME/.config/upstart if $XDG_CONFIG_HOME is not set). Session jobs are also read from the now-deprecated location "$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".

Session job output is logged to "$XDG_CACHE_HOME/upstart/" (or "$HOME/.cache/upstart/" if $XDG_CACHE_HOME is not set). Since each job is logged to its own file, management and analysis of application output is much simpler. Note that applications and services running as the user which are not managed by Upstart as Session Jobs will continue to write their output "$HOME/.xsession-errors". The Session Init itself will also write output to this file if run in debug mode (by adding the "--debug" command-line option or toggling it by running "initctl log-priority debug" to enable debug mode and "initctl log-priority message" to disable it again).

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.

Addition to listening on the private D-Bus address specified by $UPSTART_SESSION, the Session Init also connects to the users D-Bus session bus.

Log files are rotated automatically using a session 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 more precise details on 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 that if you are upgrading from Precise to Trusty, it is necessary to reboot once before the stateful re-exec ability is enabled since the version of Upstart in Precise is not stateful re-exec capable.

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.

init-checkconf restriction removed

The init-checkconf command can now be run as the root user if desired (although this has never been necessary).

See the manual page for further details:

• init-checkconf (8)

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.

Changed Behaviour

Handling of Chroot Sessions

The Ubuntu version of Upstart has been modified to disable chroot(2) session support by default. To re-enable chroot support which was introduced in Precise, it is now necessary to pass the following option to Upstart either via the kernel command-line (via your bootloader such as grub) or by customising your initramfs:

    --chroot-sessions

See Also

• precise release notes

• saucy release notes

• trusty release notes