• Stanzas

This is a list of stanzas that can be used in a job file, how can it be used (syntax, arguments) and why using it (what it does, with an example).

This page corresponds to upstart 0.3.9. The syntax and job control mechanisms is greatly improved in 0.5.0.

See also Stanzas for 0.5.1

exec

• Syntax: exec command arguments...

• Example:

  exec /usr/bin/dbus-daemon --system

• Description: Main process command. The command gets run in "start" action. Shorthand for

  • script

    • exec command arguments...

    end script

script

• Syntax:

  • script

    • some shell scripting

    end script

• Example:

  script
    . /etc/default/hal
    exec /usr/sbin/hald --daemon=no $DAEMON_OPTS
  end script

• Description: Specify main command as a shell script instead of a single-line command. Alternative to exec, can't be used together with it.

pre-start

• Syntax: pre-start command

• Example 1:

  pre-start exec rm -f /usr/share/hal/fdi/policy/gparted-disable-automount.fdi

• Example 2:

  pre-start script
          set -e
          rm -f /usr/share/hal/fdi/policy/gparted-disable-automount.fdi
          test -e /var/run/dbus/system_bus_socket
          test -d /sys/kernel
          test -d /proc/sys/fs/also inotify
  end script

• Description: specify a command executed before actually running the process

post-start

• Syntax: post-start command

• Description: Command executed after main process is spawned but before moving to running state. Exit code is ignored.

• Example 1:

  post-start exec touch /var/run/service

• Example 2:

  post-start script
     mkdir -p /var/run/service
     echo $UPSTART_JOB > /var/run/service/job
  end script

pre-stop

• Syntax: pre-stop command

• Description: Command executed when a job in running state gets stopped (initctl stop or stop on event).

post-stop

• Syntax: post-stop command

• Description: Command executed when job is stopped after the main process is killed. The post-stop command is executed if the job failed to launch main process or pre-start command failed, too.

start on

• Syntax: start on event-name [args...]

• Example:

  start on startup

• Description: say when to start the job

stop onalso

• Syntax: stop on event-name [args...]

• Example:

  stop on stopping dbus ok

• Description: say when to stop the job

description

• Syntax: description text

• Example:

  description "DBus is a message bus system, a simple way for applications to talk to each other."

• Informal only.
• Description: Description of the job.

author

• Syntax: author author

• Example:

  author "Obi-wan Kennedy <bidy@whitehouse.gov>"

• also Informal only
• Description: Author of the job file.

version

• Syntax: version version

• Example:

  version "0.0.0.0.1 test"

• Informal only
• Description: Version of the job file.

emits

• Syntax: emits name...

• Example:

  emits spam egg ham

• Informal only
• Description: Signals that can be emitted by this job.

respawn

• Syntax/Example 1: respawn

• Description: set the service and respawn flags for the job. The respawn flag means that the process will be restarted if ended unexpectedly.

respawn limit

• Syntax: respawn limit count timeout

• Example:

  respawn limit 15 5

• Description: This configures the respawn limits, which only apply if the respawn flag is set. The respawn limits function as follows: If the process is respawned more than count times within an interval of timeout seconds, the process will be stopped automatically, and not restarted. Unless set explicitly, the limit defaults to 10 times within 5 seconds.

• A separate respawn stanza must be present to actually set the respawn flag, as of version 0.3.9.

service

• Syntax/Example: service

• Description: this mean that the job has reached its goal when running.

• Implied by respawn

instance

• Syntax/Example: instance

• Description: Job is always waiting and just spawn instances.

daemon

• Syntax/Example: daemon

• Description: Sets the daemon flag for the job. This means that the job will fork in the background and that its PID is supposed to be obtained There is no mechanism to obtain the pid in version 0.3.9, however, this flag only prevents job from entering running state.

• in upstart 0.5.0 this was replaced with "expect fork"

pid

• Sets how to know the PID of a daemon (as of 0.3.9, not implemented, just silently ignored)

 

• Syntax 1: pid file pid_file

• Example 1:

  pid file /var/run/dbus.pid

• Description: identify daemon by pid file

 

• Syntax 2: pid binary path_to_binary

• Example 2:

  pid binary /usr/bin/dbus-daemonalso 

• Description: identify daemon by executable

 

• Syntax 3: pid timeout time

• Description: set amount of time before giving up on obtaining a pid

kill timeout

• Syntax: kill timeout time

• Example:

  kill timeout 5

• Description: time to wait between sending TERM and KILL signals

normal exit

• Syntax: normal exit <exit-code|signal-name>...

• Example:

  normal exit 0 TERM

• Description: List exit codes or signal names that are considered normal. If main process exits normally it is not respawn. The stopping and stopped signal have an ok arg, too.

console

• Syntax: console <logged|output|owner|none>

• Example:

  console owner

• Description: set what to do with process console

  • logged: redirect to logger (the default setting)

  • output: direct output to current stdout

  • owner: the process become the owner of the console, that means it can receive signals from keyboard

  • none: output is redirected to /dev/null

env

• Syntax: env name=value

• Example:

  env PIDFILE=/var/run/myprocess.pid

• Description: set an environment variable of the job processes

umask

• Syntax: umask mask

• Example:

  umask 0755

• Description: set the file creation mask umask of the job processes

nice

• Syntax: nice priority

• Example:

  nice -5

• Description: set the scheduling priority of the job processes

limit

• Syntax: limit resource <unlimited|soft> <unlimited|hard>

• Example:

  limit nproc 10 20

• Description: set resource limits for the job processes. Both the soft and the hard limit must be specified.

• Resources: as core cpu data fsize memlock msgqueue nice nofile nproc rss rtprio sigpending stack

chroot

• Syntax: chroot path

• Example:

  chroot /var/lib/www/jail

• Description: set the root directory to path for the job processes

chdir

• Syntax: chdir path

• Example:

  chdir /var/tmp

• Description: set the working directory of the job processes

-- CategoryDoc