initctl(8)						      System Manager's Manual							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.

       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

       --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  com-
	      pletes.

	      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.

       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  com-
	      pletes.

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

       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 com-
	      pletes.

	      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 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.

	      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 dis-
	      cussion 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  stan-
	      dard output.

AUTHOR

       Written by Scott James Remnant <scott@netsplit.com>

REPORTING BUGS

       Report bugs at <https://launchpad.net/upstart/+bugs>

COPYRIGHT

       Copyright (C) 2010 Canonical Ltd.
       This is free software; see the source for copying conditions.  There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICU-
       LAR PURPOSE.

SEE ALSO

       init(8) telinit(8) shutdown(8)

Upstart 							    2010-02-04								initctl(8)