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

reset-env (Session Init only)

set-env (Session Init only)

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):

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):

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:

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:

init-checkconf restriction removed

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: