← Back to branch summary

~jamesodhunt/upstart/foo

« back to all changes in this revision

Viewing changes to init/man/init.5

Merge of lp:~jamesodhunt/upstart/upstream-override-support.

Show diffs side-by-side

added added

removed removed

Lines of Context:
init/man/init.5
4
4
init \- Upstart init daemon job configuration
5
5
.\"
6
6
.SH SYNOPSIS
7
 
.B /etc/init
 
7
.B /etc/init/
8
8
.\"
9
9
.SH DESCRIPTION
10
10
On startup, the Upstart
14
14
directory, and watches for future changes to these files using
15
15
.BR inotify (7).
16
16
 
17
 
Files in this directory must end in
 
17
To be considered by Upstart, files in this directory must have a
 
18
recognized suffix and may also be present in sub-directories.  There are
 
19
two recognized suffixes:
 
20
 
 
21
.IP \(bu 4 
 
22
Files ending in
18
23
.I .conf
19
 
and may also be present in sub-directories.
20
 
 
21
 
Each file defines a single service or task, with the name taken from its
22
 
relative path within the directory without the extension.  For example a
23
 
job defined in
 
24
are called configuration files, or simply "conf files" for short.
 
25
These are the primary vehicle for specifying a job.
 
26
.IP \(bu 4 
 
27
Files ending in
 
28
.I .override
 
29
are called override files.  If an override file is present, the stanzas
 
30
it contains take precedence over those equivalently named stanzas in the
 
31
corresponding configuration file contents for a particular job.
 
32
The main use for override files is to modify how a job will run without
 
33
having to modify its configuration file directly.  See the section
 
34
\fBOverride File Handling\fP below for further details.
 
35
.P
 
36
A job can thus be defined by either:
 
37
.IP \[bu] 2
 
38
A single configuration file.
 
39
.IP \[bu]
 
40
A single configuration file \fBand\fP a single override file.
 
41
.P
 
42
Unless explicitly stated otherwise, any reference to a jobs
 
43
configuration can refer both to a configuration file or an override
 
44
file.
 
45
 
 
46
Each configuration file defines the template for a single \fIservice\fP
 
47
(long-running process or daemon) or \fItask\fP (short-lived process).
 
48
 
 
49
Note that a configuration file is not itself a job: it is a description
 
50
of an environmenta job could be run in.  A job is the runtime embodiment
 
51
of a configuration file.
 
52
 
 
53
The configuration file name as displayed by Upstart and associated
 
54
tooling is taken from its relative path within the directory without the
 
55
extension.  For example a configuration file
24
56
.I /etc/init/rc-sysinit.conf
25
57
is named
26
58
.IR rc-sysinit ,
27
 
while a job defined in
 
59
while a configuration file
28
60
.I /etc/init/net/apache.conf
29
61
is named
30
62
.IR net/apache .
 
63
Since override files only modify the way a configuration file is
 
64
interpreted, they are not named.
31
65
 
32
 
These files are plain text and should not be executable.
 
66
Configuration files are plain text and should not be executable.
33
67
.\"
34
 
.SS Format
 
68
.SS Configuration File Format
35
69
Each line begins with a configuration stanza and continues until either
36
70
the end of the line or a line containing a closing stanza.  Line breaks
37
71
within a stanza are permitted within single or double quotes, or if
571
605
.B unlimited
572
606
may be specified for either.
573
607
.\"
 
608
.SS Override File Handling
 
609
Override files allow a jobs environment to be changed without modifying
 
610
the jobs configuration file. Rules governing override files:
 
611
 
 
612
.IP \[bu] 2
 
613
If a job is embodied with only a configuration file, the contents of
 
614
this file define the job.
 
615
.IP \[bu]
 
616
If an override files exists where there is no existing cofiguration
 
617
file, the override file is ignored.
 
618
.IP \[bu]
 
619
If both a configuration file \fBand\fP an override file exist for a job
 
620
and both files are syntactically correct:
 
621
.RS
 
622
.IP \[bu] 2
 
623
stanzas in the override file will take precedence over stanzas present
 
624
in the corresponding configuration file.
 
625
.IP \[bu]
 
626
stanzas in the override file which are not present in the corresponding
 
627
configuration file will be honoured when the job runs.
 
628
.RE
 
629
.IP \[bu]
 
630
If both a configuration file and an override file exist for a job and
 
631
subsequently the override file is deleted, the configuration file is
 
632
automatically reloaded with the effect that any changes introduced by
 
633
the override file are undone and the configuration file alone now defines
 
634
the job.
 
635
.IP \[bu]
 
636
If both a configuration file and an override file exist for a job and
 
637
subsequently the configuration file is deleted, a new instance of the
 
638
job can no longer be started (since without a corresponding
 
639
configuration file an override file is ignored).
 
640
.IP \[bu]
 
641
If both a configuration file and an override file exist for a job and
 
642
any of the contents of the override file are invalid, the override file
 
643
is ignored and only the contents of the configuration file are
 
644
considered.
 
645
.P
 
646
 
 
647
.\"
574
648
.SS Miscellaneous
575
649
.TP
576
650
.B kill signal \fISIGNAL
588
662
Specifies the interval between sending the job's main process the
589
663
"stopping" (see above) and
590
664
.I SIGKILL
591
 
signals when stopping the running job.
 
665
signals when stopping the running job. Default is 5 seconds.
592
666
.\"
593
667
.TP
594
668
.B expect stop