Man Linux: Main Page and Category List

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.

       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

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

              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.

              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.

AUTHOR

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

REPORTING BUGS

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

COPYRIGHT

       Copyright (C) 2010 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)