.TH initctl 8 2011-06-02 "Upstart"
.\"
.SH NAME
initctl \- init daemon control tool
.\"
.SH SYNOPSIS
.B initctl
.RI [ OPTION ]...
.I COMMAND
.RI [ OPTION ]...
.IR ARG ...
.\"
.SH DESCRIPTION
.B initctl
allows a system administrator to communicate and interact with the Upstart
.BR init (8)
daemon.

If D\-Bus has been configured to allow non\-privileged users to invoke all
Upstart D\-Bus methods, this command is also able to manage user jobs.
See
.BR init (5)
for further details.

When run as
.BR initctl ,
the first non\-option argument is the
.IR COMMAND .
Global options may be specified before or after the command.

You may also create symbolic or hard links to
.B initctl
named after commands.  When invoked through these links the tool will
behave only as that command, with global and command\-specific options
intermixed.  The default installation supplies such links
for the
.BR start ", " stop ", " restart ", " reload " and " status
commands.
.\"
.SH OPTIONS
.TP
.B \-\-user
User mode. In this mode, initctl will talk to the
.BR init (8)
daemon using the D\-Bus private socket defined in the
.B UPSTART_SESSION
environment variable.

Note that if the
.B UPSTART_SESSION
variable is defined, this option is implied.
.\"
.TP
.B \-\-session
Connect to
.BR init (8)
daemon using the existing D\-Bus session bus (for testing purposes only).
.\"
.TP
.B \-\-system
Communication with the
.BR init (8)
daemon is normally performed over a private socket connection.  This has
the advantage of speed and robustness, when issuing commands to start or
stop services or even reboot the system you do not want to be affected by
changes to the D\-Bus system bus daemon.

The disadvantage to using the private socket however is security,
.BR init (8)
only permits the root user to communicate over this socket which means
that read\-only commands such as
.BR status " and " list
cannot be made by other users.

The
.B \-\-system
option instructs
.BR initctl
to communicate via the D\-Bus system bus rather than over the private
socket.

This is only possible if the system bus daemon is running and if
.BR init (8)
is connected to it.  The advantage is that the default security configuration
allows non\-root users to use read\-only commands.
.\"
.TP
.B \-\-dest
Specifies the well\-known name of the
.BR init (8)
daemon when using
.BR \-\-system .

There is normally no need to use this option since the
.BR init (8)
daemon uses the default
.B com.ubuntu.Upstart
name.  However it may be useful for debugging.
.\"
.TP
.B \-\-no\-wait
Applies to the
.BR start ", " stop ", " restart " and " emit
commands.

Normally
.B initctl
will wait for the command to finish before returning.

For the
.BR start ", " stop " and " restart
commands, finishing means that the named job is running (or has finished
for tasks) or has been fully stopped.

For the
.B emit
command, finishing means that all of the jobs affected by the event
are running (or have finished for tasks) or have been fully stopped.

This option instead causes these commands to only wait for the goal
change or event to be queued.
.\"
.TP
.B \-\-quiet
Reduces output of all commands to errors only.
.\"
.SH COMMANDS
.TP
.B start
.I JOB
.RI [ KEY=VALUE ]...

Requests that a new instance of the named
.I JOB
be started, outputting the status of the job to standard output when the
command completes.

See
.B status
for a description of the output format.

The optional
.I KEY=VALUE
arguments specify environment variables to be passed to the starting job,
and placed in its environment.  They also serve to specify which instance
of multi\-instance jobs should be started.

Most jobs only permit a single instance; those that use the
.B instance
stanza in their configuration define a string expanded from environment
variables to name the instance.  As many unique instances may be started
as unique names may be generated by the stanza.  Thus the environment
variables also serve to select which instance of
.I JOB
is to be acted upon.

If the job is already running,
.B start
will return an error.

When called from the
.IR pre\-stop
stanza of a job configuration,
.B start
may be called without argument to cancel the
.B stop.
.\"
.TP
.B stop
.I JOB
.RI [ KEY=VALUE ]...

Requests that an instance of the named
.I JOB
be stopped, outputting the status of the job to standard output when the
command completes.

See
.B status
for a description of the output format and
.B start
for a discussion on instances.

When called from the
.IR pre\-start
stanza of a job configuration,
.B stop
may be called without an argument to cancel the
.B start.
.\"
.TP
.B restart
.I JOB
.RI [ KEY=VALUE ]...

Requests that an instance of the named
.I JOB
be restarted, outputting the status of the job to standard output when
the command completes.

The job instance being restarted will retain its original configuration.
To have the new instance run with the latest job configuration,
.B stop
the job and then
.B start
it again instead.

See
.B status
for a description of the output format and
.B start
for a discussion on instances.

Note that this command can only be used when there is an instance of
.IR JOB ,
if there is none then it returns an error instead of starting a new one.
.\"
.TP
.B reload
.I JOB
.RI [ KEY=VALUE ]...

Sends the
.I SIGHUP
signal to running process of the named
.I JOB
instance.

See
.B start
for a discussion on instances.
.\"
.TP
.B status
.I JOB
.RI [ KEY=VALUE ]...

Requests the status an instance of the named
.IR JOB ,
outputting to standard output.

See
.B start
for a discussion on instances.

For a single\-instance job a line like the following is output:

.nf
  job start/running, process 1234
.fi

The job name is given first followed by the current goal and state of
the selected instance.  The goal is either
.IR start " or " stop ,
the status may be one of
.IR waiting ", " starting ", " pre\-start ", " spawned ", " post\-start ", "
.IR running ", " pre\-stop ", " stopping ", " killed " or " post\-stop .

If the job has an active process, the process id will follow on the same
line.  If the state is
.IR pre\-start " or " post\-stop
this will be the process id of the equivalent process, otherwise it will
be the process id of the main process.

.nf
  job start/pre\-start, process 902
.fi

The
.IR post\-start " and " pre\-stop
states may have multiple processes attached, the extra processes will follow
on consecutive lines indented by a tab:

.nf
  job start/post\-start, process 1234
          post\-start process 1357
.fi

If there is no main process, they may follow on the same line but will be
prefixed to indicate that it is not the main process id being given:

.nf
  job start/post\-start, (post\-start) process 1357
.fi

Jobs that permit multiple instances have names for each instance, the
output is otherwise identical to the above except that the instance
name follows the job name in parentheses:

.nf
  job (tty1) start/post\-start, process 1234
          post\-start process 1357
.fi
.\"
.TP
.B list

Requests a list of the known jobs and instances, outputs the status of
each to standard output.

Note that this command includes in the enumeration as\-yet\-to\-run jobs (in other words
configuration files for which no job instances have yet been created) in
the output with status "stop/waiting". In effect such entries denote
configuration files which represent potential future jobs.

See
.B status
for a description of the output format and
.B start
for a discussion on instances.

No particular order is used for the output, and there is no difference in
the output (other than the instance name appearing in parentheses) between
single\-instance and multiple\-instance jobs.
.\"
.TP
.B emit
.I EVENT
.RI [ KEY=VALUE ]...

Requests that the named
.I EVENT
be emitted, potentially causing jobs to be started and stopped depending
on their use of the
.BR "start on" " and " "stop on"
stanzas in their configuration.

The optional
.I KEY=VALUE
arguments specify environment variables to be included with the event and
thus exported into the environment of any jobs started and stopped by
the event.

The environment may also serve to specify which instance of multi\-instance
jobs should be started or stopped.  See
.B start
for a discussion on instances.

There is no limitation on the event names that may be emitted with this
command, you are free to invent new events and use them in your job
configurations.

The most well\-known event used by the default Upstart configuration is
the
.BR runlevel (7)
event.  This is normally emitted by the
.BR telinit (8)
and
.BR shutdown (8)
tools.
.\"
.TP
.B reload\-configuration

Requests that the
.BR init (8)
daemon reloads its configuration.

This command is generally not necessary since
.BR init (8)
watches its configuration directories with
.BR inotify (7)
and automatically reloads in cases of changes.

No jobs will be started by this command.
\"
.TP
.B version

Requests and outputs the version of the running init daemon.
.\"
.TP
.B log\-priority
.RI [ PRIORITY ]

When called with a
.I PRIORITY
argument, it requests that the
.BR init (8)
daemon log all messages with that priority or greater.  This may be used
to both increase and decrease the volume of logged messages.

.I PRIORITY
may be one of
.IR debug ", " info ", " message ", " warn ", " error " or " fatal .

When called without argument, it requests the current minimum message
priority that the
.BR init (8)
daemon will log and outputs to standard output.
.\"
.TP
.B show\-config
.RI [ OPTIONS "] [" CONF "]"

Display emits, start on and stop on job configuration details (in that
order) for specified job configuration, \fICONF\fP. If \fICONF\fP is not
specified, list information for all valid job configurations.

Note that a job configuration is the name of a job configuration file,
without the extension. Note too that this information is static: it
does not refer to any running job.

For each event emitted, a separate line is displayed beginning with two
space characters followed by, \(aqemits \fIevent\fP\(aq where
\(aq\fIevent\fP\(aq denotes a single emitted event.

The \fBstart on\fP and \fBstop on\fP conditions
are listed on separate lines beginning with two space characters and
followed by \(aqstart on\(aq and \(aqstop on\(aq respectively and ending
with the appropriate condition.

If a job configuration has no emits, start on, or stop on conditions,
the name of the job configuration will be displayed with no further
details.

Note that the \fBstart on\fP and \fBstop on\fP conditions will be fully
bracketed, regardless of whether they appear like this in the job
configuration file. This is useful to see how the
.BR init (8)
daemon perceives the condition.

Example output:

.nf
foo
  emits boing
  emits blip
  start on (starting A and (B or C var=2)) 
  stop on (bar HELLO=world testing=123 or stopping wibble)
.fi

.B OPTIONS
.RS
.IP "\fB\-e\fP, \fB\-\-enumerate\fP"

If specified, rather than listing the precise \fBstart on\fP and \fBstop
on\fP conditions, outputs the emits lines along with one line for each
event or job the \fICONF\fP in question \fImay\fP be started or stopped
by if it were to become a job. If the start on condition specifies a
non\-job event, this will be listed verbatim, whereas for a job event,
the name of the \fIjob\fP as opposed to the event the job emits will be
listed.

The type of entity, its triggering event (if appropriate) and its full
environment is displayed in brackets following its name for clarity.

This option is useful for tools which generate graphs of relationships
between jobs and events. It is also instructive since it shows how the
.BR init (8)
daemon has parsed the job configuration file.

Example output (an analog of the default output format above):

.nf
foo
  emits boing
  emits blip
  start on starting (job: A, env:)
  start on B (job:, env:)
  start on C (job:, env: var=2)
  stop on bar (job:, env: HELLO=world testing=123)
  stop on stopping (job: wibble, event: stopping, env:)
.fi
.RE
.\"
.TP
.B check\-config
.RI [ OPTIONS "] [" CONF "]"

Considers all job configurations looking for jobs that cannot be started
or stopped, given the currently available job configurations. This is
achieved by considering the start on, stop on and emits stanzas for each
job configuration and identifying unreachable scenarios.

This option is useful for determining the impact of adding or removing
job configuration files.

Note that to use this command, it is necessary to ensure that all job
configuration files advertise the events they emit correctly.

If errors are identified, the name of the job configuration will be
displayed. Subsequent lines will show the failed conditions for the job
configuration, one per line. Condition lines begin with two spaces and
are followed with either "start on: " or "stop on: ", the word
"unknown", the type of entity that is not known and finally its name.

Note that only job configurations that are logically in error (those
with unsatisfiable conditions) will be displayed. Note too that job
configurations that are syntactically invalid may trigger an error if
they would cause a condition to be in error.

Assuming job configuration file \fI/etc/init/foo.conf\fP contains the
following:

.nf
  start on starting grape
  stop on peach
.fi

The check\-config command might display:

.nf
  foo
    start on: unknown job grape
    stop on: unknown event peach
.fi

If any errors are detected, the exit code will be 1 (one). If all checks pass,
the exit code will be 0 (zero).

Note that for complex start on and stop on conditions, this command may
give what appears to be misleading output when an error condition is
found since all expressions in the failing condition that are in error
will generate error output. For example, if job configuration
\fI/etc/init/bar.conf\fP contains the following:

.nf
  start on (A and (started B or (starting C or D)))
.fi

And only event A can be satisfied, the output will be:

.nf
  bar
    start on: unknown job B
    start on: unknown job C
    start on: unknown event D
.fi

.B OPTIONS
.RS
.IP "\fB-i\fP \fI[EVENTS]\fP, \fB\-\-ignore\-events\fP \fI[EVENTS]\fP"

If specified, the argument should be a list of comma\-separated events to
ignore when checking the job configuration files.

This option may be useful to ignore errors if a particular job
configuration file does not advertise it emits an event.

Note that internal events (such as \fBstartup\fP(7) and
\fBstarting\fP(7)) are automatically ignored.
.IP "\fB-w\fP, \fB\-\-warn\fP"
If specified, treat \fIany\fP unknown jobs and events as errors.
.RE
.\"
.TP
.B notify\-disk\-writeable
Notify the
.BR init (8)
daemon that the disk is now writeable. This currently causes the
.BR init (8)
daemon to flush its internal cache of \(aqearly job\(aq output data.
An early job is any job which
.I finishes
before the log disk becomes writeable. If job logging is not disabled,
this command should be called once the log disk becomes writeable
to ensure that output from all early jobs is flushed. If the data is
written successfully to disk, the internal cache is deleted.
.RE
.\"
.TP
.B notify\-dbus\-address
Notify the
.BR init (8)
daemon of the D\-Bus address it should use to connect to.

This command is only permitted when running in
.B User Session Mode.
See 
.BR init (5)
for further details.
.\"
.TP
.B list\-env
.RI [ OPTIONS "]

Display a lexicographically sorted list of all variables and their
values in a job environment table.

When run from within a job, this command will automatically query the
job-specific environment table; otherwise the global environment table
that is applied to all jobs when they first start is queried.

Note that the global job environment table comprises those variables
already set in the
.BR init (8)
daemons environment at startup, the minimal set of standard system
variables added by the
.BR init (8)
daemon, and any variables set using
.BR set\-env "."
See
.BR init (5)
for further details.

.B OPTIONS
.RS
.IP "\fB\-g\fP, \fB\-\-global\fP"
Operate on the global job environment table. This option is implied when not
run from within a job.
.RE
.\"
.TP
.B get\-env
.RI [ OPTIONS "] " VARIABLE

Display the value of the specified variable in a job environment table.

When run from within a job, this command will automatically query the
job-specific environment table; otherwise the global environment table
that is applied to all jobs when they first start is queried.

.B OPTIONS
.RS
.IP "\fB\-g\fP, \fB\-\-global\fP"
Operate on the global job environment table. This option is implied when not
run from within a job.
.RE
.\"
.TP
.B set\-env
.RI [ OPTIONS "] " VARIABLE[=VALUE]

Adds or updates a variable in a job environment table. Variables set
in this way will apply to all the subsequently-starting processes for a
job.

This command is only permitted when running in
.B User Session Mode.
See 
.BR init (5)
for further details.

.B OPTIONS
.RS
.IP "\fB\-r\fP, \fB\-\-retain\fP"
If the specified variable is already set, do not modify it.
.RE
.RS
.IP "\fB\-g\fP, \fB\-\-global\fP"
Operate on the global job environment table and all existing running job
environment tables. This option is implied when not run from within a job.
.sp
This is an advanced option whose use is discouraged since it can change
the environment of a job as it moves between different process stages
(for example between
.B pre\-start
and the main process). See 
.BR init (5)
for further details.
.RE
.\"
.TP
.B unset\-env
.RI [ OPTIONS "] " VARIABLE

Remove the specified variable from a job environment table. If the
variable does not already exist in the table, no change will be made.

This command is only permitted when running in
.B User Session Mode.
See 
.BR init (5)
for further details.

.B OPTIONS
.RS
.IP "\fB\-r\fP, \fB\-\-retain\fP"
If the specified variable is already set, do not modify it.
.RE
.RS
.IP "\fB\-g\fP, \fB\-\-global\fP"
Operate on the global job environment table  and all existing running
jobenvironment tables. This option is implied when not run from within a job.
.sp
This is an advanced option whose use is discouraged since it can change
the environment of a job as it moves between different process stages
(for example between
.B pre\-start
and the main process). See 
.BR init (5)
for further details.
.RE
.\"
.TP
.B reset\-env
.RI [ OPTIONS ]

Discards all changes make to a job environment table, setting it back
to its default set of variables and values.

This command is only permitted when running in
.B User Session Mode.
See 
.BR init (5)
for further details.

Note that the effect of the Session Init process that manages the User
Session Mode restarting is equivalent to this command having been
called.

.B OPTIONS
.RS
.IP "\fB\-r\fP, \fB\-\-retain\fP"
If the specified variable is already set, do not modify it.
.RE
.RS
.IP "\fB\-g\fP, \fB\-\-global\fP"
Operate on the global job environment table. This option is implied when
not run from within a job.
.sp
Note that unlike \fBset\-env\fR and \fBunset\-env\fR, this option does
not modify running job environment tables.
.RE
.\"
.TP
.B list\-sessions

List the pid of the Session Init process followed by the value of
.B UPSTART_SESSION
in use for that session separted by a space character. Session files
relating to non-longer running Session Init processes are considered
\(aqstale\(aq and are not listed (although when run using
.BR \-\-verbose ","
the full path of the stale session file is displayed).
.\"
.TP
.B usage
.I JOB
.RI [ KEY=VALUE ]...

Show usage information for the named
.IR JOB "."
If the job specified does not define the
.BR usage
stanza, a blank usage will be displayed.

Example output for a job that specifies the
.BR usage
stanza is shown below. See
.BR init (5)
for further details of the
.B usage
stanza:

.nf
  Usage: tty DEV=ttyX - where X is console id
.fi
.\"
.SH AUTHOR
Written by Scott James Remnant
.RB < scott@netsplit.com >
and James Hunt
.RB < james.hunt@canonical.com > .
.\"
.SH REPORTING BUGS
Report bugs at
.RB < https://launchpad.net/upstart/+bugs >
.\"
.SH COPYRIGHT
Copyright \(co 2009\-2011 Canonical Ltd.
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.SH SEE ALSO
.BR init (5)
.BR init (8)
.BR telinit (8)
.BR shutdown (8)