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