initctl man page on ElementaryOS

Man page or keyword search:  
man Server   4994 pages
apropos Keyword Search (all sections)
Output format
ElementaryOS logo
[printable version]

initctl(8)							    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 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
       --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 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 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	chang‐
	      ing  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 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 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 configura‐
	      tions.

	      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  con‐
	      dition.

	      If a job configuration has no emits, start on, or stop on condi‐
	      tions, 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 follow‐
		     ing 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 configura‐
	      tions. 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 cor‐
	      rectly.

	      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 com‐
	      mand may give what appears to be misleading output when an error
	      condition is found since all expressions in the  failing	condi‐
	      tion  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-sep‐
		     arated  events to ignore when checking the job configura‐
		     tion files.

		     This option may be useful to ignore errors if a  particu‐
		     lar job configuration file does not advertise it emits an
		     event.

		     Note that internal events (such as startup(7) and	start‐
		     ing(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  fin‐
	      ishes  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 inter‐
	      nal 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 vari‐
	      ables 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 a variable in a job environment table. Variables
	      set in this way will apply to all the subsequently-starting pro‐
	      cesses for a job.

	      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  dis‐
	      played.

	      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
       init(5) init(8) telinit(8) shutdown(8)

Upstart				  2012-12-20			    initctl(8)
[top]

List of man pages available for ElementaryOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net