9
9
Default location of system job configuration files.
12
.B $XDG_CONFIG_HOME/upstart/, $XDG_CONFIG_DIRS/upstart/
13
Default locations of user session job configuration files.
13
Default location of user job configuration files.
17
Deprecated location of user job configuration files (still
18
honoured by User Session Mode).
16
21
On startup, the Upstart
20
25
directory, and watches for future changes to these files using
23
If D\-Bus has been configured to allow non\-privileged users to invoke all
24
Upstart D\-Bus methods, Upstart is also able to manage User Jobs. See
28
If Upstart was invoked as a user process with \-\-user option, it will
29
run in User Session mode. See
26
31
for further details.
28
33
To be considered by Upstart, files in this directory must have a
77
82
Configuration files are plain text and should not be executable.
81
A User Job is a job configuration file created by a non\-privileged user
84
directory. Job configuration files in this directory have the same
85
syntax as system job configuration files.
86
Files in this directory will be read and an
88
watch created the first time a user runs
91
Any user can create user jobs, but that user can control
95
Users are able to manage their jobs using the standard
99
Note that stanzas which manipulate resources limits may cause a job to
100
fail to start should the value provided to such a stanza attempt to
101
exceed the maximum value the users privilege level allows.
103
Note that a user job configuration file cannot have the same name as a
104
system job configuration file.
106
84
.SS Chroot Support
108
86
Upstart is able to manage jobs within a \fBchroot\fP(2). To control jobs
115
93
.B Process environment
118
Note too that User Jobs can be created within a chroot environment.
99
Upstart can manage complete User Sessions. In this mode it runs with a
100
process id greater than 1 and will read job configuration files from the
101
following list of directories in the order shown:
104
.I $XDG_CONFIG_HOME/upstart/
108
.I $XDG_CONFIG_DIRS/upstart/
110
.I /usr/share/upstart/sessions/
113
Note that the first directory to contain a job is considered the owner
114
of that job name: any subsequently searched directory that contains a
115
job of the same name will be ignored. The same applies for override
116
files: only the first override file found in the search order will be
117
applied. Note that an override file can be in the same directory or
118
earlier to that directory which contains the job file.
120
Jobs in these locations are expected to launch the user's session.
121
Upstart will try to parent all spawned process with the aid of
123
If successful this will ensure that even double-forking daemons will be
124
reparented to the User Session process, and not to the
126
daemon running with process id 1.
128
When running in User Session mode, Upstart will kill all job processes
129
on session logout or shutdown.
131
All log output will be in
132
.I $XDG_CACHE_HOME/upstart
134
.I $HOME/.cache/upstart
121
138
.SS Configuration File Format
366
383
is via \fBstart\fP (8).
368
385
.SS Job environment
369
Each job is run with the environment from the events or commands that
370
started it. In addition, you may define defaults in the job which may
371
be overridden later and specify which environment variables are exported
372
into the events generated for the job.
386
Each job is run with an environment constructed from the
387
following categories:
390
A minimal set of standard system variables added by Upstart.
399
Variables set using the
401
job environment commands (such as \fIset-env\fP).
403
These commands also allow unsetting of variables.
406
A set of special variables added by Upstart that relate to the job itself.
408
All jobs also contain the
412
environment variables, containing the name of the job and instance. These
413
are mostly used by the
415
utility to default to acting on the job the commands are called from.
418
Those variables introduced by the events or command that started the
375
422
.B UPSTART_EVENTS
376
423
environment variable contains the list of events that started the job,
377
424
it will not be present if the job was started manually.
385
432
.B UPSTART_STOP_EVENTS
386
433
environment variable contains the list of events that stopped the job,
387
434
it will not be present if the job was stopped manually.
389
All jobs also contain the
437
Variables set within the job itself using the
393
environment variables, containing the name of the job and instance. These
394
are mostly used by the
396
utility to default to acting on the job the commands are called from.
441
stanzas. These provide default values - if the command or event which causes the
442
job to start specifies alternative values, those are given priority over
399
447
.B env \fIKEY\fR[=\fIVALUE\fR]
400
448
Defines a default environment variable, the value of which may be overridden
417
465
and to all resultant events
419
467
(not just those relating to the current job).
470
The first two categories above comprise the
471
.I job environment table
472
which is applied to all jobs. Note that changing the job environment
473
table will only affect newly-started jobs.
421
475
.SS Services, tasks and respawning
614
Only applies to system jobs:
615
if specified by user jobs, the job will be considered to have specified
619
For system jobs, if \fBlog\fR is specified, standard input is connected
668
If \fBlog\fR is specified, standard input is connected
621
670
.IR /dev/null ","
622
671
and standard output and standard error are connected to a pseudo-tty
623
672
which logs all job output.
625
674
Output is logged to file
626
.IR /var/log/upstart/<job-log-file> "."
675
.IR /var/log/upstart/<job-log-file>
677
.IR $XDG_CACHE_HOME/upstart/<job-log-file>
678
for system and user session jobs respectively.
627
680
If a job has specified \fBinstance\fR,
628
681
.I <job-log-file>
821
874
block is used for all job processes. If both stanzas are unspecified,
822
875
all job processes will run with its group ID set to 0 in the case of
823
876
system jobs, and as the primary group of the user in the case of User
826
879
.SS Override File Handling
827
880
Override files allow a jobs environment to be changed without modifying
967
1020
.I $HOME/.init/*.conf
968
User job configuration files.
969
Note that you may make the directory
972
.BR $HOME/.config/upstart/ "."
1021
User job configuration files
975
1025
.I $HOME/.init/*.override
976
1026
User job override files.
1030
.I $XDG_CONFIG_HOME/upstart/*.conf
1031
User session job configuration files. See
1032
.B User Session Mode
1033
for other locations.
1036
.I $XDG_CONFIG_HOME/upstart/*.override
1037
User session job override files. See
1038
.B User Session Mode
1039
for other locations.
979
1042
.I /var/log/upstart/*.log
980
1043
Default location of system job output logs.
1046
.I $XDG_CACHE_HOME/upstart/*.log
1047
Default location of user session job output logs.
1049
.I $XDG_RUNTIME_DIR/upstart/sessions/*.session
1050
Location of session files created when running in User Session mode.
991
1061
.RB < https://launchpad.net/upstart/+bugs >
994
Copyright \(co 2009-2011 Canonical Ltd.
1064
Copyright \(co 2009-2013 Canonical Ltd.
996
1066
This is free software; see the source for copying conditions. There is NO
997
1067
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.