Introduction¶

Overview¶

Supervisor is a client/server system that allows its users to control a number of processes on UNIX-like operating systems. It was inspired by the following:

Convenience

Accuracy

Delegation

Process Groups

Features¶

Simple

Centralized

Efficient

Extensible

Compatible

Proven

Supervisor Components¶

supervisord

supervisorctl

Web Server

XML-RPC Interface

Platform Requirements¶

Supervisor has been tested and is known to run on Linux (Ubuntu 9.10), Mac OS X (10.4/10.5/10.6), and Solaris (10 for Intel) and FreeBSD 6.1. It will likely work fine on most UNIX systems.

Supervisor will not run at all under any version of Windows.

Supervisor is known to work with Python 2.4 or later but will not work under any version of Python 3.

Running Supervisor¶

This section makes reference to a BINDIR when explaining how to run the supervisord and supervisorctl commands. This is the "bindir" directory that your Python installation has been configured with. For example, for an installation of Python installed via ./configure --prefix=/usr/local/py; make; make install, BINDIR would be /usr/local/py/bin. Python interpreters on different platforms use a different BINDIR. Look at the output of setup.py install if you can't figure out where yours is.

Adding a Program¶

Before supervisord will do anything useful for you, you'll need to add at least one program section to its configuration. The program section will define a program that is run and managed when you invoke the supervisord command. To add a program, you'll need to edit the supervisord.conf file.

One of the simplest possible programs to run is the UNIX cat program. A program section that will run cat when the supervisord process starts up is shown below.

[program:foo]
command=/bin/cat

This stanza may be cut and pasted into the supervisord.conf file. This is the simplest possible program configuration, because it only names a command. Program configuration sections have many other configuration options which aren't shown here. See programx_section for more information.

Running supervisord¶

To start supervisord, run $BINDIR/supervisord. The resulting process will daemonize itself and detach from the terminal. It keeps an operations log at $CWD/supervisor.log by default.

You may start the supervisord executable in the foreground by passing the -n flag on its command line. This is useful to debug startup problems.

WARNING:

To change the set of programs controlled by supervisord, edit the supervisord.conf file and kill -HUP or otherwise restart the supervisord process. This file has several example program definitions.

The supervisord command accepts a number of command-line options. Each of these command line options overrides any equivalent value in the configuration file.

supervisord Command-Line Options¶

supervisorctl Command-Line Options¶

action [arguments]

Actions are commands like "tail" or "stop". If -i is specified or no action is specified on the command line, a "shell" interpreting actions typed interactively is started. Use the action "help" to find out about available actions.

Running supervisorctl¶

To start supervisorctl, run $BINDIR/supervisorctl. A shell will be presented that will allow you to control the processes that are currently managed by supervisord. Type "help" at the prompt to get information about the supported commands.

The supervisorctl executable may be invoked with "one time" commands when invoked with arguments from a command line. An example: supervisorctl stop all. If arguments are present on the command-line, it will prevent the interactive shell from being invoked. Instead, the command will be executed and supervisorctl will exit.

If supervisorctl is invoked in interactive mode against a supervisord that requires authentication, you will be asked for authentication credentials.

Signals¶

The supervisord program may be sent signals which cause it to perform certain actions while it's running.

You can send any of these signals to the single supervisord process id. This process id can be found in the file represented by the pidfile parameter in the [supervisord] section of the configuration file (by default it's $CWD/supervisord.pid).

Signal Handlers¶

SIGTERM

SIGINT

SIGQUIT

SIGHUP

SIGUSR2

Runtime Security¶

The developers have done their best to assure that use of a supervisord process running as root cannot lead to unintended privilege escalation. But caveat emptor. Supervisor is not as paranoid as something like DJ Bernstein's daemontools, inasmuch as supervisord allows for arbitrary path specifications in its configuration file to which data may be written. Allowing arbitrary path selections can create vulnerabilities from symlink attacks. Be careful when specifying paths in your configuration. Ensure that the supervisord configuration file cannot be read from or written to by unprivileged users and that all files installed by the supervisor package have "sane" file permission protection settings. Additionally, ensure that your PYTHONPATH is sane and that all Python standard library files have adequate file permission protections.

Running supervisord automatically on startup¶

If you are using a distribution-packaged version of Supervisor, it should already be integrated into the service management infrastructure of your distribution.

There are user-contributed scripts for various operating systems at: https://github.com/Supervisor/initscripts

There are some answers at Serverfault in case you get stuck: How to automatically start supervisord on Linux (Ubuntu)

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

Subprocesses¶

supervisord's primary purpose is to create and manage processes based on data in its configuration file. It does this by creating subprocesses. Each subprocess spawned by supervisor is managed for the entirety of its lifetime by supervisord (supervisord is the parent process of each process it creates). When a child dies, supervisor is notified of its death via the SIGCHLD signal, and it performs the appropriate operation.

Nondaemonizing of Subprocesses¶

Programs meant to be run under supervisor should not daemonize themselves. Instead, they should run in the foreground. They should not detach from the terminal from which they are started.

The easiest way to tell if a program will run in the foreground is to run the command that invokes the program from a shell prompt. If it gives you control of the terminal back, but continues running, it's daemonizing itself and that will almost certainly be the wrong way to run it under supervisor. You want to run a command that essentially requires you to press Ctrl-C to get control of the terminal back. If it gives you a shell prompt back after running it without needing to press Ctrl-C, it's not useful under supervisor. All programs have options to be run in the foreground but there's no "standard way" to do it; you'll need to read the documentation for each program.

Below are configuration file examples that are known to start common programs in "foreground" mode under Supervisor.

Examples of Program Configurations¶

Here are some "real world" program configuration examples:

Apache 2.2.6¶

[program:apache2]
command=/path/to/httpd -c "ErrorLog /dev/stdout" -DFOREGROUND
redirect_stderr=true

Two Zope 2.X instances and one ZEO server¶

[program:zeo]
command=/path/to/runzeo
priority=1
[program:zope1]
command=/path/to/instance/home/bin/runzope
priority=2
redirect_stderr=true
[program:zope2]
command=/path/to/another/instance/home/bin/runzope
priority=2
redirect_stderr=true

Postgres 8.X¶

[program:postgres]
command=/path/to/postmaster
; we use the "fast" shutdown signal SIGINT
stopsignal=INT
redirect_stderr=true

OpenLDAP slapd¶

[program:slapd]
command=/path/to/slapd -f /path/to/slapd.conf -h ldap://0.0.0.0:8888
redirect_stderr=true

Other Examples¶

Other examples of shell scripts that could be used to start services under supervisord can be found at http://thedjbway.b0llix.net/services.html. These examples are actually for daemontools but the premise is the same for supervisor.

Another collection of recipes for starting various programs in the foreground is available from http://smarden.org/runit/runscripts.html.

pidproxy Program¶

Some processes (like mysqld) ignore signals sent to the actual process which is spawned by supervisord. Instead, a "special" thread/process is created by these kinds of programs which is responsible for handling signals. This is problematic because supervisord can only kill a process which it creates itself. If a process created by supervisord creates its own child processes, supervisord cannot kill them.

Fortunately, these types of programs typically write a "pidfile" which contains the "special" process' PID, and is meant to be read and used in order to kill the process. As a workaround for this case, a special pidproxy program can handle startup of these kinds of processes. The pidproxy program is a small shim that starts a process, and upon the receipt of a signal, sends the signal to the pid provided in a pidfile. A sample configuration program entry for a pidproxy-enabled program is provided below.

[program:mysql]
command=/path/to/pidproxy /path/to/pidfile /path/to/mysqld_safe

The pidproxy program is put into your configuration's $BINDIR when supervisor is installed (it is a "console script").

Subprocess Environment¶

Subprocesses will inherit the environment of the shell used to start the supervisord program. Several environment variables will be set by supervisord itself in the child's environment also, including SUPERVISOR_ENABLED (a flag indicating the process is under supervisor control), SUPERVISOR_PROCESS_NAME (the config-file-specified process name for this process) and SUPERVISOR_GROUP_NAME (the config-file-specified process group name for the child process).

These environment variables may be overridden within the [supervisord] section config option named environment (applies to all subprocesses) or within the per- [program:x] section environment config option (applies only to the subprocess specified within the [program:x] section). These "environment" settings are additive. In other words, each subprocess' environment will consist of:

No shell is executed by supervisord when it runs a subprocess, so environment variables such as USER, PATH, HOME, SHELL, LOGNAME, etc. are not changed from their defaults or otherwise reassigned. This is particularly important to note when you are running a program from a supervisord run as root with a user= stanza in the configuration. Unlike cron, supervisord does not attempt to divine and override "fundamental" environment variables like USER, PATH, HOME, and LOGNAME when it performs a setuid to the user defined within the user= program config option. If you need to set environment variables for a particular program that might otherwise be set by a shell invocation for a particular user, you must do it explicitly within the environment= program config option. An example of setting these environment variables is as below.

[program:apache2]
command=/home/chrism/bin/httpd -c "ErrorLog /dev/stdout" -DFOREGROUND
user=chrism
environment=HOME="/home/chrism",USER="chrism"

Process States¶

A process controlled by supervisord will be in one of the below states at any given time. You may see these state names in various user interface elements in clients.

STOPPED (0)

STARTING (10)

RUNNING (20)

BACKOFF (30)

STOPPING (40)

EXITED (100)

FATAL (200)

UNKNOWN (1000)

Each process run under supervisor progresses through these states as per the following directed graph.

Logging¶

One of the main tasks that supervisord performs is logging. supervisord logs an activity log detailing what it's doing as it runs. It also logs child process stdout and stderr output to other files if configured to do so.

Activity Log¶

The activity log is the place where supervisord logs messages about its own health, its subprocess' state changes, any messages that result from events, and debug and informational messages. The path to the activity log is configured via the logfile parameter in the [supervisord] section of the configuration file, defaulting to $CWD/supervisord.log. Sample activity log traffic is shown in the example below. Some lines have been broken to better fit the screen.

Sample Activity Log Output¶

2007-09-08 14:43:22,886 DEBG 127.0.0.1:Medusa (V1.11) started at Sat Sep  8 14:43:22 2007


        Hostname: kingfish


        Port:9001
2007-09-08 14:43:22,961 INFO RPC interface 'supervisor' initialized
2007-09-08 14:43:22,961 CRIT Running without any HTTP authentication checking
2007-09-08 14:43:22,962 INFO supervisord started with pid 27347
2007-09-08 14:43:23,965 INFO spawned: 'listener_00' with pid 27349
2007-09-08 14:43:23,970 INFO spawned: 'eventgen' with pid 27350
2007-09-08 14:43:23,990 INFO spawned: 'grower' with pid 27351
2007-09-08 14:43:24,059 DEBG 'listener_00' stderr output:


 /Users/chrism/projects/supervisor/supervisor2/dev-sandbox/bin/python:


 can't open file '/Users/chrism/projects/supervisor/supervisor2/src/supervisor/scripts/osx_eventgen_listener.py':


 [Errno 2] No such file or directory
2007-09-08 14:43:24,060 DEBG fd 7 closed, stopped monitoring <PEventListenerDispatcher at 19910168 for


 <Subprocess at 18892960 with name listener_00 in state STARTING> (stdout)>
2007-09-08 14:43:24,060 INFO exited: listener_00 (exit status 2; not expected)
2007-09-08 14:43:24,061 DEBG received SIGCHLD indicating a child quit

The activity log "level" is configured in the config file via the loglevel parameter in the [supervisord] ini file section. When loglevel is set, messages of the specified priority, plus those with any higher priority are logged to the activity log. For example, if loglevel is error, messages of error and critical priority will be logged. However, if loglevel is warn, messages of warn, error, and critical will be logged.

Activity Log Levels¶

The below table describes the logging levels in more detail, ordered in highest priority to lowest. The "Config File Value" is the string provided to the loglevel parameter in the [supervisord] section of configuration file and the "Output Code" is the code that shows up in activity log output lines.

Activity Log Rotation¶

The activity log is "rotated" by supervisord based on the combination of the logfile_maxbytes and the logfile_backups parameters in the [supervisord] section of the configuration file. When the activity log reaches logfile_maxbytes bytes, the current log file is moved to a backup file and a new activity log file is created. When this happens, if the number of existing backup files is greater than or equal to logfile_backups, the oldest backup file is removed and the backup files are renamed accordingly. If the file being written to is named supervisord.log, when it exceeds logfile_maxbytes, it is closed and renamed to supervisord.log.1, and if files supervisord.log.1, supervisord.log.2 etc. exist, then they are renamed to supervisord.log.2, supervisord.log.3 etc. respectively. If logfile_maxbytes is 0, the logfile is never rotated (and thus backups are never made). If logfile_backups is 0, no backups will be kept.

Child Process Logs¶

The stdout of child processes spawned by supervisor, by default, is captured for redisplay to users of supervisorctl and other clients. If no specific logfile-related configuration is performed in a [program:x], [fcgi-program:x], or [eventlistener:x] section in the configuration file, the following is true:

The configuration keys that influence child process logging in [program:x] and [fcgi-program:x] sections are these:

redirect_stderr, stdout_logfile, stdout_logfile_maxbytes, stdout_logfile_backups, stdout_capture_maxbytes, stderr_logfile, stderr_logfile_maxbytes, stderr_logfile_backups and stderr_capture_maxbytes.

One may set stdout_logfile or stderr_logfile to the special string "syslog". In this case, logs will be routed to the syslog service instead of being saved to files.

[eventlistener:x] sections may not specify redirect_stderr, stdout_capture_maxbytes, or stderr_capture_maxbytes, but otherwise they accept the same values.

The configuration keys that influence child process logging in the [supervisord] config file section are these: childlogdir, and nocleanup.

Capture Mode¶

Capture mode is an advanced feature of Supervisor. You needn't understand capture mode unless you want to take actions based on data parsed from subprocess output.

If a [program:x] section in the configuration file defines a non-zero stdout_capture_maxbytes or stderr_capture_maxbytes parameter, each process represented by the program section may emit special tokens on its stdout or stderr stream (respectively) which will effectively cause supervisor to emit a PROCESS_COMMUNICATION event (see events for a description of events).

The process communications protocol relies on two tags, one which commands supervisor to enter "capture mode" for the stream and one which commands it to exit. When a process stream enters "capture mode", data sent to the stream will be sent to a separate buffer in memory, the "capture buffer", which is allowed to contain a maximum of capture_maxbytes bytes. During capture mode, when the buffer's length exceeds capture_maxbytes bytes, the earliest data in the buffer is discarded to make room for new data. When a process stream exits capture mode, a PROCESS_COMMUNICATION event subtype is emitted by supervisor, which may be intercepted by event listeners.

The tag to begin "capture mode" in a process stream is <!--XSUPERVISOR:BEGIN-->. The tag to exit capture mode is <!--XSUPERVISOR:END-->. The data between these tags may be arbitrary, and forms the payload of the PROCESS_COMMUNICATION event. For example, if a program is set up with a stdout_capture_maxbytes of "1MB", and it emits the following on its stdout stream:

<!--XSUPERVISOR:BEGIN-->Hello!<!--XSUPERVISOR:END-->

In this circumstance, supervisord will emit a PROCESS_COMMUNICATIONS_STDOUT event with data in the payload of "Hello!".

An example of a script (written in Python) which emits a process communication event is in the scripts directory of the supervisor package, named sample_commevent.py.

The output of processes specified as "event listeners" ([eventlistener:x] sections) is not processed this way. Output from these processes cannot enter capture mode.

Extending Supervisor's XML-RPC API¶

Supervisor can be extended with new XML-RPC APIs. Several third-party plugins already exist that can be wired into your Supervisor configuration. You may additionally write your own. Extensible XML-RPC interfaces is an advanced feature, introduced in version 3.0. You needn't understand it unless you wish to use an existing third-party RPC interface plugin or if you wish to write your own RPC interface plugin.

Configuring XML-RPC Interface Factories¶

An additional RPC interface is configured into a supervisor installation by adding a [rpcinterface:x] section in the Supervisor configuration file.

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

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

This 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 additional XML-RPC interface namespaces to a configuration of 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 written in Python which should have a function signature that accepts a single positional argument supervisord and as many keyword arguments as required to perform configuration. Any key/value pairs defined within the rpcinterface:foo section will be passed as keyword arguments to the factory. Here's an example of a factory function, created in the package my.package.

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

Glossary¶

XML-RPC API Documentation¶

To use the XML-RPC interface, connect to supervisor's HTTP port with any XML-RPC client library and run commands against it. An example of doing this using Python's xmlrpclib client library is as follows.

import xmlrpclib
server = xmlrpclib.Server('http://localhost:9001/RPC2')

You may call methods against supervisord and its subprocesses by using the supervisor namespace. An example is provided below.

server.supervisor.getState()

You can get a list of methods supported by the supervisord XML-RPC interface by using the XML-RPC system.listMethods API:

server.system.listMethods()

You can see help on a method by using the system.methodHelp API against the method:

server.system.methodHelp('supervisor.shutdown')

The supervisord XML-RPC interface also supports the XML-RPC multicall API.

You can extend supervisord functionality with new XML-RPC API methods by adding new top-level RPC interfaces as necessary. See rpcinterface_factories.

NOTE:

Status and Control¶

{'statecode': 1,


 'statename': 'RUNNING'}

Process Control¶

{'name':           'process name',


 'group':          'group name',


 'description':    'pid 18806, uptime 0:03:12'


 'start':          1200361776,


 'stop':           0,


 'now':            1200361812,


 'state':          1,


 'statename':      'RUNNING',


 'spawnerr':       '',


 'exitstatus':     0,


 'logfile':        '/path/to/stdout-log', # deprecated, b/c only


 'stdout_logfile': '/path/to/stdout-log',


 'stderr_logfile': '/path/to/stderr-log',


 'pid':            1}

Process Logging¶

System Methods¶