start


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

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

Upstart                           2012-12-20                        initctl(8)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2018 Hurricane Electric. All Rights Reserved.