Creating a Configuration File¶

Once the Supervisor installation has completed, run echo_supervisord_conf. This will print a "sample" Supervisor configuration file to your terminal's stdout.

Once you see the file echoed to your terminal, reinvoke the command as echo_supervisord_conf > /etc/supervisord.conf. This won't work if you do not have root access.

If you don't have root access, or you'd rather not put the supervisord.conf file in /etc/supervisord.conf`, you can place it in the current directory (echo_supervisord_conf > supervisord.conf) and start supervisord with the -c flag in order to specify the configuration file location.

For example, supervisord -c supervisord.conf. Using the -c flag actually is redundant in this case, because supervisord searches the current directory for a supervisord.conf before it searches any other locations for the file, but it will work.

Once you have a configuration file on your filesystem, you can begin modifying it to your liking.

Configuration File¶

The Supervisor configuration file is conventionally named supervisord.conf. It is used by both supervisord and supervisorctl. If either application is started without the -c option (the option which is used to tell the application the configuration filename explicitly), the application will look for a file named supervisord.conf within the following locations, in the specified order. It will use the first file it finds.

NOTE:

File Format¶

supervisord.conf is a Windows-INI-style (Python ConfigParser) file. It has sections (each denoted by a [header]) and key / value pairs within the sections. The sections and their allowable values are described below.

Environment Variables¶

Environment variables that are present in the environment at the time that supervisord is started can be used in the configuration file using the Python string expression syntax %(ENV_X)s:

[program:example]
command=/usr/bin/example --loglevel=%(ENV_LOGLEVEL)s

In the example above, the expression %(ENV_LOGLEVEL)s would be expanded to the value of the environment variable LOGLEVEL.

NOTE:

[unix_http_server] Section Settings¶

The supervisord.conf file contains a section named [unix_http_server] under which configuration parameters for an HTTP server that listens on a UNIX domain socket should be inserted. If the configuration file has no [unix_http_server] section, a UNIX domain socket HTTP server will not be started. The allowable configuration values are as follows.

[unix_http_server] Section Values¶

file

chmod

chown

username

password

[unix_http_server] Section Example¶

[unix_http_server]
file = /tmp/supervisor.sock
chmod = 0777
chown= nobody:nogroup
username = user
password = 123

[inet_http_server] Section Settings¶

The supervisord.conf file contains a section named [inet_http_server] under which configuration parameters for an HTTP server that listens on a TCP (internet) socket should be inserted. If the configuration file has no [inet_http_server] section, an inet HTTP server will not be started. The allowable configuration values are as follows.

[inet_http_server] Section Values¶

port

username

password

[inet_http_server] Section Example¶

[inet_http_server]
port = 127.0.0.1:9001
username = user
password = 123

[supervisord] Section Settings¶

The supervisord.conf file contains a section named [supervisord] in which global settings related to the supervisord process should be inserted. These are as follows.

[supervisord] Section Values¶

logfile

logfile_maxbytes

logfile_backups

loglevel

pidfile

umask

nodaemon

minfds

minprocs

nocleanup

childlogdir

user

directory

strip_ansi

environment

identifier

[supervisord] Section Example¶

[supervisord]
logfile = /tmp/supervisord.log
logfile_maxbytes = 50MB
logfile_backups=10
loglevel = info
pidfile = /tmp/supervisord.pid
nodaemon = false
minfds = 1024
minprocs = 200
umask = 022
user = chrism
identifier = supervisor
directory = /tmp
nocleanup = true
childlogdir = /tmp
strip_ansi = false
environment = KEY1="value1",KEY2="value2"

[supervisorctl] Section Settings¶

[supervisorctl] Section Values¶

serverurl

username

password

prompt

history_file

[supervisorctl] Section Example¶

[supervisorctl]
serverurl = unix:///tmp/supervisor.sock
username = chris
password = 123
prompt = mysupervisor

[program:x] Section Settings¶

The configuration file must contain one or more program sections in order for supervisord to know which programs it should start and control. The header value is composite value. It is the word "program", followed directly by a colon, then the program name. A header value of [program:foo] describes a program with the name of "foo". The name is used within client applications that control the processes that are created as a result of this configuration. It is an error to create a program section that does not have a name. The name must not include a colon character or a bracket character. The value of the name is used as the value for the %(program_name)s string expression expansion within other values where specified.

NOTE:

[program:x] Section Values¶

command

process_name

numprocs

numprocs_start

priority

autostart

startsecs

startretries

autorestart

exitcodes

stopsignal

stopwaitsecs

stopasgroup

killasgroup

user

redirect_stderr

stdout_logfile

stdout_logfile_maxbytes

stdout_logfile_backups

stdout_capture_maxbytes

stdout_events_enabled

stderr_logfile

stderr_logfile_maxbytes

stderr_logfile_backups

stderr_capture_maxbytes

stderr_events_enabled

environment

directory

umask

serverurl

[program:x] Section Example¶

[program:cat]
command=/bin/cat
process_name=%(program_name)s
numprocs=1
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=10
startretries=3
exitcodes=0,2
stopsignal=TERM
stopwaitsecs=10
stopasgroup=false
killasgroup=false
user=chrism
redirect_stderr=false
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_capture_maxbytes=1MB
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_capture_maxbytes=1MB
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO

[include] Section Settings¶

The supervisord.conf file may contain a section named [include]. If the configuration file contains an [include] section, it must contain a single key named "files". The values in this key specify other configuration files to be included within the configuration.

[include] Section Values¶

files

[include] Section Example¶

[include]
files = /an/absolute/filename.conf /an/absolute/*.conf foo.conf config??.conf

[group:x] Section Settings¶

It is often useful to group "homogeneous" process groups (aka "programs") together into a "heterogeneous" process group so they can be controlled as a unit from Supervisor's various controller interfaces.

To place programs into a group so you can treat them as a unit, define a [group:x] section in your configuration file. The group header value is a composite. It is the word "group", followed directly by a colon, then the group name. A header value of [group:foo] describes a group with the name of "foo". The name is used within client applications that control the processes that are created as a result of this configuration. It is an error to create a group section that does not have a name. The name must not include a colon character or a bracket character.

For a [group:x], there must be one or more [program:x] sections elsewhere in your configuration file, and the group must refer to them by name in the programs value.

If "homogeneous" process groups (represented by program sections) are placed into a "heterogeneous" group via [group:x] section's programs line, the homogeneous groups that are implied by the program section will not exist at runtime in supervisor. Instead, all processes belonging to each of the homogeneous groups will be placed into the heterogeneous group. For example, given the following group configuration:

[group:foo]
programs=bar,baz
priority=999

Given the above, at supervisord startup, the bar and baz homogeneous groups will not exist, and the processes that would have been under them will now be moved into the foo group.

[group:x] Section Values¶

programs

priority

[group:x] Section Example¶

[group:foo]
programs=bar,baz
priority=999

[fcgi-program:x] Section Settings¶

Supervisor can manage groups of FastCGI processes that all listen on the same socket. Until now, deployment flexibility for FastCGI was limited. To get full process management, you could use mod_fastcgi under Apache but then you were stuck with Apache's inefficient concurrency model of one process or thread per connection. In addition to requiring more CPU and memory resources, the process/thread per connection model can be quickly saturated by a slow resource, preventing other resources from being served. In order to take advantage of newer event-driven web servers such as lighttpd or nginx which don't include a built-in process manager, you had to use scripts like cgi-fcgi or spawn-fcgi. These can be used in conjunction with a process manager such as supervisord or daemontools but require each FastCGI child process to bind to its own socket. The disadvantages of this are: unnecessarily complicated web server configuration, ungraceful restarts, and reduced fault tolerance. With fewer sockets to configure, web server configurations are much smaller if groups of FastCGI processes can share sockets. Shared sockets allow for graceful restarts because the socket remains bound by the parent process while any of the child processes are being restarted. Finally, shared sockets are more fault tolerant because if a given process fails, other processes can continue to serve inbound connections.

With integrated FastCGI spawning support, Supervisor gives you the best of both worlds. You get full-featured process management with groups of FastCGI processes sharing sockets without being tied to a particular web server. It's a clean separation of concerns, allowing the web server and the process manager to each do what they do best.

NOTE:

All the options available to [program:x] sections are also respected by fcgi-program sections.

[fcgi-program:x] Section Values¶

[fcgi-program:x] sections have a single key which [program:x] sections do not have.

socket

socket_owner

socket_mode

Consult [program:x] Section Settings for other allowable keys, delta the above constraints and additions.

[fcgi-program:x] Section Example¶

[fcgi-program:fcgiprogramname]
command=/usr/bin/example.fcgi
socket=unix:///var/run/supervisor/%(program_name)s.sock
socket_owner=chrism
socket_mode=0700
process_name=%(program_name)s_%(process_num)02d
numprocs=5
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=1
startretries=3
exitcodes=0,2
stopsignal=QUIT
stopasgroup=false
killasgroup=false
stopwaitsecs=10
user=chrism
redirect_stderr=true
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO

[eventlistener:x] Section Settings¶

Supervisor allows specialized homogeneous process groups ("event listener pools") to be defined within the configuration file. These pools contain processes that are meant to receive and respond to event notifications from supervisor's event system. See events for an explanation of how events work and how to implement programs that can be declared as event listeners.

Note that all the options available to [program:x] sections are respected by eventlistener sections except for stdout_capture_maxbytes and stderr_capture_maxbytes (event listeners cannot emit process communication events, see capture_mode).

[eventlistener:x] Section Values¶

[eventlistener:x] sections have a few keys which [program:x] sections do not have.

buffer_size

events

result_handler

Consult [program:x] Section Settings for other allowable keys, delta the above constraints and additions.

[eventlistener:x] Section Example¶

[eventlistener:theeventlistenername]
command=/bin/eventlistener
process_name=%(program_name)s_%(process_num)02d
numprocs=5
events=PROCESS_STATE
buffer_size=10
directory=/tmp
umask=022
priority=-1
autostart=true
autorestart=unexpected
startsecs=1
startretries=3
exitcodes=0,2
stopsignal=QUIT
stopwaitsecs=10
stopasgroup=false
killasgroup=false
user=chrism
redirect_stderr=false
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO

[rpcinterface:x] Section Settings¶

Adding rpcinterface:x settings in the configuration file is only useful for people who wish to extend supervisor with additional custom behavior.

In the sample config file, there is a section which is named [rpcinterface:supervisor]. By default it looks like the following.

[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface

The [rpcinterface:supervisor] section must remain in the configuration for the standard setup of supervisor to work properly. If you don't want supervisor to do anything it doesn't already do out of the box, this is all you need to know about this type of section.

However, if you wish to add rpc interface namespaces in order to customize supervisor, you may add additional [rpcinterface:foo] sections, where "foo" represents the namespace of the interface (from the web root), and the value named by supervisor.rpcinterface_factory is a factory callable which should have a function signature that accepts a single positional argument supervisord and as many keyword arguments as required to perform configuration. Any extra key/value pairs defined within the [rpcinterface:x] section will be passed as keyword arguments to the factory.

Here's an example of a factory function, created in the __init__.py file of the Python package my.package.

from my.package.rpcinterface import AnotherRPCInterface
def make_another_rpcinterface(supervisord, **config):


    retries = int(config.get('retries', 0))


    another_rpc_interface = AnotherRPCInterface(supervisord, retries)


    return another_rpc_interface

And a section in the config file meant to configure it.

[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1

[rpcinterface:x] Section Values¶

supervisor.rpcinterface_factory

[rpcinterface:x] Section Example¶

[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1

Glossary¶