]>
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 | |
3a1d9de8 ER |
53 | starting shutdown |
54 | started shutdown | |
8b027762 JK |
55 | when rc.shutdown starts |
56 | ||
57 | pld.network-starting | |
30a91466 | 58 | starting network |
8b027762 JK |
59 | just before network initialization is started |
60 | ||
61 | pld.network-started | |
30a91466 | 62 | started network |
8b027762 JK |
63 | when network is initialized |
64 | ||
65 | pld.network-stopping | |
30a91466 | 66 | stopping network |
8b027762 JK |
67 | just before network shutdown is started |
68 | ||
69 | pld.network-stopped | |
30a91466 | 70 | stopped network |
8b027762 JK |
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 | |
29eedaa7 JK |
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:: | |
8b027762 | 83 | |
29eedaa7 JK |
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'. | |
8b027762 JK |
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 | ||
3b2adafb | 100 | Job description files in ``/etc/init`` are not only the recipes to start |
8b027762 | 101 | a service, but also configuration files for that service. Keep that in mind |
3b2adafb | 102 | when writing the ``*.conf`` files. No complicated logic, that can change from |
8b027762 JK |
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 | |
3b2adafb | 105 | settings (like resource limit) reimplemented in the script or started daemon |
8b027762 JK |
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 | |
3b2adafb | 119 | |
8b027762 JK |
120 | env SERVICE=syslog |
121 | export SERVICE | |
3b2adafb | 122 | |
8b027762 | 123 | respawn |
3b2adafb | 124 | |
8b027762 | 125 | console output |
3b2adafb | 126 | |
8b027762 JK |
127 | exec /usr/sbin/syslog-ng -F -f /etc/syslog-ng/syslog-ng.conf |
128 | ||
29eedaa7 JK |
129 | Checking upstart configuration |
130 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
131 | ||
132 | Since Upstart 1.3 one can check current configuration with:: | |
133 | ||
134 | initctl check-config | |
135 | ||
3b2adafb | 136 | Also, with an 'initctl2dot' tool the configuration may be visualised in |
29eedaa7 JK |
137 | a graphical diagram. |
138 | ||
2aa2fcb1 JK |
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 | |
3b2adafb ER |
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 | |
2aa2fcb1 JK |
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. | |
8b027762 | 170 | |
821d0f6e JK |
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 | ||
30a91466 ER |
216 | See also http://upstart.ubuntu.com/wiki/Debugging |
217 | ||
8b027762 JK |
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 | |
3b2adafb | 224 | service is expected to have its ``/etc/rc.d/init.d/$name`` script also present. |
8b027762 JK |
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 | |
3b2adafb | 232 | ``/etc/rc.d/init.d/function`` was included). This command (shell alias actually) |
8b027762 JK |
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 | |
a2653f82 JK |
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. | |
8b027762 JK |
250 | |
251 | The minimal init script, for a service which will be controlled by upstart | |
252 | only would be:: | |
253 | ||
254 | #!/bin/sh | |
3b2adafb | 255 | |
8b027762 | 256 | . /etc/rc.d/init.d/functions |
3b2adafb | 257 | |
8b027762 | 258 | upstart_controlled |
3b2adafb | 259 | |
8b027762 JK |
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:: | |
3b2adafb | 264 | |
8b027762 JK |
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" | |
98e096f3 | 280 | emit starting JOB=syslog-ng SERVICE=syslog |
8b027762 | 281 | daemon /usr/sbin/syslog-ng -f /etc/syslog-ng/syslog-ng.conf $OPTIONS |
98e096f3 | 282 | emit started JOB=syslog-ng SERVICE=syslog |
8b027762 JK |
283 | RETVAL=$? |
284 | ||
285 | The ``emit`` function does nothing when upstart-controlled boot is disabled (not | |
8c5418f1 | 286 | to trigger any upstart jobs), otherwise it calls ``/sbin/initctl emit`` |
8b027762 | 287 | |
8c5418f1 | 288 | .. |
2aa2fcb1 | 289 | vi: tw=78 ft=rst spl=en |