1init(5) File Formats Manual init(5)
2
6 init - Upstart init daemon job configuration
7
9 /etc/init/
10
12 On startup, the Upstart init(8) daemon reads its job configuration from
13 files in the /etc/init/ directory, and watches for future changes to
14 these files using inotify(7).
15 To be considered by Upstart, files in this directory must have a recog‐
17 nized suffix and may also be present in sub-directories. There are two
18 recognized suffixes:
19 · Files ending in .conf are called configuration files, or simply
22 "conf files" for short. These are the primary vehicle for specify‐
23 ing a job.
24 · Files ending in .override are called override files. If an over‐
26 ride file is present, the stanzas it contains take precedence over
27 those equivalently named stanzas in the corresponding configuration
28 file contents for a particular job. The main use for override
29 files is to modify how a job will run without having to modify its
30 configuration file directly. See the section Override File Han‐
31 dling below for further details.
32 A job can thus be defined by either:
34 · A single configuration file.
36 · A single configuration file and a single override file.
38 Unless explicitly stated otherwise, any reference to a jobs configura‐
40 tion can refer both to a configuration file or an override file.
41 Each configuration file defines the template for a single service
43 (long-running process or daemon) or task (short-lived process).
44 Note that a configuration file is not itself a job: it is a description
46 of an environmenta job could be run in. A job is the runtime embodi‐
47 ment of a configuration file.
48 The configuration file name as displayed by Upstart and associated
50 tooling is taken from its relative path within the directory without
51 the extension. For example a configuration file /etc/init/rc-
52 sysinit.conf is named rc-sysinit, while a configuration file
53 /etc/init/net/apache.conf is named net/apache. Since override files
54 only modify the way a configuration file is interpreted, they are not
55 named.
56 Configuration files are plain text and should not be executable.
58 Configuration File Format
60 Each line begins with a configuration stanza and continues until either
61 the end of the line or a line containing a closing stanza. Line breaks
62 within a stanza are permitted within single or double quotes, or if
63 preceeded by a blackslash.
64 If a stanza is duplicated, the last occurence will be used. Unrecog‐
66 nized stanzas will generate parse errors, which will stop a job from
67 running.
68 Stanzas and their arguments are delimited by whitespace, which consists
70 of one or more space or tab characters which are otherwise ignored
71 unless placed within single or double quotes.
72 Comments begin with a `#' and continue until the end of the line.
74 Blank lines and lines consisting only of whitespace or comments are
75 ignored.
76 Process definition
78 The primary use of jobs is to define services or tasks to be run by the
79 init(8) daemon. Each job may have one or more different processes run
80 as part of its lifecycle, with the most common known as the main
81 process.
82 The main process is defined using either the exec or script stanzas,
84 only one of which is permitted. These specify the executable or shell
85 script that will be run when the job is considered to be running. Once
86 this process terminates, the job stops.
87 All processes are run with the full job environment available as envi‐
89 ronment variables in their process.
90 exec COMMAND [ ARG ]...
93 This stanza defines the process to be run as the name of an exe‐
94 cutable on the filesystem, and zero or more arguments to be
95 passed to it. Any special characters, e.g. quotes or `$' speci‐
96 fied will result in the entire command being passed to a shell
97 for expansion.
98 exec /usr/sbin/acpid -c $EVENTSDIR -s $SOCKET
100 script ... end script
102 This stanza defines the process to be run as a shell script that
103 will be executed using sh(1). The -e shell option is always
104 used, so any command that fails will terminate the script.
105 The script stanza appears on its own on a line, the script is
107 everything up until the first end script stanza appearing on its
108 own on a line.
109 script
111 dd bs=1 if=/proc/kmsg of=$KMSGSINK
112 exec /sbin/klogd -P $KMSGSINK
113 end script
114 There are an additional four processes that may be run as part of the
117 job's lifecycle. These are specified as the process name, followed by
118 an exec or script stanza.
119 pre-start exec|script...
122 This process will be run after the job's starting(7) event has
123 finished, but before the main process is run. It is typically
124 used to prepare the environment, such as making necessary direc‐
125 tories.
126 post-start exec|script...
128 This process will be run before the job's started(7) event is
129 emitted, but after the main process has been spawned. It is
130 typically used to send necessary commands to the main process,
131 or to delay the started(7) event until the main process is ready
132 to receive clients.
133 pre-stop exec|script...
135 This process is run if the job is stopped by an event listed in
136 its stop on stanza or by the stop(8) command. It will be run
137 before the job's stopping(7) event is emitted and before the
138 main process is killed. It is typically used to send any neces‐
139 sary shutdown commands to the main process, and it may also call
140 the start(8) command without arguments to cancel the stop.
141 post-stop exec|script...
143 This process is run after the main process has been killed and
144 before the job's stopped(7) event is emitted. It is typically
145 used to clean up the environment, such as removing temporary
146 directories.
147 All of these processes, including the main process, are optional. Ser‐
150 vices without a main process will appear to be running until they are
151 stopped: this is commonly used to define states such as runlevels. It
152 is permissable to have no main process, but to have pre-start and post-
153 stop processes for the state.
154 pre-start exec ifup -a
156 post-stop exec ifdown -a
157 Event definition
159 Jobs can be manually started and stopped at any time by a system admin‐
160 strator using the start(8) and stop(8) tools, however it is far more
161 useful for jobs to be started and stopped automatically by the init(8)
162 daemon when necessary.
163 This is done by specifying which events should cause your job to be
165 started, and which cause your process to be stopped again.
166 The set of possible events is limitless, however there are a number of
168 standard events defined by the init(8) daemon and telinit(8) tools that
169 you will want to use.
170 When first started, the init(8) daemon will emit the startup(7) event.
172 This will activate jobs that implement System V compatibility and the
173 runlevel(7) event. As jobs are started and stopped, the init(8) daemon
174 will emit the starting(7), started(7), stopping(7) and stopped(7)
175 events on their behalf.
176 start on EVENT [[KEY=]VALUE]... [and|or...]
179 The start on stanza defines the set of events that will cause
180 the job to be automatically started. Each EVENT is given by its
181 name. Multiple events are permitted using the and & or opera‐
182 tors, and complex expressions may be performed with parentheses
183 (within which line breaks are permitted).
184 You may also match on the environment variables contained within
186 the event by specifying the KEY and expected VALUE. If you know
187 the order in which the variables are given to the event you may
188 omit the KEY.
189 VALUE may contain wildcard matches and globs as permitted by
191 fnmatch(3) and may expand the value of any variable defined with
192 the env stanza.
193 Negation is permitted by using != between the KEY and VALUE.
195 start on started gdm or started kdm
197 start on device-added SUBSYSTEM=tty DEVPATH=ttyS*
199 start on net-device-added INTERFACE!=lo
201 stop on EVENT [[KEY=]VALUE]... [and|or...]
203 The stop on stanza defines the set of events that will cause the
204 job to be automatically stopped. It has the same syntax as
205 start on.
206 VALUE may additionally expand the value of any variable that
208 came from the job's start environment (either the event or the
209 command that started it).
210 stop on stopping gdm or stopping kdm
212 stop on device-removed DEVPATH=$DEVPATH
214 manual This stanza will disregard any previously seen start on defini‐
217 tion. By adding this stanza on any line below the start on def‐
218 inition, it provides the ability to stop a job from being auto‐
219 matically started. When specified, the only way to start such a
220 job is via start (8).
221 Job environment
224 Each job is run with the environment from the events or commands that
225 started it. In addition, you may define defaults in the job which may
226 be overridden later and specify which environment variables are
227 exported into the events generated for the job.
228 The special UPSTART_EVENTS environment variable contains the list of
230 events that started the job, it will not be present if the job was
231 started manually.
232 In addition, the pre-stop and post-stop scripts are run with the envi‐
234 ronment of the events or commands that stopped the job. THe
235 UPSTART_STOP_EVENTS environment variable contains the list of events
236 that stopped the job, it will not be present if the job was stopped
237 manually.
238 All jobs also contain the UPSTART_JOB and UPSTART_INSTANCE environment
240 variables, containing the name of the job and instance. These are
241 mostly used by the initctl(8) utility to default to acting on the job
242 the commands are called from.
243 env KEY[=VALUE]
246 Defines a default environment variable, the value of which may
247 be overriden by the event or command that starts the job. If
248 ´KEY=VALUE´ is specified, the variable KEY is given the value
249 VALUE. If only ´KEY´ is given, then the value is taken from the
250 init(8) daemon's own environment.
251 export KEY
253 Exports the value of an environment variable into the start‐
254 ing(7), started(7), stopping(7) and stopped(7) events for this
255 job and to all resultant events (not just those relating to the
256 current job).
257 Services, tasks and respawning
259 Jobs are services by default. This means that the act of starting the
260 job is considered to be finished when the job is running, and that even
261 exiting with a zero exit status means the service will be respawned.
262 task This stanza may be used to specify that the job is a task
265 instead. This means that the act of starting the job is not
266 considered to be finished until the job itself has been run and
267 stopped again, but that exiting with a zero exit status means
268 the task has completed successfully and will not be respawned.
269 The start(8) command, and any starting(7) or stopping(7) events will
272 block only until a service is running or until a task has finished.
273 respawn
276 A service or task with this stanza will be automatically started
277 if it should stop abnormally. All reasons for a service stop‐
278 ping, except the stop(8) command itself, are considered abnor‐
279 mal. Tasks may exit with a zero exit status to prevent being
280 respawned.
281 respawn limit COUNT INTERVAL
283 Respawning is subject to a limit, if the job is respawned more
284 than COUNT times in INTERVAL seconds, it will be considered to
285 be having deeper problems and will be stopped. Default COUNT is
286 10. Default INTERVAL is 5 seconds.
287 This only applies to automatic respawns and not the restart(8)
289 command.
290 normal exit STATUS|SIGNAL...
292 Additional exit statuses or even signals may be added, if the
293 job process terminates with any of these it will not be consid‐
294 ered to have failed and will not be respawned.
295 normal exit 0 1 TERM HUP
297 Instances
299 By default, only one instance of any job is permitted to exist at one
300 time. Attempting to start a job when it's already starting or running
301 results in an error. Note that a job is considered to be running if its
302 pre-start process is running.
303 Multiple instances may be permitted by defining the names of those
305 instances. If an instance with the same name is not already starting
306 or running, a new instance will be started instead of returning an
307 error.
308 instance NAME
311 This stanza defines the names of instances, on its own its not
312 particularly useful since it would just define the name of the
313 single permitted instance, however NAME expands any variable
314 defined in the job's environment.
315 These will often be variables that you need to pass to the
317 process anyway, so are an excellent way to limit the instances.
318 instance $CONFFILE
320 exec /sbin/httpd -c $CONFFILE
321 instance $TTY
323 exec /sbin/getty -8 38300 $TTY
324 These jobs appear in the initctl(8) output with the instance
326 name in parentheses, and have the INSTANCE environment variable
327 set in their events.
328 Documentation
330 Upstart provides several stanzas useful for documentation and external
331 tools.
332 description DESCRIPTION
335 This stanza may contain a description of the job.
336 description "This does neat stuff"
338 author AUTHOR
340 This stanza may contain the author of the job, often used as a
341 contact for bug reports.
342 author "Scott James Remnant <scott@netsplit.com>"
344 version VERSION
346 This stanza may contain version information about the job, such
347 as revision control or package version number. It is not used
348 or interpreted by init(8) in any way.
349 version "$Id$"
351 emits EVENT...
353 All processes on the system are free to emit their own events by
354 using the initctl(8) tool, or by communicating directly with the
355 init(8) daemon.
356 This stanza allows a job to document in its job configuration
358 what events it emits itself, and may be useful for graphing pos‐
359 sible transitions.
360 Process environment
362 Many common adjustments to the process environment, such as resource
363 limits, may be configured directly in the job rather than having to
364 handle them yourself.
365 console output|owner
368 By default the standard input, output and error file descriptors
369 of jobs are connected to /dev/null
370 If this stanza is specified, they are connected to /dev/console
372 instead.
373 console owner is special, it not only connects the job to the
375 system console but sets the job to be the owner of the system
376 console, which means it will receive certain signals from the
377 kernel when special key combinations such as Control-C are
378 pressed.
379 umask UMASK
381 A common configuration is to set the file mode creation mask for
382 the process. UMASK should be an octal value for the mask, see
383 umask(2) for more details.
384 nice NICE
386 Another common configuration is to adjust the process's nice
387 value, see nice(1) for more details.
388 oom ADJUSTMENT|never
390 Normally the OOM killer regards all processes equally, this
391 stanza advises the kernel to treat this job differently.
392 ADJUSTMENT may be an integer value from -16 (very unlikely to be
394 killed by the OOM killer) up to 14 (very likely to be killed by
395 the OOM killer). It may also be the special value never to have
396 the job ignored by the OOM killer entirely.
397 chroot DIR
399 Runs the job's processes in a chroot(8) environment underneath
400 DIR
401 Note that DIR must have all the necessary system libraries for
403 the process to be run, often including /bin/sh
404 chdir DIR
406 Runs the job's processes with a working directory of DIR instead
407 of the root of the filesystem.
408 limit LIMIT SOFT|unlimited HARD|unlimited
410 Sets initial system resource limits for the job's processes.
411 LIMIT may be one of core, cpu, data, fsize, memlock, msgqueue,
412 nice, nofile, nproc, rss, rtprio, sigpending or stack.
413 Limits are specified as both a SOFT value and a HARD value, both
415 of which are integers. The special value unlimited may be spec‐
416 ified for either.
417 Override File Handling
419 Override files allow a jobs environment to be changed without modifying
420 the jobs configuration file. Rules governing override files:
421 · If a job is embodied with only a configuration file, the contents of
424 this file define the job.
425 · If an override files exists where there is no existing cofiguration
427 file, the override file is ignored.
428 · If both a configuration file and an override file exist for a job and
430 both files are syntactically correct:
431 · stanzas in the override file will take precedence over stanzas
433 present in the corresponding configuration file.
434 · stanzas in the override file which are not present in the corre‐
436 sponding configuration file will be honoured when the job runs.
437 · If both a configuration file and an override file exist for a job and
439 subsequently the override file is deleted, the configuration file is
440 automatically reloaded with the effect that any changes introduced by
441 the override file are undone and the configuration file alone now
442 defines the job.
443 · If both a configuration file and an override file exist for a job and
445 subsequently the configuration file is deleted, a new instance of the
446 job can no longer be started (since without a corresponding configu‐
447 ration file an override file is ignored).
448 · If both a configuration file and an override file exist for a job and
450 any of the contents of the override file are invalid, the override
451 file is ignored and only the contents of the configuration file are
452 considered.
453 Miscellaneous
455 kill timeout INTERVAL
456 Specifies the interval between sending the job's main process
457 the SIGTERM and SIGKILL signals when stopping the running job.
458 Default is 5 seconds.
459 expect stop
461 Specifies that the job's main process will raise the SIGSTOP
462 signal to indicate that it is ready. init(8) will wait for this
463 signal before running the job's post-start script, or consider‐
464 ing the job to be running.
465 init(8) will send the process the SIGCONT signal to allow it to
467 continue.
468 expect daemon
470 Specifies that the job's main process is a daemon, and will fork
471 twice after being run. init(8) will follow this daemonisation,
472 and will wait for this to occur before running the job's post-
473 start script or considering the job to be running.
474 Without this stanza init(8) is unable to supervise daemon pro‐
476 cesses and will believe them to have stopped as soon as they
477 daemonise on startup.
478 expect fork
480 Specifies that the job's main process will fork once after being
481 run. init(8) will follow this fork, and will wait for this to
482 occur before running the job's post-start script or considering
483 the job to be running.
484 Without this stanza init(8) is unable to supervise forking pro‐
486 cesses and will believe them to have stopped as soon as they
487 fork on startup.
488
490 The and and or operators allowed with start on and stop on do not work
491 intuitively: operands to the right of either operator are only evalu‐
492 ated once and state information is then discarded. This can lead to
493 jobs with complex start on or stop on conditions not behaving as
494 expected when restarted. For example, if a job encodes the following
495 condition:
496 start on A and (B or C)
498 When 'A' and 'B' become true, the condition is satisfied so the job
500 will be run. However, if the job ends and subsequently 'A' and 'C'
501 become true, the job will not be re-run even though the condtion is
502 satisfied. Avoid using complex conditions with jobs which need to be
503 restarted.
504
506 Manual page written by Scott James Remnant <scott@netsplit.com> and
507 James Hunt <james.hunt@canonical.com>.
508
510 Report bugs at <https://launchpad.net/upstart/+bugs>
511
513 Copyright © 2010 Canonical Ltd.
514 This is free software; see the source for copying conditions. There is
515 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
516 PURPOSE.
517
520 init(8) sh(1)
521Upstart 2011-01-12 init(5)