UpstartBundle
For Symfony 2 and 3., (*1)
About
This is a Symfony bundle for painless Upstart configuration.
It helps to make any symfony command (or any other script) run forever in background and restart on fails.
Most common example of such script is queue consumer, another example is websocket server., (*2)
Installation
Require the bundle and its dependencies with composer:, (*3)
$ composer require sfnix/upstart
Register the bundle:, (*4)
// app/AppKernel.php
public function registerBundles()
{
//...
$bundles = [
//...
new SfNix\UpstartBundle\UpstartBundle(),
];
//...
}
Usage
Add the upstart section to your configuration files:, (*5)
# app/config/config.yml
imports:
# ...
- { resource: upstart.yml }
```yml, (*6)
app/config/upstart.yml
upstart:
project: imagin
default:
verbose: 1
native:
respawn: true
setuid: www-data
chdir: %kernel.root_dir%/..
job:
websocket:
tag: [server]
script: php bin/chat-server.php
imageResizer:
tag: [image]
quantity: 10
command: rabbitmq:consumer imageResizer -w
faceRecognizer:
tag: [image]
quantity: 5
native:
exec: python faceRecognizer.py
killSignal: SIGKILL
test:
command: upstart:test --error 10
verbose: 3, (*7)
Generate and install upstart files derived from your configuration.
It also will try to enable bash completion for other commands of this bundle.
```bash
# ./app/console upstart:install
List jobs, and their statuses.
It can show statuses continuously with --watch (-w) option.
Refresh interval is 1 second by default, see --interval (-i) option., (*8)
# ./app/console upstart:list
Start jobs., (*9)
# ./app/console upstart:start
Stop jobs., (*10)
# ./app/console upstart:stop
Stop and start jobs., (*11)
# ./app/console upstart:restart
Show tails of logs of jobs.
It can show logs continuously with --watch (-w) option.
If you are redirecting script output in any way then you need to use log, logDir job config options., (*12)
# ./app/console upstart:log
Delete upstart files and bash completion scripts generated by this bundle., (*13)
# ./app/console upstart:delete
You can use multiple job names or tags as arguments for any command, to filter jobs on which this command will operate., (*14)
# ./app/console upstart:stop websocket image
You can use test command as script in your job configuration, for learning purposes.
It runs forever by default, but take a look at --exit and --error options., (*15)
# ./app/console upstart:test --error 10 -vvv
Separate console application with bash completion support.
This bundle includes separate console application ./bin/upstart (Symfony 2) or ./vendor/bin/upstart (Symfony 3).
Each command of this bundle is available through this application without "upstart:" namespace.
upstart also has bash completion support for command options, job names and tags.
To start using bash completion, you must run upstart install, then logout and login again.
Usage:, (*16)
# ./bin/upstart install
# exit
# ./bin/upstart <Tab>
# ./bin/upstart start <Tab>
Full configuration reference
Read Upstart Cookbook for detailed description of all native stanzas., (*17)
upstart:
# Project name will be used as a directory name for upstart config files, and as a prefix for event names.
project: ~ # Required, Example: sfnix
# Root directory of upstart config files.
configDir: /etc/init
# Defaults for all jobs.
default:
# Symfony command debug option (debug: 0 -> --no-debug). It will be ignored if job has no "command".
debug: ~
# Symfony command verbose level option (verbose: 0 -> no options, verbose: 3 -> -vvv). It will be ignored if job has no "command".
verbose: ~
# Symfony command env option (env: prod -> --env prod) It will be ignored if job has no "command".
env: dev
# If you use any output redirection for the script,
# this option can help you tell the bundle where the log directory is.
logDir: /var/log/upstart
# Native upstart stanzas. They always will overwrite any stanzas generated by this bundle.
native:
# This stanza will tell Upstart to ignore the start on / stop on stanzas.
manual: ~ # Example: true
#This stanza defines the set of Events that will cause the Job to be automatically started.
#Syntax: EVENT [[KEY=]VALUE]... [and|or...]
startOn: ~ # Example: event1 and runlevel [2345] and (local-filesystems and net-device-up IFACE!=lo)
#This stanza defines the set of Events that will cause the Job to be automatically stopped if it is already running.
#Syntax: EVENT [[KEY=]VALUE]... [and|or...]
stopOn: ~ # Example: runlevel [016] or event2
# Allows an environment variable to be set which is accessible in all script sections.
env:
# Examples:
myVar1: Hello world!
myVar2: Goodby world!
# Export variables previously set with env to all events that result from this job.
export:
# Examples:
- myVar1
- myVar2
#Used to change Upstart's idea of what a "normal" exit status is.
#Conventionally, processes exit with status 0 (zero) to denote success and non-zero to denote failure.
normalExit: ~ #Example: [0, 13, SIGUSR1, SIGWINCH]
#With this stanza, whenever the main script/exec exits,
#without the goal of the job having been changed to stop,
#the job will be started again.
#This includes running pre-start, post-start and post-stop.
#Note that pre-stop will not be run.
respawn: ~ # Example: true
#Syntax: [int $COUNT, int $INTERVAL] | ["unlimited"]
#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.
respawnLimit: ~
#In concept, a task is just a short lived job.
#In practice, this is accomplished by changing how the transition from a goal of "stop" to "start" is handled.
#
#Without the 'task' keyword, the events that cause the job to start will be unblocked as soon as the job is started.
#This means the job has emitted a starting(7) event, run its pre-start, begun its script/exec, and post-start,
#and emitted its started(7) event.
#
#With task, the events that lead to this job starting will be blocked until the job has completely transitioned back to stopped.
#This means that the job has run up to the previously mentioned started(7) event, and has also completed its post-stop,
#and emitted its stopped(7) event.
task: ~ # Example: true
# Load specified AppArmor Mandatory Access Control system profile into the kernel prior to starting the job.
# The main job process (as specified by exec or script) will be confined to this profile.
# Notes:
# - <profile-path> must be an absolute path.
# - The job will fail if the profile doesn't exist, or the profile fails to load.
apparmorLoad: ~
# Run main job process with already-loaded AppArmor Mandatory Access Control system profile.
# Notes:
# - The job will fail if the profile named does not exist, or is not already loaded.
apparmorSwitch: ~
# Upstart 1.13 supports cgroups with the aid of cgmanager (see cgmanager(8)).
# A new "cgroup" stanza is introduced that allows job processes to be run within the specified cgroup.
# http://upstart.ubuntu.com/cookbook/#cgroup
cgroup:
# Examples:
- [cgroup, cpu]
- [memory, $UPSTART_CGROUP, limit_in_bytes, 52428800]
console: ~ # One of "logged"; "output"; "owner"; "none"
# Runs the job's processes with a working directory in the specified directory instead of the root of the filesystem.
chdir: ~
# Runs the job's processes in a chroot(8) environment underneath the specified directory.
chroot: ~
# Provides the ability to specify resource limits for a job.
# 0: limit # One of "core"; "cpu"; "data"; "fsize"; "memlock"; "msgqueue"; "nice"; "nofile"; "nproc"; "rss"; "rtprio"; "sigpending"; "stack"
# 1: soft limit # integer or "unlimited"
# 2: hard limit # integer or "unlimited"
limit:
# Examples:
- [cpu, unlimited, unlimited]
# Change the jobs scheduling priority from the default. See nice(1).
nice: ~
# Linux has an "Out of Memory" killer facility.
# Normally the OOM killer regards all processes equally, this stanza advises the kernel to treat this job differently.
# The "adjustment" value provided to this stanza 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
# (potentially dangerous unless you really trust the application in all possible system scenarios).
oomScore: ~
# Changes to the group before running the job's process.
setgid: ~
# Changes to the user before running the job's process.
setuid: ~
# Set the file mode creation mask for the process. Value should be an octal value for the mask. See umask(2) for more details.
umask: ~
# fork - Upstart will expect the process executed to call fork(2) exactly once.
# daemon - Upstart will expect the process executed to call fork(2) exactly twice.
# 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 and then:
# - Immediately send the process SIGCONT to allow it to continue.
# - Run the job's post-start script (if any).
# Only then will Upstart consider the job to be running.
expect: ~ # One of "fork"; "deamon"; "stop"
# Specifies the stopping signal, SIGTERM by default, a job's main process will receive when stopping the running job.
killSignal: ~ # One of "SIGHUP"; "SIGINT"; "SIGQUIT"; "SIGILL"; "SIGTRAP"; "SIGIOT"; "SIGBUS"; "SIGFPE"; "SIGKILL"; "SIGUSR1"; "SIGSEGV"; "SIGUSR2"; "SIGPIPE"; "SIGALRM"; "SIGTERM"; "SIGSTKFLT"; "SIGCHLD"; "SIGCONT"; "SIGSTOP"; "SIGTSTP"; "SIGTTIN"; "SIGTTOU"; "SIGURG"; "SIGXCPU"; "SIGXFSZ"; "SIGVTALRM"; "SIGPROF"; "SIGWINCH"; "SIGIO"; "SIGPWR"
# The number of seconds Upstart will wait before killing a process. The default is 5 seconds.
killTimeout: ~
# Specifies the signal that Upstart will send to the jobs main process when the job needs to be reloaded (the default is SIGHUP).
reloadSignal: ~ # One of "SIGHUP"; "SIGINT"; "SIGQUIT"; "SIGILL"; "SIGTRAP"; "SIGIOT"; "SIGBUS"; "SIGFPE"; "SIGKILL"; "SIGUSR1"; "SIGSEGV"; "SIGUSR2"; "SIGPIPE"; "SIGALRM"; "SIGTERM"; "SIGSTKFLT"; "SIGCHLD"; "SIGCONT"; "SIGSTOP"; "SIGTSTP"; "SIGTTIN"; "SIGTTOU"; "SIGURG"; "SIGXCPU"; "SIGXFSZ"; "SIGVTALRM"; "SIGPROF"; "SIGWINCH"; "SIGIO"; "SIGPWR"
# Quoted name (and maybe contact details) of author of this Job Configuration File.
author: ~
# List of jobs.
job:
-
# Name of a job. Will be used as upstart config file name and log file name.
name: ~
# Tags.
tag: []
# Number of job instances to run.
quantity: 1
# Symfony command.
command: ~ # Example: rabbitmq:consumer imageResizer -w
# Symfony command debug option (debug: 0 -> --no-debug)
debug: ~
# Symfony command verbose level option (verbose: 0 -> no options, verbose: 3 -> -vvv)
verbose: ~
# Symfony command env option (env: prod -> --env prod)
env: ~
# Run some shell script, not a symfony command.
# This is a shortcut for native:{exec:"..."}, or native:{script:"..."}.
script: ~ # Example: php bin/websocket-server.php
# If you use any output redirection for the script,
# this option can help you tell the bundle where the log directory is.
logDir: ~
# If you use any output redirection for the script,
# this option can help you tell the bundle what is log file base name.
log: ~
# Native upstart stanzas. They always will overwrite any stanzas generated by this bundle.
native:
# This stanza will tell Upstart to ignore the start on / stop on stanzas.
manual: ~ # Example: true
#This stanza defines the set of Events that will cause the Job to be automatically started.
#Syntax: EVENT [[KEY=]VALUE]... [and|or...]
startOn: ~ # Example: event1 and runlevel [2345] and (local-filesystems and net-device-up IFACE!=lo)
#This stanza defines the set of Events that will cause the Job to be automatically stopped if it is already running.
#Syntax: EVENT [[KEY=]VALUE]... [and|or...]
stopOn: ~ # Example: runlevel [016] or event2
# Allows an environment variable to be set which is accessible in all script sections.
env:
# Examples:
myVar1: Hello world!
myVar2: Goodby world!
# Export variables previously set with env to all events that result from this job.
export:
# Examples:
- myVar1
- myVar2
# Stanza that allows the specification of a single-line command to run.
exec: ~ # Example: /usr/bin/my-daemon --option foo -v
# Use this stanza to prepare the environment for the job.
preStart: ~ # Example: [ -d "/var/cache/squid" ] || squid -k
# Script or process to run after the main process has been spawned, but before the started(7) event has been emitted.
postStart: ~ # Example: while ! mysqladmin ping localhost ; do sleep 1 ; done
# The pre-stop stanza will be executed before the job's stopping(7) event is emitted and before the main process is killed.
preStop: ~ # Example: /some/directory/script
#There are times where the cleanup done in pre-start is not enough.
#Ultimately, the cleanup should be done both pre-start and post-stop,
#to ensure the service starts with a consistent environment,
#and does not leave behind anything that it shouldn.
postStop: ~ # Example: /some/directory/script
# Allows the specification of a multi-line block of shell code to be executed. Block is terminated by end script.
script: ~ # Example: /some/directory/script >> /var/log/some-log.log
#Used to change Upstart's idea of what a "normal" exit status is.
#Conventionally, processes exit with status 0 (zero) to denote success and non-zero to denote failure.
normalExit: ~ #Example: [0, 13, SIGUSR1, SIGWINCH]
#With this stanza, whenever the main script/exec exits,
#without the goal of the job having been changed to stop,
#the job will be started again.
#This includes running pre-start, post-start and post-stop.
#Note that pre-stop will not be run.
respawn: ~ # Example: true
#Syntax: [int $COUNT, int $INTERVAL] | ["unlimited"]
#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.
respawnLimit: ~
#In concept, a task is just a short lived job.
#In practice, this is accomplished by changing how the transition from a goal of "stop" to "start" is handled.
#
#Without the 'task' keyword, the events that cause the job to start will be unblocked as soon as the job is started.
#This means the job has emitted a starting(7) event, run its pre-start, begun its script/exec, and post-start,
#and emitted its started(7) event.
#
#With task, the events that lead to this job starting will be blocked until the job has completely transitioned back to stopped.
#This means that the job has run up to the previously mentioned started(7) event, and has also completed its post-stop,
#and emitted its stopped(7) event.
task: ~ # Example: true
#Sometimes you want to run the same job, but with different arguments.
#The variable that defines the unique instance of this job is defined with instance.
instance: ~
# Load specified AppArmor Mandatory Access Control system profile into the kernel prior to starting the job.
# The main job process (as specified by exec or script) will be confined to this profile.
# Notes:
# - <profile-path> must be an absolute path.
# - The job will fail if the profile doesn't exist, or the profile fails to load.
apparmorLoad: ~
# Run main job process with already-loaded AppArmor Mandatory Access Control system profile.
# Notes:
# - The job will fail if the profile named does not exist, or is not already loaded.
apparmorSwitch: ~
# Upstart 1.13 supports cgroups with the aid of cgmanager (see cgmanager(8)).
# A new "cgroup" stanza is introduced that allows job processes to be run within the specified cgroup.
# http://upstart.ubuntu.com/cookbook/#cgroup
cgroup:
# Examples:
- [cgroup, cpu]
- [memory, $UPSTART_CGROUP, limit_in_bytes, 52428800]
console: ~ # One of "logged"; "output"; "owner"; "none"
# Runs the job's processes with a working directory in the specified directory instead of the root of the filesystem.
chdir: ~
# Runs the job's processes in a chroot(8) environment underneath the specified directory.
chroot: ~
# Provides the ability to specify resource limits for a job.
limit:
# Examples:
- [cpu, unlimited, unlimited]
# Change the jobs scheduling priority from the default. See nice(1).
nice: ~
# Linux has an "Out of Memory" killer facility.
# Normally the OOM killer regards all processes equally, this stanza advises the kernel to treat this job differently.
# The "adjustment" value provided to this stanza 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
# (potentially dangerous unless you really trust the application in all possible system scenarios).
oomScore: ~
# Changes to the group before running the job's process.
setgid: ~
# Changes to the user before running the job's process.
setuid: ~
# Set the file mode creation mask for the process. Value should be an octal value for the mask. See umask(2) for more details.
umask: ~
# fork - Upstart will expect the process executed to call fork(2) exactly once.
# daemon - Upstart will expect the process executed to call fork(2) exactly twice.
# 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 and then:
# - Immediately send the process SIGCONT to allow it to continue.
# - Run the job's post-start script (if any).
# Only then will Upstart consider the job to be running.
expect: ~ # One of "fork"; "deamon"; "stop"
# Specifies the stopping signal, SIGTERM by default, a job's main process will receive when stopping the running job.
killSignal: ~ # One of "SIGHUP"; "SIGINT"; "SIGQUIT"; "SIGILL"; "SIGTRAP"; "SIGIOT"; "SIGBUS"; "SIGFPE"; "SIGKILL"; "SIGUSR1"; "SIGSEGV"; "SIGUSR2"; "SIGPIPE"; "SIGALRM"; "SIGTERM"; "SIGSTKFLT"; "SIGCHLD"; "SIGCONT"; "SIGSTOP"; "SIGTSTP"; "SIGTTIN"; "SIGTTOU"; "SIGURG"; "SIGXCPU"; "SIGXFSZ"; "SIGVTALRM"; "SIGPROF"; "SIGWINCH"; "SIGIO"; "SIGPWR"
# The number of seconds Upstart will wait before killing a process. The default is 5 seconds.
killTimeout: ~
# Specifies the signal that Upstart will send to the jobs main process when the job needs to be reloaded (the default is SIGHUP).
reloadSignal: ~ # One of "SIGHUP"; "SIGINT"; "SIGQUIT"; "SIGILL"; "SIGTRAP"; "SIGIOT"; "SIGBUS"; "SIGFPE"; "SIGKILL"; "SIGUSR1"; "SIGSEGV"; "SIGUSR2"; "SIGPIPE"; "SIGALRM"; "SIGTERM"; "SIGSTKFLT"; "SIGCHLD"; "SIGCONT"; "SIGSTOP"; "SIGTSTP"; "SIGTTIN"; "SIGTTOU"; "SIGURG"; "SIGXCPU"; "SIGXFSZ"; "SIGVTALRM"; "SIGPROF"; "SIGWINCH"; "SIGIO"; "SIGPWR"
# Quoted name (and maybe contact details) of author of this Job Configuration File.
author: ~
# One line quoted description of Job Configuration File.
description: ~
# Specifies the events the job configuration file generates (directly or indirectly via a child process).
# This stanza can be specified multiple times for each event emitted.
# This stanza can also use the following shell wildcard meta-characters to simplify the specification:
# - asterisk ("*")
# - question mark ("?")
# - square brackets ("[" and "]")
emits: ~ # Example: [*-device-*, foo-event, bar-event]
# 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: ~
# Brief message explaining how to start the job in question.
# Most useful for instance jobs which require environment variable parameters to be specified before they can be started.
usage: ~
Wallogit.com
