||<tablestyle="float:right; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;">'''Table of Contents'''<<BR>> <<TableOfContents>>||

= Upstart 0.9 =

[[Upstart]] has been updated to 0.9.7-1.

== Chroot support ==

Upstart is now "chroot-aware". If `initctl` is run as root from within a chroot
the Upstart init daemon (outside the chroot) will honour requests from
within the chroot to manipulate jobs within the chroot.

Notes:

 * Within the chroot, only jobs within the chroot can be manipulated.
 * It is only possible to control such chroot jobs from within the chroot. That is to say, the "outer" system cannot manipulate jobs within the chroot.
 * Due to the design of this feature, Upstart will '''not''' be able to detect changes to job configuration files within the chroot ''until a process within the chroot has either manipulated a job, or listed one or more jobs''.
 * Chroot support can be disabled at boot by passing the "`--no-sessions`" option on the Grub kernel command-line. If chroots are disabled, running Upstart commands within a chroot will affect jobs outside the chroot only.
 * If a job is run in a chroot environment (such as provided by schroot(1)), exiting the chroot will kill the job.

== Basic Job/Event Visualisation ==

Upstart provides a new Python script `initctl2dot` which converts the
output of the new `initctl show-config` command to
[[http://www.graphviz.org/|GraphViz]] format. By default, all job
configuration files are considered and the links between jobs and events
are displayed graphically. Additionally, it is possible to list a set of
jobs to graph. Run "{{{initctl2dot --help}}}" or "{{{man initctl2dot}}}" for full options.

== New Initctl Commands ==

Two new `initctl` commands have been added:

 1. `show-config`
 1. `check-config`

The `show-config` command displays core job configuration details,
namely the `start on`, `stop on` and `emits` stanza information. This is
useful since it allows users to see how Upstart has parsed the job
configuration files. Additionally, the `show-config` command accepts an
optional `--enumerate` option which makes it easy to see which elements
of complex conditions are jobs, which are events and which are
environment details. This option forms the basis of the Visualisation
feature above.

The `check-config` command is useful for System Adminstrators and
tooling to ensure that all jobs are theoretically startable/stoppable.
For example, if a job configuration file specified the following complex
condition:

{{{
  start on (A and (B or (starting C or (starting D or starting E))))
}}}

The `check-config` command would flag an error if for example none of
the jobs 'C', 'D' or 'E' were available since that would indicate
the job in question could never be automatically started (since the
start on condition could never be true). Similar checks are performed on
events, so if jobs 'C', 'D' and 'E' are available but events 'A' and 'B'
are not advertised as being emitted by any job, 'check-config' will
generate an error. If no errors are detected, `check-config` displays no
output and returns zero. If errors are detected for a job, each
condition that is unsatisfiable is displayed with a message.

== D-Bus service activation ==

D-Bus version 1.4.1-0ubuntu2 and higher allow D-Bus services to be activated via Upstart. To convert an existing D-Bus service to be activated by Upstart:

 1. Add the keyword, "`UpstartJob=true`" to the "`.service`" file.
 1. Create a corresponding Upstart job configuration file with a `start on` condition specifying the new "`dbus-activation`" event, followed by the service name (such as "{{{start on dbus-activation com.ubuntu.NattyService}}}").
 1. Ensure that "`dbus-daemon`" is invoked with the "`--activation=upstart`" option.

== Manual stanza ==

A new job configuration stanza, "`manual`" has been added. If specified, this has the effect of removing any previously defined "start on" stanza for job so that the job can only be started with "`initctl start`" / "`start`". This is most useful when used in combination with Override files.

== Override files ==

Override files are files ending in "`.override`" which if placed into
the job configuration directory ("`/etc/init/`") are able to modify the
way in which a job configuration file behaves. They could be used by
System Administrators or tooling to change the behaviour of a job
without modifying a packages configuration files directly.

Override files support the same syntax as the existing job configuration
(".conf") files.

For example, to ensure that a service is never automatically started:

{{{
  echo manual >> /etc/init/myjob.override
}}}

To allow the original behaviour, simply delete the Override file.

Another example: to change the start on condition for a job:

{{{
  echo "start on (starting job-A or event-B)" >> /etc/init/myjob.override
}}}

Note that Override files have no effect unless there is a corresponding
job configuration file (a file with the same prefix name).

The effect of deleting an override file is to revert the job (immediately)
back to its original configuration.

== Socket bridge ==

Upstart now provides a socket bridge (`upstart-socket-bridge`) which is
a daemon started early in the boot process that allows jobs to be
started when socket connections are made. Jobs register their desire to
be started by a socket connection by requiring the new "`socket`" event
in their `start on` (or `stop on`) stanza(s):

{{{
  # Internet sockets
  start on socket PROTO=PROTO PORT=PORT ADDR=ADDR

  # Local and Abstract sockets
  socket PROTO=PROTO PATH=PATH
}}}

For example, to have a web server only start when the first client
connection is received, its job configuration file might specify:

{{{
  start on socket PROTO=inet PORT=80
}}}

See the new manual pages for further details:

 * [[http://manpages.ubuntu.com/manpages/natty/en/man7/socket-event.7.html|socket-event (7)]]
 * [[http://manpages.ubuntu.com/manpages/natty/en/man8/upstart-socket-bridge.8.html|upstart-socket-bridge (8)]]

== Miscellaneous ==

 * A new manual page, [[http://manpages.ubuntu.com/manpages/natty/en/man7/upstart-events.7.html|upstart-events (7)]] summarising well-known Upstart events.
 * A Bash completion script has been included for `initctl`.
 * A new script `init-checkconf` has been provided which allows a user to check an individual job configuration file to ensure it is syntactically correct before installing it in "`/etc/init/`". Run "{{{init-checkconf -h}}}" or see the man page for [[http://manpages.ubuntu.com/manpages/natty/en/man8/init-checkconf.8.html|init-checkconf (8)]] for full options.
 * The [[http://www.vim.org|Vim]] package "{{{vim-runtime}}}" now includes syntax support for upstart job configuration files.