doc/upstart.txt

   1 ===================================
   2 Upstart event-based service startup
   3 ===================================
   4
   5 This version of rc-scripts support Upstart event-based service startup. This
   6 can co-exist with old-style startup scripts.
   7
   8 Enabling/disabling event-base service startup
   9 ---------------------------------------------
  10
  11 Upstart event-based service startup may be disabled on boot time
  12 by using a ``pld.no-upstart`` kernel command-line option.
  13
  14 An init script may be called with ``USE_UPSTART=no`` environment variable
  15 to disable special upstart-related processing – this way one may use
  16 ``/etc/rc.d/init.d/$service start`` to start a service even if upstart job
  17 for that service is present. The ``/sbin/service`` script has two new options
  18 ``--upstart`` and ``--no-upstart`` to force new- or old-style service control.
  19
  20 ``USE_UPSTART=no`` can also be places in ``/etc/sysconfig/system``
  21 configuration file, though it can break ``*-upstart`` packages
  22 installation/removal a bit.
  23
  24 Available events
  25 ----------------
  26
  27 Ubuntu-compatible system events
  28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29
  30 all-swaps
  31         when swaps from ``/etc/fstab`` are activated
  32
  33 filesystem
  34         when basic filesystem hierarchy (FHS) is mounted
  35         NOTE: currently it doesn't wait for network filesystems!
  36
  37 local-filesystems
  38         when all local filesystems are mounted and initialized
  39
  40 root-filesystem
  41         when root filesystem is mounted r/w and initialized
  42
  43 virtual-filesystems
  44         when virtual filesystems (/proc, /sys, etc.) are mounted
  45
  46 PLD-specific system events:
  47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  48
  49 pld.sysinit-done
  50         when rc.sysinit finished its job
  51
  52 pld.shutdown-started
  53 starting shutdown
  54 started shutdown
  55         when rc.shutdown starts
  56
  57 pld.network-starting
  58 starting network
  59         just before network initialization is started
  60
  61 pld.network-started
  62 started network
  63         when network is initialized
  64
  65 pld.network-stopping
  66 stopping network
  67         just before network shutdown is started
  68
  69 pld.network-stopped
  70 stopped network
  71         when network configuration is shut down
  72
  73 Jobs
  74 ~~~~
  75
  76 The standard Upstart events are available for job control:
  77 starting(7) started(7) stopping(7) stopped(7)  (see man pages)
  78
  79 As relying on job name is not good enough when several alternative
  80 implementations of a service are available. In such case
  81 each of the alternative jobs should have an extra 'SERVICE_syslog=y'
  82 variable exported. In van then be used like this::
  83
  84   start on started SERVICE_syslog=y
  85
  86 Please note that using 'SERVICE=something' will not work, as the value
  87 will be inherited by any other job with 'export SERVICE'.
  88
  89 Job events and enabling/disabling event-base service startup
  90 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  91
  92 Please note that relying on events not raised by PLD service jobs
  93 or scripts (like 'startup') will make job ignore the 'pld.no-upstart'
  94 setting.
  95
  96
  97 Writing Upstart job descriptions
  98 --------------------------------
  99
 100 Job description files in ``/etc/init`` are not only the recipes to start
 101 a service, but also configuration files for that service. Keep that in mind
 102 when writing the ``*.conf`` files. No complicated logic, that can change from
 103 a release to a release, should be implemented there, the script should be
 104 readable, basic configuration settings easy to find and no upstart-controlled
 105 settings (like resource limit)  reimplemented in the script or started daemon
 106 arguments.
 107
 108 The syntax of the ``/etc/init/*.conf`` files is described in the init(5) man
 109 page.
 110
 111 Instead of using ``/etc/sysconfig/$service`` files put the service
 112 configuration directly into the ``*.conf`` file. When 'env' stanza is used for
 113 that, the value may be overridden when starting the job with initctl.
 114
 115 Simple example, the job description for syslog-ng::
 116
 117   start on pld.network-started
 118   stop on pld.shutdown-started
 119
 120   env SERVICE=syslog
 121   export SERVICE
 122
 123   respawn
 124
 125   console output
 126
 127   exec /usr/sbin/syslog-ng -F -f /etc/syslog-ng/syslog-ng.conf
 128
 129 Checking upstart configuration
 130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 131
 132 Since Upstart 1.3 one can check current configuration with::
 133
 134   initctl check-config
 135
 136 Also, with an 'initctl2dot' tool the configuration may be visualised in
 137 a graphical diagram.
 138
 139 Tracking startup progress
 140 ~~~~~~~~~~~~~~~~~~~~~~~~~
 141
 142 The easiest way to run a program from an upstart job is to ``exec`` it
 143 the way it will stay in foreground (that is what is the ``-F`` option in the
 144 example above for). However, when process is started this way Upstart cannot
 145 differentiate before the ``program starting failed`` and ``program has
 146 terminated`` cases. It will also assumed the job has started as soon as the
 147 command has been executed and that may be not what other jobs wait for.
 148
 149 A 'proper daemon' first checks command line arguments and configuration, then
 150 forks two times and returns with success only when the child process is ready.
 151 Upstart can handle such daemons with ``expect daemon`` stanza. So, to manage
 152 such daemon via Upstart, exec so it daemonize and use ``expect daemon``
 153 directive to tell Upstart what happens. Unfortunately, when ``expect daemon``
 154 is used and the process forks only once or does some more weird thing, Upstart
 155 job may lock up. Also, libdaemon-based daemons don't play well with ``expect
 156 daemon``.
 157
 158 When the service forks once ``expect fork`` should be used instead.
 159
 160 There is also an ``expect stop`` option, probably the most elegant way to
 161 track process startup. The process doesn't have to fork in this case and
 162 Upstart doesn't have to track that forking. The process should raise SIGSTOP
 163 when it is ready – only then Upstart will emit the job's ``started`` event and
 164 let the process continue. Unfortunately, currently hardly anything supports
 165 this interface.
 166
 167 When no ``expect`` stanza will help and we need to properly wait for process
 168 startup, then ``post-start`` script must be used. See the init(5) man page for
 169 details.
 170
 171 Debuging jobs
 172 ~~~~~~~~~~~~~
 173
 174 Making sure job description is correct and Upstart will properly manage the
 175 process may be tricky. One way to check if the job was described and started
 176 properly is to use ``pstree -p`` command and compare it to ``initctl status``
 177 output. Example::
 178
 179   # initctl status cherokee
 180   cherokee start/running, process 22419
 181
 182   # pstree -p
 183   init(1)─┬─Terminal(19446)─┬─bash(8983)───console(9003)
 184         ....
 185           |-bacula-sd(3514)---{bacula-sd}(3520)
 186           |-cherokee(22419)-+-cherokee-worker(22423)-+-rrdtool(22425)
 187           |                 |                        |-{cherokee-worker}(22424)
 188           |                 |                        |-{cherokee-worker}(22426)
 189           |                 |                        |-{cherokee-worker}(22427)
 190           |                 |                        |-{cherokee-worker}(22428)
 191           |                 |                        |-{cherokee-worker}(22429)
 192           |                 |                        |-{cherokee-worker}(22430)
 193           |                 |                        |-{cherokee-worker}(22431)
 194           |                 |                        |-{cherokee-worker}(22432)
 195           |                 |                        |-{cherokee-worker}(22433)
 196           |                 |                        `-{cherokee-worker}(22434)
 197           |                 `-{cherokee}(22422)
 198           |-conserver(3471)---conserver(3477)
 199         ....
 200
 201
 202 As you can see, Upstart thinks the main process of 'cherokee' is '22419',
 203 and indeed this is the only 'cherokee' child of init. So this state is correct.
 204
 205 Common problem that may appear in pstree output:
 206
 207   1. The main process pid differs from what Upstart thinks. That usually
 208      happens when bad 'expect fork' or 'expect daemon' is used. May cause
 209      Upstart lock-up when the PID reported by ``initctl status`` does not exist
 210      at all.
 211
 212   2. Init has multiple children processes for one job instance. It may happen
 213      when previously running job was not properly killed, when bad 'expect' was
 214      used or when the daemon does weird forking on startup.
 215
 216 See also http://upstart.ubuntu.com/wiki/Debugging
 217
 218 Updating init scripts
 219 ---------------------
 220
 221 Parts of the system will still expect ``service $name`` or even, directly,
 222 ``/etc/rc.d/init.d/$name`` scripts working. Also, LSB expects compatible
 223 init scripts in /etc/init.d. For this still to work, an upstart-controlled
 224 service is expected to have its ``/etc/rc.d/init.d/$name`` script also present.
 225 It must also be named exactly as the main upstart job for the service.
 226
 227 The script must be a bit modified (in comparison to the traditional init
 228 scripts) to make use of the upstart features.
 229
 230 For the start/stop/status/reload commands to work the script should include a
 231 ``upstart_controlled`` command placed before commands are handled (and after
 232 ``/etc/rc.d/init.d/function`` was included). This command (shell alias actually)
 233 will be ignored when upstart boot control is disabled or no upstart job is
 234 available for the service. Otherwise it will implement the basic LSB commands
 235 and exit.
 236
 237 Sometimes some commands must be implemented in a special way (not all services
 238 may understand SIGHUP as a signal to reload their configuration) or extra
 239 commands are provided (like 'configtest'). In such case ``upstart_controlled``
 240 should be given a list of commands to implement or, preferrably, ``--except``
 241 and the list of commands which stay implemented in the script. If the first
 242 argument of the script is one to be of the 'not upstart_controlled' commands,
 243 processing will continue past 'upstart_controlled' call and the commands may
 244 be handled by the init script.
 245
 246 When ``configtest`` is includes in the ``upstart_controlled --except`` list
 247 then ``$script configtest`` will be called before each restart/reload attempt,
 248 but only when done by ``/sbin/service`` or call to the script. Direct initctl
 249 calls are not affected.
 250
 251 The minimal init script, for a service which will be controlled by upstart
 252 only would be::
 253
 254   #!/bin/sh
 255
 256   . /etc/rc.d/init.d/functions
 257
 258   upstart_controlled
 259
 260   echo "Service available only via upstart boot"
 261   exit 3
 262
 263 Minimal change to an existing PLD script to handle upstart control is to add::
 264
 265   upstart_controlled
 266
 267 before the usual::
 268
 269   RETVAL=0
 270   # See how we were called.
 271   case "$1" in
 272     start)
 273
 274 Sometimes other upstart jobs will rely on a service started by the traditional
 275 init script. In such case, the script should emit appropriate events.
 276
 277 e.g.::
 278
 279         msg_starting "syslog-ng"
 280         emit starting JOB=syslog-ng SERVICE=syslog
 281         daemon /usr/sbin/syslog-ng -f /etc/syslog-ng/syslog-ng.conf $OPTIONS
 282         emit started JOB=syslog-ng SERVICE=syslog
 283         RETVAL=$?
 284
 285 The ``emit`` function does nothing when upstart-controlled boot is disabled (not
 286 to trigger any upstart jobs), otherwise it calls ``/sbin/initctl emit``
 287
 288 ..
 289  vi: tw=78 ft=rst spl=en