Provided by: upstart_1.12.1-0ubuntu4_amd64 bug

NAME

       init - Upstart init daemon job configuration

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 honoured 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 recognized suffix and may
       also be present in sub-directories.  There are two recognized suffixes:

       ·   Files  ending  in  .conf  are  called  configuration files, or simply "conf files" for
           short.  These are the primary vehicle for specifying a job.

       ·   Files ending in .override are called override files.  If an override 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 Handling below for further
           details.

       A job can thus be defined by either:

       · A single configuration file.

       · A single configuration file and a single override file.

       Unless  explicitly  stated otherwise, any reference to a jobs configuration 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 embodiment 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
       /etc/init/net/apache.conf is named net/apache.  Since override files only modify the way a
       configuration file is interpreted, they are not named.

       Configuration files are plain text and should not be executable.

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

       ·   $XDG_CONFIG_HOME/upstart/

       ·   $HOME/.init/

       ·   $XDG_CONFIG_DIRS/upstart/

       ·   /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 daemons 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. Unrecognized 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 environment variables in
       their process.

       exec COMMAND [ ARG ]...
              This stanza defines the process to be run as the  name  of  an  executable  on  the
              filesystem, and zero or more arguments to be passed to it.  Any special characters,
              e.g. quotes or `$' specified 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  directories,  and  it  may also call the stop(8) command without
              arguments 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 before the job's  stopping(7)  event  is
              emitted  and  before  the main process is killed.  It is typically used to send any
              necessary 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.  Services 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 administrator  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 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.

              If an event is emitted for which no jobs have registered interest (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  environment  variables,  the overall condition
              becomes true, the job is started and -- assuming no other  job  has  registered  an
              interest in it -- the event is destroyed.

              However,  if  an event is emitted which matches part of a jobs start condition, the
              job is said to be blocking the event (since the event is  unable  to  change  state
              until  the  job  has  started) and will both cause the event to persist and the job
              start condition to be marked as partially completed. Once all events in  the  start
              condition  have  been emitted, the overall job start condition becomes true and the
              job will be started. If no other jobs have registered interest in the events in the
              start condition, they will then be destroyed.

              Note  that  no  job processes are started until the overall expression 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 possible 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 definition.  By adding this
              stanza on any line below the start on definition, it provides the ability to stop a
              job from being automatically started.  When specified, the only way to start such a
              job is via start (8).

   Job environment
       Each job is run with an environment constructed from the following categories:

       ·   A minimal set of standard system variables added by Upstart.

           All jobs contain the TERM and PATH variables.

       ·   Variables set using the initctl(8) job environment commands (such as set-env).

           These commands also allow unsetting of variables.

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

           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.

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

       ·   Variables  set  within  the job itself using the env and export stanzas. 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 starting(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).

       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 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 stopping, except the stop(8) command itself,
              are  considered  abnormal.  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 considered 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
       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 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 possible 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 command. 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  discarded.   This  used  to  be  the  default  prior  to  the
                     introduction 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.

                     Output    is    logged    to    file    /var/log/upstart/<job-log-file>   or
                     $XDG_CACHE_HOME/upstart/<job-log-file> for  system  and  user  session  jobs
                     respectively.

                     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.

                     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 output 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 directory.
                     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 succeeded
                     (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  available
                     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 output 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 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 specified 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 supplementary 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 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.

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

              If  this  stanza  is  unspecified,  the  primary group of the user specified in the
              setuid block is used for all job processes. If both this and the setuid stanza  are
              unspecified,  all job processes 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:

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

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

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

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

         · stanzas in the override file which are not present in the corresponding  configuration
           file will be honoured when the job runs.

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

       · 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 configuration file an override file is ignored).

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

              apparmor load /etc/apparmor.d/usr.sbin.cupsd

       apparmor switch NAME
              This  stanza  specifies  the  name  of an AppArmor profile name to switch to before
              running the main process.  NAME must be the name of a profile already  loaded  into
              the running Linux kernel, and will result in a failure if not available.

              apparmor switch /usr/sbin/cupsd

   Miscellaneous
       kill signal SIGNAL
              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 considering 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 processes 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  processes  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 unpredictable behaviour resulting from broken or inaccessible links  (such  as
       would  be caused by a link crossing 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 evaluated once and state information is
       then discarded. This can lead to 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 © 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 PURPOSE.

SEE ALSO

       apparmor(7), init(8), initctl(8), prctl(2), pty(7), sh(1), upstart-events(7).