init


SYNOPSIS
       /etc/init/
              Default location of system job configuration files.

       $XDG_CONFIG_HOME/upstart/, $XDG_CONFIG_DIRS/upstart/
              Default locations of user session job configuration files.

       $HOME/.init/
              Deprecated  location of user job configuration files (still hon-
              oured by User Session Mode).

DESCRIPTION
       On startup, the Upstart init(8) daemon reads its job configuration from
       files  in  the  /etc/init/ directory, and watches for future changes to
       these files using inotify(7).

       If Upstart was invoked as a user process with --user  option,  it  will
       run in User Session mode. See User Session Mode for further details.

       To be considered by Upstart, files in this directory must have a recog-
       nized suffix and may also be present in sub-directories.  There are two
       recognized suffixes:


       o   Files  ending  in  .conf  are called configuration files, or simply
           "conf files" for short.  These are the primary vehicle for specify-
           ing a job.

       o   Files  ending  in .override are called override files.  If an over-
           ride file is present, the stanzas it contains take precedence  over
           those equivalently named stanzas in the corresponding configuration
           file contents for a particular job.   The  main  use  for  override
           files  is to modify how a job will run without having to modify its
           configuration file directly.  See the section  Override  File  Han-
           dling below for further details.

       A job can thus be defined by either:

       o A single configuration file.

       o A single configuration file and a single override file.

       Unless  explicitly stated otherwise, any reference to a jobs configura-
       tion can refer both to a configuration file or an override file.

       Each configuration file defines  the  template  for  a  single  service
       (long-running process or daemon) or task (short-lived process).

       Note that a configuration file is not itself a job: it is a description
       of an environment a job could be run in.  A job is the runtime  embodi-
       ment of a configuration file.

       The  configuration  file  name  as  displayed by Upstart and associated
       Note  that  it  is not necessary to install D-Bus within the chroot (in
       fact it is not recommended).

       Note that this facility is distinct from the chroot stanza (see Process
       environment below).


   User Session Mode
       Upstart  can manage complete User Sessions. In this mode it runs with a
       process id greater than 1 and will read job  configuration  files  from
       the following list of directories in the order shown:


       o   $XDG_CONFIG_HOME/upstart/

       o   $HOME/.init/

       o   $XDG_CONFIG_DIRS/upstart/

       o   /usr/share/upstart/sessions/

       Note  that the first directory to contain a job is considered the owner
       of that job name: any subsequently searched directory that  contains  a
       job  of  the  same  name will be ignored. The same applies for override
       files: only the first override file found in the search order  will  be
       applied.  Note  that  an  override file can be in the same directory or
       earlier to that directory which contains the job file.

       Jobs in these locations are expected  to  launch  the  user's  session.
       Upstart  will  try  to  parent  all  spawned  process  with  the aid of
       prctl(2).  If successful this will ensure that even double-forking dae-
       mons  will  be  reparented  to the User Session process, and not to the
       init(8) daemon running with process id 1.

       When running in User Session mode, Upstart will kill all job  processes
       on session logout or shutdown.

       All  log  output  will  be in $XDG_CACHE_HOME/upstart which defaults to
       $HOME/.cache/upstart


   Configuration File Format
       Each line begins with a configuration stanza and continues until either
       the end of the line or a line containing a closing stanza.  Line breaks
       within a stanza are permitted within single or  double  quotes,  or  if
       preceded by a blackslash.

       If  a  stanza  is duplicated, the last occurence will be used. Unrecog-
       nized stanzas will generate parse errors, which will stop  a  job  from
       running.

       Stanzas and their arguments are delimited by whitespace, which consists
       of one or more space or tab  characters  which  are  otherwise  ignored
       unless placed within single or double quotes.
       only  one of which is permitted.  These specify the executable or shell
       script that will be run when the job is considered to be running.  Once
       this process terminates, the job stops.

       All  processes are run with the full job environment available as envi-
       ronment variables in their process.


       exec COMMAND [ ARG ]...
              This stanza defines the process to be run as the name of an exe-
              cutable  on  the  filesystem,  and  zero or more arguments to be
              passed to it.  Any special characters, e.g. quotes or `$' speci-
              fied  will  result in the entire command being passed to a shell
              for expansion.

              exec /usr/sbin/acpid -c $EVENTSDIR -s $SOCKET

       script ... end script
              This stanza defines the process to be run as a shell script that
              will  be  executed  using  sh(1).  The -e shell option is always
              used, so any command that fails will terminate the script.

              The script stanza appears on its own on a line,  the  script  is
              everything up until the first end script stanza appearing on its
              own on a line.

              script
                  dd bs=1 if=/proc/kmsg of=$KMSGSINK
                  exec /sbin/klogd -P $KMSGSINK
              end script


       There are an additional four processes that may be run as part  of  the
       job's  lifecycle.  These are specified as the process name, followed by
       an exec or script stanza.


       pre-start exec|script...
              This process will be run after the job's starting(7)  event  has
              finished,  but  before the main process is run.  It is typically
              used to prepare the environment, such as making necessary direc-
              tories,  and  it may also call the stop(8) command without argu-
              ments to cancel the start.

       post-start exec|script...
              This process will be run before the job's  started(7)  event  is
              emitted,  but  after  the  main process has been spawned.  It is
              typically used to send necessary commands to the  main  process,
              or to delay the started(7) event until the main process is ready
              to receive clients.

       pre-stop exec|script...
              This process is run if the job is stopped by an event listed  in
              its  stop  on  stanza or by the stop(8) command.  It will be run

       All of these processes, including the main process, are optional.  Ser-
       vices  without  a main process will appear to be running until they are
       stopped: this is commonly used to define states such as runlevels.   It
       is  permissible  to  have  no  main  process, but to have pre-start and
       post-stop processes for the state.

              pre-start exec ifup -a
              post-stop exec ifdown -a

   Event definition
       Jobs can be manually started and stopped at any time by a system admin-
       istrator  using  the start(8) and stop(8) tools, however it is far more
       useful for jobs to be started and stopped automatically by the  init(8)
       daemon when necessary.

       This  is  done  by  specifying which events should cause your job to be
       started, and which cause your process to be stopped again.

       The set of possible events is limitless, however there are a number  of
       standard events defined by the init(8) daemon and telinit(8) tools that
       you will want to use.

       When first started, the init(8) daemon will emit the startup(7)  event.
       This  will  activate jobs that implement System V compatibility and the
       runlevel(7) event.  As jobs are started and stopped, the init(8) daemon
       will  emit  the  starting(7),  started(7),  stopping(7)  and stopped(7)
       events on their behalf.


       start on EVENT [[KEY=]VALUE]... [and|or...]
              The start on stanza defines the set of events  that  will  cause
              the job to be automatically started.  Each EVENT is given by its
              name.  Multiple events are permitted using the and & or  logical
              operators,  and complex expressions may be performed with paren-
              theses (within which line breaks are permitted).

              You may also match on the environment variables contained within
              the event by specifying the KEY and expected VALUE.  If you know
              the order in which the variables are given to the event you  may
              omit the KEY.

              VALUE  may  contain  wildcard  matches and globs as permitted by
              fnmatch(3) and may expand the value of any variable defined with
              the env stanza.

              Negation is permitted by using != between the KEY and VALUE.

              If  an event is emitted for which no jobs have registered inter-
              est (via either start on or stop on), the event is destroyed.

              If a job specifies a single event in  its  start  condition  and
              that  event  is emitted and matches any specifies event environ-
              ment variables, the overall condition becomes true, the  job  is
              started  and -- assuming no other job has registered an interest
              Note that no job processes are started until the overall expres-
              sion evaluates to true.

              Note that if a new job is created which specifies that it starts
              on one or more events that have already been destroyed, that job
              will  not  start  automatically  until  those events are emitted
              again. Depending on the event, this may  not  happen  until  the
              next time the system is booted.

              Although  complex expressions are supported, it should be possi-
              ble to specify the start condition for the majority of jobs with
              very  simple  expressions (between one and four events as a very
              approximate guide). A large number  or  complex  combination  of
              events  is  often  an  indication  that  the condition should be
              refactored.

              Examples of start on conditions:

              start on started gdm or started kdm

              start on stopped JOB=foo RESULT=failed PROCESS=pre-start

              start on device-added SUBSYSTEM=tty DEVPATH=ttyS*

              start on net-device-added INTERFACE!=lo

              start on (A and B C=D and E F=G)


       stop on EVENT [[KEY=]VALUE]... [and|or...]
              The stop on stanza defines the set of events that will cause the
              job  to  be  automatically  stopped.   It has the same syntax as
              start on.

              VALUE may additionally expand the value  of  any  variable  that
              came  from  the job's start environment (either the event or the
              command that started it).

              Examples of stop on conditions:

              stop on A

              stop on starting B and stopped JOB=C

              stop on stopping gdm or stopping kdm

              stop on device-removed DEVPATH=$DEVPATH


       manual This stanza will disregard any previously seen start on  defini-
              tion.  By adding this stanza on any line below the start on def-
              inition, it provides the ability to stop a job from being  auto-
              matically started.  When specified, the only way to start such a
              job is via start (8).

           These commands also allow unsetting of variables.

       o   A set of special variables added by Upstart that relate to the  job
           itself.

           All jobs also contain the UPSTART_JOB and UPSTART_INSTANCE environ-
           ment variables, containing the name of the job and instance.  These
           are  mostly  used by the initctl(8) utility to default to acting on
           the job the commands are called from.

       o   Those variables introduced by the events or  command  that  started
           the job.

           The  special  UPSTART_EVENTS environment variable contains the list
           of events that started the job, it will not be present if  the  job
           was started manually.

           The  pre-stop and post-stop scripts are run with the environment of
           the   events   or   commands   that   stopped   the    job.     The
           UPSTART_STOP_EVENTS  environment  variable  contains  the  list  of
           events that stopped the job, it will not be present if the job  was
           stopped manually.

       o   Variables  set within the job itself using the env and export stan-
           zas. These provide default values - if the command or  event  which
           causes  the  job  to  start specifies alternative values, those are
           given priority over the defaults.

           env KEY[=VALUE]
                  Defines a default environment variable, the value  of  which
                  may  be  overridden  by the event or command that starts the
                  job.  If 'KEY=VALUE' is specified, the variable KEY is given
                  the  value VALUE.  If only 'KEY' is given, then the value is
                  taken from the init(8) daemon's own environment.

           export KEY
                  Exports the value of an environment variable into the start-
                  ing(7),  started(7),  stopping(7)  and stopped(7) events for
                  this job and to all resultant events (not just those  relat-
                  ing to the current job).

       The first two categories above comprise the job environment table which
       is applied to all jobs. Note that changing the  job  environment  table
       will only affect newly-started jobs.

   Services, tasks and respawning
       Jobs  are services by default.  This means that the act of starting the
       job is considered to be finished when the job is running, and that even
       exiting with a zero exit status means the service will be respawned.


       task   This  stanza  may  be  used  to  specify  that the job is a task
              instead.  This means that the act of starting  the  job  is  not
              ping, except the stop(8) command itself, are  considered  abnor-
              mal.   Tasks  may  exit with a zero exit status to prevent being
              respawned.

       respawn limit COUNT INTERVAL
              Respawning is subject to a limit, if the job is  respawned  more
              than  COUNT  times in INTERVAL seconds, it will be considered to
              be having deeper problems and will be stopped. Default COUNT  is
              10. Default INTERVAL is 5 seconds.

              This  only  applies to automatic respawns and not the restart(8)
              command.

       normal exit STATUS|SIGNAL...
              Additional exit statuses or even signals may be  added,  if  the
              job  process terminates with any of these it will not be consid-
              ered to have failed and will not be respawned. A signal  can  be
              specified  either  as  a  full name (for example "SIGTERM") or a
              partial name (for example "TERM").

              normal exit 0 1 TERM SIGHUP

   Instances
       By default, only one instance of any job is permitted to exist  at  one
       time.   Attempting to start a job when it's already starting or running
       results in an error. Note that a job is considered to be running if its
       pre-start process is running.

       Multiple  instances  may  be  permitted  by defining the names of those
       instances.  If an instance with the same name is not  already  starting
       or  running,  a  new  instance  will be started instead of returning an
       error.


       instance NAME
              This stanza defines the names of instances, on its own  its  not
              particularly  useful  since it would just define the name of the
              single permitted instance, however  NAME  expands  any  variable
              defined in the job's environment.

              These  will  often  be  variables  that  you need to pass to the
              process anyway, so are an excellent way to limit the instances.

              instance $CONFFILE
              exec /sbin/httpd -c $CONFFILE

              instance $TTY
              exec /sbin/getty -8 38300 $TTY

              These jobs appear in the initctl(8)  output  with  the  instance
              name  in parentheses, and have the INSTANCE environment variable
              set in their events.

   Documentation

              author "Scott James Remnant <scott@netsplit.com>"

       version VERSION
              This stanza may contain version information about the job,  such
              as  revision  control or package version number.  It is not used
              or interpreted by init(8) in any way.

              version "$Id$"

       emits EVENT...
              All processes on the system are free to emit their own events by
              using the initctl(8) tool, or by communicating directly with the
              init(8) daemon.

              This stanza allows a job to document in  its  job  configuration
              what events it emits itself, and may be useful for graphing pos-
              sible transitions.

              The initctl(8) check-config command attempts to use this  stanza
              to resolve events.

              EVENT can be either a literal string or a string including shell
              wildcard meta-characters (asterisk ('*'), question  mark  ('?'),
              and  square brackets ('[' and ']')).  Meta-characters are useful
              to allow initctl(8) check-config to resolve a class  of  events,
              such as those emitted by upstart-udev-bridge(8).


       usage USAGE
              This  stanza  may contain the text used by initctl(8) usage com-
              mand. This text  may  be  also  shown  when  commands  start(8),
              stop(8) or status(8) fail.

              usage "tty DEV=ttyX - where X is console id"

   Process environment
       Many  common  adjustments  to the process environment, such as resource
       limits, may be configured directly in the job  rather  than  having  to
       handle them yourself.


       console none|log|output|owner
              none
                     If  none  is specified, the jobs standard input, standard
                     output and standard error file descriptors are  connected
                     to /dev/null.  Any output generated by a job will be dis-
                     carded.  This used to be the default prior to the  intro-
                     duction of log in Upstart 1.4.

              log
                     If  log  is  specified,  standard  input  is connected to
                     /dev/null, and standard output  and  standard  error  are
                     connected to a pseudo-tty which logs all job output.

                     Jobs  started from within a chroot will have their output
                     logged to such a path within the chroot.

                     If log files already exist, they are appended to.

                     All slash ('/') characters in <job-log-file> are replaced
                     with underscore ('_') characters. For example, any output
                     from the 'wibble' instance of the 'foo/bar' job would  be
                     encoded  in  file  'foo_bar-wibble.log'  in  the log file
                     directory. This gives  the  log  file  directory  a  flat
                     structure.

                     If the directory for system jobs does not exist, job out-
                     put for each job will be cached until the  job  finishes.
                     Thus,  the boot process must ensure that the directory is
                     available as soon as possible since any job that finishes
                     before  a writeable disk is available will not be able to
                     take advantage of this facility.

                     If it is not possible to write to any  log  file  due  to
                     lack  of  disk  space, the job will be considered to have
                     specified a console value of none and all subsequent  job
                     output will be discarded.

                     If  the logger detects that the file it is about to write
                     to was deleted, it will re-open the file first.

                     Care should be taken if the  log  directory  is  a  mount
                     point  since  any  job  that  starts before that mount is
                     available and which produces output will then attempt  to
                     write  logs to the mount point, not to the mounted direc-
                     tory. This may give the impression that log data has  not
                     been  recorded. A strategy to handle this situation is to
                     ensure the mount point directory is  not  writeable  such
                     that  logs  will  only be written when the mount has suc-
                     ceeded (assuming the mount itself is  writeable  and  has
                     sufficient space).

                     Note  that  since  log  utilizes pseudo-ttys, your kernel
                     must support these. If it does  not,  the  console  value
                     will  be  modified  automatically to none.  Further, note
                     that it may be necessary to increase the number of avail-
                     able pty devices; see pty(7) for details.

                     Under  Linux,  full Unix 98 pty support requires that the
                     devpts filesystem be mounted.

                     If pty setup fails for any reason, an error message  will
                     be displayed and the job's console value will be reset to
                     none.

              output
                     If output is specified, the standard input, standard out-

              the  process.   UMASK should be an octal value for the mask, see
              umask(2) for more details.

       nice NICE
              Another common configuration is to  adjust  the  process's  nice
              value, see nice(1) for more details.

       oom score ADJUSTMENT|never
              Normally  the  OOM  killer  regards  all processes equally, this
              stanza advises the kernel to treat this job differently.

              ADJUSTMENT may be an integer value from -999 (very  unlikely  to
              be  killed  by  the  OOM  killer)  up to 1000 (very likely to be
              killed by the OOM killer).  It may also  be  the  special  value
              never to have the job ignored by the OOM killer entirely.

       chroot DIR
              Runs  the  job's processes in a chroot(8) environment underneath
              DIR

              Note that DIR must have all the necessary system  libraries  for
              the process to be run, often including /bin/sh

       chdir DIR
              Runs the job's processes with a working directory of DIR instead
              of the root of the filesystem.

       limit LIMIT SOFT|unlimited HARD|unlimited
              Sets initial system resource limits  for  the  job's  processes.
              LIMIT  may  be one of core, cpu, data, fsize, memlock, msgqueue,
              nice, nofile, nproc, rss, rtprio, sigpending or stack.

              Limits are specified as both a SOFT value and a HARD value, both
              of which are integers.  The special value unlimited may be spec-
              ified for either.

       setuid USERNAME
              Changes to the user USERNAME before running any job process.

              The job process will run with the primary group of user USERNAME
              unless  the  setgid  stanza is also specified in which case that
              group will be used instead.

              For system jobs initgroups(3) will be called to set  up  supple-
              mentary group access.

              Failure  to  determine  and/or  set  user and group details will
              result in the overall job failing to start.

              If this stanza is unspecified, all job processes will  run  with
              user  ID 0 (root) in the case of system jobs, and as the user in
              the case of user jobs.

              Note that system jobs using the setuid stanza are  still  system
              cesses will run with their group ID set to 0 (root) in the  case
              of system jobs, and as the primary group of the user in the case
              of User Session jobs.

   Override File Handling
       Override files allow a jobs environment to be changed without modifying
       the jobs configuration file. Rules governing override files:


       o If  a job is embodied with only a configuration file, the contents of
         this file define the job.

       o If an override files exists where there is no  existing  cofiguration
         file, the override file is ignored.

       o If both a configuration file and an override file exist for a job and
         both files are syntactically correct:

         o stanzas in the override file  will  take  precedence  over  stanzas
           present in the corresponding configuration file.

         o stanzas  in  the  override file which are not present in the corre-
           sponding configuration file will be honoured when the job runs.

       o If both a configuration file and an override file exist for a job and
         subsequently  the override file is deleted, the configuration file is
         automatically reloaded with the effect that any changes introduced by
         the  override  file  are  undone and the configuration file alone now
         defines the job.

       o If both a configuration file and an override file exist for a job and
         subsequently the configuration file is deleted, a new instance of the
         job can no longer be started (since without a corresponding  configu-
         ration file an override file is ignored).

       o If both a configuration file and an override file exist for a job and
         any of the contents of the override file are  invalid,  the  override
         file  is  ignored and only the contents of the configuration file are
         considered.

   AppArmor support
       Upstart provides several stanzas for loading and switching to different
       AppArmor  profiles.  If AppArmor isn't enabled in the currently running
       kernel, the stanzas will be silently ignored.


       apparmor load PROFILE
              This stanza specifies an AppArmor profile to load into the Linux
              kernel  at  job  start. The AppArmor profile will confine a main
              process automatically using  path  attachment,  or  manually  by
              using  the  apparmor switch stanza.  PROFILE must be an absolute
              path to a profile and a failure will occur if the  file  doesn't
              exist.

              Specifies the stopping signal, SIGTERM by default, a job's  main
              process  will  receive when stopping the running job. The signal
              should be specified as a full name (for example "SIGTERM") or  a
              partial  name  (for example "TERM"). Note that it is possible to
              specify the signal as a number (for example "15") although  this
              should  be  avoided  if at all possible since signal numbers may
              differ between systems.

              kill signal INT

       reload signal SIGNAL
              Specifies the reload signal, SIGHUP by  default,  a  job's  main
              process  will receive when reloading the running job. The signal
              should be specified as a full name (for example "SIGHUP")  or  a
              partial  name  (for  example "HUP"). Note that it is possible to
              specify the signal as a number (for example "1")  although  this
              should  be  avoided  if at all possible since signal numbers may
              differ between systems.

              reload signal USR1

       kill timeout INTERVAL
              Specifies the interval between sending the  job's  main  process
              the "stopping" (see above) and SIGKILL signals when stopping the
              running job. Default is 5 seconds.

       expect stop
              Specifies that the job's main process  will  raise  the  SIGSTOP
              signal to indicate that it is ready.  init(8) will wait for this
              signal before running the job's post-start script, or  consider-
              ing the job to be running.

              init(8)  will send the process the SIGCONT signal to allow it to
              continue.

       expect daemon
              Specifies that the job's main process is a daemon, and will fork
              twice  after being run.  init(8) will follow this daemonisation,
              and will wait  for  this  to  occur  before  running  the  job's
              post-start script or considering the job to be running.

              Without  this  stanza init(8) is unable to supervise daemon pro-
              cesses and will believe them to have stopped  as  soon  as  they
              daemonise on startup.

       expect fork
              Specifies that the job's main process will fork once after being
              run.  init(8) will follow this fork, and will wait for  this  to
              occur  before running the job's post-start script or considering
              the job to be running.

              Without this stanza init(8) is unable to supervise forking  pro-
              cesses  and  will  believe  them to have stopped as soon as they
              fork on startup.

       jobs  with  complex  start  on  or  stop  on conditions not behaving as
       expected when restarted. For example, if a job  encodes  the  following
       condition:

              start on A and (B or C)

       When  'A'  and  'B'  become true, the condition is satisfied so the job
       will be run. However, if the job ends  and  subsequently  'A'  and  'C'
       become  true,  the  job  will not be re-run even though the condtion is
       satisfied.  Avoid using complex conditions with jobs which need  to  be
       restarted.

FILES
       /etc/init/*.conf
              System job configuration files.

       /etc/init/*.override
              System job override files.

       $HOME/.init/*.conf
              User job configuration files (deprecated).

       $HOME/.init/*.override
              User job override files.  (deprecated).

       $XDG_CONFIG_HOME/upstart/*.conf
              User  session job configuration files. See User Session Mode for
              other locations.

       $XDG_CONFIG_HOME/upstart/*.override
              User session job override files. See User Session Mode for other
              locations.

       /var/log/upstart/*.log
              Default location of system job output logs.

       $XDG_CACHE_HOME/upstart/*.log
              Default location of user session job output logs.

       $XDG_RUNTIME_DIR/upstart/sessions/*.session
              Location  of  session files created when running in User Session
              mode.

AUTHOR
       Manual page 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 (C) 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
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.