Provided by: upstart_1.5-0ubuntu5_amd64 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

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

       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.

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

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

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