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]
file = /tmp/supervisor.sock
chmod = 0777
chown= nobody:nogroup
username = user
password = 123
      

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]
port = 127.0.0.1:9001
username = user
password = 123
      

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]
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
      

The configuration file may contain settings for the supervisorctl interactive shell program. These options are listed below.

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

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

A [program:x] section actually represents a "homogeneous process group" to supervisor (as of 3.0). The members of the group are defined by the combination of the numprocs and process_name parameters in the configuration. By default, if numprocs and process_name are left unchanged from their defaults, the group represented by [program:x] will be named x and will have a single process named x in it. This provides a modicum of backwards compatibility with older supervisor releases, which did not treat program sections as homogeneous process group defnitions.

But for instance, if you have a [program:foo] section with a numprocs of 3 and a process_name expression of %(program_name)s_%(process_num)02d, the "foo" group will contain three processes, named foo_00, foo_01, and foo_02. This makes it possible to start a number of very similar processes using a single [program:x] section. All logfile names, all environment strings, and the command of programs can also contain similar Python string expressions, to pass slightly different parameters to each process.

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

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

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

It is often useful to group "homogeneous" processes 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" program 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
        

... 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:foo]
programs=bar,baz
priority=999
      

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 it's own socket. The disadvantages of this are: unnecessarily complicated web server configuration, ungraceful restarts, and reduced fault tolerance. With less 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 that all the options available to [program:x] sections are also respected by fcgi-program sections.

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

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

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

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 "Supervisor Events" elsewhere in this document 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 and Process Communication Events" elsewhere in this document).

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

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

[eventlistener:theeventlistenername]
command=/bin/eventlistener
process_name=%(program_name)s_%(process_num)02d
numprocs=5
events=PROCESS_STATE_CHANGE
buffer_size=10
priority=-1
autostart=true
autorestart=unexpected
startsecs=1
startretries=3
exitcodes=0,2
stopsignal=QUIT
stopwaitsecs=10
user=chrism
redirect_stderr=true
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups
environment=A=1,B=2
      

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:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1