<> This page summarizes the changes to Upstart between the following releases: * lucid to precise * oneiric to precise For full details, please refer to the following: * [[http://manpages.ubuntu.com/manpages/precise/man5/init.5|init (5)]] * [[http://manpages.ubuntu.com/manpages/precise/man8/init.8|init (8)]] * [[http://manpages.ubuntu.com/manpages/precise/man8/initctl.8|initctl (8)]] * [[http://manpages.ubuntu.com/manpages/precise/man7/upstart-events.7.html|upstart-events (7)]] * [[http://upstart.ubuntu.com/cookbook/|The Upstart Cookbook]] === Change Summary === ||'''Added Since Release''' ||'''New Stanzas''' ||'''New init Options''' ||'''New initctl Commands''' ||'''New Commands''' || ||<|6> lucid || [[#console log|console log]] || [[#init--confdir|--confdir]] || [[#check-config|initctl check-config]] || [[#init-checkconf|init-checkconf]] || || [[#kill-signal|kill signal]] || [[#init--logdir|--logdir]] || [[#notify-disk-writeable|notify-disk-writeable]] || [[#initctl2dot|initctl2dot]] || || [[#manual|manual]] || [[#init--no-log|--no-log]] || [[#show-config|show-config]] || || || [[#setgid|setgid]] || [[#init--default-console|--default-console]] || [[#initctl-usage|usage]] || || || [[#setuid|setuid]] || [[#init--no-sessions|--no-sessions]] || || || || [[#usage|usage]] || || || || ||<|4> oneiric || [[#console log|console log]] || [[#init--confdir|--confdir]] || [[#notify-disk-writeable|notify-disk-writeable]] || || || [[#setgid|setgid]] || [[#init--logdir|--logdir]] || [[#initctl-usage|usage]] || || || [[#setuid|setuid]] || [[#init--no-log|--no-log]] || || || || [[#usage|usage]] || [[#init--default-console|--default-console]] || || || ==== New Stanzas and Stanza Values ==== ===== console log ===== <> As of Upstart 1.4, the new default value for the `console` stanza is `log`. This means all job output written to standard output and standard error will be logged to file `/var/log/upstart/${job}.log` (or `/var/log/upstart/${job}-${instance}.log` if the job specifies the `instance` stanza). To revert to the old default behaviour where job output is discarded, use the [[#init--no-log|--no-log]] option. To modify the value of `console` for jobs which do not explicitly specify it, use the [[#init--default-console|--default-console]] option. To change the location where log files are written to, use the [[#init--logdir|--logdir]] option. If you specify this advanced option, you should also update the logrotate script `/etc/logrotate.d/upstart`. ===== kill signal ===== <> Specifies the stopping signal (`SIGTERM` by default) that a job's main process will receive when stopping the running job. Usage: {{{ kill signal }}} Example: {{{ kill signal INT }}} ===== manual ===== <> Specifying the "`manual`" stanza removes ''any previously defined'' "start on" stanza for job so that the job can only be started with "`initctl start`" or "`start`". This is most useful when used in combination with Override files. ===== setgid ===== <> Usage: {{{ setgid }}} Run the job under the specified group. If this stanza is unspecified, the primary group of the user specified in the `setuid` block is used for all job processes. If neither `setuid` nor `setgid` are specified, all job processes will run with its group ID set to 0 in the case of system jobs, and as the primary group of the user in the case of User Jobs. ===== setuid ===== <> Usage: {{{ setuid }}} Run the job under as the specified user. If this stanza is unspecified, all job processes will run as root in the case of system jobs, and as the user in the case of user jobs. Note that system jobs using the `setuid` stanza are still system jobs, and can not be controlled by an unprivileged user, even if the `setuid` stanza specifies that user. ===== usage ===== <> Brief message explaining how to start the job in question. Most useful for `instance` jobs which require environment variable parameters to be specified before they can be started. Syntax: {{{ usage }}} Example: {{{ instance $DB usage "DB - name of database instance" }}} If a job specifies the `usage` stanza, attempting to start the job without specifying the correct variables will display the usage statement. Additionally, the usage can be queried using the `initctl` [[#initctl-usage|usage]] command. ==== New Commands ==== ===== init-checkconf ===== <> Performs checks on a job configuration file prior to installing it in `/etc/init/`. The script must be run as a non-root user. By default checks both Upstart stanzas and script sections for validity. Usage: {{{ $ init-checkconf myjob.conf File myjob.conf: syntax ok }}} See [[http://manpages.ubuntu.com/manpages/precise/man8/init-checkconf.8.html|init-checkconf (8)]] for full details. ===== initctl2dot ===== <> Basic visualization tool which which converts the output of the `initctl` [[#show-config|show-config]] command to 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. See [[http://manpages.ubuntu.com/manpages/precise/man8/initctl2dot.8.html|initctl2dot(8)]] for full details. ==== New initctl Commands ==== ===== check-config ===== <> 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. ===== notify-disk-writeable ===== <> Command that is used to notify Upstart that the log disk is writeable, which is required for job logging. This command is called automatically by `/etc/init/flush-early-job-log.conf` job. ===== show-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. ===== usage ===== <> Display the usage for a job: {{{ $ initctl usage }}} Note that if a job is specified which does not use the `usage` stanza, no usage will be displayed. ==== New init options ==== WARNING: Under normal conditions, you should not need to specify any command-line options to Upstart. A number of these options were added specifically for testing Upstart itself and if used without due care can stop your system from booting. ===== --confdir ===== <> Specify alternate configuration directory (default: `/etc/init/`). ===== --default-console ===== <> Specify default value for jobs not specifying "`console`". See [[http://manpages.ubuntu.com/manpages/precise/man5/init.5|init (5)]] for permissible values. ===== --logdir ===== <> Specify alternate log directory (default: `/var/log/upstart/`). ===== --no-log ===== <> Disable job logging (all job output will be discarded). ===== --no-sessions ===== <> Disable user jobs and chroot support. See [[#chroot-support|Chroot Support]]. === New Features === ==== Chroot support ==== <> Upstart is now "chroot-aware". If `initctl` is run as the `root` user from within a chroot the Upstart `/sbin/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 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. ==== 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. ==== 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. ==== 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 }}} Notes: * It is necessary for daemons which wish to make use of this facility to be modified to understand the facility, specifically how to handle the `UPSTART_FDS` environment variable. See the manual pages for further details: * [[http://manpages.ubuntu.com/manpages/precise/man7/socket-event.7.html|socket-event (7)]] * [[http://manpages.ubuntu.com/manpages/precise/man8/upstart-socket-bridge.8.html|upstart-socket-bridge (8)]] ==== Miscellaneous ==== * A new manual page, [[http://manpages.ubuntu.com/manpages/precise/man7/upstart-events.7.html|upstart-events (7)]] summarising well-known Upstart events. This should be used when creating new jobs to identify appropriate `start on` and `stop on` conditions. * A Bash completion script has been included for `initctl`. * The [[http://www.vim.org|Vim]] package "{{{vim-runtime}}}" now includes syntax support for Upstart job configuration files.