NAME

initctl - init daemon control tool

SYNOPSIS

initctl [OPTION]... COMMAND [OPTION]... ARG...

DESCRIPTION

initctl allows a system administrator to communicate and interact with the Upstart 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 init(5) for further details.
When run as initctl, the first non-option argument is the COMMAND. Global options may be
specified before or after the command.
You may also create symbolic or hard links to 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
start, stop, restart, reload and status commands.

OPTIONS

--session
Connect to init(8) daemon using the D-Bus session bus (for testing purposes only).
--system
Communication with the 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, init(8) only
permits the root user to communicate over this socket which means that read-only
commands such as status and list cannot be made by other users.
The --system option instructs 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 init(8) is
connected to it. The advantage is that the default security configuration allows
non-root users to use read-only commands.
--dest Specifies the well-known name of the init(8) daemon when using --system.
There is normally no need to use this option since the init(8) daemon uses the
default com.ubuntu.Upstart name. However it may be useful for debugging.
--no-wait
Applies to the start, stop, restart and emit commands.
Normally initctl will wait for the command to finish before returning.
For the 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 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.
--quiet
Reduces output of all commands to errors only.

COMMANDS

startJOB [KEY=VALUE]...
Requests that a new instance of the named JOB be started, outputting the status of
the job to standard output when the command completes.
See status for a description of the output format.
The optional 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 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 JOB is to be acted upon.
If the job is already running, start will return an error.
stopJOB [KEY=VALUE]...
Requests that an instance of the named JOB be stopped, outputting the status of the
job to standard output when the command completes.
See status for a description of the output format and start for a discussion on
instances.
restartJOB [KEY=VALUE]...
Requests that an instance of the named 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, stop the job and then start
it again instead.
See status for a description of the output format and start for a discussion on
instances.
Note that this command can only be used when there is an instance of JOB, if there
is none then it returns an error instead of starting a new one.
reloadJOB [KEY=VALUE]...
Sends the SIGHUP signal to running process of the named JOB instance.
See start for a discussion on instances.
statusJOB [KEY=VALUE]...
Requests the status an instance of the named JOB, outputting to standard output.
See start for a discusson on instances.
For a single-instance job a line like the following is output:
job start/running, process 1234
The job name is given first followed by the current goal and state of the selected
instance. The goal is either start or stop, the status may be one of waiting,
starting, pre-start, spawned, post-start, 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 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.
job start/pre-start, process 902
The post-start and pre-stop states may have multiple processes attached, the extra
processes will follow on consecutive lines indented by a tab:
job start/post-start, process 1234
post-start process 1357
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:
job start/post-start, (post-start) process 1357
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:
job (tty1) start/post-start, process 1234
post-start process 1357
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 status for a description of the output format and 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.
emitEVENT [KEY=VALUE]...
Requests that the named EVENT be emitted, potentially causing jobs to be started
and stopped depending on their use of the starton and stopon stanzas in their
configuration.
The optional 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 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
runlevel(7) event. This is normally emitted by the telinit(8) and shutdown(8)
tools.
reload-configuration
Requests that the init(8) daemon reloads its configuration.
This command is generally not necessary since init(8) watches its configuration
directories with inotify(7) and automatically reloads in cases of changes.
No jobs will be started by this command.
version
Requests and outputs the version of the running init daemon.
log-priority
[PRIORITY]
When called with a PRIORITY argument, it requests that the 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.
PRIORITY may be one of debug, info, message, warn, error or fatal.
When called without argument, it requests the current minimum message priority that
the init(8) daemon will log and ouputs to standard output.
show-config
[OPTIONS] [CONF]
Display emits, start on and stop on job configuration details (in that order) for
specified job configuration, CONF. If CONF 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, 'emits event' where 'event' denotes a single emitted event.
The starton and stopon conditions are listed on separate lines beginning with two
space characters and followed by 'start on' and 'stop on' 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 starton and stopon conditions will be fully bracketed, regardless
of whether they appear like this in the job configuration file. This is useful to
see how the init(8) daemon perceives the condition.
Example output:
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)
OPTIONS-e, --enumerate
If specified, rather than listing the precise starton and stopon
conditions, outputs the emits lines along with one line for each event or
job the CONF in question may 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 job 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
init(8) daemon has parsed the job configuration file.
Example output (an analog of the default output format above):
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:)
check-config
[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 /etc/init/foo.conf contains the following:
start on starting grape
stop on peach
The check-config command might display:
foo
start on: unknown job grape
stop on: unknown event peach
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 /etc/init/bar.conf contains the following:
start on (A and (started B or (starting C or D)))
And only event A can be satisfied, the output will be:
bar
start on: unknown job B
start on: unknown job C
start on: unknown event D
OPTIONS-i[EVENTS], --ignore-events[EVENTS]
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 startup(7) and starting(7)) are
automatically ignored.
-w, --warn
If specified, treat any unknown jobs and events as errors.
notify-disk-writeable
Notify the init(8) daemon that the disk is now writeable. This currently causes the
init(8) daemon to flush its internal cache of 'early job' output data. An early
job is any job which 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.
usageJOB [KEY=VALUE]...
Show usage information an instance of the named JOB defined with usage stanza.
For job with usage stanza a line like the following is output, see init(5) :
Usage: tty DEV=ttyX - where X is console id