Upstart configuration for Chromium OS
=====================================

This document attempts to address the most common questions when adding
an Upstart configuration file to Chromium OS.


Where should your .conf file go?
--------------------------------
Ideally not in this directory.

It is far better if your Upstart configuration file accompany your source,
either along with the source code under src/platform or src/third_party
if appropriate, or in the files/ directory alongside your ebuild in
src/third_party/chromiumos-overlay.


What should the 'start on'/'stop on' lines be?
----------------------------------------------
The majority of services will use:

  start on starting system-services
  stop on stopping system-services

"System Services" can expect the standard virtual filesystems to be
mounted, the stateful partition to be writable and services such as udev
and D-Bus to be running.

A special case is if your service should also be run in the case of the
UI failing to come up, this is particularly important for services that
would aid debugging (such as the SSH server on test images). These
services may assume the same dependencies and may instead use:

  start on starting failsafe
  stop on stopping failsafe

In both cases your service will not be started until the login prompt
is visible, so doesn't hold up the boot.

Some services might need to hold up the boot; you should think carefully
about this, even if you only add 100ms to the boot time, if ten people
do that we slip from 8s to 9s. These services can still depend on the
standard virtual filesystems to be mounted, the stateful partition to be
writable but can only depend on udev to be running - no other service.
They may use:

  start on starting boot-services
  stop on stopping boot-services

The UI itself is one of these services.

On the other end of the spectrum, you might have something to run after
the boot; for example because it examines log files and soforth. This
can be run with:

  start on started system-services

Note the use of 'started' rather than 'starting', that's important!


Should I put 'task' in my configuration?
----------------------------------------
Probably not.

To illustrate what 'task' does, here is an example configuration file:

  start on starting boot-services
  script
    :
  end script

Note that this has no 'stop on' line, this script finishes by itself and
should not be interrupted; and only has a single 'script' block without
any pre-start, post-stop, etc. If your configuration file does not look
like this, you should not use 'task'.

When the boot-services milestone is reached, your script will begin
running alongside all other boot-services starting up. Your script might
take longer than that, and the system-services may begin starting too.

If this is not what you want, because your script does something that
all system services are likely to depend on, then 'task' may be
appropriate. But it may be better to have the other jobs depend on your
script finishing with 'and stopped your-script-name'.

Finally you should be aware that 'task' only affects the 'starting'
event; if your script is 'start on started system-services' then 'task'
has no effect so should not be used.


Which of 'script', 'pre-start', 'exec', etc. should I use?
----------------------------------------------------------
The most common case is that you are defining a service, but need to do
some setup work before and cleanup work after. In which case your
configuration file would look like:

  pre-start script
    # setup work here
  end script

  exec # daemon command-line here

  post-stop script
    # cleanup work here
  end script

You should omit the pre-start or post-stop script if you're not using
them.

Another common case is where the daemon takes a little more to get going
than just exec'ing a path with arguments, in which case you'd want to
use 'script' instead of 'exec'. A good pattern is:

  script
    # setup work here
    # work needed to get going here

    # daemon command-line here, forcing it to stay in the foreground

    # clean-up work here
  end script

In this case we need the daemon to stay in the foreground, otherwise the
clean-up work would happen while it's running. You cannot use the 'expect'
stanza with this style of configuration.

There's also a middle-ground:

  script
    # setup work here
    # work needed to get going here

    exec # daemon command-line here, but again in the foreground
  end script

  post-stop script
    # cleanup work here
  end script

This merges the 'pre-start' into the 'script' but keeps the 'post-stop'
separate. Note the use of 'exec' for the daemon, this ensures that it
has the same PID as the script that ran it, which is worthwhile. You
also cannot use 'expect' with this style.

Finally there's another style of configuration that is sometimes useful;
this is for when you have no need of a process running but only need to
perform work on startup and on shutdown - for example changing settings.
This looks like:

  pre-start script
    # work on startup here
  end script

  post-stop script
    # work on shutdown here
  end script

Upstart fully supports this, and it's known upstream as the "state
pattern". You may also see the "run once pattern" which consists
only of a 'pre-start'.