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 com-
       mands.  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 secu-
	      rity, 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, out-
	      putting the status of the job to standard output when  the  com-
	      mand 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.

       stop   JOB [KEY=VALUE]...

	      Requests	that  an  instance  of	the named JOB be stopped, out-
	      putting the status of the job to standard output when  the  com-
	      mand completes.

	      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,  out-
	      putting  the  status of the job to standard output when the com-
	      mand completes.

	      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 dif-
	      ference 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 envi-
	      ronment 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 configura-
	      tion  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.


usage
JOB [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

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

SEE ALSO
       init(8) telinit(8) shutdown(8)



Upstart				  2010-02-04			    initctl(8)