Provided by: upstart_1.8-0ubuntu1_i386 bug

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.

       --session
              Connect  to  init(8)  daemon  using  the  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,
              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.

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

              When called from the pre-start stanza of  a  job  configuration,
              stop may be called without an argument to cancel the start.

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

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

       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 only includes the
              minimal set of standard system variables added  by  the  init(8)
              daemon  along with 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 subsequently-starting jobs.

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