init


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

       $HOME/.init/
              Default location of user job configuration files.

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  D-Bus  has  been configured to allow non-privileged users to invoke
       all Upstart D-Bus methods, Upstart is also able to  manage  User  Jobs.
       See User Jobs 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 environmenta 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
       tooling is taken from its relative path within  the  directory  without
       the   extension.    For  example  a  configuration  file  /etc/init/rc-
       sysinit.conf  is  named  rc-sysinit,   while   a   configuration   file

       Any user can create user jobs, but that user can control only jobs they
       create.

       Users are able to manage  their  jobs  using  the  standard  initctl(8)
       facility.

       Note  that stanzas which manipulate resources limits may cause a job to
       fail to start should the value provided to such  a  stanza  attempt  to
       exceed the maximum value the users privilege level allows.

       Note  that a user job configuration file cannot have the same name as a
       system job configuration file.

   Chroot Support
       Upstart is able to manage jobs within  a  chroot(2).  To  control  jobs
       within  the  chroot  environment, use the standard initctl(8) facility.
       Note that it is not necessary to install D-Bus within  the  chroot  (in
       fact it is not recommended).

       Note that User Jobs can be created within a chroot environment.


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

       Comments begin with a `#' and continue  until  the  end  of  the  line.
       Blank  lines  and  lines  consisting only of whitespace or comments are
       ignored.

   Process definition
       The primary use of jobs is to define services or tasks to be run by the
       init(8)  daemon.  Each job may have one or more different processes run
       as part of its lifecycle, with  the  most  common  known  as  the  main
       process.

       The  main  process  is defined using either the exec or script stanzas,
       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.
              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.

       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
              before the job's stopping(7) event is  emitted  and  before  the
              main process is killed.  It is typically used to send any neces-
              sary shutdown commands to the main process, and it may also call
              the start(8) command without arguments to cancel the stop.

       post-stop exec|script...
              This  process  is run after the main process has been killed and
              before the job's stopped(7) event is emitted.  It  is  typically
              used  to  clean  up  the environment, such as removing temporary
              directories.


       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  permissable  to  have  no  main  process, but to have pre-start and
       post-stop processes for the state.

              pre-start exec ifup -a

       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  opera-
              tors,  and complex expressions may be performed with parentheses
              (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.

              start on started gdm or started kdm

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

              start on net-device-added INTERFACE!=lo

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

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

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

       All jobs also contain the UPSTART_JOB and UPSTART_INSTANCE  environment
       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.


       env KEY[=VALUE]
              Defines  a  default environment variable, the value of which may
              be overriden 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 relating to the
              current job).

   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
              considered to be finished until the job itself has been run  and
              stopped  again,  but  that exiting with a zero exit status means
              the task has completed successfully and will not be respawned.


       The start(8) command, and any starting(7) or  stopping(7)  events  will
       block only until a service is running or until a task has finished.


       respawn
              A service or task with this stanza will be automatically started
              if it should stop abnormally.  All reasons for a  service  stop-
              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.

       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
       Upstart  provides several stanzas useful for documentation and external
       tools.


       description DESCRIPTION
              This stanza may contain a description of the job.

              description "This does neat stuff"

       author AUTHOR
              This stanza may contain the author of the job, often used  as  a
              contact for bug reports.

              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
              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
                     Only applies to system jobs: if specified by  user  jobs,
                     the  job  will  be considered to have specified the value
                     none.

                     For system jobs, 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.

                     Output is logged to file /var/log/upstart/<job-log-file>.
                     If a job  has  specified  instance,  <job-log-file>  will
                     equate  to  <job>-<instance>.log  where  '<instance>'  is
                     replaced by the specific instance value  and  '<job>'  is
                     replaced  with the job name (job configuration file name,
                     without the extension).  If instance  is  not  specified,
                     <job-log-file>   will   be  <job>.log  where  '<job>'  is
                     replaced with the job name.

                     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 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-
                     put  and standard error file descriptors are connected to
                     /dev/console.

              owner
                     The owner value is special: it not only connects the  job
                     to the system console but sets the job to be the owner of
                     the system console, which means it will  receive  certain
                     signals  from  the  kernel  when special key combinations
                     such as Control-C are pressed.

       umask UMASK
              A common configuration is to set the file mode creation mask for
              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
              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.

              If this stanza is unspecified, all job  processes  will  run  as
              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
              jobs, and can not be controlled by an unprivileged user, even if
              the setuid stanza specifies that user.

       setgid GROUPNAME
              Changes to the group GROUPNAME before running any job process.

              If this stanza is unspecified, the primary  group  of  the  user
              specified  in the setuid block is used for all job processes. If
              both stanzas are unspecified, all job processes  will  run  with
              its  group  ID  set  to 0 in the case of system jobs, and as the
              primary group of the user in the case of User 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

   Miscellaneous
       kill signal SIGNAL
              Specifies the stopping signal, SIGTERM by default, a job's  main
              process will receive when stopping the running job.

              kill signal INT

       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.

RESTRICTIONS
       The  use of symbolic links in job configuration file directories is not
       supported since it can lead to unpredicable  behaviour  resulting  from
       broken  or inaccessible links (such as would be caused by a link cross-
       ing a filesystem boundary  to  a  filesystem  that  has  not  yet  been
       mounted).

BUGS
       The  and and or operators allowed with start on and stop on do not work
       intuitively: operands to the right of either operator are  only  evalu-
       ated  once  and  state  information is then discarded. This can lead to
       jobs with complex start on  or  stop  on  conditions  not  behaving  as
       /etc/init/*.conf
              System job configuration files.

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

       $HOME/.init/*.conf
              User job configuration files.  Note that you may make the direc-
              tory $HOME/.init/ a symbolic link to $HOME/.config/upstart/.

       $HOME/.init/*.override
              User job override files.

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

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-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) initctl(8) sh(1) upstart-events(7) pty(7)



Upstart                           2011-05-12                           init(5)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.