table of contents
other sections
init(5) | File Formats Manual | init(5) |
NAME¶
init - Upstart init daemon job configurationSYNOPSIS¶
- /etc/init/
- Default location of system job configuration files.
- $HOME/.init/
- Default location of user job configuration files.
DESCRIPTION¶
On startup, the Upstart init(8) daemon reads its job configuration from files in the /etc/init/ directory, and watches for future changes to these files using inotify(7).- •
- Files ending in .conf are called configuration files, or simply "conf files" for short. These are the primary vehicle for specifying a job.
- •
- Files ending in .override are called override files. If an override file is present, the stanzas it contains take precedence over those equivalently named stanzas in the corresponding configuration file contents for a particular job. The main use for override files is to modify how a job will run without having to modify its configuration file directly. See the section Override File Handling below for further details.
- •
- A single configuration file.
- •
- A single configuration file and a single override file.
User Jobs¶
A User Job is a job configuration file created by a non-privileged user in their $HOME/.init/ directory. Job configuration files in this directory have the same syntax as system job configuration files. Files in this directory will be read and an inotify(7) watch created the first time a user runs initctl(8).Chroot Support¶
Upstart is able to manage jobs within a chroot(2). To control jobs within the chroot environment, use the standard initctl(8) facility. Note that it is not necessary to install D-Bus within the chroot (in fact it is not recommended).Configuration File Format¶
Each line begins with a configuration stanza and continues until either the end of the line or a line containing a closing stanza. Line breaks within a stanza are permitted within single or double quotes, or if preceded by a blackslash.Process definition¶
The primary use of jobs is to define services or tasks to be run by the init(8) daemon. Each job may have one or more different processes run as part of its lifecycle, with the most common known as the main process.- exec COMMAND [ ARG ]...
- This stanza defines the process to be run as the name of an
executable on the filesystem, and zero or more arguments to be passed to
it. Any special characters, e.g. quotes or `$' specified will result in
the entire command being passed to a shell for expansion.
exec /usr/sbin/acpid -c $EVENTSDIR -s $SOCKET
- script ... end script
- This stanza defines the process to be run as a shell script
that will be executed using sh(1). The -e shell option is
always used, so any command that fails will terminate the script.
script dd bs=1 if=/proc/kmsg of=$KMSGSINK exec /sbin/klogd -P $KMSGSINK end script
- pre-start exec|script...
- This process will be run after the job's starting(7) event has finished, but before the main process is run. It is typically used to prepare the environment, such as making necessary directories, and it may also call the stop(8) command without arguments to cancel the start.
- post-start exec|script...
- This process will be run before the job's started(7) event is emitted, but after the main process has been spawned. It is typically used to send necessary commands to the main process, or to delay the started(7) event until the main process is ready to receive clients.
- pre-stop exec|script...
- This process is run if the job is stopped by an event listed in its stop on stanza or by the stop(8) command. It will be run before the job's stopping(7) event is emitted and before the main process is killed. It is typically used to send any necessary shutdown commands to the main process, and it may also call the start(8) command without arguments to cancel the stop.
- post-stop exec|script...
- This process is run after the main process has been killed
and before the job's stopped(7) event is emitted. It is typically
used to clean up the environment, such as removing temporary directories.
pre-start exec ifup -a post-stop exec ifdown -a
Event definition¶
Jobs can be manually started and stopped at any time by a system administrator using the start(8) and stop(8) tools, however it is far more useful for jobs to be started and stopped automatically by the init(8) daemon when necessary.- start on EVENT [[KEY=]VALUE]... [and|or...]
- The start on stanza defines the set of events that
will cause the job to be automatically started. Each EVENT is given
by its name. Multiple events are permitted using the and &
or operators, and complex expressions may be performed with
parentheses (within which line breaks are permitted).
start on started gdm or started kdm start on device-added SUBSYSTEM=tty DEVPATH=ttyS* start on net-device-added INTERFACE!=lo
- stop on EVENT [[KEY=]VALUE]... [and| or...]
- The stop on stanza defines the set of events that
will cause the job to be automatically stopped. It has the same syntax as
start on.
stop on stopping gdm or stopping kdm stop on device-removed DEVPATH=$DEVPATH
- manual
- This stanza will disregard any previously seen
start on definition. By adding this stanza on any line below the
start on definition, it provides the ability to stop a job from
being automatically started. When specified, the only way to start such a
job is via start (8).
Job environment¶
Each job is run with the environment from the events or commands that started it. In addition, you may define defaults in the job which may be overridden later and specify which environment variables are exported into the events generated for the job.- env KEY[=VALUE]
- Defines a default environment variable, the value of which may be overridden by the event or command that starts the job. If ´KEY=VALUE´ is specified, the variable KEY is given the value VALUE. If only ´KEY´ is given, then the value is taken from the init(8) daemon's own environment.
- export KEY
- Exports the value of an environment variable into the starting(7), started(7), stopping(7) and stopped(7) events for this job and to all resultant events (not just those relating to the current job).
Services, tasks and respawning¶
Jobs are services by default. This means that the act of starting the job is considered to be finished when the job is running, and that even exiting with a zero exit status means the service will be respawned.- task
- This stanza may be used to specify that the job is a
task instead. This means that the act of starting the job is not
considered to be finished until the job itself has been run and stopped
again, but that exiting with a zero exit status means the task has
completed successfully and will not be respawned.
- respawn
- A service or task with this stanza will be automatically started if it should stop abnormally. All reasons for a service stopping, except the stop(8) command itself, are considered abnormal. Tasks may exit with a zero exit status to prevent being respawned.
- respawn limit COUNT INTERVAL
- Respawning is subject to a limit, if the job is respawned
more than COUNT times in INTERVAL seconds, it will be
considered to be having deeper problems and will be stopped. Default COUNT
is 10. Default INTERVAL is 5 seconds.
- normal exit STATUS|SIGNAL...
- Additional exit statuses or even signals may be added, if
the job process terminates with any of these it will not be considered to
have failed and will not be respawned.
normal exit 0 1 TERM HUP
Instances¶
By default, only one instance of any job is permitted to exist at one time. Attempting to start a job when it's already starting or running results in an error. Note that a job is considered to be running if its pre-start process is running.- instance NAME
- This stanza defines the names of instances, on its own its
not particularly useful since it would just define the name of the single
permitted instance, however NAME expands any variable defined in
the job's environment.
instance $CONFFILE exec /sbin/httpd -c $CONFFILE
instance $TTY exec /sbin/getty -8 38300 $TTY
Documentation¶
Upstart provides several stanzas useful for documentation and external tools.- description DESCRIPTION
- This stanza may contain a description of the job.
description "This does neat stuff"
- author AUTHOR
- This stanza may contain the author of the job, often used
as a contact for bug reports.
author "Scott James Remnant <scott@netsplit.com>"
- version VERSION
- This stanza may contain version information about the job,
such as revision control or package version number. It is not used or
interpreted by init(8) in any way.
version "$Id$"
- emits EVENT...
- All processes on the system are free to emit their own
events by using the initctl(8) tool, or by communicating directly
with the init(8) daemon.
- usage USAGE
- This stanza may contain the text used by initctl(8)
usage command. This text may be also shown when commands
start(8), stop(8) or status(8) fail.
usage "tty DEV=ttyX - where X is console id"
Process environment¶
Many common adjustments to the process environment, such as resource limits, may be configured directly in the job rather than having to handle them yourself.- console none|log|output|owner
none
If none is specified, the jobs standard
input, standard output and standard error file descriptors are connected to
/dev/null. Any output generated by a job will be discarded. This used
to be the default prior to the introduction of log in Upstart
1.4.
log
Only applies to system jobs: if
specified by user jobs, the job will be considered to have specified the value
none.
For system jobs, if log is specified, standard input is connected to
/dev/null, and standard output and standard error are connected to a
pseudo-tty which logs all job output.
Output is logged to file /var/log/upstart/<job-log-file>. If a job
has specified instance, <job-log-file> will equate to
<job>-<instance>.log where '<instance>' is replaced
by the specific instance value and '<job>' is replaced with the job name
(job configuration file name, without the extension). If instance is
not specified, <job-log-file> will be <job>.log
where '<job>' is replaced with the job name.
Jobs started from within a chroot will have their output logged to such a path
within the chroot.
If log files already exist, they are appended to.
All slash ('/') characters in <job-log-file> are replaced with
underscore ('_') characters. For example, any output from the 'wibble'
instance of the 'foo/bar' job would be encoded in file 'foo_bar-wibble.log' in
the log file directory. This gives the log file directory a flat structure.
If the directory for system jobs does not exist, job output for each job will be
cached until the job finishes. Thus, the boot process must ensure that
the directory is available as soon as possible since any job that finishes
before a writeable disk is available will not be able to take advantage of
this facility.
If it is not possible to write to any log file due to lack of disk space, the
job will be considered to have specified a console value of none
and all subsequent job output will be discarded.
If the logger detects that the file it is about to write to was deleted, it will
re-open the file first.
Care should be taken if the log directory is a mount point since any job that
starts before that mount is available and which produces output will then
attempt to write logs to the mount point, not to the mounted directory. This
may give the impression that log data has not been recorded. A strategy to
handle this situation is to ensure the mount point directory is not writeable
such that logs will only be written when the mount has succeeded (assuming the
mount itself is writeable and has sufficient space).
Note that since log utilizes pseudo-ttys, your kernel must support these.
If it does not, the console value will be modified automatically to
none. Further, note that it may be necessary to increase the number of
available pty devices; see pty(7) for details.
Under Linux, full Unix 98 pty support requires that the devpts filesystem
be mounted.
If pty setup fails for any reason, an error message will be displayed and the
job's console value will be reset to none.
output
If output is specified, the standard
input, standard output and standard error file descriptors are connected to
/dev/console.
owner
The owner value is special: it not only
connects the job to the system console but sets the job to be the owner of the
system console, which means it will receive certain signals from the kernel
when special key combinations such as Control-C are pressed.
- umask UMASK
- A common configuration is to set the file mode creation mask for the process. UMASK should be an octal value for the mask, see umask(2) for more details.
- nice NICE
- Another common configuration is to adjust the process's nice value, see nice(1) for more details.
- oom score ADJUSTMENT|never
- Normally the OOM killer regards all processes equally, this
stanza advises the kernel to treat this job differently.
- chroot DIR
- Runs the job's processes in a chroot(8) environment
underneath DIR
- chdir DIR
- Runs the job's processes with a working directory of DIR instead of the root of the filesystem.
- limit LIMIT SOFT|unlimited HARD|unlimited
- Sets initial system resource limits for the job's
processes. LIMIT may be one of core, cpu,
data, fsize, memlock, msgqueue, nice,
nofile, nproc, rss, rtprio, sigpending
or stack.
- setuid USERNAME
- Changes to the user USERNAME before running any job
process.
- setgid GROUPNAME
- Changes to the group GROUPNAME before running any
job process.
Override File Handling¶
Override files allow a jobs environment to be changed without modifying the jobs configuration file. Rules governing override files:- •
- If a job is embodied with only a configuration file, the contents of this file define the job.
- •
- If an override files exists where there is no existing cofiguration file, the override file is ignored.
- •
- If both a configuration file and an override file exist for a job and both files are syntactically correct:
- •
- stanzas in the override file will take precedence over stanzas present in the corresponding configuration file.
- •
- stanzas in the override file which are not present in the corresponding configuration file will be honoured when the job runs.
- •
- If both a configuration file and an override file exist for a job and subsequently the override file is deleted, the configuration file is automatically reloaded with the effect that any changes introduced by the override file are undone and the configuration file alone now defines the job.
- •
- If both a configuration file and an override file exist for a job and subsequently the configuration file is deleted, a new instance of the job can no longer be started (since without a corresponding configuration file an override file is ignored).
- •
- If both a configuration file and an override file exist for a job and any of the contents of the override file are invalid, the override file is ignored and only the contents of the configuration file are considered.
Miscellaneous¶
- kill signal SIGNAL
- Specifies the stopping signal, SIGTERM by default, a
job's main process will receive when stopping the running job.
kill signal INT
- kill timeout INTERVAL
- Specifies the interval between sending the job's main process the "stopping" (see above) and SIGKILL signals when stopping the running job. Default is 5 seconds.
- expect stop
- Specifies that the job's main process will raise the
SIGSTOP signal to indicate that it is ready. init(8) will
wait for this signal before running the job's post-start script, or
considering the job to be running.
- expect daemon
- Specifies that the job's main process is a daemon, and will
fork twice after being run. init(8) will follow this daemonisation,
and will wait for this to occur before running the job's post-start script
or considering the job to be running.
- expect fork
- Specifies that the job's main process will fork once after
being run. init(8) will follow this fork, and will wait for this to
occur before running the job's post-start script or considering the job to
be running.
RESTRICTIONS¶
The use of symbolic links in job configuration file directories is not supported since it can lead to unpredicable behaviour resulting from broken or inaccessible links (such as would be caused by a link crossing a filesystem boundary to a filesystem that has not yet been mounted).BUGS¶
The and and or operators allowed with start on and stop on do not work intuitively: operands to the right of either operator are only evaluated once and state information is then discarded. This can lead to jobs with complex start on or stop on conditions not behaving as expected when restarted. For example, if a job encodes the following condition:start on A and (B or C)When 'A' and 'B' become true, the condition is satisfied so the job will be run. However, if the job ends and subsequently 'A' and 'C' become true, the job will not be re-run even though the condtion is satisfied. Avoid using complex conditions with jobs which need to be restarted.
FILES¶
- /etc/init/*.conf
- System job configuration files.
- /etc/init/*.override
- System job override files.
- $HOME/.init/*.conf
- User job configuration files. Note that you may make the directory $HOME/.init/ a symbolic link to $HOME/.config/upstart/.
- $HOME/.init/*.override
- User job override files.
- /var/log/upstart/*.log
- Default location of system job output logs.
AUTHOR¶
Manual page written by Scott James Remnant <scott@netsplit.com> and James Hunt <james.hunt@canonical.com>.REPORTING BUGS¶
Report bugs at <https://launchpad.net/upstart/+bugs>COPYRIGHT¶
Copyright © 2009-2011 Canonical Ltd.SEE ALSO¶
init(8) initctl(8) sh(1) upstart-events(7) pty(7)2011-05-12 | Upstart |