Home Man
Today's Posts

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for initctl (linux section 8)

initctl(8)									       initctl(8)

       initctl - init daemon control tool

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

       initctl allows a system administrator to communicate and interact with the Upstart init(8)

       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 com-
       mand-specific options intermixed.  The default installation supplies such  links  for  the
       start, stop, restart, reload and status commands.

	      Connect to init(8) daemon using the D-Bus session bus (for testing purposes only).

	      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 per-
	      mits  the root user to communicate over this socket which means that read-only com-
	      mands 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 con-
	      nected 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.

	      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.

	      Reduces output of all commands to errors only.

       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.

       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

	      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

	      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

	      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


	      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

	      No  particular order is used for the output, and there is no difference in the out-
	      put (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

	      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 run-
	      level(7) event.  This is normally emitted by the telinit(8) and shutdown(8) tools.


	      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.


	      Requests and outputs the version of the running init daemon.


	      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.

	      [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 run-
	      ning job.

	      For each event emitted, a separate line is displayed beginning with two space char-
	      acters 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:

		emits boing
		emits blip
		start on (starting A and (B or C var=2))
		stop on (bar HELLO=world testing=123 or stopping wibble)


	      -e, --enumerate

		     If specified, rather than listing the precise start on and  stop  on  condi-
		     tions, 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 verba-
		     tim, 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 envi-
		     ronment 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):

		       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:)

	      [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 con-
	      sidering 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 configu-
	      ration 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. Sub-
	      sequent 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 unsatis-
	      fiable 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

	      Assuming job configuration file /etc/init/foo.conf contains the following:

		start on starting grape
		stop on peach

	      The check-config command might display:

		  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  expres-
	      sions  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:

		  start on: unknown job B
		  start on: unknown job C
		  start on: unknown event D


	      -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 automati-
		     cally ignored.

	      -w, --warn
		     If specified, treat any unknown jobs and events as errors.

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

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

       Copyright (C) 2009-2011 Canonical Ltd.
       This  is  free software; see the source for copying conditions.	There is NO warranty; not

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

Upstart 				    2011-06-02				       initctl(8)

All times are GMT -4. The time now is 10:15 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
Show Password

Not a Forum Member?
Forgot Password?