Contents
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:
Change Summary
Added Since Release |
New Stanzas |
New init Options |
New initctl Commands |
New Commands |
lucid |
||||
|
||||
|
||||
|
|
|||
|
|
|
||
oneiric |
|
|||
|
||||
|
|
|||
|
|
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 --no-log option.
To modify the value of console for jobs which do not explicitly specify it, use the --default-console option.
To change the location where log files are written to, use the --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 <signal_name>
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 <group_name>
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 <user_name>
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 <string>
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 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 init-checkconf (8) for full details.
initctl2dot
Basic visualization tool which which converts the output of the initctl 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 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 <job>
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 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.
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:
Add the keyword, "UpstartJob=true" to the ".service" file.
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").
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:
Miscellaneous
A new manual page, 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 Vim package "vim-runtime" now includes syntax support for Upstart job configuration files.