initctl(8)
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
--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. Note that if the UPSTART_SESSION variable is defined, this option is implied. --session Connect to init(8) daemon using the existing 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 by
changing its goal to start. The status of the job is displayed
on 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 by
changing its goal to stop. The status of the job is displayed
on 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.
By default SIGTERM is sent to the job process. If it does not
respond within a reasonable period, it will be forcibly stopped
by sending SIGKILL.
This behaviour can be changed using the kill signal and kill
timeout stanzas. See init(5) for further details.
restart
JOB [KEY=VALUE]...
Requests that an instance of the named JOB be restarted by first
changing its goal to stop, and then changing its goal to start.
The status of the job is displayed on standard output when the
command completes.
This command is similar to running stop followed by start with
one exception: 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.
Table 1 in the Job States section of init(8) summarises job goal
and state transitions.
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-cgroup-manager-address
ADDRESS Specify the D-Bus address on which the cgroup manager
can be contacted. This command should only be run when the
cgroup manager has started to accept connections.
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.
notify-dbus-address
Notify the init(8) daemon of the D-Bus address it should use to
connect to.
This command is only permitted when running in User Session
Mode. See init(5) for further details.
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 comprises those
variables already set in the init(8) daemons environment at
startup, the minimal set of standard system variables added by
the init(8) daemon, and 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 one or more variables 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 User Session
Mode. See init(5) for further details.
OPTIONS
-r, --retain
If any of the specified variables are already set, do not
modify them.
-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 variables from a job environment table. If
any of the variables specified do not already exist in the
table, those variables will be ignored.
This command is only permitted when running in User Session
Mode. See init(5) for further details.
OPTIONS
-r, --retain
If any of the specified variables are already set, do not
unset them.
-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
AUTHOR
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-2013 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.
SEE ALSO
cgmanager(8) init(5) init(8) telinit(8) shutdown(8)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
