||<>|| This page forms part of the [[TrustyTahr/ReleaseNotes/|Ubuntu 14.04 (Trusty Tahr) release notes]]. It summarizes the changes to Upstart between the following releases: * [[PrecisePangolin/ReleaseNotes|precise]] (12.04 running [[PrecisePangolin/ReleaseNotes/TechnicalOverviewUpstart|Upstart 1.5]]) to [[TrustyTahr/ReleaseNotes|trusty]] (14.04, running Upstart 1.12.1) * [[SaucySalamander/ReleaseNotes|saucy]] (13.10, running [[SaucySalamander/ReleaseNotes#Upstart_1.10|Upstart 1.10]]) to [[TrustyTahr/ReleaseNotes|trusty]] (14.04, running Upstart 1.12.1) For full details, please refer to the following: * [[http://manpages.ubuntu.com/manpages/trusty/man5/init.5|init (5)]] * [[http://manpages.ubuntu.com/manpages/trusty/man8/init.8|init (8)]] * [[http://manpages.ubuntu.com/manpages/trusty/man8/initctl.8|initctl (8)]] * [[http://manpages.ubuntu.com/manpages/trusty/man7/upstart-events.7.html|upstart-events (7)]] * [[http://upstart.ubuntu.com/cookbook/|The Upstart Cookbook]] ---- === Change Summary === ||<#F1F1ED>'''Added Since Release'''||<#F1F1ED>'''New Stanzas'''||<#F1F1ED>'''New `init` Options'''||<#F1F1ED>'''New `initctl` Commands'''||<#F1F1ED>'''New Commands'''||<#F1F1ED>'''New Bridges'''|| ||<(|6> precise || [[#apparmor load|apparmor load]] || [[#init--no-dbus|--no-dbus]] || [[#get-env|initctl get-env]] || [[#upstart-monitor|upstart-monitor]] || [[#upstart-dbus-bridge|upstart-dbus-bridge]] || || [[#apparmor switch|apparmor switch]] || [[#init--user|--user]] || [[#list-env|initctl list-env]] || || [[#upstart-dconf-bridge|upstart-dconf-bridge]] || || [[#reload-signal|reload signal]] || || [[#list-sessions|initctl list-sessions]] || || [[#upstart-event-bridge|upstart-event-bridge]]|| || || || [[#reset-env|initctl reset-env]] || || [[#upstart-file-bridge|upstart-file-bridge]] || || || || [[#set-env|initctl set-env]] || || [[#upstart-local-bridge|upstart-local-bridge]] || || || || [[#unset-env|initctl unset-env]] || || || ||<-6#F1F1ED> || ||<(>saucy || || [[#init--no-dbus|--no-dbus]] || || || || ||<-6#F1F1ED> || ---- ==== 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: {{{#!html 
    apparmor load <profile-path>
}}} Notes: * The `` must be an absolute path. * The job will fail if the profile does not exist, or the profile fails to load. Example: {{{#!html 
    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: {{{#!html 
    apparmor switch <profile-name>
}}} Notes: * The job will fail if the profile named does not exist, or is not already loaded. Example: {{{#!html 
    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 {{{#!html 
        reload signal SIGUSR1
}}} * Partial signal name {{{#!html 
        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|upstart-event-bridge]]). ===== --user (Running a Session Init) ===== <> Runs Upstart as a Session Init. See [[#session-init|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: * [[http://manpages.ubuntu.com/manpages/trusty/man8/upstart-monitor.8|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: {{{#!html 
    $ 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: {{{#!html 
    <session-init-pid> <private-dbus-address>
}}} Note that `` shows the value of the `$SESSION_INIT` variable set for all jobs in that Session Inits environment. Example: {{{#!html 
    $ 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: {{{#!html 
    $ initctl set-env foo='hello world'
}}} ===== unset-env (Session Init only) ===== <> Discards the specified variable from the job environment table. Example: {{{#!html 
    $ 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`: {{{#!html 
$ 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: {{{#!html 
$ initctl list
}}} To list ''system'' jobs from within a user session, run one of the following two commands: {{{#!html 
$ 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 [[#unset-env|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: {{{#!html 
    $ 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): * [[http://manpages.ubuntu.com/manpages/trusty/man5/init.5.html|init (5)]] * [[http://manpages.ubuntu.com/manpages/trusty/man8/init.8.html|init (8)]] * [[http://manpages.ubuntu.com/manpages/trusty/man7/upstart-events.7.html|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): {{{#!html 
    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: * [[http://manpages.ubuntu.com/manpages/trusty/man7/dbus-event.7.html|dbus-event (7)]] * [[http://manpages.ubuntu.com/manpages/trusty/man8/upstart-dbus-bridge.8.html|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): {{{#!html 
    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: * [[http://manpages.ubuntu.com/manpages/trusty/man7/dconf-event.7.html|dconf-event (7)]] * [[http://manpages.ubuntu.com/manpages/trusty/man8/upstart-dconf-bridge.8.html|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: {{{#!html 
    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: {{{#!html 
    :sys:started JOB=foo
}}} See the manual page for further details: * [[http://manpages.ubuntu.com/manpages/trusty/man8/upstart-event-bridge.8.html|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: {{{#!html 
    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: {{{#!html 
    start on file FILE=/var/crash/*.crash EVENT=create
    exec ...
}}} See the manual pages for further details: * [[http://manpages.ubuntu.com/manpages/trusty/man7/file-event.7.html|file-event (7)]] * [[http://manpages.ubuntu.com/manpages/trusty/man8/upstart-file-bridge.8.html|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: * [[http://manpages.ubuntu.com/manpages/trusty/man8/upstart-local-bridge.8.html|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: * [[http://manpages.ubuntu.com/manpages/trusty/man8/init-checkconf.8.html|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 [[PrecisePangolin/ReleaseNotes/TechnicalOverviewUpstart#Chroot_support|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 === * [[PrecisePangolin/ReleaseNotes|precise release notes]] * [[SaucySalamander/ReleaseNotes|saucy release notes]] * [[TrustyTahr/ReleaseNotes|trusty release notes]] ----