Unix/Linux Go Back    


Linux 2.6 - man page for init (linux section 5)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


init(5) 										  init(5)

NAME
       init - Upstart init daemon job configuration

SYNOPSIS
       /etc/init/

       $HOME/.init/

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:

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

       o   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 configura-
	   tion file directly.	See the section Override File Handling 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 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 configu-
       ration file.

   Chroot Support
       Upstart is able to manage jobs within a chroot(2). To control jobs within the chroot envi-
       ronment,  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 gen-
       erate 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 auto-
	      matically started.  Each EVENT is given by its name.  Multiple events are permitted
	      using  the and & or operators, and complex expressions may be performed with paren-
	      theses (within which line breaks are permitted).

	      You may also match on the environment variables contained within the event by spec-
	      ifying  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 automat-
	      ically 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, contain-
       ing  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  termi-
	      nates  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).

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

       console output|owner
	      By default the standard input, output and error file descriptors of jobs	are  con-
	      nected to /dev/null

	      If this stanza is specified, they are connected to /dev/console instead.

	      console  owner  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 ker-
	      nel 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,  sig-
	      pending or stack.

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

   Override File Handling
       Override files allow a jobs environment to be changed without modifying the jobs  configu-
       ration 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  corre-
	   sponding configuration file.

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

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

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

       o If  both  a  configuration file and an override file exist for a job and any of the con-
	 tents of the override file are invalid, the override file is ignored and only	the  con-
	 tents 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:  oper-
       ands 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.

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)

Upstart 				    2011-05-12					  init(5)
Unix & Linux Commands & Man Pages : ©2000 - 2017 Unix and Linux Forums


All times are GMT -4. The time now is 11:45 PM.