start
init daemon control tool
see also :
init - telinit - shutdown
Synopsis
initctl
[OPTION]... COMMAND [OPTION]...
ARG...
add an example, a script, a trick and tips
examples
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
--user
User mode. In this mode, initctl
will talk to the init(8) daemon using the D-Bus
private socket defined in the UPSTART_SESSION environment
variable.
--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
start
JOB [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.
When called from the pre-stop stanza of a job
configuration, start may be called without argument to
cancel the stop.
stop
JOB [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.
When called from the pre-start stanza of a job
configuration, stop may be called without an argument to
cancel the start.
restart
JOB [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.
reload
JOB [KEY=VALUE]...
Sends the SIGHUP signal to running process of the named
JOB instance.
See start for a discussion on instances.
status
JOB [KEY=VALUE]...
Requests the status an instance of the named JOB,
outputting to standard output.
See start for a discussion 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.
emit
EVENT [KEY=VALUE]...
Requests that the named EVENT be emitted, potentially
causing jobs to be started and stopped depending on their use of
the start on and stop on 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
outputs 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 start on and stop on 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 start on and stop on 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 start on and
stop on 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.
list-env
[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 only includes the
minimal set of standard system variables added by the
init(8) daemon along with any variables set using
set-env. See init(5) for further details.
OPTIONS
-g, --global
Operate on the global job environment table. This option is
implied when not run from within a job.
get-env
[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.
OPTIONS
-g, --global
Operate on the global job environment table. This option is
implied when not run from within a job.
set-env
[OPTIONS] VARIABLE[=VALUE]
Adds or updates a variable in a job environment table. Variables
set in this way will apply to all subsequently-starting jobs.
This command is only permitted When running in User Session
Mode. See init(5) for further details.
OPTIONS
-r, --retain
If the specified variable is already set, do not modify it.
-g, --global
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.
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 pre-start and the main
process). See init(5) for further details.
unset-env
[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 User Session
Mode. See init(5) for further details.
OPTIONS
-r, --retain
If the specified variable is already set, do not modify it.
-g, --global
Operate on the global job environment table and all existing
running jobenvironment tables. This option is implied when not
run from within a job.
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 pre-start and the main
process). See init(5) for further details.
reset-env
[ 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 User Session
Mode. See 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.
OPTIONS
-r, --retain
If the specified variable is already set, do not modify it.
-g, --global
Operate on the global job environment table. This option is
implied when not run from within a job.
Note that unlike set-env and unset-env, this option
does not modify running job environment tables.
list-sessions
List the pid of the Session Init process followed by the value of
UPSTART_SESSION in use for that session separted by a
space character. Session files relating to non-longer running
Session Init processes are considered 'stale' and are not listed
(although when run using --verbose, the full path of the
stale session file is displayed).
usage
JOB [KEY=VALUE]...
Show usage information for the named JOB. If the job
specified does not define the usage stanza, a blank usage
will be displayed.
Example output for a job that specifies the usage stanza
is shown below. See init(5) for further details of the
usage stanza:
Usage: tty DEV=ttyX - where X is console id
copyright
Copyright © 2009-2011 Canonical Ltd.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE.
reporting bugs
Report bugs at <https://launchpad.net/upstart/+bugs>
see also
init
init telinit shutdown
author
Written by
Scott James Remnant <scott[:at:]netsplit[:dot:]com> and
James Hunt
<james.hunt[:at:]canonical[:dot:]com>.