.\" Man page generated from reStructuredText.
.
.TH "SUPERVISOR" "1" "December 10, 2015" "3.2.0" "Supervisor"
.SH NAME
supervisor \- Supervisor Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Supervisor is a client/server system that allows its users to monitor
and control a number of processes on UNIX\-like operating systems.
.sp
It shares some of the same goals of programs like launchd,
daemontools, and runit\&. Unlike some of these programs,
it is not meant to be run as a substitute for \fBinit\fP as "process id
1". Instead it is meant to be used to control processes related to a
project or a customer, and is meant to start like any other program at
boot time.
.SH NARRATIVE DOCUMENTATION
.SS Introduction
.SS Overview
.sp
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:
.sp
Convenience
.INDENT 0.0
.INDENT 3.5
It is often inconvenient to need to write \fBrc.d\fP scripts for every
single process instance.  \fBrc.d\fP scripts are a great
lowest\-common\-denominator form of process
initialization/autostart/management, but they can be painful to
write and maintain.  Additionally, \fBrc.d\fP scripts cannot
automatically restart a crashed process and many programs do not
restart themselves properly on a crash.  Supervisord starts
processes as its subprocesses, and can be configured to
automatically restart them on a crash.  It can also automatically be
configured to start processes on its own invocation.
.UNINDENT
.UNINDENT
.sp
Accuracy
.INDENT 0.0
.INDENT 3.5
It\(aqs often difficult to get accurate up/down status on processes on
UNIX.  Pidfiles often lie.  Supervisord starts processes as
subprocesses, so it always knows the true up/down status of its
children and can be queried conveniently for this data.
.UNINDENT
.UNINDENT
.sp
Delegation
.INDENT 0.0
.INDENT 3.5
Users who need to control process state often need only to do that.
They don\(aqt want or need full\-blown shell access to the machine on
which the processes are running.  Processes which listen on "low"
TCP ports often need to be started and restarted as the root user (a
UNIX misfeature).  It\(aqs usually the case that it\(aqs perfectly fine to
allow "normal" people to stop or restart such a process, but
providing them with shell access is often impractical, and providing
them with root access or sudo access is often impossible.  It\(aqs also
(rightly) difficult to explain to them why this problem exists.  If
supervisord is started as root, it is possible to allow "normal"
users to control such processes without needing to explain the
intricacies of the problem to them.  Supervisorctl allows a very
limited form of access to the machine, essentially allowing users to
see process status and control supervisord\-controlled subprocesses
by emitting "stop", "start", and "restart" commands from a simple
shell or web UI.
.UNINDENT
.UNINDENT
.sp
Process Groups
.INDENT 0.0
.INDENT 3.5
Processes often need to be started and stopped in groups, sometimes
even in a "priority order".  It\(aqs often difficult to explain to
people how to do this.  Supervisor allows you to assign priorities
to processes, and allows user to emit commands via the supervisorctl
client like "start all", and "restart all", which starts them in the
preassigned priority order.  Additionally, processes can be grouped
into "process groups" and a set of logically related processes can
be stopped and started as a unit.
.UNINDENT
.UNINDENT
.SS Features
.sp
Simple
.INDENT 0.0
.INDENT 3.5
Supervisor is configured through a simple INI\-style config file
that’s easy to learn. It provides many per\-process options that make
your life easier like restarting failed processes and automatic log
rotation.
.UNINDENT
.UNINDENT
.sp
Centralized
.INDENT 0.0
.INDENT 3.5
Supervisor provides you with one place to start, stop, and monitor
your processes. Processes can be controlled individually or in
groups. You can configure Supervisor to provide a local or remote
command line and web interface.
.UNINDENT
.UNINDENT
.sp
Efficient
.INDENT 0.0
.INDENT 3.5
Supervisor starts its subprocesses via fork/exec and subprocesses
don’t daemonize. The operating system signals Supervisor immediately
when a process terminates, unlike some solutions that rely on
troublesome PID files and periodic polling to restart failed
processes.
.UNINDENT
.UNINDENT
.sp
Extensible
.INDENT 0.0
.INDENT 3.5
Supervisor has a simple event notification protocol that programs
written in any language can use to monitor it, and an XML\-RPC
interface for control. It is also built with extension points that
can be leveraged by Python developers.
.UNINDENT
.UNINDENT
.sp
Compatible
.INDENT 0.0
.INDENT 3.5
Supervisor works on just about everything except for Windows. It is
tested and supported on Linux, Mac OS X, Solaris, and FreeBSD. It is
written entirely in Python, so installation does not require a C
compiler.
.UNINDENT
.UNINDENT
.sp
Proven
.INDENT 0.0
.INDENT 3.5
While Supervisor is very actively developed today, it is not new
software. Supervisor has been around for years and is already in use
on many servers.
.UNINDENT
.UNINDENT
.SS Supervisor Components
.sp
\fBsupervisord\fP
.INDENT 0.0
.INDENT 3.5
The server piece of supervisor is named \fBsupervisord\fP\&.  It
is responsible for starting child programs at its own invocation,
responding to commands from clients, restarting crashed or exited
subprocesseses, logging its subprocess \fBstdout\fP and \fBstderr\fP
output, and generating and handling "events" corresponding to points
in subprocess lifetimes.
.sp
The server process uses a configuration file.  This is typically
located in \fB/etc/supervisord.conf\fP\&.  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.
.UNINDENT
.UNINDENT
.sp
\fBsupervisorctl\fP
.INDENT 0.0
.INDENT 3.5
The command\-line client piece of the supervisor is named
\fBsupervisorctl\fP\&.  It provides a shell\-like interface to the
features provided by \fBsupervisord\fP\&.  From
\fBsupervisorctl\fP, a user can connect to different
\fBsupervisord\fP processes, get status on the subprocesses
controlled by, stop and start subprocesses of, and get lists of
running processes of a \fBsupervisord\fP\&.
.sp
The command\-line client talks to the server across a UNIX domain
socket or an internet (TCP) socket.  The server can assert that the
user of a client should present authentication credentials before it
allows him to perform commands.  The client process typically uses
the same configuration file as the server but any configuration file
with a \fB[supervisorctl]\fP section in it will work.
.UNINDENT
.UNINDENT
.sp
Web Server
.INDENT 0.0
.INDENT 3.5
A (sparse) web user interface with functionality comparable to
\fBsupervisorctl\fP may be accessed via a browser if you start
\fBsupervisord\fP against an internet socket.  Visit the server
URL (e.g. \fBhttp://localhost:9001/\fP) to view and control process
status through the web interface after activating the configuration
file\(aqs \fB[inet_http_server]\fP section.
.UNINDENT
.UNINDENT
.sp
XML\-RPC Interface
.INDENT 0.0
.INDENT 3.5
The same HTTP server which serves the web UI serves up an XML\-RPC
interface that can be used to interrogate and control supervisor and
the programs it runs.  See xml_rpc\&.
.UNINDENT
.UNINDENT
.SS Platform Requirements
.sp
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.
.sp
Supervisor will \fInot\fP run at all under any version of Windows.
.sp
Supervisor is known to work with Python 2.4 or later but will not work
under any version of Python 3.
.SS Running Supervisor
.sp
This section makes reference to a \fBBINDIR\fP when explaining how
to run the \fBsupervisord\fP and \fBsupervisorctl\fP
commands.  This is the "bindir" directory that your Python
installation has been configured with.  For example, for an
installation of Python installed via \fB\&./configure
\-\-prefix=/usr/local/py; make; make install\fP, \fBBINDIR\fP would
be \fB/usr/local/py/bin\fP\&. Python interpreters on different
platforms use a different \fBBINDIR\fP\&.  Look at the output of
\fBsetup.py install\fP if you can\(aqt figure out where yours is.
.SS Adding a Program
.sp
Before \fBsupervisord\fP will do anything useful for you, you\(aqll
need to add at least one \fBprogram\fP section to its configuration.
The \fBprogram\fP section will define a program that is run and managed
when you invoke the \fBsupervisord\fP command.  To add a program,
you\(aqll need to edit the \fBsupervisord.conf\fP file.
.sp
One of the simplest possible programs to run is the UNIX
\fBcat\fP program.  A \fBprogram\fP section that will run \fBcat\fP
when the \fBsupervisord\fP process starts up is shown below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[program:foo]
command=/bin/cat
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This stanza may be cut and pasted into the \fBsupervisord.conf\fP
file.  This is the simplest possible program configuration, because it
only names a command.  Program configuration sections have many other
configuration options which aren\(aqt shown here.  See
programx_section for more information.
.SS Running \fBsupervisord\fP
.sp
To start \fBsupervisord\fP, run \fB$BINDIR/supervisord\fP\&.  The
resulting process will daemonize itself and detach from the terminal.
It keeps an operations log at \fB$CWD/supervisor.log\fP by default.
.sp
You may start the \fBsupervisord\fP executable in the foreground
by passing the \fB\-n\fP flag on its command line.  This is useful to
debug startup problems.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
When \fBsupervisord\fP starts up, it will search for its
configuration file in default locations \fIincluding the current working
directory\fP\&.  If you are security\-conscious you will probably want to
specify a "\-c" argument after the \fBsupervisord\fP command
specifying an absolute path to a configuration file to ensure that someone
doesn\(aqt trick you into running supervisor from within a directory that
contains a rogue \fBsupervisord.conf\fP file.  A warning is emitted when
supervisor is started as root without this \fB\-c\fP argument.
.UNINDENT
.UNINDENT
.sp
To change the set of programs controlled by \fBsupervisord\fP,
edit the \fBsupervisord.conf\fP file and \fBkill \-HUP\fP or otherwise
restart the \fBsupervisord\fP process.  This file has several
example program definitions.
.sp
The \fBsupervisord\fP command accepts a number of command\-line
options.  Each of these command line options overrides any equivalent
value in the configuration file.
.SS \fBsupervisord\fP Command\-Line Options
.INDENT 0.0
.TP
.BI \-c \ FILE\fP,\fB \ \-\-configuration\fB= FILE
The path to a \fBsupervisord\fP configuration file.
.TP
.B \-n\fP,\fB  \-\-nodaemon
Run \fBsupervisord\fP in the foreground.
.TP
.B \-h\fP,\fB  \-\-help
Show \fBsupervisord\fP command help.
.TP
.BI \-u \ USER\fP,\fB \ \-\-user\fB= USER
UNIX username or numeric user id.  If \fBsupervisord\fP is
started as the root user, setuid to this user as soon as possible
during startup.
.TP
.BI \-m \ OCTAL\fP,\fB \ \-\-umask\fB= OCTAL
Octal number (e.g. 022) representing the umask that should
be used by \fBsupervisord\fP after it starts.
.TP
.BI \-d \ PATH\fP,\fB \ \-\-directory\fB= PATH
When supervisord is run as a daemon, cd to this directory before
daemonizing.
.TP
.BI \-l \ FILE\fP,\fB \ \-\-logfile\fB= FILE
Filename path to use as the supervisord activity log.
.TP
.BI \-y \ BYTES\fP,\fB \ \-\-logfile_maxbytes\fB= BYTES
Max size of the supervisord activity log file before a rotation
occurs.  The value is suffix\-multiplied, e.g "1" is one byte, "1MB"
is 1 megabyte, "1GB" is 1 gigabyte.
.TP
.BI \-y \ NUM\fP,\fB \ \-\-logfile_backups\fB= NUM
Number of backup copies of the supervisord activity log to keep
around.  Each logfile will be of size \fBlogfile_maxbytes\fP\&.
.TP
.BI \-e \ LEVEL\fP,\fB \ \-\-loglevel\fB= LEVEL
The logging level at which supervisor should write to the activity
log.  Valid levels are \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarn\fP,
\fBerror\fP, and \fBcritical\fP\&.
.TP
.BI \-j \ FILE\fP,\fB \ \-\-pidfile\fB= FILE
The filename to which supervisord should write its pid file.
.TP
.BI \-i \ STRING\fP,\fB \ \-\-identifier\fB= STRING
Arbitrary string identifier exposed by various client UIs for this
instance of supervisor.
.TP
.BI \-q \ PATH\fP,\fB \ \-\-childlogdir\fB= PATH
A path to a directory (it must already exist) where supervisor will
write its \fBAUTO\fP \-mode child process logs.
.TP
.B \-k\fP,\fB  \-\-nocleanup
Prevent \fBsupervisord\fP from performing cleanup (removal of
old \fBAUTO\fP process log files) at startup.
.TP
.BI \-a \ NUM\fP,\fB \ \-\-minfds\fB= NUM
The minimum number of file descriptors that must be available to
the supervisord process before it will start successfully.
.TP
.B \-t\fP,\fB  \-\-strip_ansi
Strip ANSI escape sequences from all child log process.
.TP
.B \-v\fP,\fB  \-\-version
Print the supervisord version number out to stdout and exit.
.TP
.BI \-\-profile_options\fB= LIST
Comma\-separated options list for profiling.  Causes
\fBsupervisord\fP to run under a profiler, and output results
based on the options, which is a comma\-separated list of the
following: \fBcumulative\fP, \fBcalls\fP, \fBcallers\fP\&.
E.g. \fBcumulative,callers\fP\&.
.TP
.BI \-\-minprocs\fB= NUM
The minimum number of OS process slots that must be available to
the supervisord process before it will start successfully.
.UNINDENT
.SS \fBsupervisorctl\fP Command\-Line Options
.INDENT 0.0
.TP
.B \-c\fP,\fB  \-\-configuration
Configuration file path (default /etc/supervisord.conf)
.TP
.B \-h\fP,\fB  \-\-help
Print usage message and exit
.TP
.B \-i\fP,\fB  \-\-interactive
Start an interactive shell after executing commands
.TP
.BI \-s\fP,\fB  \-\-serverurl \ URL
URL on which supervisord server is listening (default "\fI\%http://localhost:9001\fP").
.TP
.B \-u\fP,\fB  \-\-username
Username to use for authentication with server
.TP
.B \-p\fP,\fB  \-\-password
Password to use for authentication with server
.TP
.B \-r\fP,\fB  \-\-history\-file
Keep a readline history (if readline is available)
.UNINDENT
.sp
\fIaction [arguments]\fP
.sp
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.
.SS Running \fBsupervisorctl\fP
.sp
To start \fBsupervisorctl\fP, run \fB$BINDIR/supervisorctl\fP\&.  A
shell will be presented that will allow you to control the processes
that are currently managed by \fBsupervisord\fP\&.  Type "help" at
the prompt to get information about the supported commands.
.sp
The \fBsupervisorctl\fP executable may be invoked with "one time"
commands when invoked with arguments from a command line.  An example:
\fBsupervisorctl stop all\fP\&.  If arguments are present on the
command\-line, it will prevent the interactive shell from being
invoked.  Instead, the command will be executed and
\fBsupervisorctl\fP will exit.
.sp
If \fBsupervisorctl\fP is invoked in interactive mode against a
\fBsupervisord\fP that requires authentication, you will be asked
for authentication credentials.
.SS Signals
.sp
The \fBsupervisord\fP program may be sent signals which cause it
to perform certain actions while it\(aqs running.
.sp
You can send any of these signals to the single \fBsupervisord\fP
process id.  This process id can be found in the file represented by
the \fBpidfile\fP parameter in the \fB[supervisord]\fP section of the
configuration file (by default it\(aqs \fB$CWD/supervisord.pid\fP).
.SS Signal Handlers
.sp
\fBSIGTERM\fP
.INDENT 0.0
.INDENT 3.5
\fBsupervisord\fP and all its subprocesses will shut down.
This may take several seconds.
.UNINDENT
.UNINDENT
.sp
\fBSIGINT\fP
.INDENT 0.0
.INDENT 3.5
\fBsupervisord\fP and all its subprocesses will shut down.
This may take several seconds.
.UNINDENT
.UNINDENT
.sp
\fBSIGQUIT\fP
.INDENT 0.0
.INDENT 3.5
\fBsupervisord\fP and all its subprocesses will shut down.
This may take several seconds.
.UNINDENT
.UNINDENT
.sp
\fBSIGHUP\fP
.INDENT 0.0
.INDENT 3.5
\fBsupervisord\fP will stop all processes, reload the
configuration from the first config file it finds, and restart all
processes.
.UNINDENT
.UNINDENT
.sp
\fBSIGUSR2\fP
.INDENT 0.0
.INDENT 3.5
\fBsupervisord\fP will close and reopen the main activity log
and all child log files.
.UNINDENT
.UNINDENT
.SS Runtime Security
.sp
The developers have done their best to assure that use of a
\fBsupervisord\fP process running as root cannot lead to
unintended privilege escalation.  But \fBcaveat emptor\fP\&.  Supervisor
is not as paranoid as something like DJ Bernstein\(aqs
daemontools, inasmuch as \fBsupervisord\fP 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 \fBsupervisord\fP
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 \fBPYTHONPATH\fP is sane and that all Python standard
library files have adequate file permission protections.
.SS Running \fBsupervisord\fP automatically on startup
.sp
If you are using a distribution\-packaged version of Supervisor, it should
already be integrated into the service management infrastructure of your
distribution.
.sp
There are user\-contributed scripts for various operating systems at:
\fI\%https://github.com/Supervisor/initscripts\fP
.sp
There are some answers at Serverfault in case you get stuck:
\fI\%How to automatically start supervisord on Linux (Ubuntu)\fP
.SS Configuration File
.sp
The Supervisor configuration file is conventionally named
\fBsupervisord.conf\fP\&.  It is used by both \fBsupervisord\fP
and \fBsupervisorctl\fP\&.  If either application is started
without the \fB\-c\fP option (the option which is used to tell the
application the configuration filename explicitly), the application
will look for a file named \fBsupervisord.conf\fP within the
following locations, in the specified order.  It will use the first
file it finds.
.INDENT 0.0
.IP 1. 3
\fB$CWD/supervisord.conf\fP
.IP 2. 3
\fB$CWD/etc/supervisord.conf\fP
.IP 3. 3
\fB/etc/supervisord.conf\fP
.IP 4. 3
\fB\&../etc/supervisord.conf\fP (Relative to the executable)
.IP 5. 3
\fB\&../supervisord.conf\fP (Relative to the executable)
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Some distributions have packaged Supervisor with their own
customizations.  These modified versions of Supervisor may load the
configuration file from locations other than those described here.
Notably, Ubuntu packages have been found that use
\fB/etc/supervisor/supervisord.conf\fP\&.
.UNINDENT
.UNINDENT
.SS File Format
.sp
\fBsupervisord.conf\fP is a Windows\-INI\-style (Python ConfigParser)
file.  It has sections (each denoted by a \fB[header]\fP) and key / value
pairs within the sections.  The sections and their allowable values
are described below.
.SS Environment Variables
.sp
Environment variables that are present in the environment at the time that
\fBsupervisord\fP is started can be used in the configuration file
using the Python string expression syntax \fB%(ENV_X)s\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[program:example]
command=/usr/bin/example \-\-loglevel=%(ENV_LOGLEVEL)s
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the example above, the expression \fB%(ENV_LOGLEVEL)s\fP would be expanded
to the value of the environment variable \fBLOGLEVEL\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In Supervisor 3.2 and later, \fB%(ENV_X)s\fP expressions are supported in
all options.  In prior versions, some options support them, but most
do not.  See the documentation for each option below.
.UNINDENT
.UNINDENT
.SS \fB[unix_http_server]\fP Section Settings
.sp
The \fBsupervisord.conf\fP file contains a section named
\fB[unix_http_server]\fP under which configuration parameters for an
HTTP server that listens on a UNIX domain socket should be inserted.
If the configuration file has no \fB[unix_http_server]\fP section, a
UNIX domain socket HTTP server will not be started.  The allowable
configuration values are as follows.
.SS \fB[unix_http_server]\fP Section Values
.sp
\fBfile\fP
.INDENT 0.0
.INDENT 3.5
A path to a UNIX domain socket (e.g. \fB/tmp/supervisord.sock\fP)
on which supervisor will listen for HTTP/XML\-RPC requests.
\fBsupervisorctl\fP uses XML\-RPC to communicate with
\fBsupervisord\fP over this port.  This option can include the
value \fB%(here)s\fP, which expands to the directory in which the
\fBsupervisord\fP configuration file was found.
.sp
\fIDefault\fP:  None.
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBchmod\fP
.INDENT 0.0
.INDENT 3.5
Change the UNIX permission mode bits of the UNIX domain socket to
this value at startup.
.sp
\fIDefault\fP: \fB0700\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBchown\fP
.INDENT 0.0
.INDENT 3.5
Change the user and group of the socket file to this value.  May be
a UNIX username (e.g. \fBchrism\fP) or a UNIX username and group
separated by a colon (e.g. \fBchrism:wheel\fP).
.sp
\fIDefault\fP:  Use the username and group of the user who starts supervisord.
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBusername\fP
.INDENT 0.0
.INDENT 3.5
The username required for authentication to this HTTP server.
.sp
\fIDefault\fP:  No username required.
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBpassword\fP
.INDENT 0.0
.INDENT 3.5
The password required for authentication to this HTTP server.  This
can be a cleartext password, or can be specified as a SHA\-1 hash if
prefixed by the string \fB{SHA}\fP\&.  For example,
\fB{SHA}82ab876d1387bfafe46cc1c8a2ef074eae50cb1d\fP is the SHA\-stored
version of the password "thepassword".
.sp
Note that hashed password must be in hex format.
.sp
\fIDefault\fP:  No password required.
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.SS \fB[unix_http_server]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[unix_http_server]
file = /tmp/supervisor.sock
chmod = 0777
chown= nobody:nogroup
username = user
password = 123
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[inet_http_server]\fP Section Settings
.sp
The \fBsupervisord.conf\fP file contains a section named
\fB[inet_http_server]\fP under which configuration parameters for an
HTTP server that listens on a TCP (internet) socket should be
inserted.  If the configuration file has no \fB[inet_http_server]\fP
section, an inet HTTP server will not be started.  The allowable
configuration values are as follows.
.SS \fB[inet_http_server]\fP Section Values
.sp
\fBport\fP
.INDENT 0.0
.INDENT 3.5
A TCP host:port value or (e.g. \fB127.0.0.1:9001\fP) on which
supervisor will listen for HTTP/XML\-RPC requests.
\fBsupervisorctl\fP will use XML\-RPC to communicate with
\fBsupervisord\fP over this port.  To listen on all interfaces
in the machine, use \fB:9001\fP or \fB*:9001\fP\&.
.sp
\fIDefault\fP:  No default.
.sp
\fIRequired\fP:  Yes.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBusername\fP
.INDENT 0.0
.INDENT 3.5
The username required for authentication to this HTTP server.
.sp
\fIDefault\fP:  No username required.
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBpassword\fP
.INDENT 0.0
.INDENT 3.5
The password required for authentication to this HTTP server.  This
can be a cleartext password, or can be specified as a SHA\-1 hash if
prefixed by the string \fB{SHA}\fP\&.  For example,
\fB{SHA}82ab876d1387bfafe46cc1c8a2ef074eae50cb1d\fP is the SHA\-stored
version of the password "thepassword".
.sp
Note that hashed password must be in hex format.
.sp
\fIDefault\fP:  No password required.
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.SS \fB[inet_http_server]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[inet_http_server]
port = 127.0.0.1:9001
username = user
password = 123
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[supervisord]\fP Section Settings
.sp
The \fBsupervisord.conf\fP file contains a section named
\fB[supervisord]\fP in which global settings related to the
\fBsupervisord\fP process should be inserted.  These are as
follows.
.SS \fB[supervisord]\fP Section Values
.sp
\fBlogfile\fP
.INDENT 0.0
.INDENT 3.5
The path to the activity log of the supervisord process.  This
option can include the value \fB%(here)s\fP, which expands to the
directory in which the supervisord configuration file was found.
.sp
\fIDefault\fP:  \fB$CWD/supervisord.log\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBlogfile_maxbytes\fP
.INDENT 0.0
.INDENT 3.5
The maximum number of bytes that may be consumed by the activity log
file before it is rotated (suffix multipliers like "KB", "MB", and
"GB" can be used in the value).  Set this value to 0 to indicate an
unlimited log size.
.sp
\fIDefault\fP:  50MB
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBlogfile_backups\fP
.INDENT 0.0
.INDENT 3.5
The number of backups to keep around resulting from activity log
file rotation.  If set to 0, no backups will be kept.
.sp
\fIDefault\fP:  10
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBloglevel\fP
.INDENT 0.0
.INDENT 3.5
The logging level, dictating what is written to the supervisord
activity log.  One of \fBcritical\fP, \fBerror\fP, \fBwarn\fP, \fBinfo\fP,
\fBdebug\fP, \fBtrace\fP, or \fBblather\fP\&.  Note that at log level
\fBdebug\fP, the supervisord log file will record the stderr/stdout
output of its child processes and extended info info about process
state changes, which is useful for debugging a process which isn\(aqt
starting properly.  See also: activity_log_levels\&.
.sp
\fIDefault\fP:  info
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBpidfile\fP
.INDENT 0.0
.INDENT 3.5
The location in which supervisord keeps its pid file.  This option
can include the value \fB%(here)s\fP, which expands to the directory
in which the supervisord configuration file was found.
.sp
\fIDefault\fP:  \fB$CWD/supervisord.pid\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBumask\fP
.INDENT 0.0
.INDENT 3.5
The umask of the supervisord process.
.sp
\fIDefault\fP:  \fB022\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBnodaemon\fP
.INDENT 0.0
.INDENT 3.5
If true, supervisord will start in the foreground instead of
daemonizing.
.sp
\fIDefault\fP:  false
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBminfds\fP
.INDENT 0.0
.INDENT 3.5
The minimum number of file descriptors that must be available before
supervisord will start successfully.  A call to setrlimit will be made
to attempt to raise the soft and hard limits of the supervisord process to
satisfy \fBminfds\fP\&.  The hard limit may only be raised if supervisord
is run as root.  supervisord uses file descriptors liberally, and will
enter a failure mode when one cannot be obtained from the OS, so it\(aqs
useful to be able to specify a minimum value to ensure it doesn\(aqt run out
of them during execution. This option is particularly useful on Solaris,
which has a low per\-process fd limit by default.
.sp
\fIDefault\fP:  1024
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBminprocs\fP
.INDENT 0.0
.INDENT 3.5
The minimum number of process descriptors that must be available
before supervisord will start successfully.  A call to setrlimit will be
made to attempt to raise the soft and hard limits of the supervisord process
to satisfy \fBminprocs\fP\&.  The hard limit may only be raised if supervisord
is run as root.  supervisord will enter a failure mode when the OS runs out
of process descriptors, so it\(aqs useful to ensure that enough process
descriptors are available upon \fBsupervisord\fP startup.
.sp
\fIDefault\fP:  200
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBnocleanup\fP
.INDENT 0.0
.INDENT 3.5
Prevent supervisord from clearing any existing \fBAUTO\fP
child log files at startup time.  Useful for debugging.
.sp
\fIDefault\fP:  false
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBchildlogdir\fP
.INDENT 0.0
.INDENT 3.5
The directory used for \fBAUTO\fP child log files.  This option can
include the value \fB%(here)s\fP, which expands to the directory in
which the \fBsupervisord\fP configuration file was found.
.sp
\fIDefault\fP: value of Python\(aqs \fBtempfile.get_tempdir()\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBuser\fP
.INDENT 0.0
.INDENT 3.5
Instruct \fBsupervisord\fP to switch users to this UNIX user
account before doing any meaningful processing.  The user can only
be switched if \fBsupervisord\fP is started as the root user.
If \fBsupervisord\fP can\(aqt switch users, it will still continue
but will write a log message at the \fBcritical\fP level saying that it
can\(aqt drop privileges.
.sp
\fIDefault\fP: do not switch users
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBdirectory\fP
.INDENT 0.0
.INDENT 3.5
When \fBsupervisord\fP daemonizes, switch to this directory.
This option can include the value \fB%(here)s\fP, which expands to the
directory in which the \fBsupervisord\fP configuration file was
found.
.sp
\fIDefault\fP: do not cd
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstrip_ansi\fP
.INDENT 0.0
.INDENT 3.5
Strip all ANSI escape sequences from child log files.
.sp
\fIDefault\fP: false
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBenvironment\fP
.INDENT 0.0
.INDENT 3.5
A list of key/value pairs in the form \fBKEY="val",KEY2="val2"\fP that
will be placed in the \fBsupervisord\fP process\(aq environment
(and as a result in all of its child process\(aq environments).  This
option can include the value \fB%(here)s\fP, which expands to the
directory in which the supervisord configuration file was found.
Values containing non\-alphanumeric characters should be quoted
(e.g. \fBKEY="val:123",KEY2="val,456"\fP).  Otherwise, quoting the
values is optional but recommended.  To escape percent characters,
simply use two. (e.g. \fBURI="/first%%20name"\fP) \fBNote\fP that
subprocesses will inherit the environment variables of the shell
used to start \fBsupervisord\fP except for the ones overridden
here and within the program\(aqs \fBenvironment\fP option.  See
subprocess_environment\&.
.sp
\fIDefault\fP: no values
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBidentifier\fP
.INDENT 0.0
.INDENT 3.5
The identifier string for this supervisor process, used by the RPC
interface.
.sp
\fIDefault\fP: supervisor
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.SS \fB[supervisord]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[supervisorctl]\fP Section Settings
.INDENT 0.0
.INDENT 3.5
The configuration file may contain settings for the
\fBsupervisorctl\fP interactive shell program.  These options
are listed below.
.UNINDENT
.UNINDENT
.SS \fB[supervisorctl]\fP Section Values
.sp
\fBserverurl\fP
.INDENT 0.0
.INDENT 3.5
The URL that should be used to access the supervisord server,
e.g. \fBhttp://localhost:9001\fP\&.  For UNIX domain sockets, use
\fBunix:///absolute/path/to/file.sock\fP\&.
.sp
\fIDefault\fP: \fBhttp://localhost:9001\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBusername\fP
.INDENT 0.0
.INDENT 3.5
The username to pass to the supervisord server for use in
authentication.  This should be same as \fBusername\fP from the
supervisord server configuration for the port or UNIX domain socket
you\(aqre attempting to access.
.sp
\fIDefault\fP: No username
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBpassword\fP
.INDENT 0.0
.INDENT 3.5
The password to pass to the supervisord server for use in
authentication. This should be the cleartext version of \fBpassword\fP
from the supervisord server configuration for the port or UNIX
domain socket you\(aqre attempting to access.  This value cannot be
passed as a SHA hash.  Unlike other passwords specified in this
file, it must be provided in cleartext.
.sp
\fIDefault\fP: No password
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBprompt\fP
.INDENT 0.0
.INDENT 3.5
String used as supervisorctl prompt.
.sp
\fIDefault\fP: \fBsupervisor\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBhistory_file\fP
.INDENT 0.0
.INDENT 3.5
A path to use as the \fBreadline\fP persistent history file.  If you
enable this feature by choosing a path, your supervisorctl commands
will be kept in the file, and you can use readline (e.g. arrow\-up)
to invoke commands you performed in your last supervisorctl session.
.sp
\fIDefault\fP: No file
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0a5
.UNINDENT
.UNINDENT
.SS \fB[supervisorctl]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[supervisorctl]
serverurl = unix:///tmp/supervisor.sock
username = chris
password = 123
prompt = mysupervisor
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[program:x]\fP Section Settings
.sp
The configuration file must contain one or more \fBprogram\fP 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 \fB[program:foo]\fP 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 \fBprogram\fP 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
\fB%(program_name)s\fP string expression expansion within other values
where specified.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
A \fB[program:x]\fP 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 \fBnumprocs\fP and
\fBprocess_name\fP parameters in the configuration.  By default, if
numprocs and process_name are left unchanged from their defaults,
the group represented by \fB[program:x]\fP will be named \fBx\fP and
will have a single process named \fBx\fP in it.  This provides a
modicum of backwards compatibility with older supervisor releases,
which did not treat program sections as homogeneous process group
definitions.
.sp
But for instance, if you have a \fB[program:foo]\fP section with a
\fBnumprocs\fP of 3 and a \fBprocess_name\fP expression of
\fB%(program_name)s_%(process_num)02d\fP, the "foo" group will
contain three processes, named \fBfoo_00\fP, \fBfoo_01\fP, and
\fBfoo_02\fP\&.  This makes it possible to start a number of very
similar processes using a single \fB[program:x]\fP 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.
.UNINDENT
.UNINDENT
.SS \fB[program:x]\fP Section Values
.sp
\fBcommand\fP
.INDENT 0.0
.INDENT 3.5
The command that will be run when this program is started.  The
command can be either absolute (e.g. \fB/path/to/programname\fP) or
relative (e.g. \fBprogramname\fP).  If it is relative, the
supervisord\(aqs environment \fB$PATH\fP will be searched for the
executable.  Programs can accept arguments, e.g. \fB/path/to/program
foo bar\fP\&.  The command line can use double quotes to group
arguments with spaces in them to pass to the program,
e.g. \fB/path/to/program/name \-p "foo bar"\fP\&.  Note that the value of
\fBcommand\fP may include Python string expressions,
e.g. \fB/path/to/programname \-\-port=80%(process_num)02d\fP might
expand to \fB/path/to/programname \-\-port=8000\fP at runtime.  String
expressions are evaluated against a dictionary containing the keys
\fBgroup_name\fP, \fBhost_node_name\fP, \fBprocess_num\fP, \fBprogram_name\fP,
\fBhere\fP (the directory of the supervisord config file), and all
supervisord\(aqs environment variables prefixed with \fBENV_\fP\&.  Controlled
programs should themselves not be daemons, as supervisord assumes it is
responsible for daemonizing its subprocesses (see
nondaemonizing_of_subprocesses).
.sp
\fIDefault\fP: No default.
.sp
\fIRequired\fP:  Yes.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBprocess_name\fP
.INDENT 0.0
.INDENT 3.5
A Python string expression that is used to compose the supervisor
process name for this process.  You usually don\(aqt need to worry
about setting this unless you change \fBnumprocs\fP\&.  The string
expression is evaluated against a dictionary that includes
\fBgroup_name\fP, \fBhost_node_name\fP, \fBprocess_num\fP, \fBprogram_name\fP,
and \fBhere\fP (the directory of the supervisord config file).
.sp
\fIDefault\fP: \fB%(program_name)s\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBnumprocs\fP
.INDENT 0.0
.INDENT 3.5
Supervisor will start as many instances of this program as named by
numprocs.  Note that if numprocs > 1, the \fBprocess_name\fP
expression must include \fB%(process_num)s\fP (or any other
valid Python string expression that includes \fBprocess_num\fP) within
it.
.sp
\fIDefault\fP: 1
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBnumprocs_start\fP
.INDENT 0.0
.INDENT 3.5
An integer offset that is used to compute the number at which
\fBnumprocs\fP starts.
.sp
\fIDefault\fP: 0
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBpriority\fP
.INDENT 0.0
.INDENT 3.5
The relative priority of the program in the start and shutdown
ordering.  Lower priorities indicate programs that start first and
shut down last at startup and when aggregate commands are used in
various clients (e.g. "start all"/"stop all").  Higher priorities
indicate programs that start last and shut down first.
.sp
\fIDefault\fP: 999
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBautostart\fP
.INDENT 0.0
.INDENT 3.5
If true, this program will start automatically when supervisord is
started.
.sp
\fIDefault\fP: true
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstartsecs\fP
.INDENT 0.0
.INDENT 3.5
The total number of seconds which the program needs to stay running
after a startup to consider the start successful (moving the process
from the \fBSTARTING\fP state to the \fBRUNNING\fP state).  Set to \fB0\fP
to indicate that the program needn\(aqt stay running for any particular
amount of time.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Even if a process exits with an "expected" exit code (see
\fBexitcodes\fP), the start will still be considered a failure
if the process exits quicker than \fBstartsecs\fP\&.
.UNINDENT
.UNINDENT
.sp
\fIDefault\fP: 1
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstartretries\fP
.INDENT 0.0
.INDENT 3.5
The number of serial failure attempts that \fBsupervisord\fP
will allow when attempting to start the program before giving up and
putting the process into an \fBFATAL\fP state.  See
process_states for explanation of the \fBFATAL\fP state.
.sp
\fIDefault\fP: 3
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBautorestart\fP
.INDENT 0.0
.INDENT 3.5
Specifies if \fBsupervisord\fP should automatically restart a
process if it exits when it is in the \fBRUNNING\fP state.  May be
one of \fBfalse\fP, \fBunexpected\fP, or \fBtrue\fP\&.  If \fBfalse\fP, the
process will not be autorestarted.  If \fBunexpected\fP, the process
will be restarted when the program exits with an exit code that is
not one of the exit codes associated with this process\(aq configuration
(see \fBexitcodes\fP).  If \fBtrue\fP, the process will be unconditionally
restarted when it exits, without regard to its exit code.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBautorestart\fP controls whether \fBsupervisord\fP will
autorestart a program if it exits after it has successfully started
up (the process is in the \fBRUNNING\fP state).
.sp
\fBsupervisord\fP has a different restart mechanism for when the
process is starting up (the process is in the \fBSTARTING\fP state).
Retries during process startup are controlled by \fBstartsecs\fP
and \fBstartretries\fP\&.
.UNINDENT
.UNINDENT
.sp
\fIDefault\fP: unexpected
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBexitcodes\fP
.INDENT 0.0
.INDENT 3.5
The list of "expected" exit codes for this program used with \fBautorestart\fP\&.
If the \fBautorestart\fP parameter is set to \fBunexpected\fP, and the process
exits in any other way than as a result of a supervisor stop
request, \fBsupervisord\fP will restart the process if it exits
with an exit code that is not defined in this list.
.sp
\fIDefault\fP: 0,2
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstopsignal\fP
.INDENT 0.0
.INDENT 3.5
The signal used to kill the program when a stop is requested.  This
can be any of TERM, HUP, INT, QUIT, KILL, USR1, or USR2.
.sp
\fIDefault\fP: TERM
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstopwaitsecs\fP
.INDENT 0.0
.INDENT 3.5
The number of seconds to wait for the OS to return a SIGCHILD to
\fBsupervisord\fP after the program has been sent a stopsignal.
If this number of seconds elapses before \fBsupervisord\fP
receives a SIGCHILD from the process, \fBsupervisord\fP will
attempt to kill it with a final SIGKILL.
.sp
\fIDefault\fP: 10
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstopasgroup\fP
.INDENT 0.0
.INDENT 3.5
If true, the flag causes supervisor to send the stop signal to the
whole process group and implies \fBkillasgroup\fP is true.  This is useful
for programs, such as Flask in debug mode, that do not propagate
stop signals to their children, leaving them orphaned.
.sp
\fIDefault\fP: false
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0b1
.UNINDENT
.UNINDENT
.sp
\fBkillasgroup\fP
.INDENT 0.0
.INDENT 3.5
If true, when resorting to send SIGKILL to the program to terminate
it send it to its whole process group instead, taking care of its
children as well, useful e.g with Python programs using
\fBmultiprocessing\fP\&.
.sp
\fIDefault\fP: false
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0a11
.UNINDENT
.UNINDENT
.sp
\fBuser\fP
.INDENT 0.0
.INDENT 3.5
Instruct \fBsupervisord\fP to use this UNIX user account as the
account which runs the program.  The user can only be switched if
\fBsupervisord\fP is run as the root user.  If \fBsupervisord\fP
can\(aqt switch to the specified user, the program will not be started.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The user will be changed using \fBsetuid\fP only.  This does not start
a login shell and does not change environment variables like
\fBUSER\fP or \fBHOME\fP\&.  See subprocess_environment for details.
.UNINDENT
.UNINDENT
.sp
\fIDefault\fP: Do not switch users
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBredirect_stderr\fP
.INDENT 0.0
.INDENT 3.5
If true, cause the process\(aq stderr output to be sent back to
\fBsupervisord\fP on its stdout file descriptor (in UNIX shell
terms, this is the equivalent of executing \fB/the/program 2>&1\fP).
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Do not set \fBredirect_stderr=true\fP in an \fB[eventlistener:x]\fP section.
Eventlisteners use \fBstdout\fP and \fBstdin\fP to communicate with
\fBsupervisord\fP\&.  If \fBstderr\fP is redirected, output from
\fBstderr\fP will interfere with the eventlistener protocol.
.UNINDENT
.UNINDENT
.sp
\fIDefault\fP: false
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0, replaces 2.0\(aqs \fBlog_stdout\fP and \fBlog_stderr\fP
.UNINDENT
.UNINDENT
.sp
\fBstdout_logfile\fP
.INDENT 0.0
.INDENT 3.5
Put process stdout output in this file (and if redirect_stderr is
true, also place stderr output in this file).  If \fBstdout_logfile\fP
is unset or set to \fBAUTO\fP, supervisor will automatically choose a
file location.  If this is set to \fBNONE\fP, supervisord will create
no log file.  \fBAUTO\fP log files and their backups will be deleted
when \fBsupervisord\fP restarts.  The \fBstdout_logfile\fP value
can contain Python string expressions that will evaluated against a
dictionary that contains the keys \fBgroup_name\fP, \fBhost_node_name\fP,
\fBprocess_num\fP, \fBprogram_name\fP, and \fBhere\fP (the directory of the
supervisord config file).
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
It is not possible for two processes to share a single log file
(\fBstdout_logfile\fP) when rotation (\fBstdout_logfile_maxbytes\fP)
is enabled.  This will result in the file being corrupted.
.UNINDENT
.UNINDENT
.sp
\fIDefault\fP: \fBAUTO\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0, replaces 2.0\(aqs \fBlogfile\fP
.UNINDENT
.UNINDENT
.sp
\fBstdout_logfile_maxbytes\fP
.INDENT 0.0
.INDENT 3.5
The maximum number of bytes that may be consumed by
\fBstdout_logfile\fP before it is rotated (suffix multipliers like
"KB", "MB", and "GB" can be used in the value).  Set this value to 0
to indicate an unlimited log size.
.sp
\fIDefault\fP: 50MB
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0, replaces 2.0\(aqs \fBlogfile_maxbytes\fP
.UNINDENT
.UNINDENT
.sp
\fBstdout_logfile_backups\fP
.INDENT 0.0
.INDENT 3.5
The number of \fBstdout_logfile\fP backups to keep around resulting
from process stdout log file rotation.  If set to 0, no backups
will be kept.
.sp
\fIDefault\fP: 10
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0, replaces 2.0\(aqs \fBlogfile_backups\fP
.UNINDENT
.UNINDENT
.sp
\fBstdout_capture_maxbytes\fP
.INDENT 0.0
.INDENT 3.5
Max number of bytes written to capture FIFO when process is in
"stdout capture mode" (see capture_mode).  Should be an
integer (suffix multipliers like "KB", "MB" and "GB" can used in the
value).  If this value is 0, process capture mode will be off.
.sp
\fIDefault\fP: 0
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0, replaces 2.0\(aqs \fBlogfile_backups\fP
.UNINDENT
.UNINDENT
.sp
\fBstdout_events_enabled\fP
.INDENT 0.0
.INDENT 3.5
If true, PROCESS_LOG_STDOUT events will be emitted when the process
writes to its stdout file descriptor.  The events will only be
emitted if the file descriptor is not in capture mode at the time
the data is received (see capture_mode).
.sp
\fIDefault\fP: 0
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0a7
.UNINDENT
.UNINDENT
.sp
\fBstderr_logfile\fP
.INDENT 0.0
.INDENT 3.5
Put process stderr output in this file unless \fBredirect_stderr\fP is
true.  Accepts the same value types as \fBstdout_logfile\fP and may
contain the same Python string expressions.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
It is not possible for two processes to share a single log file
(\fBstderr_logfile\fP) when rotation (\fBstderr_logfile_maxbytes\fP)
is enabled.  This will result in the file being corrupted.
.UNINDENT
.UNINDENT
.sp
\fIDefault\fP: \fBAUTO\fP
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstderr_logfile_maxbytes\fP
.INDENT 0.0
.INDENT 3.5
The maximum number of bytes before logfile rotation for
\fBstderr_logfile\fP\&.  Accepts the same value types as
\fBstdout_logfile_maxbytes\fP\&.
.sp
\fIDefault\fP: 50MB
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstderr_logfile_backups\fP
.INDENT 0.0
.INDENT 3.5
The number of backups to keep around resulting from process stderr
log file rotation.  If set to 0, no backups will be kept.
.sp
\fIDefault\fP: 10
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstderr_capture_maxbytes\fP
.INDENT 0.0
.INDENT 3.5
Max number of bytes written to capture FIFO when process is in
"stderr capture mode" (see capture_mode).  Should be an
integer (suffix multipliers like "KB", "MB" and "GB" can used in the
value).  If this value is 0, process capture mode will be off.
.sp
\fIDefault\fP: 0
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBstderr_events_enabled\fP
.INDENT 0.0
.INDENT 3.5
If true, PROCESS_LOG_STDERR events will be emitted when the process
writes to its stderr file descriptor.  The events will only be
emitted if the file descriptor is not in capture mode at the time
the data is received (see capture_mode).
.sp
\fIDefault\fP: false
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0a7
.UNINDENT
.UNINDENT
.sp
\fBenvironment\fP
.INDENT 0.0
.INDENT 3.5
A list of key/value pairs in the form \fBKEY="val",KEY2="val2"\fP that
will be placed in the child process\(aq environment.  The environment
string may contain Python string expressions that will be evaluated
against a dictionary containing \fBgroup_name\fP, \fBhost_node_name\fP,
\fBprocess_num\fP, \fBprogram_name\fP, and \fBhere\fP (the directory of the
supervisord config file).  Values containing non\-alphanumeric characters
should be quoted (e.g. \fBKEY="val:123",KEY2="val,456"\fP).  Otherwise,
quoting the values is optional but recommended.  \fBNote\fP that the
subprocess will inherit the environment variables of the shell used to
start "supervisord" except for the ones overridden here.  See
subprocess_environment\&.
.sp
\fIDefault\fP: No extra environment
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBdirectory\fP
.INDENT 0.0
.INDENT 3.5
A file path representing a directory to which \fBsupervisord\fP
should temporarily chdir before exec\(aqing the child.
.sp
\fIDefault\fP: No chdir (inherit supervisor\(aqs)
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBumask\fP
.INDENT 0.0
.INDENT 3.5
An octal number (e.g. 002, 022) representing the umask of the
process.
.sp
\fIDefault\fP: No special umask (inherit supervisor\(aqs)
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBserverurl\fP
.INDENT 0.0
.INDENT 3.5
The URL passed in the environment to the subprocess process as
\fBSUPERVISOR_SERVER_URL\fP (see \fBsupervisor.childutils\fP) to
allow the subprocess to easily communicate with the internal HTTP
server.  If provided, it should have the same syntax and structure
as the \fB[supervisorctl]\fP section option of the same name.  If this
is set to AUTO, or is unset, supervisor will automatically construct
a server URL, giving preference to a server that listens on UNIX
domain sockets over one that listens on an internet socket.
.sp
\fIDefault\fP: AUTO
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.SS \fB[program:x]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[include]\fP Section Settings
.sp
The \fBsupervisord.conf\fP file may contain a section named
\fB[include]\fP\&.  If the configuration file contains an \fB[include]\fP
section, it must contain a single key named "files".  The values in
this key specify other configuration files to be included within the
configuration.
.SS \fB[include]\fP Section Values
.sp
\fBfiles\fP
.INDENT 0.0
.INDENT 3.5
A space\-separated sequence of file globs.  Each file glob may be
absolute or relative.  If the file glob is relative, it is
considered relative to the location of the configuration file which
includes it.  A "glob" is a file pattern which matches a specified
pattern according to the rules used by the Unix shell. No tilde
expansion is done, but \fB*\fP, \fB?\fP, and character ranges expressed
with \fB[]\fP will be correctly matched.  Recursive includes from
included files are not supported.
.sp
\fIDefault\fP: No default (required)
.sp
\fIRequired\fP:  Yes.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.SS \fB[include]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[include]
files = /an/absolute/filename.conf /an/absolute/*.conf foo.conf config??.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[group:x]\fP Section Settings
.sp
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\(aqs various controller
interfaces.
.sp
To place programs into a group so you can treat them as a unit, define
a \fB[group:x]\fP 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 \fB[group:foo]\fP
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 \fBgroup\fP
section that does not have a name.  The name must not include a colon
character or a bracket character.
.sp
For a \fB[group:x]\fP, there must be one or more \fB[program:x]\fP
sections elsewhere in your configuration file, and the group must
refer to them by name in the \fBprograms\fP value.
.sp
If "homogeneous" process groups (represented by program sections) are
placed into a "heterogeneous" group via \fB[group:x]\fP section\(aqs
\fBprograms\fP 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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[group:foo]
programs=bar,baz
priority=999
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Given the above, at supervisord startup, the \fBbar\fP and \fBbaz\fP
homogeneous groups will not exist, and the processes that would have
been under them will now be moved into the \fBfoo\fP group.
.SS \fB[group:x]\fP Section Values
.sp
\fBprograms\fP
.INDENT 0.0
.INDENT 3.5
A comma\-separated list of program names.  The programs which are
listed become members of the group.
.sp
\fIDefault\fP: No default (required)
.sp
\fIRequired\fP:  Yes.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBpriority\fP
.INDENT 0.0
.INDENT 3.5
A priority number analogous to a \fB[program:x]\fP priority value
assigned to the group.
.sp
\fIDefault\fP: 999
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.SS \fB[group:x]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[group:foo]
programs=bar,baz
priority=999
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[fcgi\-program:x]\fP Section Settings
.sp
Supervisor can manage groups of \fI\%FastCGI\fP
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\(aqs 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\(aqt 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.
.sp
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\(aqs a clean separation of concerns, allowing
the web server and the process manager to each do what they do best.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The socket manager in Supervisor was originally developed to support
FastCGI processes but it is not limited to FastCGI.  Other protocols may
be used as well with no special configuration.  Any program that can
access an open socket from a file descriptor (e.g. with
\fI\%socket.fromfd\fP
in Python) can use the socket manager.  Supervisor will automatically
create the socket, bind, and listen before forking the first child in a
group.  The socket will be passed to each child on file descriptor
number \fB0\fP (zero).  When the last child in the group exits,
Supervisor will close the socket.
.UNINDENT
.UNINDENT
.sp
All the options available to \fB[program:x]\fP sections are
also respected by \fBfcgi\-program\fP sections.
.SS \fB[fcgi\-program:x]\fP Section Values
.sp
\fB[fcgi\-program:x]\fP sections have a single key which \fB[program:x]\fP
sections do not have.
.sp
\fBsocket\fP
.INDENT 0.0
.INDENT 3.5
The FastCGI socket for this program, either TCP or UNIX domain
socket. For TCP sockets, use this format: \fBtcp://localhost:9002\fP\&.
For UNIX domain sockets, use \fBunix:///absolute/path/to/file.sock\fP\&.
String expressions are evaluated against a dictionary containing the
keys "program_name" and "here" (the directory of the supervisord
config file).
.sp
\fIDefault\fP: No default.
.sp
\fIRequired\fP:  Yes.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBsocket_owner\fP
.INDENT 0.0
.INDENT 3.5
For UNIX domain sockets, this parameter can be used to specify the user
and group for the FastCGI socket. May be a UNIX username (e.g. chrism)
or a UNIX username and group separated by a colon (e.g. chrism:wheel).
.sp
\fIDefault\fP: Uses the user and group set for the fcgi\-program
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
\fBsocket_mode\fP
.INDENT 0.0
.INDENT 3.5
For UNIX domain sockets, this parameter can be used to specify the
permission mode.
.sp
\fIDefault\fP: 0700
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.sp
Consult \fI\%[program:x] Section Settings\fP for other allowable keys, delta the
above constraints and additions.
.SS \fB[fcgi\-program:x]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[eventlistener:x]\fP Section Settings
.sp
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\(aqs event system.  See events for
an explanation of how events work and how to implement programs that
can be declared as event listeners.
.sp
Note that all the options available to \fB[program:x]\fP sections are
respected by eventlistener sections \fIexcept\fP for
\fBstdout_capture_maxbytes\fP and \fBstderr_capture_maxbytes\fP (event
listeners cannot emit process communication events, see
capture_mode).
.SS \fB[eventlistener:x]\fP Section Values
.sp
\fB[eventlistener:x]\fP sections have a few keys which \fB[program:x]\fP
sections do not have.
.sp
\fBbuffer_size\fP
.INDENT 0.0
.INDENT 3.5
The event listener pool\(aqs event queue buffer size.  When a listener
pool\(aqs event buffer is overflowed (as can happen when an event
listener pool cannot keep up with all of the events sent to it), the
oldest event in the buffer is discarded.
.UNINDENT
.UNINDENT
.sp
\fBevents\fP
.INDENT 0.0
.INDENT 3.5
A comma\-separated list of event type names that this listener is
"interested" in receiving notifications for (see
event_types for a list of valid event type names).
.UNINDENT
.UNINDENT
.sp
\fBresult_handler\fP
.INDENT 0.0
.INDENT 3.5
A \fI\%pkg_resources entry point string\fP that
resolves to a Python callable.  The default value is
\fBsupervisor.dispatchers:default_handler\fP\&.  Specifying an alternate
result handler is a very uncommon thing to need to do, and as a
result, how to create one is not documented.
.UNINDENT
.UNINDENT
.sp
Consult \fI\%[program:x] Section Settings\fP for other allowable keys, delta the
above constraints and additions.
.SS \fB[eventlistener:x]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[rpcinterface:x]\fP Section Settings
.sp
Adding \fBrpcinterface:x\fP settings in the configuration file is only
useful for people who wish to extend supervisor with additional custom
behavior.
.sp
In the sample config file, there is a section which is named
\fB[rpcinterface:supervisor]\fP\&.  By default it looks like the
following.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB[rpcinterface:supervisor]\fP section \fImust\fP remain in the
configuration for the standard setup of supervisor to work properly.
If you don\(aqt want supervisor to do anything it doesn\(aqt already do out
of the box, this is all you need to know about this type of section.
.sp
However, if you wish to add rpc interface namespaces in order to
customize supervisor, you may add additional \fB[rpcinterface:foo]\fP
sections, where "foo" represents the namespace of the interface (from
the web root), and the value named by
\fBsupervisor.rpcinterface_factory\fP is a factory callable which should
have a function signature that accepts a single positional argument
\fBsupervisord\fP and as many keyword arguments as required to perform
configuration.  Any extra key/value pairs defined within the
\fB[rpcinterface:x]\fP section will be passed as keyword arguments to
the factory.
.sp
Here\(aqs an example of a factory function, created in the
\fB__init__.py\fP file of the Python package \fBmy.package\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from my.package.rpcinterface import AnotherRPCInterface

def make_another_rpcinterface(supervisord, **config):
    retries = int(config.get(\(aqretries\(aq, 0))
    another_rpc_interface = AnotherRPCInterface(supervisord, retries)
    return another_rpc_interface
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And a section in the config file meant to configure it.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB[rpcinterface:x]\fP Section Values
.sp
\fBsupervisor.rpcinterface_factory\fP
.INDENT 0.0
.INDENT 3.5
\fBpkg_resources\fP "entry point" dotted name to your RPC interface\(aqs
factory function.
.sp
\fIDefault\fP: N/A
.sp
\fIRequired\fP:  No.
.sp
\fIIntroduced\fP: 3.0
.UNINDENT
.UNINDENT
.SS \fB[rpcinterface:x]\fP Section Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Subprocesses
.sp
\fBsupervisord\fP\(aqs 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
(\fBsupervisord\fP is the parent process of each process it
creates).  When a child dies, supervisor is notified of its death via
the \fBSIGCHLD\fP signal, and it performs the appropriate operation.
.SS Nondaemonizing of Subprocesses
.sp
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.
.sp
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\(aqs
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 \fBCtrl\-C\fP to get control of the terminal
back.  If it gives you a shell prompt back after running it without
needing to press \fBCtrl\-C\fP, it\(aqs not useful under supervisor.  All
programs have options to be run in the foreground but there\(aqs no
"standard way" to do it; you\(aqll need to read the documentation for
each program.
.sp
Below are configuration file examples that are known to start
common programs in "foreground" mode under Supervisor.
.SS Examples of Program Configurations
.sp
Here are some "real world" program configuration examples:
.SS Apache 2.2.6
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[program:apache2]
command=/path/to/httpd \-c "ErrorLog /dev/stdout" \-DFOREGROUND
redirect_stderr=true
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Two Zope 2.X instances and one ZEO server
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Postgres 8.X
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[program:postgres]
command=/path/to/postmaster
; we use the "fast" shutdown signal SIGINT
stopsignal=INT
redirect_stderr=true
.ft P
.fi
.UNINDENT
.UNINDENT
.SS OpenLDAP \fBslapd\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[program:slapd]
command=/path/to/slapd \-f /path/to/slapd.conf \-h ldap://0.0.0.0:8888
redirect_stderr=true
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Other Examples
.sp
Other examples of shell scripts that could be used to start services
under \fBsupervisord\fP can be found at
\fI\%http://thedjbway.b0llix.net/services.html\fP\&.  These examples are
actually for \fBdaemontools\fP but the premise is the same for
supervisor.
.sp
Another collection of recipes for starting various programs in the
foreground is available from \fI\%http://smarden.org/runit/runscripts.html\fP\&.
.SS \fBpidproxy\fP Program
.sp
Some processes (like \fBmysqld\fP) ignore signals sent to the
actual process which is spawned by \fBsupervisord\fP\&.  Instead, a
"special" thread/process is created by these kinds of programs which
is responsible for handling signals.  This is problematic because
\fBsupervisord\fP can only kill a process which it creates
itself.  If a process created by \fBsupervisord\fP creates its
own child processes, \fBsupervisord\fP cannot kill them.
.sp
Fortunately, these types of programs typically write a "pidfile" which
contains the "special" process\(aq PID, and is meant to be read and used
in order to kill the process.  As a workaround for this case, a
special \fBpidproxy\fP program can handle startup of these kinds
of processes.  The \fBpidproxy\fP 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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[program:mysql]
command=/path/to/pidproxy /path/to/pidfile /path/to/mysqld_safe
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBpidproxy\fP program is put into your configuration\(aqs
\fB$BINDIR\fP when supervisor is installed (it is a "console script").
.SS Subprocess Environment
.sp
Subprocesses will inherit the environment of the shell used to start
the \fBsupervisord\fP program.  Several environment variables
will be set by \fBsupervisord\fP itself in the child\(aqs
environment also, including \fBSUPERVISOR_ENABLED\fP (a flag
indicating the process is under supervisor control),
\fBSUPERVISOR_PROCESS_NAME\fP (the config\-file\-specified process
name for this process) and \fBSUPERVISOR_GROUP_NAME\fP (the
config\-file\-specified process group name for the child process).
.sp
These environment variables may be overridden within the
\fB[supervisord]\fP section config option named \fBenvironment\fP (applies
to all subprocesses) or within the per\- \fB[program:x]\fP section
\fBenvironment\fP config option (applies only to the subprocess
specified within the \fB[program:x]\fP section).  These "environment"
settings are additive.  In other words, each subprocess\(aq environment
will consist of:
.INDENT 0.0
.INDENT 3.5
The environment variables set within the shell used to start
supervisord...
.sp
\&... added\-to/overridden\-by ...
.INDENT 0.0
.TP
.B \&... the environment variables set within the "environment" global
.INDENT 7.0
.INDENT 3.5
config option ...
.UNINDENT
.UNINDENT
.sp
\&... added\-to/overridden\-by ...
.INDENT 7.0
.TP
.B \&... supervisor\-specific environment variables
(\fBSUPERVISOR_ENABLED\fP,
\fBSUPERVISOR_PROCESS_NAME\fP,
\fBSUPERVISOR_GROUP_NAME\fP) ..
.UNINDENT
.sp
\&... added\-to/overridden\-by ...
.INDENT 7.0
.TP
.B \&... the environment variables set within the per\-process
"environment" config option.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
No shell is executed by \fBsupervisord\fP when it runs a
subprocess, so environment variables such as \fBUSER\fP,
\fBPATH\fP, \fBHOME\fP, \fBSHELL\fP, \fBLOGNAME\fP,
etc. are not changed from their defaults or otherwise reassigned.
This is particularly important to note when you are running a program
from a \fBsupervisord\fP run as root with a \fBuser=\fP stanza in
the configuration.  Unlike \fBcron\fP, \fBsupervisord\fP
does not attempt to divine and override "fundamental" environment
variables like \fBUSER\fP, \fBPATH\fP, \fBHOME\fP, and
\fBLOGNAME\fP when it performs a setuid to the user defined within
the \fBuser=\fP 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 \fBenvironment=\fP program config option.  An
example of setting these environment variables is as below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[program:apache2]
command=/home/chrism/bin/httpd \-c "ErrorLog /dev/stdout" \-DFOREGROUND
user=chrism
environment=HOME="/home/chrism",USER="chrism"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Process States
.sp
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.
.sp
\fBSTOPPED\fP (0)
.INDENT 0.0
.INDENT 3.5
The process has been stopped due to a stop request or
has never been started.
.UNINDENT
.UNINDENT
.sp
\fBSTARTING\fP (10)
.INDENT 0.0
.INDENT 3.5
The process is starting due to a start request.
.UNINDENT
.UNINDENT
.sp
\fBRUNNING\fP (20)
.INDENT 0.0
.INDENT 3.5
The process is running.
.UNINDENT
.UNINDENT
.sp
\fBBACKOFF\fP (30)
.INDENT 0.0
.INDENT 3.5
The process entered the \fBSTARTING\fP state but subsequently exited
too quickly to move to the \fBRUNNING\fP state.
.UNINDENT
.UNINDENT
.sp
\fBSTOPPING\fP (40)
.INDENT 0.0
.INDENT 3.5
The process is stopping due to a stop request.
.UNINDENT
.UNINDENT
.sp
\fBEXITED\fP (100)
.INDENT 0.0
.INDENT 3.5
The process exited from the \fBRUNNING\fP state (expectedly or
unexpectedly).
.UNINDENT
.UNINDENT
.sp
\fBFATAL\fP (200)
.INDENT 0.0
.INDENT 3.5
The process could not be started successfully.
.UNINDENT
.UNINDENT
.sp
\fBUNKNOWN\fP (1000)
.INDENT 0.0
.INDENT 3.5
The process is in an unknown state (\fBsupervisord\fP
programming error).
.UNINDENT
.UNINDENT
.sp
Each process run under supervisor progresses through these states as
per the following directed graph.
.INDENT 0.0
.INDENT 2.5
[image: Subprocess State Transition Graph]
[image]
Subprocess State Transition Graph.UNINDENT
.UNINDENT
.sp
A process is in the \fBSTOPPED\fP state if it has been stopped
adminstratively or if it has never been started.
.sp
When an autorestarting process is in the \fBBACKOFF\fP state, it will be
automatically restarted by \fBsupervisord\fP\&.  It will switch
between \fBSTARTING\fP and \fBBACKOFF\fP states until it becomes evident
that it cannot be started because the number of \fBstartretries\fP has
exceeded the maximum, at which point it will transition to the
\fBFATAL\fP state.  Each start retry will take progressively
more time.
.sp
When a process is in the \fBEXITED\fP state, it will
automatically restart:
.INDENT 0.0
.IP \(bu 2
never if its \fBautorestart\fP parameter is set to \fBfalse\fP\&.
.IP \(bu 2
unconditionally if its \fBautorestart\fP parameter is set to \fBtrue\fP\&.
.IP \(bu 2
conditionally if its \fBautorestart\fP parameter is set to
\fBunexpected\fP\&.  If it exited with an exit code that doesn\(aqt match
one of the exit codes defined in the \fBexitcodes\fP configuration
parameter for the process, it will be restarted.
.UNINDENT
.sp
A process automatically transitions from \fBEXITED\fP to \fBRUNNING\fP as
a result of being configured to autorestart conditionally or
unconditionally.  The number of transitions between \fBRUNNING\fP and
\fBEXITED\fP is not limited in any way: it is possible to create a
configuration that endlessly restarts an exited process.  This is a
feature, not a bug.
.sp
An autorestarted process will never be automatically restarted if it
ends up in the \fBFATAL\fP state (it must be manually restarted from
this state).
.sp
A process transitions into the \fBSTOPPING\fP state via an
administrative stop request, and will then end up in the
\fBSTOPPED\fP state.
.sp
A process that cannot be stopped successfully will stay in the
\fBSTOPPING\fP state forever.  This situation should never be reached
during normal operations as it implies that the process did not
respond to a final \fBSIGKILL\fP signal sent to it by supervisor, which
is "impossible" under UNIX.
.sp
State transitions which always require user action to invoke are
these:
.sp
\fBFATAL\fP   \-> \fBSTARTING\fP
.sp
\fBRUNNING\fP \-> \fBSTOPPING\fP
.sp
State transitions which typically, but not always, require user
action to invoke are these, with exceptions noted:
.sp
\fBSTOPPED\fP \-> \fBSTARTING\fP (except at supervisord startup if process
is configured to autostart)
.sp
\fBEXITED\fP \-> \fBSTARTING\fP (except if process is configured to
autorestart)
.sp
All other state transitions are managed by supervisord automatically.
.SS Logging
.sp
One of the main tasks that \fBsupervisord\fP performs is logging.
\fBsupervisord\fP logs an activity log detailing what it\(aqs doing
as it runs.  It also logs child process stdout and stderr output to
other files if configured to do so.
.SS Activity Log
.sp
The activity log is the place where \fBsupervisord\fP logs
messages about its own health, its subprocess\(aq state changes, any
messages that result from events, and debug and informational
messages.  The path to the activity log is configured via the
\fBlogfile\fP parameter in the \fB[supervisord]\fP section of the
configuration file, defaulting to \fB$CWD/supervisord.log\fP\&.
Sample activity log traffic is shown in the example below.  Some lines
have been broken to better fit the screen.
.SS Sample Activity Log Output
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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 \(aqsupervisor\(aq 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: \(aqlistener_00\(aq with pid 27349
2007\-09\-08 14:43:23,970 INFO spawned: \(aqeventgen\(aq with pid 27350
2007\-09\-08 14:43:23,990 INFO spawned: \(aqgrower\(aq with pid 27351
2007\-09\-08 14:43:24,059 DEBG \(aqlistener_00\(aq stderr output:
 /Users/chrism/projects/supervisor/supervisor2/dev\-sandbox/bin/python:
 can\(aqt open file \(aq/Users/chrism/projects/supervisor/supervisor2/src/supervisor/scripts/osx_eventgen_listener.py\(aq:
 [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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The activity log "level" is configured in the config file via the
\fBloglevel\fP parameter in the \fB[supervisord]\fP ini file section.
When \fBloglevel\fP is set, messages of the specified priority, plus
those with any higher priority are logged to the activity log.  For
example, if \fBloglevel\fP is \fBerror\fP, messages of \fBerror\fP and
\fBcritical\fP priority will be logged.  However, if loglevel is
\fBwarn\fP, messages of \fBwarn\fP, \fBerror\fP, and \fBcritical\fP will be
logged.
.SS Activity Log Levels
.sp
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 \fBloglevel\fP parameter in the \fB[supervisord]\fP
section of configuration file and the "Output Code" is the code that
shows up in activity log output lines.
.TS
center;
|l|l|l|.
_
T{
Config File Value
T}	T{
Output Code
T}	T{
Description
T}
_
T{
critical
T}	T{
CRIT
T}	T{
Messages that indicate a condition that
requires immediate user attention, a
supervisor state change, or an error in
supervisor itself.
T}
_
T{
error
T}	T{
ERRO
T}	T{
Messages that indicate a potentially
ignorable error condition (e.g. unable to
clear a log directory).
T}
_
T{
warn
T}	T{
WARN
T}	T{
Messages that indicate an anomalous
condition which isn\(aqt an error.
T}
_
T{
info
T}	T{
INFO
T}	T{
Normal informational output.  This is the
default log level if none is explicitly
configured.
T}
_
T{
debug
T}	T{
DEBG
T}	T{
Messages useful for users trying to debug
process configuration and communications
behavior (process output, listener state
changes, event notifications).
T}
_
T{
trace
T}	T{
TRAC
T}	T{
Messages useful for developers trying to
debug supervisor plugins, and information
about HTTP and RPC requests and responses.
T}
_
T{
blather
T}	T{
BLAT
T}	T{
Messages useful for developers trying to
debug supervisor itself.
T}
_
.TE
.SS Activity Log Rotation
.sp
The activity log is "rotated" by \fBsupervisord\fP based on the
combination of the \fBlogfile_maxbytes\fP and the \fBlogfile_backups\fP
parameters in the \fB[supervisord]\fP section of the configuration file.
When the activity log reaches \fBlogfile_maxbytes\fP 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 \fBlogfile_backups\fP, the oldest backup file
is removed and the backup files are renamed accordingly.  If the file
being written to is named \fBsupervisord.log\fP, when it exceeds
\fBlogfile_maxbytes\fP, it is closed and renamed to
\fBsupervisord.log.1\fP, and if files \fBsupervisord.log.1\fP,
\fBsupervisord.log.2\fP etc. exist, then they are renamed to
\fBsupervisord.log.2\fP, \fBsupervisord.log.3\fP etc.
respectively.  If \fBlogfile_maxbytes\fP is 0, the logfile is never
rotated (and thus backups are never made).  If \fBlogfile_backups\fP is
0, no backups will be kept.
.SS Child Process Logs
.sp
The stdout of child processes spawned by supervisor, by default, is
captured for redisplay to users of \fBsupervisorctl\fP and other
clients.  If no specific logfile\-related configuration is performed in
a \fB[program:x]\fP, \fB[fcgi\-program:x]\fP, or \fB[eventlistener:x]\fP
section in the configuration file, the following is true:
.INDENT 0.0
.IP \(bu 2
\fBsupervisord\fP will capture the child process\(aq stdout and
stderr output into temporary files.  Each stream is captured to a
separate file.  This is known as \fBAUTO\fP log mode.
.IP \(bu 2
\fBAUTO\fP log files are named automatically and placed in the
directory configured as \fBchildlogdir\fP of the \fB[supervisord]\fP
section of the config file.
.IP \(bu 2
The size of each \fBAUTO\fP log file is bounded by the
\fB{streamname}_logfile_maxbytes\fP value of the program section
(where {streamname} is "stdout" or "stderr").  When it reaches that
number, it is rotated (like the activity log), based on the
\fB{streamname}_logfile_backups\fP\&.
.UNINDENT
.sp
The configuration keys that influence child process logging in
\fB[program:x]\fP and \fB[fcgi\-program:x]\fP sections are these:
.sp
\fBredirect_stderr\fP, \fBstdout_logfile\fP, \fBstdout_logfile_maxbytes\fP,
\fBstdout_logfile_backups\fP, \fBstdout_capture_maxbytes\fP,
\fBstderr_logfile\fP, \fBstderr_logfile_maxbytes\fP,
\fBstderr_logfile_backups\fP and \fBstderr_capture_maxbytes\fP\&.
.sp
One may set \fBstdout_logfile\fP or \fBstderr_logfile\fP to the
special string "syslog". In this case, logs will be routed to the
syslog service instead of being saved to files.
.sp
\fB[eventlistener:x]\fP sections may not specify
\fBredirect_stderr\fP, \fBstdout_capture_maxbytes\fP, or
\fBstderr_capture_maxbytes\fP, but otherwise they accept the same values.
.sp
The configuration keys that influence child process logging in the
\fB[supervisord]\fP config file section are these:
\fBchildlogdir\fP, and \fBnocleanup\fP\&.
.SS Capture Mode
.sp
Capture mode is an advanced feature of Supervisor.  You needn\(aqt
understand capture mode unless you want to take actions based on data
parsed from subprocess output.
.sp
If a \fB[program:x]\fP section in the configuration file defines a
non\-zero \fBstdout_capture_maxbytes\fP or \fBstderr_capture_maxbytes\fP
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 \fBPROCESS_COMMUNICATION\fP
event (see events for a description of events).
.sp
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
\fBcapture_maxbytes\fP bytes.  During capture mode, when the buffer\(aqs
length exceeds \fBcapture_maxbytes\fP bytes, the earliest data in the
buffer is discarded to make room for new data.  When a process stream
exits capture mode, a \fBPROCESS_COMMUNICATION\fP event subtype is
emitted by supervisor, which may be intercepted by event listeners.
.sp
The tag to begin "capture mode" in a process stream is
\fB<!\-\-XSUPERVISOR:BEGIN\-\->\fP\&.  The tag to exit capture mode is
\fB<!\-\-XSUPERVISOR:END\-\->\fP\&.  The data between these tags may be
arbitrary, and forms the payload of the \fBPROCESS_COMMUNICATION\fP
event.  For example, if a program is set up with a
\fBstdout_capture_maxbytes\fP of "1MB", and it emits the following on
its stdout stream:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<!\-\-XSUPERVISOR:BEGIN\-\->Hello!<!\-\-XSUPERVISOR:END\-\->
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this circumstance, \fBsupervisord\fP will emit a
\fBPROCESS_COMMUNICATIONS_STDOUT\fP event with data in the payload of
"Hello!".
.sp
An example of a script (written in Python) which emits a process
communication event is in the \fBscripts\fP directory of the
supervisor package, named \fBsample_commevent.py\fP\&.
.sp
The output of processes specified as "event listeners"
(\fB[eventlistener:x]\fP sections) is not processed this way.
Output from these processes cannot enter capture mode.
.SS Extending Supervisor\(aqs XML\-RPC API
.sp
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\(aqt 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.
.SS Configuring XML\-RPC Interface Factories
.sp
An additional RPC interface is configured into a supervisor
installation by adding a \fB[rpcinterface:x]\fP section in the
Supervisor configuration file.
.sp
In the sample config file, there is a section which is named
\fB[rpcinterface:supervisor]\fP\&.  By default it looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This section \fImust\fP remain in the configuration for the standard setup
of supervisor to work properly.  If you don\(aqt want supervisor to do
anything it doesn\(aqt already do out of the box, this is all you need to
know about this type of section.
.sp
However, if you wish to add additional XML\-RPC interface namespaces to
a configuration of supervisor, you may add additional
\fB[rpcinterface:foo]\fP sections, where "foo" represents the namespace
of the interface (from the web root), and the value named by
\fBsupervisor.rpcinterface_factory\fP is a factory callable written in
Python which should have a function signature that accepts a single
positional argument \fBsupervisord\fP and as many keyword arguments as
required to perform configuration.  Any key/value pairs defined within
the \fBrpcinterface:foo\fP section will be passed as keyword arguments
to the factory.  Here\(aqs an example of a factory function, created in
the package \fBmy.package\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def make_another_rpcinterface(supervisord, **config):
    retries = int(config.get(\(aqretries\(aq, 0))
    another_rpc_interface = AnotherRPCInterface(supervisord, retries)
    return another_rpc_interface
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And a section in the config file meant to configure it.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Glossary
.INDENT 0.0
.TP
.B daemontools
A \fI\%process control system by D.J. Bernstein\fP\&.
.TP
.B launchd
A \fI\%process control system used by Apple\fP as process 1 under Mac
OS X.
.TP
.B runit
A \fI\%process control system\fP\&.
.TP
.B Superlance
A package which provides various event listener implementations
that plug into Supervisor which can help monitor process memory
usage and crash status: \fI\%http://pypi.python.org/pypi/superlance\fP\&.
.TP
.B umask
Abbreviation of \fIuser mask\fP: sets the file mode creation mask of
the current process.  See \fI\%http://en.wikipedia.org/wiki/Umask\fP\&.
.UNINDENT
.SH API DOCUMENTATION
.SS XML\-RPC API Documentation
.sp
To use the XML\-RPC interface, connect to supervisor\(aqs HTTP port
with any XML\-RPC client library and run commands against it.  An
example of doing this using Python\(aqs \fBxmlrpclib\fP client library
is as follows.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import xmlrpclib
server = xmlrpclib.Server(\(aqhttp://localhost:9001/RPC2\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You may call methods against \fBsupervisord\fP and its
subprocesses by using the \fBsupervisor\fP namespace.  An example is
provided below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server.supervisor.getState()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can get a list of methods supported by the
\fBsupervisord\fP XML\-RPC interface by using the XML\-RPC
\fBsystem.listMethods\fP API:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server.system.listMethods()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can see help on a method by using the \fBsystem.methodHelp\fP API
against the method:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server.system.methodHelp(\(aqsupervisor.shutdown\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBsupervisord\fP XML\-RPC interface also supports the
\fI\%XML\-RPC multicall API\fP\&.
.sp
You can extend \fBsupervisord\fP functionality with new XML\-RPC
API methods by adding new top\-level RPC interfaces as necessary.
See rpcinterface_factories\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Any XML\-RPC method call may result in a fault response.  This includes errors caused
by the client such as bad arguments, and any errors that make \fBsupervisord\fP
unable to fulfill the request.  Many XML\-RPC client programs will raise an exception
when a fault response is encountered.
.UNINDENT
.UNINDENT
.SS Status and Control
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
.INDENT 7.0
.TP
.B getAPIVersion()
Return the version of the RPC API used by supervisord
.sp
@return string version version id
.sp
This API is versioned separately from Supervisor itself. The API version
returned by \fBgetAPIVersion\fP only changes when the API changes. Its purpose
is to help the client identify with which version of the Supervisor API it
is communicating.
.sp
When writing software that communicates with this API, it is highly
recommended that you first test the API version for compatibility before
making method calls.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \fBgetAPIVersion\fP method replaces \fBgetVersion\fP found in Supervisor
versions prior to 3.0a1. It is aliased for compatibility but getVersion()
is deprecated and support will be dropped from Supervisor in a future
version.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B getSupervisorVersion()
Return the version of the supervisor package in use by supervisord
.sp
@return string version version id
.UNINDENT
.INDENT 7.0
.TP
.B getIdentification()
Return identifiying string of supervisord
.sp
@return string identifier identifying string
.sp
This method allows the client to identify with which Supervisor
instance it is communicating in the case of environments where
multiple Supervisors may be running.
.sp
The identification is a string that must be set in Supervisor’s
configuration file. This method simply returns that value back to the
client.
.UNINDENT
.INDENT 7.0
.TP
.B getState()
Return current state of supervisord as a struct
.sp
@return struct A struct with keys int statecode, string statename
.sp
This is an internal value maintained by Supervisor that determines what
Supervisor believes to be its current operational state.
.sp
Some method calls can alter the current state of the Supervisor. For
example, calling the method supervisor.shutdown() while the station is
in the RUNNING state places the Supervisor in the SHUTDOWN state while
it is shutting down.
.sp
The supervisor.getState() method provides a means for the client to check
Supervisor\(aqs state, both for informational purposes and to ensure that the
methods it intends to call will be permitted.
.sp
The return value is a struct:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqstatecode\(aq: 1,
 \(aqstatename\(aq: \(aqRUNNING\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The possible return values are:
.TS
center;
|l|l|l|.
_
T{
statecode
T}	T{
statename
T}	T{
Description
T}
_
T{
2
T}	T{
FATAL
T}	T{
Supervisor has experienced a serious error.
T}
_
T{
1
T}	T{
RUNNING
T}	T{
Supervisor is working normally.
T}
_
T{
0
T}	T{
RESTARTING
T}	T{
Supervisor is in the process of restarting.
T}
_
T{
\-1
T}	T{
SHUTDOWN
T}	T{
Supervisor is in the process of shutting down.
T}
_
.TE
.sp
The \fBFATAL\fP state reports unrecoverable errors, such as internal
errors inside Supervisor or system runaway conditions. Once set to
\fBFATAL\fP, the Supervisor can never return to any other state without
being restarted.
.sp
In the \fBFATAL\fP state, all future methods except
supervisor.shutdown() and supervisor.restart() will automatically fail
without being called and the fault \fBFATAL_STATE\fP will be raised.
.sp
In the \fBSHUTDOWN\fP or \fBRESTARTING\fP states, all method calls are
ignored and their possible return values are undefined.
.UNINDENT
.INDENT 7.0
.TP
.B getPID()
Return the PID of supervisord
.sp
@return int PID
.UNINDENT
.INDENT 7.0
.TP
.B readLog(offset, length)
Read length bytes from the main log starting at offset
.sp
@param int offset         offset to start reading from.
@param int length         number of bytes to read from the log.
@return string result     Bytes of log
.sp
It can either return the entire log, a number of characters from the
tail of the log, or a slice of the log specified by the offset and
length parameters:
.TS
center;
|l|l|l|.
_
T{
Offset
T}	T{
Length
T}	T{
Behavior of \fBreadProcessLog\fP
T}
_
T{
Negative
T}	T{
Not Zero
T}	T{
Bad arguments. This will raise the fault
\fBBAD_ARGUMENTS\fP\&.
T}
_
T{
Negative
T}	T{
Zero
T}	T{
This will return the tail of the log, or offset
number of characters from the end of the log.
For example, if \fBoffset\fP = \-4 and \fBlength\fP
= 0, then the last four characters will be
returned from the end of the log.
T}
_
T{
Zero or
Positive
T}	T{
Negative
T}	T{
Bad arguments. This will raise the fault
\fBBAD_ARGUMENTS\fP\&.
T}
_
T{
Zero or
Positive
T}	T{
Zero
T}	T{
All characters will be returned from the
\fBoffset\fP specified.
T}
_
T{
Zero or
Positive
T}	T{
Positive
T}	T{
A number of characters length will be returned
from the \fBoffset\fP\&.
T}
_
.TE
.sp
If the log is empty and the entire log is requested, an empty string
is returned.
.sp
If either offset or length is out of range, the fault
\fBBAD_ARGUMENTS\fP will be returned.
.sp
If the log cannot be read, this method will raise either the
\fBNO_FILE\fP error if the file does not exist or the \fBFAILED\fP error
if any other problem was encountered.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The readLog() method replaces readMainLog() found in Supervisor
versions prior to 2.1. It is aliased for compatibility but
readMainLog() is deprecated and support will be dropped from
Supervisor in a future version.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B clearLog()
Clear the main log.
.sp
@return boolean result always returns True unless error
.sp
If the log cannot be cleared because the log file does not exist, the
fault \fBNO_FILE\fP will be raised. If the log cannot be cleared for any
other reason, the fault \fBFAILED\fP will be raised.
.UNINDENT
.INDENT 7.0
.TP
.B shutdown()
Shut down the supervisor process
.sp
@return boolean result always returns True unless error
.sp
This method shuts down the Supervisor daemon. If any processes are running,
they are automatically killed without warning.
.sp
Unlike most other methods, if Supervisor is in the \fBFATAL\fP state,
this method will still function.
.UNINDENT
.INDENT 7.0
.TP
.B restart()
Restart the supervisor process
.sp
@return boolean result  always return True unless error
.sp
This method soft restarts the Supervisor daemon. If any processes are
running, they are automatically killed without warning. Note that the
actual UNIX process for Supervisor cannot restart; only Supervisor’s
main program loop. This has the effect of resetting the internal
states of Supervisor.
.sp
Unlike most other methods, if Supervisor is in the \fBFATAL\fP state,
this method will still function.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Process Control
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
.INDENT 7.0
.TP
.B getProcessInfo(name)
Get info about a process named name
.sp
@param string name The name of the process (or \(aqgroup:name\(aq)
@return struct result     A structure containing data about the process
.sp
The return value is a struct:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqname\(aq:           \(aqprocess name\(aq,
 \(aqgroup\(aq:          \(aqgroup name\(aq,
 \(aqdescription\(aq:    \(aqpid 18806, uptime 0:03:12\(aq
 \(aqstart\(aq:          1200361776,
 \(aqstop\(aq:           0,
 \(aqnow\(aq:            1200361812,
 \(aqstate\(aq:          1,
 \(aqstatename\(aq:      \(aqRUNNING\(aq,
 \(aqspawnerr\(aq:       \(aq\(aq,
 \(aqexitstatus\(aq:     0,
 \(aqlogfile\(aq:        \(aq/path/to/stdout\-log\(aq, # deprecated, b/c only
 \(aqstdout_logfile\(aq: \(aq/path/to/stdout\-log\(aq,
 \(aqstderr_logfile\(aq: \(aq/path/to/stderr\-log\(aq,
 \(aqpid\(aq:            1}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Name of the process
.UNINDENT
.INDENT 7.0
.TP
.B group
Name of the process\(aq group
.UNINDENT
.INDENT 7.0
.TP
.B description
If process state is running description\(aqs value is process_id
and uptime. Example "pid 18806, uptime 0:03:12 ".
If process state is stopped description\(aqs value is stop time.
Example:"Jun 5 03:16 PM ".
.UNINDENT
.INDENT 7.0
.TP
.B start
UNIX timestamp of when the process was started
.UNINDENT
.INDENT 7.0
.TP
.B stop
UNIX timestamp of when the process last ended, or 0 if the process
has never been stopped.
.UNINDENT
.INDENT 7.0
.TP
.B now
UNIX timestamp of the current time, which can be used to calculate
process up\-time.
.UNINDENT
.INDENT 7.0
.TP
.B state
State code, see process_states\&.
.UNINDENT
.INDENT 7.0
.TP
.B statename
String description of \fIstate\fP, see process_states\&.
.UNINDENT
.INDENT 7.0
.TP
.B logfile
Deprecated alias for \fBstdout_logfile\fP\&.  This is provided only
for compatibility with clients written for Supervisor 2.x and
may be removed in the future.  Use \fBstdout_logfile\fP instead.
.UNINDENT
.INDENT 7.0
.TP
.B stdout_logfile
Absolute path and filename to the STDOUT logfile
.UNINDENT
.INDENT 7.0
.TP
.B stderr_logfile
Absolute path and filename to the STDOUT logfile
.UNINDENT
.INDENT 7.0
.TP
.B spawnerr
Description of error that occurred during spawn, or empty string
if none.
.UNINDENT
.INDENT 7.0
.TP
.B exitstatus
Exit status (errorlevel) of process, or 0 if the process is still
running.
.UNINDENT
.INDENT 7.0
.TP
.B pid
UNIX process ID (PID) of the process, or 0 if the process is not
running.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B getAllProcessInfo()
Get info about all processes
.sp
@return array result  An array of process status results
.sp
Each element contains a struct, and this struct contains the exact
same elements as the struct returned by \fBgetProcessInfo\fP\&. If the process
table is empty, an empty array is returned.
.UNINDENT
.INDENT 7.0
.TP
.B startProcess(name, wait=True)
Start a process
.sp
@param string name Process name (or \fBgroup:name\fP, or \fBgroup:*\fP)
@param boolean wait Wait for process to be fully started
@return boolean result     Always true unless error
.UNINDENT
.INDENT 7.0
.TP
.B startAllProcesses(wait=True)
Start all processes listed in the configuration file
.sp
@param boolean wait    Wait for each process to be fully started
@return array result   An array of process status info structs
.UNINDENT
.INDENT 7.0
.TP
.B startProcessGroup(name, wait=True)
Start all processes in the group named \(aqname\(aq
.sp
@param string name     The group name
@param boolean wait    Wait for each process to be fully started
@return array result   An array of process status info structs
.UNINDENT
.INDENT 7.0
.TP
.B stopProcess(name, wait=True)
Stop a process named by name
.sp
@param string name  The name of the process to stop (or \(aqgroup:name\(aq)
@param boolean wait        Wait for the process to be fully stopped
@return boolean result     Always return True unless error
.UNINDENT
.INDENT 7.0
.TP
.B stopProcessGroup(name, wait=True)
Stop all processes in the process group named \(aqname\(aq
.sp
@param string name     The group name
@param boolean wait    Wait for each process to be fully stopped
@return array result   An array of process status info structs
.UNINDENT
.INDENT 7.0
.TP
.B stopAllProcesses(wait=True)
Stop all processes in the process list
.sp
@param  boolean wait   Wait for each process to be fully stopped
@return array result   An array of process status info structs
.UNINDENT
.INDENT 7.0
.TP
.B sendProcessStdin(name, chars)
Send a string of chars to the stdin of the process name.
If non\-7\-bit data is sent (unicode), it is encoded to utf\-8
before being sent to the process\(aq stdin.  If chars is not a
string or is not unicode, raise INCORRECT_PARAMETERS.  If the
process is not running, raise NOT_RUNNING.  If the process\(aq
stdin cannot accept input (e.g. it was closed by the child
process), raise NO_FILE.
.sp
@param string name        The process name to send to (or \(aqgroup:name\(aq)
@param string chars       The character data to send to the process
@return boolean result    Always return True unless error
.UNINDENT
.INDENT 7.0
.TP
.B sendRemoteCommEvent(type, data)
Send an event that will be received by event listener
subprocesses subscribing to the RemoteCommunicationEvent.
.sp
@param  string  type  String for the "type" key in the event header
@param  string  data  Data for the event body
@return boolean       Always return True unless error
.UNINDENT
.INDENT 7.0
.TP
.B reloadConfig()
Reload configuration
.sp
@return boolean result  always return True unless error
.UNINDENT
.INDENT 7.0
.TP
.B addProcessGroup(name)
Update the config for a running process from config file.
.sp
@param string name         name of process group to add
@return boolean result     true if successful
.UNINDENT
.INDENT 7.0
.TP
.B removeProcessGroup(name)
Remove a stopped process from the active configuration.
.sp
@param string name         name of process group to remove
@return boolean result     Indicates whether the removal was successful
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Process Logging
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
.INDENT 7.0
.TP
.B readProcessStdoutLog(name, offset, length)
Read length bytes from name\(aqs stdout log starting at offset
.sp
@param string name        the name of the process (or \(aqgroup:name\(aq)
@param int offset         offset to start reading from.
@param int length         number of bytes to read from the log.
@return string result     Bytes of log
.UNINDENT
.INDENT 7.0
.TP
.B readProcessStderrLog(name, offset, length)
Read length bytes from name\(aqs stderr log starting at offset
.sp
@param string name        the name of the process (or \(aqgroup:name\(aq)
@param int offset         offset to start reading from.
@param int length         number of bytes to read from the log.
@return string result     Bytes of log
.UNINDENT
.INDENT 7.0
.TP
.B tailProcessStdoutLog(name, offset, length)
Provides a more efficient way to tail the (stdout) log than
readProcessStdoutLog().  Use readProcessStdoutLog() to read
chunks and tailProcessStdoutLog() to tail.
.sp
Requests (length) bytes from the (name)\(aqs log, starting at
(offset).  If the total log size is greater than (offset +
length), the overflow flag is set and the (offset) is
automatically increased to position the buffer at the end of
the log.  If less than (length) bytes are available, the
maximum number of available bytes will be returned.  (offset)
returned is always the last offset in the log +1.
.sp
@param string name         the name of the process (or \(aqgroup:name\(aq)
@param int offset          offset to start reading from
@param int length          maximum number of bytes to return
@return array result       [string bytes, int offset, bool overflow]
.UNINDENT
.INDENT 7.0
.TP
.B tailProcessStderrLog(name, offset, length)
Provides a more efficient way to tail the (stderr) log than
readProcessStderrLog().  Use readProcessStderrLog() to read
chunks and tailProcessStderrLog() to tail.
.sp
Requests (length) bytes from the (name)\(aqs log, starting at
(offset).  If the total log size is greater than (offset +
length), the overflow flag is set and the (offset) is
automatically increased to position the buffer at the end of
the log.  If less than (length) bytes are available, the
maximum number of available bytes will be returned.  (offset)
returned is always the last offset in the log +1.
.sp
@param string name         the name of the process (or \(aqgroup:name\(aq)
@param int offset          offset to start reading from
@param int length          maximum number of bytes to return
@return array result       [string bytes, int offset, bool overflow]
.UNINDENT
.INDENT 7.0
.TP
.B clearProcessLogs(name)
Clear the stdout and stderr logs for the named process and
reopen them.
.sp
@param string name   The name of the process (or \(aqgroup:name\(aq)
@return boolean result      Always True unless error
.UNINDENT
.INDENT 7.0
.TP
.B clearAllProcessLogs()
Clear all process log files
.sp
@return array result   An array of process status info structs
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS System Methods
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B class supervisor.xmlrpc.SystemNamespaceRPCInterface(namespaces)
.INDENT 7.0
.TP
.B listMethods()
Return an array listing the available method names
.sp
@return array result  An array of method names available (strings).
.UNINDENT
.INDENT 7.0
.TP
.B methodHelp(name)
Return a string showing the method\(aqs documentation
.sp
@param string name   The name of the method.
@return string result The documentation for the method name.
.UNINDENT
.INDENT 7.0
.TP
.B methodSignature(name)
Return an array describing the method signature in the
form [rtype, ptype, ptype...] where rtype is the return data type
of the method, and ptypes are the parameter data types that the
method accepts in method argument order.
.sp
@param string name  The name of the method.
@return array result  The result.
.UNINDENT
.INDENT 7.0
.TP
.B multicall(calls)
Process an array of calls, and return an array of
results. Calls should be structs of the form {\(aqmethodName\(aq:
string, \(aqparams\(aq: array}. Each result will either be a
single\-item array containing the result value, or a struct of
the form {\(aqfaultCode\(aq: int, \(aqfaultString\(aq: string}. This is
useful when you need to make lots of small calls without lots
of round trips.
.sp
@param array calls  An array of call requests
@return array result  An array of results
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH PLUGINS
.SH INDICES AND TABLES
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
modindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
This man page was created by Orestis Ioannou <orestis@oioannou.com> using the
official documentation.
.SH COPYRIGHT
2004-2015, Agendaless Consulting and Contributors
.\" Generated by docutils manpage writer.
.