supervisord¶

The server process uses a configuration file. This is typically located in /etc/supervisord.conf. This configuration file is a "Windows-INI" style config file. It is important to keep this file secure via proper filesystem permissions because it may contain unencrypted usernames and passwords.

Running Supervisor¶

Adding a Program¶

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¶

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¶

Signals¶

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¶

SIGINT

SIGQUIT

SIGHUP

SIGUSR2

Runtime Security¶

Running supervisord automatically on startup¶

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)

Nondaemonizing of Subprocesses¶

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¶

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¶

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

pidproxy Program¶

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¶

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¶

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.

Glossary¶