tree: 7e7291d5d9a061d4921165099d83885f52c72aeb [path history] [tgz]
  1. clobber/
  2. encrypted_reboot_vault/
  3. encrypted_stateful/
  4. libpreservation/
  5. metrics/
  6. mount_encrypted/
  7. process_killer/
  8. setuid_restrictions/
  9. startup/
  10. systemd/
  11. tests/
  12. tmpfiles.d/
  13. tpm_encryption/
  14. unencrypted_stateful/
  15. upstart/
  16. BUILD.gn
  17. chromeos-boot-alert
  18. chromeos-cleanup-logs
  19. chromeos-disk-metrics
  20. chromeos-send-kernel-errors
  21. chromeos_shutdown
  22. clobber-log
  23. cros_sysrq_init.cc
  24. dev_utils.sh
  25. DIR_METADATA
  26. disk_utils.sh
  27. display_low_battery_alert
  28. file_attrs_cleaner.h
  29. file_attrs_cleaner_lib.cc
  30. file_attrs_cleaner_test.cc
  31. file_attrs_cleaner_tool.cc
  32. is_feature_enabled.sh
  33. lvm.conf
  34. net_poll_tool.cc
  35. OWNERS
  36. periodic_scheduler.cc
  37. periodic_scheduler.h
  38. periodic_scheduler_main.cc
  39. periodic_scheduler_test.cc
  40. README.md
  41. rsyslog.chromeos
  42. send-boot-metrics.sh
  43. static_node_tool.cc
  44. STYLE
  45. usermode-helper.cc
  46. usermode-helper.h
  47. usermode-helper_lib.cc
  48. usermode-helper_test.cc
  49. utils.cc
  50. utils.h
  51. utils_test.cc
init/README.md

CrOS Upstart configuration

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

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/platform2//init/ or 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?

See CrOS User-Land Boot Design for more details.

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’.