Provided by: supervisor_4.2.5-1_all 
NAME
supervisor - Supervisor Documentation
Supervisor is a client/server system that allows its users to monitor and control a number
of processes on UNIX-like operating systems.
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 init 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.
NARRATIVE DOCUMENTATION
Introduction
Overview
Supervisor is a client/server system that allows its users to control a number of
processes on UNIX-like operating systems. It was inspired by the following:
Convenience
It is often inconvenient to need to write rc.d scripts for every single process
instance. rc.d scripts are a great lowest-common-denominator form of process
initialization/autostart/management, but they can be painful to write and maintain.
Additionally, rc.d 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.
Accuracy
It's 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.
Delegation
Users who need to control process state often need only to do that. They don't 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's usually the case that it's 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's 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.
Process Groups
Processes often need to be started and stopped in groups, sometimes even in a "priority
order". It's 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.
Features
Simple
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.
Centralized
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.
Efficient
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.
Extensible
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.
Compatible
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.
Proven
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.
Supervisor Components
supervisord
The server piece of supervisor is named supervisord. It is responsible for starting
child programs at its own invocation, responding to commands from clients, restarting
crashed or exited subprocesseses, logging its subprocess stdout and stderr output, and
generating and handling "events" corresponding to points in subprocess lifetimes.
The server process uses a configuration file. This is typically located in
/etc/supervisord.conf. This configuration file is a "Windows-INI" style config file.
It is important to keep this file secure via proper filesystem permissions because it
may contain unencrypted usernames and passwords.
supervisorctl
The command-line client piece of the supervisor is named supervisorctl. It provides a
shell-like interface to the features provided by supervisord. From supervisorctl, a
user can connect to different supervisord processes, get status on the subprocesses
controlled by, stop and start subprocesses of, and get lists of running processes of a
supervisord.
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 [supervisorctl] section in it will work.
Web Server
A (sparse) web user interface with functionality comparable to supervisorctl may be
accessed via a browser if you start supervisord against an internet socket. Visit the
server URL (e.g. http://localhost:9001/) to view and control process status through the
web interface after activating the configuration file's [inet_http_server] section.
XML-RPC Interface
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.
Platform Requirements
Supervisor has been tested and is known to run on Linux (Ubuntu 9.10), Mac OS X
(10.4/10.5/10.6), and Solaris (10 for Intel) and FreeBSD 6.1. It will likely work fine on
most UNIX systems.
Supervisor will not run at all under any version of Windows.
Supervisor is known to work with Python 2.4 or later but will not work under any version
of Python 3.
Running Supervisor
This section makes reference to a BINDIR when explaining how to run the supervisord and
supervisorctl commands. This is the "bindir" directory that your Python installation has
been configured with. For example, for an installation of Python installed via
./configure --prefix=/usr/local/py; make; make install, BINDIR would be /usr/local/py/bin.
Python interpreters on different platforms use a different BINDIR. Look at the output of
setup.py install if you can't figure out where yours is.
Adding a Program
Before supervisord will do anything useful for you, you'll need to add at least one
program section to its configuration. The program section will define a program that is
run and managed when you invoke the supervisord command. To add a program, you'll need to
edit the supervisord.conf file.
One of the simplest possible programs to run is the UNIX cat program. A program section
that will run cat when the supervisord process starts up is shown below.
[program:foo]
command=/bin/cat
This stanza may be cut and pasted into the supervisord.conf file. This is the simplest
possible program configuration, because it only names a command. Program configuration
sections have many other configuration options which aren't shown here. See
programx_section for more information.
Running supervisord
To start supervisord, run $BINDIR/supervisord. The resulting process will daemonize
itself and detach from the terminal. It keeps an operations log at $CWD/supervisor.log by
default.
You may start the supervisord executable in the foreground by passing the -n flag on its
command line. This is useful to debug startup problems.
WARNING:
When supervisord starts up, it will search for its configuration file in default
locations including the current working directory. If you are security-conscious you
will probably want to specify a "-c" argument after the supervisord command specifying
an absolute path to a configuration file to ensure that someone doesn't trick you into
running supervisor from within a directory that contains a rogue supervisord.conf file.
A warning is emitted when supervisor is started as root without this -c argument.
To change the set of programs controlled by supervisord, edit the supervisord.conf file
and kill -HUP or otherwise restart the supervisord process. This file has several example
program definitions.
The supervisord command accepts a number of command-line options. Each of these command
line options overrides any equivalent value in the configuration file.
supervisord Command-Line Options
-c FILE, --configuration=FILE
The path to a supervisord configuration file.
-n, --nodaemon
Run supervisord in the foreground.
-h, --help
Show supervisord command help.
-u USER, --user=USER
UNIX username or numeric user id. If supervisord is started as the root user,
setuid to this user as soon as possible during startup.
-m OCTAL, --umask=OCTAL
Octal number (e.g. 022) representing the umask that should be used by supervisord
after it starts.
-d PATH, --directory=PATH
When supervisord is run as a daemon, cd to this directory before daemonizing.
-l FILE, --logfile=FILE
Filename path to use as the supervisord activity log.
-y BYTES, --logfile_maxbytes=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.
-y NUM, --logfile_backups=NUM
Number of backup copies of the supervisord activity log to keep around. Each
logfile will be of size logfile_maxbytes.
-e LEVEL, --loglevel=LEVEL
The logging level at which supervisor should write to the activity log. Valid
levels are trace, debug, info, warn, error, and critical.
-j FILE, --pidfile=FILE
The filename to which supervisord should write its pid file.
-i STRING, --identifier=STRING
Arbitrary string identifier exposed by various client UIs for this instance of
supervisor.
-q PATH, --childlogdir=PATH
A path to a directory (it must already exist) where supervisor will write its AUTO
-mode child process logs.
-k, --nocleanup
Prevent supervisord from performing cleanup (removal of old AUTO process log files)
at startup.
-a NUM, --minfds=NUM
The minimum number of file descriptors that must be available to the supervisord
process before it will start successfully.
-t, --strip_ansi
Strip ANSI escape sequences from all child log process.
-v, --version
Print the supervisord version number out to stdout and exit.
--profile_options=LIST
Comma-separated options list for profiling. Causes supervisord to run under a
profiler, and output results based on the options, which is a comma-separated list
of the following: cumulative, calls, callers. E.g. cumulative,callers.
--minprocs=NUM
The minimum number of OS process slots that must be available to the supervisord
process before it will start successfully.
supervisorctl Command-Line Options
-c, --configuration
Configuration file path (default /etc/supervisord.conf)
-h, --help
Print usage message and exit
-i, --interactive
Start an interactive shell after executing commands
-s,--serverurl URL
URL on which supervisord server is listening (default "http://localhost:9001").
-u, --username
Username to use for authentication with server
-p, --password
Password to use for authentication with server
-r, --history-file
Keep a readline history (if readline is available)
action [arguments]
Actions are commands like "tail" or "stop". If -i is specified or no action is specified
on the command line, a "shell" interpreting actions typed interactively is started. Use
the action "help" to find out about available actions.
Running supervisorctl
To start supervisorctl, run $BINDIR/supervisorctl. A shell will be presented that will
allow you to control the processes that are currently managed by supervisord. Type "help"
at the prompt to get information about the supported commands.
The supervisorctl executable may be invoked with "one time" commands when invoked with
arguments from a command line. An example: supervisorctl stop all. If arguments are
present on the command-line, it will prevent the interactive shell from being invoked.
Instead, the command will be executed and supervisorctl will exit.
If supervisorctl is invoked in interactive mode against a supervisord that requires
authentication, you will be asked for authentication credentials.
Signals
The supervisord program may be sent signals which cause it to perform certain actions
while it's running.
You can send any of these signals to the single supervisord process id. This process id
can be found in the file represented by the pidfile parameter in the [supervisord] section
of the configuration file (by default it's $CWD/supervisord.pid).
Signal Handlers
SIGTERM
supervisord and all its subprocesses will shut down. This may take several seconds.
SIGINT
supervisord and all its subprocesses will shut down. This may take several seconds.
SIGQUIT
supervisord and all its subprocesses will shut down. This may take several seconds.
SIGHUP
supervisord will stop all processes, reload the configuration from the first config
file it finds, and restart all processes.
SIGUSR2
supervisord will close and reopen the main activity log and all child log files.
Runtime Security
The developers have done their best to assure that use of a supervisord process running as
root cannot lead to unintended privilege escalation. But caveat emptor. Supervisor is
not as paranoid as something like DJ Bernstein's daemontools, inasmuch as supervisord
allows for arbitrary path specifications in its configuration file to which data may be
written. Allowing arbitrary path selections can create vulnerabilities from symlink
attacks. Be careful when specifying paths in your configuration. Ensure that the
supervisord configuration file cannot be read from or written to by unprivileged users and
that all files installed by the supervisor package have "sane" file permission protection
settings. Additionally, ensure that your PYTHONPATH is sane and that all Python standard
library files have adequate file permission protections.
Running supervisord automatically on startup
If you are using a distribution-packaged version of Supervisor, it should already be
integrated into the service management infrastructure of your distribution.
There are user-contributed scripts for various operating systems at:
https://github.com/Supervisor/initscripts
There are some answers at Serverfault in case you get stuck: How to automatically start
supervisord on Linux (Ubuntu)
Configuration File
The Supervisor configuration file is conventionally named supervisord.conf. It is used by
both supervisord and supervisorctl. If either application is started without the -c
option (the option which is used to tell the application the configuration filename
explicitly), the application will look for a file named supervisord.conf within the
following locations, in the specified order. It will use the first file it finds.
1. $CWD/supervisord.conf
2. $CWD/etc/supervisord.conf
3. /etc/supervisord.conf
4. ../etc/supervisord.conf (Relative to the executable)
5. ../supervisord.conf (Relative to the executable)
NOTE:
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
/etc/supervisor/supervisord.conf.
File Format
supervisord.conf is a Windows-INI-style (Python ConfigParser) file. It has sections (each
denoted by a [header]) and key / value pairs within the sections. The sections and their
allowable values are described below.
Environment Variables
Environment variables that are present in the environment at the time that supervisord is
started can be used in the configuration file using the Python string expression syntax
%(ENV_X)s:
[program:example]
command=/usr/bin/example --loglevel=%(ENV_LOGLEVEL)s
In the example above, the expression %(ENV_LOGLEVEL)s would be expanded to the value of
the environment variable LOGLEVEL.
NOTE:
In Supervisor 3.2 and later, %(ENV_X)s expressions are supported in all options. In
prior versions, some options support them, but most do not. See the documentation for
each option below.
[unix_http_server] Section Settings
The supervisord.conf file contains a section named [unix_http_server] under which
configuration parameters for an HTTP server that listens on a UNIX domain socket should be
inserted. If the configuration file has no [unix_http_server] section, a UNIX domain
socket HTTP server will not be started. The allowable configuration values are as
follows.
[unix_http_server] Section Values
file
A path to a UNIX domain socket (e.g. /tmp/supervisord.sock) on which supervisor will
listen for HTTP/XML-RPC requests. supervisorctl uses XML-RPC to communicate with
supervisord over this port. This option can include the value %(here)s, which expands
to the directory in which the supervisord configuration file was found.
Default: None.
Required: No.
Introduced: 3.0
chmod
Change the UNIX permission mode bits of the UNIX domain socket to this value at
startup.
Default: 0700
Required: No.
Introduced: 3.0
chown
Change the user and group of the socket file to this value. May be a UNIX username
(e.g. chrism) or a UNIX username and group separated by a colon (e.g. chrism:wheel).
Default: Use the username and group of the user who starts supervisord.
Required: No.
Introduced: 3.0
username
The username required for authentication to this HTTP server.
Default: No username required.
Required: No.
Introduced: 3.0
password
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 {SHA}. For
example, {SHA}82ab876d1387bfafe46cc1c8a2ef074eae50cb1d is the SHA-stored version of the
password "thepassword".
Note that hashed password must be in hex format.
Default: No password required.
Required: No.
Introduced: 3.0
[unix_http_server] Section Example
[unix_http_server]
file = /tmp/supervisor.sock
chmod = 0777
chown= nobody:nogroup
username = user
password = 123
[inet_http_server] Section Settings
The supervisord.conf file contains a section named [inet_http_server] under which
configuration parameters for an HTTP server that listens on a TCP (internet) socket should
be inserted. If the configuration file has no [inet_http_server] section, an inet HTTP
server will not be started. The allowable configuration values are as follows.
[inet_http_server] Section Values
port
A TCP host:port value or (e.g. 127.0.0.1:9001) on which supervisor will listen for
HTTP/XML-RPC requests. supervisorctl will use XML-RPC to communicate with supervisord
over this port. To listen on all interfaces in the machine, use :9001 or *:9001.
Default: No default.
Required: Yes.
Introduced: 3.0
username
The username required for authentication to this HTTP server.
Default: No username required.
Required: No.
Introduced: 3.0
password
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 {SHA}. For
example, {SHA}82ab876d1387bfafe46cc1c8a2ef074eae50cb1d is the SHA-stored version of the
password "thepassword".
Note that hashed password must be in hex format.
Default: No password required.
Required: No.
Introduced: 3.0
[inet_http_server] Section Example
[inet_http_server]
port = 127.0.0.1:9001
username = user
password = 123
[supervisord] Section Settings
The supervisord.conf file contains a section named [supervisord] in which global settings
related to the supervisord process should be inserted. These are as follows.
[supervisord] Section Values
logfile
The path to the activity log of the supervisord process. This option can include the
value %(here)s, which expands to the directory in which the supervisord configuration
file was found.
Default: $CWD/supervisord.log
Required: No.
Introduced: 3.0
logfile_maxbytes
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.
Default: 50MB
Required: No.
Introduced: 3.0
logfile_backups
The number of backups to keep around resulting from activity log file rotation. If set
to 0, no backups will be kept.
Default: 10
Required: No.
Introduced: 3.0
loglevel
The logging level, dictating what is written to the supervisord activity log. One of
critical, error, warn, info, debug, trace, or blather. Note that at log level debug,
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't starting properly. See also: activity_log_levels.
Default: info
Required: No.
Introduced: 3.0
pidfile
The location in which supervisord keeps its pid file. This option can include the
value %(here)s, which expands to the directory in which the supervisord configuration
file was found.
Default: $CWD/supervisord.pid
Required: No.
Introduced: 3.0
umask
The umask of the supervisord process.
Default: 022
Required: No.
Introduced: 3.0
nodaemon
If true, supervisord will start in the foreground instead of daemonizing.
Default: false
Required: No.
Introduced: 3.0
minfds
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 minfds. 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's useful to be
able to specify a minimum value to ensure it doesn't run out of them during execution.
This option is particularly useful on Solaris, which has a low per-process fd limit by
default.
Default: 1024
Required: No.
Introduced: 3.0
minprocs
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 minprocs. 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's useful to ensure that enough
process descriptors are available upon supervisord startup.
Default: 200
Required: No.
Introduced: 3.0
nocleanup
Prevent supervisord from clearing any existing AUTO child log files at startup time.
Useful for debugging.
Default: false
Required: No.
Introduced: 3.0
childlogdir
The directory used for AUTO child log files. This option can include the value
%(here)s, which expands to the directory in which the supervisord configuration file
was found.
Default: value of Python's tempfile.get_tempdir()
Required: No.
Introduced: 3.0
user
Instruct supervisord to switch users to this UNIX user account before doing any
meaningful processing. The user can only be switched if supervisord is started as the
root user. If supervisord can't switch users, it will still continue but will write a
log message at the critical level saying that it can't drop privileges.
Default: do not switch users
Required: No.
Introduced: 3.0
directory
When supervisord daemonizes, switch to this directory. This option can include the
value %(here)s, which expands to the directory in which the supervisord configuration
file was found.
Default: do not cd
Required: No.
Introduced: 3.0
strip_ansi
Strip all ANSI escape sequences from child log files.
Default: false
Required: No.
Introduced: 3.0
environment
A list of key/value pairs in the form KEY="val",KEY2="val2" that will be placed in the
supervisord process' environment (and as a result in all of its child process'
environments). This option can include the value %(here)s, which expands to the
directory in which the supervisord configuration file was found. Values containing
non-alphanumeric characters should be quoted (e.g. KEY="val:123",KEY2="val,456").
Otherwise, quoting the values is optional but recommended. To escape percent
characters, simply use two. (e.g. URI="/first%%20name") Note that subprocesses will
inherit the environment variables of the shell used to start supervisord except for the
ones overridden here and within the program's environment option. See
subprocess_environment.
Default: no values
Required: No.
Introduced: 3.0
identifier
The identifier string for this supervisor process, used by the RPC interface.
Default: supervisor
Required: No.
Introduced: 3.0
[supervisord] Section Example
[supervisord]
logfile = /tmp/supervisord.log
logfile_maxbytes = 50MB
logfile_backups=10
loglevel = info
pidfile = /tmp/supervisord.pid
nodaemon = false
minfds = 1024
minprocs = 200
umask = 022
user = chrism
identifier = supervisor
directory = /tmp
nocleanup = true
childlogdir = /tmp
strip_ansi = false
environment = KEY1="value1",KEY2="value2"
[supervisorctl] Section Settings
The configuration file may contain settings for the supervisorctl interactive shell
program. These options are listed below.
[supervisorctl] Section Values
serverurl
The URL that should be used to access the supervisord server, e.g.
http://localhost:9001. For UNIX domain sockets, use
unix:///absolute/path/to/file.sock.
Default: http://localhost:9001
Required: No.
Introduced: 3.0
username
The username to pass to the supervisord server for use in authentication. This should
be same as username from the supervisord server configuration for the port or UNIX
domain socket you're attempting to access.
Default: No username
Required: No.
Introduced: 3.0
password
The password to pass to the supervisord server for use in authentication. This should
be the cleartext version of password from the supervisord server configuration for the
port or UNIX domain socket you're 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.
Default: No password
Required: No.
Introduced: 3.0
prompt
String used as supervisorctl prompt.
Default: supervisor
Required: No.
Introduced: 3.0
history_file
A path to use as the readline 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.
Default: No file
Required: No.
Introduced: 3.0a5
[supervisorctl] Section Example
[supervisorctl]
serverurl = unix:///tmp/supervisor.sock
username = chris
password = 123
prompt = mysupervisor
[program:x] Section Settings
The configuration file must contain one or more program sections in order for supervisord
to know which programs it should start and control. The header value is composite value.
It is the word "program", followed directly by a colon, then the program name. A header
value of [program:foo] describes a program with the name of "foo". The name is used
within client applications that control the processes that are created as a result of this
configuration. It is an error to create a program section that does not have a name. The
name must not include a colon character or a bracket character. The value of the name is
used as the value for the %(program_name)s string expression expansion within other values
where specified.
NOTE:
A [program:x] section actually represents a "homogeneous process group" to supervisor
(as of 3.0). The members of the group are defined by the combination of the numprocs
and process_name parameters in the configuration. By default, if numprocs and
process_name are left unchanged from their defaults, the group represented by
[program:x] will be named x and will have a single process named x in it. This
provides a modicum of backwards compatibility with older supervisor releases, which did
not treat program sections as homogeneous process group definitions.
But for instance, if you have a [program:foo] section with a numprocs of 3 and a
process_name expression of %(program_name)s_%(process_num)02d, the "foo" group will
contain three processes, named foo_00, foo_01, and foo_02. This makes it possible to
start a number of very similar processes using a single [program:x] section. All
logfile names, all environment strings, and the command of programs can also contain
similar Python string expressions, to pass slightly different parameters to each
process.
[program:x] Section Values
command
The command that will be run when this program is started. The command can be either
absolute (e.g. /path/to/programname) or relative (e.g. programname). If it is
relative, the supervisord's environment $PATH will be searched for the executable.
Programs can accept arguments, e.g. /path/to/program foo bar. The command line can use
double quotes to group arguments with spaces in them to pass to the program, e.g.
/path/to/program/name -p "foo bar". Note that the value of command may include Python
string expressions, e.g. /path/to/programname --port=80%(process_num)02d might expand
to /path/to/programname --port=8000 at runtime. String expressions are evaluated
against a dictionary containing the keys group_name, host_node_name, process_num,
program_name, here (the directory of the supervisord config file), and all
supervisord's environment variables prefixed with ENV_. Controlled programs should
themselves not be daemons, as supervisord assumes it is responsible for daemonizing its
subprocesses (see nondaemonizing_of_subprocesses).
Default: No default.
Required: Yes.
Introduced: 3.0
process_name
A Python string expression that is used to compose the supervisor process name for this
process. You usually don't need to worry about setting this unless you change
numprocs. The string expression is evaluated against a dictionary that includes
group_name, host_node_name, process_num, program_name, and here (the directory of the
supervisord config file).
Default: %(program_name)s
Required: No.
Introduced: 3.0
numprocs
Supervisor will start as many instances of this program as named by numprocs. Note
that if numprocs > 1, the process_name expression must include %(process_num)s (or any
other valid Python string expression that includes process_num) within it.
Default: 1
Required: No.
Introduced: 3.0
numprocs_start
An integer offset that is used to compute the number at which numprocs starts.
Default: 0
Required: No.
Introduced: 3.0
priority
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.
Default: 999
Required: No.
Introduced: 3.0
autostart
If true, this program will start automatically when supervisord is started.
Default: true
Required: No.
Introduced: 3.0
startsecs
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 STARTING state to the
RUNNING state). Set to 0 to indicate that the program needn't stay running for any
particular amount of time.
NOTE:
Even if a process exits with an "expected" exit code (see exitcodes), the start
will still be considered a failure if the process exits quicker than startsecs.
Default: 1
Required: No.
Introduced: 3.0
startretries
The number of serial failure attempts that supervisord will allow when attempting to
start the program before giving up and putting the process into an FATAL state. See
process_states for explanation of the FATAL state.
Default: 3
Required: No.
Introduced: 3.0
autorestart
Specifies if supervisord should automatically restart a process if it exits when it is
in the RUNNING state. May be one of false, unexpected, or true. If false, the process
will not be autorestarted. If unexpected, 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' configuration (see exitcodes). If true, the process will be unconditionally
restarted when it exits, without regard to its exit code.
NOTE:
autorestart controls whether supervisord will autorestart a program if it exits
after it has successfully started up (the process is in the RUNNING state).
supervisord has a different restart mechanism for when the process is starting up
(the process is in the STARTING state). Retries during process startup are
controlled by startsecs and startretries.
Default: unexpected
Required: No.
Introduced: 3.0
exitcodes
The list of "expected" exit codes for this program used with autorestart. If the
autorestart parameter is set to unexpected, and the process exits in any other way than
as a result of a supervisor stop request, supervisord will restart the process if it
exits with an exit code that is not defined in this list.
Default: 0,2
Required: No.
Introduced: 3.0
stopsignal
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.
Default: TERM
Required: No.
Introduced: 3.0
stopwaitsecs
The number of seconds to wait for the OS to return a SIGCHILD to supervisord after the
program has been sent a stopsignal. If this number of seconds elapses before
supervisord receives a SIGCHILD from the process, supervisord will attempt to kill it
with a final SIGKILL.
Default: 10
Required: No.
Introduced: 3.0
stopasgroup
If true, the flag causes supervisor to send the stop signal to the whole process group
and implies killasgroup 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.
Default: false
Required: No.
Introduced: 3.0b1
killasgroup
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 multiprocessing.
Default: false
Required: No.
Introduced: 3.0a11
user
Instruct supervisord to use this UNIX user account as the account which runs the
program. The user can only be switched if supervisord is run as the root user. If
supervisord can't switch to the specified user, the program will not be started.
NOTE:
The user will be changed using setuid only. This does not start a login shell and
does not change environment variables like USER or HOME. See
subprocess_environment for details.
Default: Do not switch users
Required: No.
Introduced: 3.0
redirect_stderr
If true, cause the process' stderr output to be sent back to supervisord on its stdout
file descriptor (in UNIX shell terms, this is the equivalent of executing /the/program
2>&1).
NOTE:
Do not set redirect_stderr=true in an [eventlistener:x] section. Eventlisteners
use stdout and stdin to communicate with supervisord. If stderr is redirected,
output from stderr will interfere with the eventlistener protocol.
Default: false
Required: No.
Introduced: 3.0, replaces 2.0's log_stdout and log_stderr
stdout_logfile
Put process stdout output in this file (and if redirect_stderr is true, also place
stderr output in this file). If stdout_logfile is unset or set to AUTO, supervisor
will automatically choose a file location. If this is set to NONE, supervisord will
create no log file. AUTO log files and their backups will be deleted when supervisord
restarts. The stdout_logfile value can contain Python string expressions that will
evaluated against a dictionary that contains the keys group_name, host_node_name,
process_num, program_name, and here (the directory of the supervisord config file).
NOTE:
It is not possible for two processes to share a single log file (stdout_logfile)
when rotation (stdout_logfile_maxbytes) is enabled. This will result in the file
being corrupted.
Default: AUTO
Required: No.
Introduced: 3.0, replaces 2.0's logfile
stdout_logfile_maxbytes
The maximum number of bytes that may be consumed by stdout_logfile 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.
Default: 50MB
Required: No.
Introduced: 3.0, replaces 2.0's logfile_maxbytes
stdout_logfile_backups
The number of stdout_logfile backups to keep around resulting from process stdout log
file rotation. If set to 0, no backups will be kept.
Default: 10
Required: No.
Introduced: 3.0, replaces 2.0's logfile_backups
stdout_capture_maxbytes
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.
Default: 0
Required: No.
Introduced: 3.0, replaces 2.0's logfile_backups
stdout_events_enabled
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).
Default: 0
Required: No.
Introduced: 3.0a7
stderr_logfile
Put process stderr output in this file unless redirect_stderr is true. Accepts the
same value types as stdout_logfile and may contain the same Python string expressions.
NOTE:
It is not possible for two processes to share a single log file (stderr_logfile)
when rotation (stderr_logfile_maxbytes) is enabled. This will result in the file
being corrupted.
Default: AUTO
Required: No.
Introduced: 3.0
stderr_logfile_maxbytes
The maximum number of bytes before logfile rotation for stderr_logfile. Accepts the
same value types as stdout_logfile_maxbytes.
Default: 50MB
Required: No.
Introduced: 3.0
stderr_logfile_backups
The number of backups to keep around resulting from process stderr log file rotation.
If set to 0, no backups will be kept.
Default: 10
Required: No.
Introduced: 3.0
stderr_capture_maxbytes
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.
Default: 0
Required: No.
Introduced: 3.0
stderr_events_enabled
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).
Default: false
Required: No.
Introduced: 3.0a7
environment
A list of key/value pairs in the form KEY="val",KEY2="val2" that will be placed in the
child process' environment. The environment string may contain Python string
expressions that will be evaluated against a dictionary containing group_name,
host_node_name, process_num, program_name, and here (the directory of the supervisord
config file). Values containing non-alphanumeric characters should be quoted (e.g.
KEY="val:123",KEY2="val,456"). Otherwise, quoting the values is optional but
recommended. Note that the subprocess will inherit the environment variables of the
shell used to start "supervisord" except for the ones overridden here. See
subprocess_environment.
Default: No extra environment
Required: No.
Introduced: 3.0
directory
A file path representing a directory to which supervisord should temporarily chdir
before exec'ing the child.
Default: No chdir (inherit supervisor's)
Required: No.
Introduced: 3.0
umask
An octal number (e.g. 002, 022) representing the umask of the process.
Default: No special umask (inherit supervisor's)
Required: No.
Introduced: 3.0
serverurl
The URL passed in the environment to the subprocess process as SUPERVISOR_SERVER_URL
(see supervisor.childutils) to allow the subprocess to easily communicate with the
internal HTTP server. If provided, it should have the same syntax and structure as the
[supervisorctl] 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.
Default: AUTO
Required: No.
Introduced: 3.0
[program:x] Section Example
[program:cat]
command=/bin/cat
process_name=%(program_name)s
numprocs=1
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=10
startretries=3
exitcodes=0,2
stopsignal=TERM
stopwaitsecs=10
stopasgroup=false
killasgroup=false
user=chrism
redirect_stderr=false
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_capture_maxbytes=1MB
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_capture_maxbytes=1MB
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO
[include] Section Settings
The supervisord.conf file may contain a section named [include]. If the configuration
file contains an [include] section, it must contain a single key named "files". The
values in this key specify other configuration files to be included within the
configuration.
[include] Section Values
files
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 *, ?, and character ranges expressed with [] will be correctly matched.
Recursive includes from included files are not supported.
Default: No default (required)
Required: Yes.
Introduced: 3.0
[include] Section Example
[include]
files = /an/absolute/filename.conf /an/absolute/*.conf foo.conf config??.conf
[group:x] Section Settings
It is often useful to group "homogeneous" process groups (aka "programs") together into a
"heterogeneous" process group so they can be controlled as a unit from Supervisor's
various controller interfaces.
To place programs into a group so you can treat them as a unit, define a [group:x] section
in your configuration file. The group header value is a composite. It is the word
"group", followed directly by a colon, then the group name. A header value of [group:foo]
describes a group with the name of "foo". The name is used within client applications
that control the processes that are created as a result of this configuration. It is an
error to create a group section that does not have a name. The name must not include a
colon character or a bracket character.
For a [group:x], there must be one or more [program:x] sections elsewhere in your
configuration file, and the group must refer to them by name in the programs value.
If "homogeneous" process groups (represented by program sections) are placed into a
"heterogeneous" group via [group:x] section's programs line, the homogeneous groups that
are implied by the program section will not exist at runtime in supervisor. Instead, all
processes belonging to each of the homogeneous groups will be placed into the
heterogeneous group. For example, given the following group configuration:
[group:foo]
programs=bar,baz
priority=999
Given the above, at supervisord startup, the bar and baz homogeneous groups will not
exist, and the processes that would have been under them will now be moved into the foo
group.
[group:x] Section Values
programs
A comma-separated list of program names. The programs which are listed become members
of the group.
Default: No default (required)
Required: Yes.
Introduced: 3.0
priority
A priority number analogous to a [program:x] priority value assigned to the group.
Default: 999
Required: No.
Introduced: 3.0
[group:x] Section Example
[group:foo]
programs=bar,baz
priority=999
[fcgi-program:x] Section Settings
Supervisor can manage groups of FastCGI processes that all listen on the same socket.
Until now, deployment flexibility for FastCGI was limited. To get full process
management, you could use mod_fastcgi under Apache but then you were stuck with Apache's
inefficient concurrency model of one process or thread per connection. In addition to
requiring more CPU and memory resources, the process/thread per connection model can be
quickly saturated by a slow resource, preventing other resources from being served. In
order to take advantage of newer event-driven web servers such as lighttpd or nginx which
don't include a built-in process manager, you had to use scripts like cgi-fcgi or
spawn-fcgi. These can be used in conjunction with a process manager such as supervisord
or daemontools but require each FastCGI child process to bind to its own socket. The
disadvantages of this are: unnecessarily complicated web server configuration, ungraceful
restarts, and reduced fault tolerance. With fewer sockets to configure, web server
configurations are much smaller if groups of FastCGI processes can share sockets. Shared
sockets allow for graceful restarts because the socket remains bound by the parent process
while any of the child processes are being restarted. Finally, shared sockets are more
fault tolerant because if a given process fails, other processes can continue to serve
inbound connections.
With integrated FastCGI spawning support, Supervisor gives you the best of both worlds.
You get full-featured process management with groups of FastCGI processes sharing sockets
without being tied to a particular web server. It's a clean separation of concerns,
allowing the web server and the process manager to each do what they do best.
NOTE:
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 socket.fromfd 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 0 (zero).
When the last child in the group exits, Supervisor will close the socket.
All the options available to [program:x] sections are also respected by fcgi-program
sections.
[fcgi-program:x] Section Values
[fcgi-program:x] sections have a single key which [program:x] sections do not have.
socket
The FastCGI socket for this program, either TCP or UNIX domain socket. For TCP sockets,
use this format: tcp://localhost:9002. For UNIX domain sockets, use
unix:///absolute/path/to/file.sock. String expressions are evaluated against a
dictionary containing the keys "program_name" and "here" (the directory of the
supervisord config file).
Default: No default.
Required: Yes.
Introduced: 3.0
socket_owner
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).
Default: Uses the user and group set for the fcgi-program
Required: No.
Introduced: 3.0
socket_mode
For UNIX domain sockets, this parameter can be used to specify the permission mode.
Default: 0700
Required: No.
Introduced: 3.0
Consult [program:x] Section Settings for other allowable keys, delta the above constraints
and additions.
[fcgi-program:x] Section Example
[fcgi-program:fcgiprogramname]
command=/usr/bin/example.fcgi
socket=unix:///var/run/supervisor/%(program_name)s.sock
socket_owner=chrism
socket_mode=0700
process_name=%(program_name)s_%(process_num)02d
numprocs=5
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=1
startretries=3
exitcodes=0,2
stopsignal=QUIT
stopasgroup=false
killasgroup=false
stopwaitsecs=10
user=chrism
redirect_stderr=true
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO
[eventlistener:x] Section Settings
Supervisor allows specialized homogeneous process groups ("event listener pools") to be
defined within the configuration file. These pools contain processes that are meant to
receive and respond to event notifications from supervisor's event system. See events for
an explanation of how events work and how to implement programs that can be declared as
event listeners.
Note that all the options available to [program:x] sections are respected by eventlistener
sections except for stdout_capture_maxbytes and stderr_capture_maxbytes (event listeners
cannot emit process communication events, see capture_mode).
[eventlistener:x] Section Values
[eventlistener:x] sections have a few keys which [program:x] sections do not have.
buffer_size
The event listener pool's event queue buffer size. When a listener pool's 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.
events
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).
result_handler
A pkg_resources entry point string that resolves to a Python callable. The default
value is supervisor.dispatchers:default_handler. 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.
Consult [program:x] Section Settings for other allowable keys, delta the above constraints
and additions.
[eventlistener:x] Section Example
[eventlistener:theeventlistenername]
command=/bin/eventlistener
process_name=%(program_name)s_%(process_num)02d
numprocs=5
events=PROCESS_STATE
buffer_size=10
directory=/tmp
umask=022
priority=-1
autostart=true
autorestart=unexpected
startsecs=1
startretries=3
exitcodes=0,2
stopsignal=QUIT
stopwaitsecs=10
stopasgroup=false
killasgroup=false
user=chrism
redirect_stderr=false
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO
[rpcinterface:x] Section Settings
Adding rpcinterface:x settings in the configuration file is only useful for people who
wish to extend supervisor with additional custom behavior.
In the sample config file, there is a section which is named [rpcinterface:supervisor].
By default it looks like the following.
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
The [rpcinterface:supervisor] section must remain in the configuration for the standard
setup of supervisor to work properly. If you don't want supervisor to do anything it
doesn't already do out of the box, this is all you need to know about this type of
section.
However, if you wish to add rpc interface namespaces in order to customize supervisor, you
may add additional [rpcinterface:foo] sections, where "foo" represents the namespace of
the interface (from the web root), and the value named by supervisor.rpcinterface_factory
is a factory callable which should have a function signature that accepts a single
positional argument supervisord and as many keyword arguments as required to perform
configuration. Any extra key/value pairs defined within the [rpcinterface:x] section will
be passed as keyword arguments to the factory.
Here's an example of a factory function, created in the __init__.py file of the Python
package my.package.
from my.package.rpcinterface import AnotherRPCInterface
def make_another_rpcinterface(supervisord, **config):
retries = int(config.get('retries', 0))
another_rpc_interface = AnotherRPCInterface(supervisord, retries)
return another_rpc_interface
And a section in the config file meant to configure it.
[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1
[rpcinterface:x] Section Values
supervisor.rpcinterface_factory
pkg_resources "entry point" dotted name to your RPC interface's factory function.
Default: N/A
Required: No.
Introduced: 3.0
[rpcinterface:x] Section Example
[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1
Subprocesses
supervisord's primary purpose is to create and manage processes based on data in its
configuration file. It does this by creating subprocesses. Each subprocess spawned by
supervisor is managed for the entirety of its lifetime by supervisord (supervisord is the
parent process of each process it creates). When a child dies, supervisor is notified of
its death via the SIGCHLD signal, and it performs the appropriate operation.
Nondaemonizing of Subprocesses
Programs meant to be run under supervisor should not daemonize themselves. Instead, they
should run in the foreground. They should not detach from the terminal from which they
are started.
The easiest way to tell if a program will run in the foreground is to run the command that
invokes the program from a shell prompt. If it gives you control of the terminal back,
but continues running, it's daemonizing itself and that will almost certainly be the wrong
way to run it under supervisor. You want to run a command that essentially requires you
to press Ctrl-C to get control of the terminal back. If it gives you a shell prompt back
after running it without needing to press Ctrl-C, it's not useful under supervisor. All
programs have options to be run in the foreground but there's no "standard way" to do it;
you'll need to read the documentation for each program.
Below are configuration file examples that are known to start common programs in
"foreground" mode under Supervisor.
Examples of Program Configurations
Here are some "real world" program configuration examples:
Apache 2.2.6
[program:apache2]
command=/path/to/httpd -c "ErrorLog /dev/stdout" -DFOREGROUND
redirect_stderr=true
Two Zope 2.X instances and one ZEO server
[program:zeo]
command=/path/to/runzeo
priority=1
[program:zope1]
command=/path/to/instance/home/bin/runzope
priority=2
redirect_stderr=true
[program:zope2]
command=/path/to/another/instance/home/bin/runzope
priority=2
redirect_stderr=true
Postgres 8.X
[program:postgres]
command=/path/to/postmaster
; we use the "fast" shutdown signal SIGINT
stopsignal=INT
redirect_stderr=true
OpenLDAP slapd
[program:slapd]
command=/path/to/slapd -f /path/to/slapd.conf -h ldap://0.0.0.0:8888
redirect_stderr=true
Other Examples
Other examples of shell scripts that could be used to start services under supervisord can
be found at http://thedjbway.b0llix.net/services.html. These examples are actually for
daemontools but the premise is the same for supervisor.
Another collection of recipes for starting various programs in the foreground is available
from http://smarden.org/runit/runscripts.html.
pidproxy Program
Some processes (like mysqld) ignore signals sent to the actual process which is spawned by
supervisord. Instead, a "special" thread/process is created by these kinds of programs
which is responsible for handling signals. This is problematic because supervisord can
only kill a process which it creates itself. If a process created by supervisord creates
its own child processes, supervisord cannot kill them.
Fortunately, these types of programs typically write a "pidfile" which contains the
"special" process' PID, and is meant to be read and used in order to kill the process. As
a workaround for this case, a special pidproxy program can handle startup of these kinds
of processes. The pidproxy program is a small shim that starts a process, and upon the
receipt of a signal, sends the signal to the pid provided in a pidfile. A sample
configuration program entry for a pidproxy-enabled program is provided below.
[program:mysql]
command=/path/to/pidproxy /path/to/pidfile /path/to/mysqld_safe
The pidproxy program is put into your configuration's $BINDIR when supervisor is installed
(it is a "console script").
Subprocess Environment
Subprocesses will inherit the environment of the shell used to start the supervisord
program. Several environment variables will be set by supervisord itself in the child's
environment also, including SUPERVISOR_ENABLED (a flag indicating the process is under
supervisor control), SUPERVISOR_PROCESS_NAME (the config-file-specified process name for
this process) and SUPERVISOR_GROUP_NAME (the config-file-specified process group name for
the child process).
These environment variables may be overridden within the [supervisord] section config
option named environment (applies to all subprocesses) or within the per- [program:x]
section environment config option (applies only to the subprocess specified within the
[program:x] section). These "environment" settings are additive. In other words, each
subprocess' environment will consist of:
The environment variables set within the shell used to start supervisord...
... added-to/overridden-by ...
... the environment variables set within the environment global
config option ...
... added-to/overridden-by ...
... supervisor-specific environment variables
(SUPERVISOR_ENABLED, SUPERVISOR_PROCESS_NAME, SUPERVISOR_GROUP_NAME) ..
... added-to/overridden-by ...
... the environment variables set within the per-process
"environment" config option.
No shell is executed by supervisord when it runs a subprocess, so environment variables
such as USER, PATH, HOME, SHELL, LOGNAME, etc. are not changed from their defaults or
otherwise reassigned. This is particularly important to note when you are running a
program from a supervisord run as root with a user= stanza in the configuration. Unlike
cron, supervisord does not attempt to divine and override "fundamental" environment
variables like USER, PATH, HOME, and LOGNAME when it performs a setuid to the user defined
within the user= program config option. If you need to set environment variables for a
particular program that might otherwise be set by a shell invocation for a particular
user, you must do it explicitly within the environment= program config option. An example
of setting these environment variables is as below.
[program:apache2]
command=/home/chrism/bin/httpd -c "ErrorLog /dev/stdout" -DFOREGROUND
user=chrism
environment=HOME="/home/chrism",USER="chrism"
Process States
A process controlled by supervisord will be in one of the below states at any given time.
You may see these state names in various user interface elements in clients.
STOPPED (0)
The process has been stopped due to a stop request or has never been started.
STARTING (10)
The process is starting due to a start request.
RUNNING (20)
The process is running.
BACKOFF (30)
The process entered the STARTING state but subsequently exited too quickly to move to
the RUNNING state.
STOPPING (40)
The process is stopping due to a stop request.
EXITED (100)
The process exited from the RUNNING state (expectedly or unexpectedly).
FATAL (200)
The process could not be started successfully.
UNKNOWN (1000)
The process is in an unknown state (supervisord programming error).
Each process run under supervisor progresses through these states as per the following
directed graph.
[image: Subprocess State Transition Graph] [image] Subprocess State Transition
Graph.UNINDENT
A process is in the STOPPED state if it has been stopped adminstratively or if it has
never been started.
When an autorestarting process is in the BACKOFF state, it will be automatically
restarted by supervisord. It will switch between STARTING and BACKOFF states until it
becomes evident that it cannot be started because the number of startretries has
exceeded the maximum, at which point it will transition to the FATAL state. Each start
retry will take progressively more time.
When a process is in the EXITED state, it will automatically restart:
• never if its autorestart parameter is set to false.
• unconditionally if its autorestart parameter is set to true.
• conditionally if its autorestart parameter is set to unexpected. If it exited with an
exit code that doesn't match one of the exit codes defined in the exitcodes
configuration parameter for the process, it will be restarted.
A process automatically transitions from EXITED to RUNNING as a result of being configured
to autorestart conditionally or unconditionally. The number of transitions between
RUNNING and EXITED 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.
An autorestarted process will never be automatically restarted if it ends up in the FATAL
state (it must be manually restarted from this state).
A process transitions into the STOPPING state via an administrative stop request, and will
then end up in the STOPPED state.
A process that cannot be stopped successfully will stay in the STOPPING state forever.
This situation should never be reached during normal operations as it implies that the
process did not respond to a final SIGKILL signal sent to it by supervisor, which is
"impossible" under UNIX.
State transitions which always require user action to invoke are these:
FATAL -> STARTING
RUNNING -> STOPPING
State transitions which typically, but not always, require user action to invoke are
these, with exceptions noted:
STOPPED -> STARTING (except at supervisord startup if process is configured to autostart)
EXITED -> STARTING (except if process is configured to autorestart)
All other state transitions are managed by supervisord automatically.
Logging
One of the main tasks that supervisord performs is logging. supervisord logs an activity
log detailing what it's doing as it runs. It also logs child process stdout and stderr
output to other files if configured to do so.
Activity Log
The activity log is the place where supervisord logs messages about its own health, its
subprocess' state changes, any messages that result from events, and debug and
informational messages. The path to the activity log is configured via the logfile
parameter in the [supervisord] section of the configuration file, defaulting to
$CWD/supervisord.log. Sample activity log traffic is shown in the example below. Some
lines have been broken to better fit the screen.
Sample Activity Log Output
2007-09-08 14:43:22,886 DEBG 127.0.0.1:Medusa (V1.11) started at Sat Sep 8 14:43:22 2007
Hostname: kingfish
Port:9001
2007-09-08 14:43:22,961 INFO RPC interface 'supervisor' initialized
2007-09-08 14:43:22,961 CRIT Running without any HTTP authentication checking
2007-09-08 14:43:22,962 INFO supervisord started with pid 27347
2007-09-08 14:43:23,965 INFO spawned: 'listener_00' with pid 27349
2007-09-08 14:43:23,970 INFO spawned: 'eventgen' with pid 27350
2007-09-08 14:43:23,990 INFO spawned: 'grower' with pid 27351
2007-09-08 14:43:24,059 DEBG 'listener_00' stderr output:
/Users/chrism/projects/supervisor/supervisor2/dev-sandbox/bin/python:
can't open file '/Users/chrism/projects/supervisor/supervisor2/src/supervisor/scripts/osx_eventgen_listener.py':
[Errno 2] No such file or directory
2007-09-08 14:43:24,060 DEBG fd 7 closed, stopped monitoring <PEventListenerDispatcher at 19910168 for
<Subprocess at 18892960 with name listener_00 in state STARTING> (stdout)>
2007-09-08 14:43:24,060 INFO exited: listener_00 (exit status 2; not expected)
2007-09-08 14:43:24,061 DEBG received SIGCHLD indicating a child quit
The activity log "level" is configured in the config file via the loglevel parameter in
the [supervisord] ini file section. When loglevel is set, messages of the specified
priority, plus those with any higher priority are logged to the activity log. For
example, if loglevel is error, messages of error and critical priority will be logged.
However, if loglevel is warn, messages of warn, error, and critical will be logged.
Activity Log Levels
The below table describes the logging levels in more detail, ordered in highest priority
to lowest. The "Config File Value" is the string provided to the loglevel parameter in
the [supervisord] section of configuration file and the "Output Code" is the code that
shows up in activity log output lines.
┌──────────────────┬─────────────┬──────────────────────────┐
│Config File Value │ Output Code │ Description │
├──────────────────┼─────────────┼──────────────────────────┤
│critical │ CRIT │ Messages that indicate a │
│ │ │ condition that requires │
│ │ │ immediate user │
│ │ │ attention, a supervisor │
│ │ │ state change, or an │
│ │ │ error in supervisor │
│ │ │ itself. │
├──────────────────┼─────────────┼──────────────────────────┤
│error │ ERRO │ Messages that indicate a │
│ │ │ potentially ignorable │
│ │ │ error condition (e.g. │
│ │ │ unable to clear a log │
│ │ │ directory). │
├──────────────────┼─────────────┼──────────────────────────┤
│warn │ WARN │ Messages that indicate │
│ │ │ an anomalous condition │
│ │ │ which isn't an error. │
├──────────────────┼─────────────┼──────────────────────────┤
│info │ INFO │ Normal informational │
│ │ │ output. This is the │
│ │ │ default log level if │
│ │ │ none is explicitly │
│ │ │ configured. │
├──────────────────┼─────────────┼──────────────────────────┤
│debug │ DEBG │ Messages useful for │
│ │ │ users trying to debug │
│ │ │ process configuration │
│ │ │ and communications │
│ │ │ behavior (process │
│ │ │ output, listener state │
│ │ │ changes, event │
│ │ │ notifications). │
├──────────────────┼─────────────┼──────────────────────────┤
│trace │ TRAC │ Messages useful for │
│ │ │ developers trying to │
│ │ │ debug supervisor │
│ │ │ plugins, and information │
│ │ │ about HTTP and RPC │
│ │ │ requests and responses. │
├──────────────────┼─────────────┼──────────────────────────┤
│blather │ BLAT │ Messages useful for │
│ │ │ developers trying to │
│ │ │ debug supervisor itself. │
└──────────────────┴─────────────┴──────────────────────────┘
Activity Log Rotation
The activity log is "rotated" by supervisord based on the combination of the
logfile_maxbytes and the logfile_backups parameters in the [supervisord] section of the
configuration file. When the activity log reaches logfile_maxbytes bytes, the current log
file is moved to a backup file and a new activity log file is created. When this happens,
if the number of existing backup files is greater than or equal to logfile_backups, the
oldest backup file is removed and the backup files are renamed accordingly. If the file
being written to is named supervisord.log, when it exceeds logfile_maxbytes, it is closed
and renamed to supervisord.log.1, and if files supervisord.log.1, supervisord.log.2 etc.
exist, then they are renamed to supervisord.log.2, supervisord.log.3 etc. respectively.
If logfile_maxbytes is 0, the logfile is never rotated (and thus backups are never made).
If logfile_backups is 0, no backups will be kept.
Child Process Logs
The stdout of child processes spawned by supervisor, by default, is captured for redisplay
to users of supervisorctl and other clients. If no specific logfile-related configuration
is performed in a [program:x], [fcgi-program:x], or [eventlistener:x] section in the
configuration file, the following is true:
• supervisord will capture the child process' stdout and stderr output into temporary
files. Each stream is captured to a separate file. This is known as AUTO log mode.
• AUTO log files are named automatically and placed in the directory configured as
childlogdir of the [supervisord] section of the config file.
• The size of each AUTO log file is bounded by the {streamname}_logfile_maxbytes 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
{streamname}_logfile_backups.
The configuration keys that influence child process logging in [program:x] and
[fcgi-program:x] sections are these:
redirect_stderr, stdout_logfile, stdout_logfile_maxbytes, stdout_logfile_backups,
stdout_capture_maxbytes, stderr_logfile, stderr_logfile_maxbytes, stderr_logfile_backups
and stderr_capture_maxbytes.
One may set stdout_logfile or stderr_logfile to the special string "syslog". In this case,
logs will be routed to the syslog service instead of being saved to files.
[eventlistener:x] sections may not specify redirect_stderr, stdout_capture_maxbytes, or
stderr_capture_maxbytes, but otherwise they accept the same values.
The configuration keys that influence child process logging in the [supervisord] config
file section are these: childlogdir, and nocleanup.
Capture Mode
Capture mode is an advanced feature of Supervisor. You needn't understand capture mode
unless you want to take actions based on data parsed from subprocess output.
If a [program:x] section in the configuration file defines a non-zero
stdout_capture_maxbytes or stderr_capture_maxbytes parameter, each process represented by
the program section may emit special tokens on its stdout or stderr stream (respectively)
which will effectively cause supervisor to emit a PROCESS_COMMUNICATION event (see events
for a description of events).
The process communications protocol relies on two tags, one which commands supervisor to
enter "capture mode" for the stream and one which commands it to exit. When a process
stream enters "capture mode", data sent to the stream will be sent to a separate buffer in
memory, the "capture buffer", which is allowed to contain a maximum of capture_maxbytes
bytes. During capture mode, when the buffer's length exceeds capture_maxbytes bytes, the
earliest data in the buffer is discarded to make room for new data. When a process stream
exits capture mode, a PROCESS_COMMUNICATION event subtype is emitted by supervisor, which
may be intercepted by event listeners.
The tag to begin "capture mode" in a process stream is <!--XSUPERVISOR:BEGIN-->. The tag
to exit capture mode is <!--XSUPERVISOR:END-->. The data between these tags may be
arbitrary, and forms the payload of the PROCESS_COMMUNICATION event. For example, if a
program is set up with a stdout_capture_maxbytes of "1MB", and it emits the following on
its stdout stream:
<!--XSUPERVISOR:BEGIN-->Hello!<!--XSUPERVISOR:END-->
In this circumstance, supervisord will emit a PROCESS_COMMUNICATIONS_STDOUT event with
data in the payload of "Hello!".
An example of a script (written in Python) which emits a process communication event is in
the scripts directory of the supervisor package, named sample_commevent.py.
The output of processes specified as "event listeners" ([eventlistener:x] sections) is not
processed this way. Output from these processes cannot enter capture mode.
Extending Supervisor's XML-RPC API
Supervisor can be extended with new XML-RPC APIs. Several third-party plugins already
exist that can be wired into your Supervisor configuration. You may additionally write
your own. Extensible XML-RPC interfaces is an advanced feature, introduced in version
3.0. You needn't understand it unless you wish to use an existing third-party RPC
interface plugin or if you wish to write your own RPC interface plugin.
Configuring XML-RPC Interface Factories
An additional RPC interface is configured into a supervisor installation by adding a
[rpcinterface:x] section in the Supervisor configuration file.
In the sample config file, there is a section which is named [rpcinterface:supervisor].
By default it looks like this:
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
This section must remain in the configuration for the standard setup of supervisor to work
properly. If you don't want supervisor to do anything it doesn't already do out of the
box, this is all you need to know about this type of section.
However, if you wish to add additional XML-RPC interface namespaces to a configuration of
supervisor, you may add additional [rpcinterface:foo] sections, where "foo" represents the
namespace of the interface (from the web root), and the value named by
supervisor.rpcinterface_factory is a factory callable written in Python which should have
a function signature that accepts a single positional argument supervisord and as many
keyword arguments as required to perform configuration. Any key/value pairs defined
within the rpcinterface:foo section will be passed as keyword arguments to the factory.
Here's an example of a factory function, created in the package my.package.
def make_another_rpcinterface(supervisord, **config):
retries = int(config.get('retries', 0))
another_rpc_interface = AnotherRPCInterface(supervisord, retries)
return another_rpc_interface
And a section in the config file meant to configure it.
[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1
Glossary
daemontools
A process control system by D.J. Bernstein.
launchd
A process control system used by Apple as process 1 under Mac OS X.
runit A process control system.
Superlance
A package which provides various event listener implementations that plug into
Supervisor which can help monitor process memory usage and crash status:
http://pypi.python.org/pypi/superlance.
umask Abbreviation of user mask: sets the file mode creation mask of the current process.
See http://en.wikipedia.org/wiki/Umask.
API DOCUMENTATION
XML-RPC API Documentation
To use the XML-RPC interface, connect to supervisor's HTTP port with any XML-RPC client
library and run commands against it. An example of doing this using Python's xmlrpclib
client library is as follows.
import xmlrpclib
server = xmlrpclib.Server('http://localhost:9001/RPC2')
You may call methods against supervisord and its subprocesses by using the supervisor
namespace. An example is provided below.
server.supervisor.getState()
You can get a list of methods supported by the supervisord XML-RPC interface by using the
XML-RPC system.listMethods API:
server.system.listMethods()
You can see help on a method by using the system.methodHelp API against the method:
server.system.methodHelp('supervisor.shutdown')
The supervisord XML-RPC interface also supports the XML-RPC multicall API.
You can extend supervisord functionality with new XML-RPC API methods by adding new
top-level RPC interfaces as necessary. See rpcinterface_factories.
NOTE:
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 supervisord unable to
fulfill the request. Many XML-RPC client programs will raise an exception when a fault
response is encountered.
Status and Control
class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
getAPIVersion()
Return the version of the RPC API used by supervisord
@return string version version id
This API is versioned separately from Supervisor itself. The API version
returned by getAPIVersion only changes when the API changes. Its purpose
is to help the client identify with which version of the Supervisor API
it is communicating.
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.
NOTE:
The getAPIVersion method replaces getVersion 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.
getSupervisorVersion()
Return the version of the supervisor package in use by supervisord
@return string version version id
getIdentification()
Return identifiying string of supervisord
@return string identifier identifying string
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.
The identification is a string that must be set in Supervisor’s
configuration file. This method simply returns that value back to the
client.
getState()
Return current state of supervisord as a struct
@return struct A struct with keys int statecode, string statename
This is an internal value maintained by Supervisor that determines what
Supervisor believes to be its current operational state.
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.
The supervisor.getState() method provides a means for the client to check
Supervisor's state, both for informational purposes and to ensure that
the methods it intends to call will be permitted.
The return value is a struct:
{'statecode': 1,
'statename': 'RUNNING'}
The possible return values are:
┌──────────┬────────────┬──────────────────────────┐
│statecode │ statename │ Description │
├──────────┼────────────┼──────────────────────────┤
│2 │ FATAL │ Supervisor has │
│ │ │ experienced a serious │
│ │ │ error. │
├──────────┼────────────┼──────────────────────────┤
│1 │ RUNNING │ Supervisor is working │
│ │ │ normally. │
├──────────┼────────────┼──────────────────────────┤
│0 │ RESTARTING │ Supervisor is in the │
│ │ │ process of restarting. │
├──────────┼────────────┼──────────────────────────┤
│-1 │ SHUTDOWN │ Supervisor is in the │
│ │ │ process of shutting │
│ │ │ down. │
└──────────┴────────────┴──────────────────────────┘
The FATAL state reports unrecoverable errors, such as internal errors
inside Supervisor or system runaway conditions. Once set to FATAL, the
Supervisor can never return to any other state without being restarted.
In the FATAL state, all future methods except supervisor.shutdown() and
supervisor.restart() will automatically fail without being called and the
fault FATAL_STATE will be raised.
In the SHUTDOWN or RESTARTING states, all method calls are ignored and
their possible return values are undefined.
getPID()
Return the PID of supervisord
@return int PID
readLog(offset, length)
Read length bytes from the main log starting at offset
@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
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:
┌─────────────────┬──────────┬──────────────────────────┐
│Offset │ Length │ Behavior of │
│ │ │ readProcessLog │
├─────────────────┼──────────┼──────────────────────────┤
│Negative │ Not Zero │ Bad arguments. This will │
│ │ │ raise the fault │
│ │ │ BAD_ARGUMENTS. │
└─────────────────┴──────────┴──────────────────────────┘
│Negative │ Zero │ This will return the │
│ │ │ tail of the log, or │
│ │ │ offset number of │
│ │ │ characters from the end │
│ │ │ of the log. For │
│ │ │ example, if offset = -4 │
│ │ │ and length = 0, then the │
│ │ │ last four characters │
│ │ │ will be returned from │
│ │ │ the end of the log. │
├─────────────────┼──────────┼──────────────────────────┤
│Zero or Positive │ Negative │ Bad arguments. This will │
│ │ │ raise the fault │
│ │ │ BAD_ARGUMENTS. │
├─────────────────┼──────────┼──────────────────────────┤
│Zero or Positive │ Zero │ All characters will be │
│ │ │ returned from the offset │
│ │ │ specified. │
├─────────────────┼──────────┼──────────────────────────┤
│Zero or Positive │ Positive │ A number of characters │
│ │ │ length will be returned │
│ │ │ from the offset. │
└─────────────────┴──────────┴──────────────────────────┘
If the log is empty and the entire log is requested, an empty string is
returned.
If either offset or length is out of range, the fault BAD_ARGUMENTS will
be returned.
If the log cannot be read, this method will raise either the NO_FILE
error if the file does not exist or the FAILED error if any other problem
was encountered.
NOTE:
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.
clearLog()
Clear the main log.
@return boolean result always returns True unless error
If the log cannot be cleared because the log file does not exist, the
fault NO_FILE will be raised. If the log cannot be cleared for any other
reason, the fault FAILED will be raised.
shutdown()
Shut down the supervisor process
@return boolean result always returns True unless error
This method shuts down the Supervisor daemon. If any processes are
running, they are automatically killed without warning.
Unlike most other methods, if Supervisor is in the FATAL state, this
method will still function.
restart()
Restart the supervisor process
@return boolean result always return True unless error
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.
Unlike most other methods, if Supervisor is in the FATAL state, this
method will still function.
Process Control
class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
getProcessInfo(name)
Get info about a process named name
@param string name The name of the process (or 'group:name') @return
struct result A structure containing data about the process
The return value is a struct:
{'name': 'process name',
'group': 'group name',
'description': 'pid 18806, uptime 0:03:12'
'start': 1200361776,
'stop': 0,
'now': 1200361812,
'state': 1,
'statename': 'RUNNING',
'spawnerr': '',
'exitstatus': 0,
'logfile': '/path/to/stdout-log', # deprecated, b/c only
'stdout_logfile': '/path/to/stdout-log',
'stderr_logfile': '/path/to/stderr-log',
'pid': 1}
name Name of the process
group Name of the process' group
description
If process state is running description's value is process_id and
uptime. Example "pid 18806, uptime 0:03:12 ". If process state is
stopped description's value is stop time. Example:"Jun 5 03:16 PM
".
start UNIX timestamp of when the process was started
stop UNIX timestamp of when the process last ended, or 0 if the process
has never been stopped.
now UNIX timestamp of the current time, which can be used to calculate
process up-time.
state State code, see process_states.
statename
String description of state, see process_states.
logfile
Deprecated alias for stdout_logfile. This is provided only for
compatibility with clients written for Supervisor 2.x and may be
removed in the future. Use stdout_logfile instead.
stdout_logfile
Absolute path and filename to the STDOUT logfile
stderr_logfile
Absolute path and filename to the STDOUT logfile
spawnerr
Description of error that occurred during spawn, or empty string
if none.
exitstatus
Exit status (errorlevel) of process, or 0 if the process is still
running.
pid UNIX process ID (PID) of the process, or 0 if the process is not
running.
getAllProcessInfo()
Get info about all processes
@return array result An array of process status results
Each element contains a struct, and this struct contains the exact same
elements as the struct returned by getProcessInfo. If the process table
is empty, an empty array is returned.
startProcess(name, wait=True)
Start a process
@param string name Process name (or group:name, or group:*) @param
boolean wait Wait for process to be fully started @return boolean result
Always true unless error
startAllProcesses(wait=True)
Start all processes listed in the configuration file
@param boolean wait Wait for each process to be fully started @return
array result An array of process status info structs
startProcessGroup(name, wait=True)
Start all processes in the group named 'name'
@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
stopProcess(name, wait=True)
Stop a process named by name
@param string name The name of the process to stop (or 'group:name')
@param boolean wait Wait for the process to be fully stopped
@return boolean result Always return True unless error
stopProcessGroup(name, wait=True)
Stop all processes in the process group named 'name'
@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
stopAllProcesses(wait=True)
Stop all processes in the process list
@param boolean wait Wait for each process to be fully stopped @return
array result An array of process status info structs
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' 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' stdin cannot accept input (e.g. it was closed by the
child process), raise NO_FILE.
@param string name The process name to send to (or 'group:name')
@param string chars The character data to send to the process
@return boolean result Always return True unless error
sendRemoteCommEvent(type, data)
Send an event that will be received by event listener subprocesses
subscribing to the RemoteCommunicationEvent.
@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
reloadConfig()
Reload configuration
@return boolean result always return True unless error
addProcessGroup(name)
Update the config for a running process from config file.
@param string name name of process group to add @return boolean
result true if successful
removeProcessGroup(name)
Remove a stopped process from the active configuration.
@param string name name of process group to remove @return
boolean result Indicates whether the removal was successful
Process Logging
class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
readProcessStdoutLog(name, offset, length)
Read length bytes from name's stdout log starting at offset
@param string name the name of the process (or 'group:name')
@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
readProcessStderrLog(name, offset, length)
Read length bytes from name's stderr log starting at offset
@param string name the name of the process (or 'group:name')
@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
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.
Requests (length) bytes from the (name)'s 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.
@param string name the name of the process (or 'group:name')
@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]
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.
Requests (length) bytes from the (name)'s 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.
@param string name the name of the process (or 'group:name')
@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]
clearProcessLogs(name)
Clear the stdout and stderr logs for the named process and reopen them.
@param string name The name of the process (or 'group:name') @return
boolean result Always True unless error
clearAllProcessLogs()
Clear all process log files
@return array result An array of process status info structs
System Methods
class supervisor.xmlrpc.SystemNamespaceRPCInterface(namespaces)
listMethods()
Return an array listing the available method names
@return array result An array of method names available (strings).
methodHelp(name)
Return a string showing the method's documentation
@param string name The name of the method. @return string result The
documentation for the method name.
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.
@param string name The name of the method. @return array result The
result.
multicall(calls)
Process an array of calls, and return an array of results. Calls should
be structs of the form {'methodName': string, 'params': array}. Each
result will either be a single-item array containing the result value, or
a struct of the form {'faultCode': int, 'faultString': string}. This is
useful when you need to make lots of small calls without lots of round
trips.
@param array calls An array of call requests @return array result An
array of results
PLUGINS
INDICES AND TABLES
• genindex
• modindex
• search
AUTHOR
This man page was created by Orestis Ioannou <orestis@oioannou.com> using the official
documentation.
COPYRIGHT
2004-2015, Agendaless Consulting and Contributors