events(5)

NAME
events - format of event files used by the upstart init system

DESCRIPTION
upstart works on the basis of event files that describe jobs that should be managed. This includes the particulars about what binary or shell script code should executed while the job is running, and which events can cause the job to be started or stopped. Event files are stored in the /etc/event.d directory.

SYNTAX
Event files can contain the following stanzaz.

exec  <command> <arguments>
    When the event is started by init, execute the following arguments. Example: exec /bin/dbus-daemon --system

script ...
    Like exec but instead of executing a single program, execute the following shell code. script sections are closed with a end script marker. Example:
    	script
    		rm -f /var/run/sshd.pid
    		sshd
    	end script
    Only one of  exec and script can be used at a time. If both
    are bspecifed, exec takes priority.

pre-start
    Execute the command/script before actually starting the process.
    pre-start can be invoked as pre-start exec or pre-start script
    in the same way that a start action can be handled by either
    exec or script.

post-start
    Execute the command/script after starting the process.
    The format is similar to pre-start.

pre-stop
    Execute the command/script before stopping the process.
    The format is similar to pre-start.

post-stop
    Execute the command/script after stopping the process.
    The format is similar to pre-start.

start on <event>
    Describes on what condition to start this job. Without this
    section, the job can only be manually started with the
    initctl(8) command.
    Examples:
    	start on startup
    	This starts immediately after boot.
    	start on stopped rc3
    	This starts when the 'rc3' event has stopped.
    Events are matched via globbing. So a stanza of the form
    	start on runlevel [2345]
    would match any of runlevels 2, 3, 4, or 5.

stop on <event>
    Describes on what condition to stop this job. Without this
    section, the job can only be manually stopped with the
    initctl command.
    Examples:
    	stop on runlevel 0
    	This stops the job when runlevel 0 is entered.
    	stop on stopping dbus ok
    	This stops the job when the 'dbus' job is stopped.
    Events are matched via globbing. So a stanza of the form
    	stop on runlevel [!5]
    would match any runlevel other than 5.

daemon
    Sets the daemon flag for the job. This means that the job will
    fork in the background and that its PID needs to be obtained.

respawn
    This sets the daemon, service, and respawn flags for the job.
    The respawn flag means that the process will be restarted when
    it ends.

respawn limit [count [timeout]]
    This configures respawn limits. Respawn limits only apply
    if the respawn flag is set for the job; setting a limit
    does not automatically set respawning capability. If the
    process is respawned more than  count times within an
    interval of timeout seconds, the job will be stopped
    automatically, andn ot restarted. The limit defaults to 10
    times within 5 seconds.
    Example: respawn limit 10 120
    This sets the limit for respawn to ten times within two
    minutes, the historical behavior for System V init.

service
    service means that the job has reached its goal when running.
    service is implied by the respawn flag.

instance
    instance means that the job starts new instances every time
    it is started, even if there is another instance running. It
    is the converse of daemon.

kill timeout <time>
    Sets the time to wait between sending TERM and KILL signals to
    time seconds.

normal exit <status>
    When used with respawn any exit codes denoted in status will
    prevent a respawn of the process.

console {logged|output|owner|none}
    Describes what to do with the job's output. Valid values are:
    logged
    Redirect to logger. (the default setting)
    output
    Direct to the current stdout
    owner
    The process becomes the owner of the console, allowing it to
    receive signals from the keyboard
    none
    Output is redirected to /dev/null

env <name>=<value>
    Sets an environment variable for the job.
    Example: env LD_LIBRARY_PATH=/opt/app/lib

umask <umask>
    Sets the umask of the job to umask.
    Example: umask 0755

nice <value>
    Sets the nice level of the job to value.
    Example: nice 5

chroot <path>
    Changes the job's root directory to path.
    Example: chroot /var/empty

chdir <path>
    Changes the working directory of the job to path.
    Example: chdir /var/tmp

limit {as|core|cpu|data|fsize|memlock|msgqueue|nice|nofile|nproc|rss|rtprio|sigpending|stack} {unlimited|<value>}
    Changes the limit of the process to whatever is specfied.
    Examples:
    	limit nproc 10
    	limit core unlimited

description <text>
    Describes the job. Not currently used by any init(8) tools.
    Example: descripton "This is a test job."

author <text>
    Author of the job. Not currently used by any init(8) tools.
    Example: author "Obi-wan Kennedy <bidy@whitehouse.gov>"

version <version>
    Version of the job. Not currently used by any init(8) tools.
    Example: version "0.0.0.0.1 test"

emits <signals>
    Describes signals emitted by the job. Not currently used by
    any init(8) tools. For more information on signals, see the
    initctl(8) man page and the emit option.
    Example: emits spam egg ham

EVENTS
A wide array of events can be emitted by the system (see initctl(8)) but the following events are generated by upstart itself, or are usually seen on a typical install.

stalled
    No jobs are running and no events are pending.

control-alt-delete
    Control-Alt-Delete has been pressed.

kbdrequest
    A kbdrequest event has occurred.

power-status-changed
    Init received SIGPWR.

starting <job>
    The given job is being started.

started <job>
    The given job has successfully been started.

stopping <job>
    The given job is being stopped.

stopped <job>
    The given job has been stopped successfully.

startup
    Emitted when the system boots.

runlevel <runlevel>
    Init has been asked to move to the given runlevel.

FILES
/etc/event.d The directory where event files are stored.

SEE ALSO
initctl(8) telinit(8) init(8) http://upstart.ubuntu.com/getting-started.html