KarmicUpstartPackagingPolicy

Revision 1 as of 2009-06-15 10:42:58

Clear message

Summary

This specification contains the documentation for the Upstart packaging and upgrade policy.

Existing Upstart Configuration

Upstart configuration will move from /etc/event.d to /etc/init and files now require a .conf extension. It's not a simple matter of moving the files, since the actual format has also changed.

Happily not many packages currently ship Upstart jobs, which makes the job somewhat easier. The change of location also helps, since there are no issues with a newer Upstart reading an old file or vice-versa.

Packages will be updated to use the new format and location, and will depend on the new version of Upstart.

The proposed dh_installupstart helper (see below) will aid with this.

Replaced Initscripts

Initscripts being replaced by Upstart jobs will be removed from /etc/init.d and have their symlinks removed from the /etc/rc?.d directories. If the initscript was user-modified, it will be renamed to have a .dpkg-bak extension instead of being removed.

Existing Initscripts

Initscripts not being replaced should be updated to ensure they have accurate LSB header information. Upstart will eventually use this directly instead of running the existing sysv-rc shell script.

While we use sysv-rc the symlinks will remain, once we do not, they will be removed but the initscripts will remain in /etc/init.d

Jobs over upgrades

Upstart automatically attempts to keep all configured jobs running, and watches its configuration directory for new jobs. Simply installing a configuration file into /etc/init will cause Upstart to start if it can.

This isn't quite ideal, since the package may not be fully configured. Also during upgrades we want to stop the job and restart once the upgrade is over.

But we don't want the mis-behaviour where a job that was not running is started over an upgrade.

Upstart supports the facility of placing a job in "manual mode", this will be extended to support "manual mode for upgrade".

The proposed dh_installupstart helper (see below) will aid with this.

LSB Facilities for Upstart

The LSB specification defines various [http://refspecs.freestandards.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/facilname.html Facility Names] for use by initscripts defining common system states.

Since Upstart intends to honour the LSB init specification for its initscripts, it will also honour these facility names - and they may be used in Upstart jobs.

For reference, these are named here:

$local_fs:

  • all local file systems are mounted

$network:

  • basic networking support is available. Example: a server program could listen on a socket.

$named:

  • IP name-to-address translation, using the interfaces described in this specification, are available to the level the system normally provides them. Example: if a DNS query daemon normally provides this facility, then that daemon has been started.

$portmap:

  • daemons providing SunRPC/ONCRPC portmapping service as defined in RFC 1833: Binding Protocols for ONC RPC Version 2 (if present) are running.

$remote_fs:

  • all remote file systems are available. In some configurations, file systems such as /usr may be remote. Many applications that require $local_fs will probably also require $remote_fs.

$syslog:

  • system logger is operational.

$time:

  • the system time has been set, for example by using a network-based time program such as ntp or rdate, or via the hardware Real Time Clock.

It's expected that Upstart will define an additional state for the completion of standard boot stages related to the filesystem so that jobs do not need to worry about the distinction between a local and remote filesystem for the case of /usr.

dh_installupstart

It was quickly agreed that we should have a Debhelper tool to aid with Upstart packaging, this will take care of the common actions:

  • packages include debian/*.upstart, these are automatically installed to the correct location
  • a previous /etc/event.d file is automatically removed or backed up
  • a previous /etc/init.d script is automatically removed or backed up
  • maintainer script commands for placing the job in manual mode across an upgrade are automatically provided

CategorySpec