Provided by: upstart_1.5-0ubuntu5_amd64 bug

NAME

       init - Upstart init daemon job configuration

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

   User Jobs
       A  User  Job  is  a  job  configuration  file  created  by  a non-privileged user in their
       $HOME/.init/ directory. Job configuration files in this directory have the same syntax  as
       system  job  configuration  files.  Files in this directory will be read and an inotify(7)
       watch created the first time a user runs initctl(8).

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

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

              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 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  the environment from the events or commands that started it.  In
       addition, you may define defaults in the job which may be  overridden  later  and  specify
       which environment variables are exported into the events generated for 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.

       In addition, 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.

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

   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.

              normal exit 0 1 TERM HUP

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

              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:

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

   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 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  unpredicable 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.  Note that you may make the directory $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 © 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)