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 the /etc/init directory, and watches for future changes using ino‐
14 tify(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 stop.
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 an additional four processes that may be run as part of the job's
117 lifecycle. These are specified as the process name, followed by an
118 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 process, 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.
152 It's quite permissable to have no main process, but to have pre-start
153 and post-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 Job environment
216 Each job is run with the environment from the events or commands that
217 started it. In addition, you may define defaults in the job which may
218 be overridden later and specify which environment variables are
219 exported into the events generated for the job.
220 The special UPSTART_EVENTS environment variable contains the list of
222 events that started the job, it will not be present if the job was
223 started manually.
224 In addition, the pre-stop and post-stop scripts are run with the envi‐
226 ronment of the events or commands that stopped the job. THe
227 UPSTART_STOP_EVENTS environment variable contains the list of events
228 that stopped the job, it will not be present if the job was stopped
229 manually.
230 All jobs also contain the UPSTART_JOB and UPSTART_INSTANCE environment
232 variables, containing the name of the job and instance. These are
233 mostly used by the initctl(8) utility to default to acting on the job
234 the commands are called from.
235 env KEY=VALUE
238 Defines a default environment variable, the value of which may
239 be overriden by the event or command that starts the job.
240 export KEY
242 Exports the value of an environment variable into the start‐
243 ing(7), started(7), stopping(7) and stopped(7) events for this
244 job.
245 Services, tasks and respawning
247 Jobs are services by default. This means that the act of starting the
248 job is considered to be finished when the job is running, and that even
249 exiting with a zero exit status means the service will be respawned.
250 task This stanza may be used to specify that the job is a task
253 instead. This means that the act of starting the job is not
254 considered to be finished until the job itself has been run and
255 stopped again, but that existing with a zero exit status means
256 the task has completed successfully and will not be respawned.
257 The start(8) command, and any starting(7) or stopping(7) events will
260 block only until a service is running or until a task has finished.
261 respawn
264 A service or task with this stanza will be automatically started
265 if it should stop abnormally. All reasons for a service stop‐
266 ping, except the stop(8) command itself, are considered abnor‐
267 mal. Tasks may exit with a zero exit status to prevent being
268 respawned.
269 respawn limit COUNT INTERVAL
271 Respawning is subject to a limit, if the job is respawned more
272 than COUNT times in INTERVAL seconds, it will be considered to
273 be having deeper problems and will be stopped. Default COUNT is
274 10. Default INTERVAL is 5 seconds.
275 This only applies to automatic respawns and not the restart(8)
277 command.
278 normal exit STATUS|SIGNAL...
280 Additional exit statuses or even signals may be added, if the
281 job process terminates with any of these it will not be consid‐
282 ered to have failed and will not be respawned.
283 normal exit 0 1 TERM HUP
285 Instances
287 By default, only one instance of any job is permitted to exist at one
288 time. Attempting to start a job when it's already starting or running
289 results in an error. Note that a job is considered to be running if its
290 pre-start process is running.
291 Multiple instances may be permitted by defining the names of those
293 instances. If an instance with the same name is not already starting
294 or running, a new instance will be started instead of returning an
295 error.
296 instance NAME
299 This stanza defines the names of instances, on its own its not
300 particularly useful since it would just define the name of the
301 single permitted instance, however NAME expands any variable
302 defined in the job's environment.
303 These will often be variables that you need to pass to the
305 process anyway, so are an excellent way to limit the instances.
306 instance $CONFFILE
308 exec /sbin/httpd -c $CONFFILE
309 instance $TTY
311 exec /sbin/getty -8 38300 $TTY
312 These jobs appear in the initctl(8) output with the instance
314 name in parentheses, and have the INSTANCE environment variable
315 set in their events.
316 Documentation
318 Upstart provides several stanzas useful for documentation and external
319 tools.
320 description DESCRIPTION
323 This stanza may contain a description of the job.
324 description "This does neat stuff"
326 author AUTHOR
328 This stanza may contain the author of the job, often used as a
329 contact for bug reports.
330 author "Scott James Remnant <scott@netsplit.com>"
332 version VERSION
334 This stanza may contain version information about the job, such
335 as revision control or package version number. It is not used
336 or interpreted by init(8) in any way.
337 version "$Id$"
339 emits EVENT...
341 All processes on the system are free to emit their own events by
342 using the initctl(8) tool, or by communicating directly with the
343 init(8) daemon.
344 This stanza allows a job to document in its job configuration
346 what events it emits itself, and may be useful for graphing pos‐
347 sible transitions.
348 usage USAGE
350 This stanza may contain the text used by initctl(8) usage com‐
351 mand. This text may be also shown when commands start(8),
352 stop(8) or status(8) fail.
353 usage "tty DEV=ttyX - where X is console id"
355 Process environment
357 Many common adjustments to the process environment, such as resource
358 limits, may be configured directly in the job rather than having to
359 handle them yourself.
360 console output|owner
363 By default the standard input, output and error file descriptors
364 of jobs are connected to /dev/null
365 If this stanza is specified, they are connected to /dev/console
367 instead.
368 console owner is special, it not only connects the job to the
370 system console but sets the job to be the owner of the system
371 console, which means it will receive certain signals from the
372 kernel when special key combinations such as Control-C are
373 pressed.
374 umask UMASK
376 A common configuration is to set the file mode creation mask for
377 the process. UMASK should be an octal value for the mask, see
378 umask(2) for more details.
379 nice NICE
381 Another common configuration is to adjust the process's nice
382 value, see nice(1) for more details.
383 oom ADJUSTMENT|never
385 Normally the OOM killer regards all processes equally, this
386 stanza advises the kernel to treat this job differently.
387 ADJUSTMENT may be an integer value from -16 (very unlikely to be
389 killed by the OOM killer) up to 14 (very likely to be killed by
390 the OOM killer). It may also be the special value never to have
391 the job ignored by the OOM killer entirely.
392 chroot DIR
394 Runs the job's processes in a chroot(8) environment underneath
395 DIR
396 Note that DIR must have all the necessary system libraries for
398 the process to be run, often including /bin/sh
399 chdir DIR
401 Runs the job's processes with a working directory of DIR instead
402 of the root of the filesystem.
403 limit LIMIT SOFT|unlimited HARD|unlimited
405 Sets initial system resource limits for the job's processes.
406 LIMIT may be one of core, cpu, data, fsize, memlock, msgqueue,
407 nice, nofile, nproc, rss, rtprio, sigpending or stack.
408 Limits are specified as both a SOFT value and a HARD value, both
410 of which are integers. The special value unlimited may be spec‐
411 ified for either.
412 Override File Handling
414 Override files allow a jobs environment to be changed without modifying
415 the jobs configuration file. Rules governing override files:
416 · If a job is embodied with only a configuration file, the contents of
419 this file define the job.
420 · If an override files exists where there is no existing cofiguration
422 file, the override file is ignored.
423 · If both a configuration file and an override file exist for a job and
425 both files are syntactically correct:
426 · stanzas in the override file will take precedence over stanzas
428 present in the corresponding configuration file.
429 · stanzas in the override file which are not present in the corre‐
431 sponding configuration file will be honoured when the job runs.
432 · If both a configuration file and an override file exist for a job and
434 subsequently the override file is deleted, the configuration file is
435 automatically reloaded with the effect that any changes introduced by
436 the override file are undone and the configuration file alone now
437 defines the job.
438 · If both a configuration file and an override file exist for a job and
440 subsequently the configuration file is deleted, a new instance of the
441 job can no longer be started (since without a corresponding configu‐
442 ration file an override file is ignored).
443 · If both a configuration file and an override file exist for a job and
445 any of the contents of the override file are invalid, the override
446 file is ignored and only the contents of the configuration file are
447 considered.
448 Miscellaneous
450 kill timeout INTERVAL
451 Specifies the interval between sending the job's main process
452 the SIGTERM and SIGKILL signals when stopping the running job.
453 Default is 5 seconds.
454 expect stop
456 Specifies that the job's main process will raise the SIGSTOP
457 signal to indicate that it is ready. init(8) will wait for this
458 signal before running the job's post-start script, or consider‐
459 ing the job to be running.
460 init(8) will send the process the SIGCONT signal to allow it to
462 continue.
463 expect daemon
465 Specifies that the job's main process is a daemon, and will fork
466 twice after being run. init(8) will follow this daemonisation,
467 and will wait for this to occur before running the job's post-
468 start script or considering the job to be running.
469 Without this stanza init(8) is unable to supervise daemon pro‐
471 cesses and will believe them to have stopped as soon as they
472 daemonise on startup.
473 expect fork
475 Specifies that the job's main process will fork once after being
476 run. init(8) will follow this fork, and will wait for this to
477 occur before running the job's post-start script or considering
478 the job to be running.
479 Without this stanza init(8) is unable to supervise forking pro‐
481 cesses and will believe them to have stopped as soon as they
482 fork on startup.
483
485 The and and or operators allowed with start on and stop on do not work
486 intuitively: operands to the right of either operator are only evalu‐
487 ated once and state information is then discarded. This can lead to
488 jobs with complex start on or stop on conditions not behaving as
489 expected when restarted. For example, if a job encodes the following
490 condition:
491 start on A and (B or C)
493 When 'A' and 'B' become true, the condition is satisfied so the job
495 will be run. However, if the job ends and subsequently 'A' and 'C'
496 become true, the job will not be re-run even though the condtion is
497 satisfied. Avoid using complex conditions with jobs which need to be
498 restarted.
499
501 Manual page written by Scott James Remnant <scott@netsplit.com> and
502 James Hunt <james.hunt@canonical.com>.
503
505 Report bugs at <https://launchpad.net/upstart/+bugs>
506
508 Copyright © 2010 Canonical Ltd.
509 This is free software; see the source for copying conditions. There is
510 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
511 PURPOSE.
512
515 init(8) sh(1)
516Upstart 2011-01-12 init(5)