SUPERVISOR(1)

💖 NAME 💖

supervisor — Supervisor Documentation, bestie. This is the whole lore dump for Supervisor, and yeah, it's the SUPERVISOR(1) page you're reading right now. 💅

Supervisor is a client/server system that lets its users monitor and control a bunch of processes on UNIX-like operating systems. Periodt.

It shares some of the same goals as programs like launchd, daemontools, and runit. But — and this is the important part — unlike some of those, it is not meant to be run as a substitute for init as "process id 1". Nope. Instead it's meant to be used to control processes related to a project or a customer, and it's 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, and honestly, the vibes are immaculate:

💫 Convenience

It is often inconvenient to need to write rc.d scripts for every single process instance. Like, every one?? 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. Slay. 🔥

🎯 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. No cap.

🫶 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, fr). 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. So clean, so elegant. ✨

🧚 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. Iconic behaviour, honestly. 💜

---

🌈 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.

🔒 Bestie, seriously. That config file can hold unencrypted usernames and passwords. Lock it down with proper filesystem permissions.

🐚 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.

⚠️ Yeah, that's not a typo. Python 2.4 or later, and Python 3 is a hard no.

---

🚀 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 — how big the supervisord activity log file can get before it does a lil rotation ✨. The value is suffix-multiplied bestie, so "1" is literally one byte, "1MB" is 1 megabyte, "1GB" is 1 gigabyte 💅
• -y NUM, --logfile_backups=NUM — how many backup copies of the supervisord activity log you wanna keep around 🎀. Each logfile will be of size logfile_maxbytes, no cap.
• -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 where supervisord should write its pid file 📝.
• -i STRING, --identifier=STRING — an arbitrary string identifier that various client UIs expose for this instance of supervisor 🦋.
• -q PATH, --childlogdir=PATH — a path to a directory (it must already exist, okay? she's not gonna make it for you 😭) where supervisor will write its AUTO-mode child process logs.
• -k, --nocleanup — stops supervisord from doing the cleanup (that's the removal of old AUTO process log files) at startup 🧹❌.
• -a NUM, --minfds=NUM — the minimum number of file descriptors that have to 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 have to 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] — the whole point, bestie 💖

Actions are commands like "tail" or "stop" fr fr. 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 bestie, fr fr. 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 🙈.

okay this part is not a vibe, it's a warning. read it twice. 💖

---

🌸 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. 😭 so check before you assume, bestie.

---

✨ 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 that authentication to this HTTP server needs. 💅 It can be a plain cleartext password, or you can hand over a SHA-1 hash instead — just prefix it with the string {SHA}. Like, for example, {SHA}82ab876d1387bfafe46cc1c8a2ef074eae50cb1d is the SHA-stored version of the password "thepassword". Slay.

Heads up bestie: a hashed password must be in hex format. No hex, no entry. 🚫

• 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

Okay so the supervisord.conf file has a section called [supervisord] where all the global, top-level, main-character settings for the supervisord process itself live. 🫶 Here's everything that goes in there.

⚙️ [supervisord] Section Values

• logfile — the path to supervisord's activity log. 📓 This option can include the value %(here)s, which expands to the directory where the supervisord config file was found.
  • Default: $CWD/supervisord.log
  • Required: No.
  • Introduced: 3.0
• logfile_maxbytes — the max number of bytes the activity log file can eat before it gets rotated (you can use suffix multipliers like "KB", "MB", and "GB" in the value). 🔄 Set it to 0 and the log size is unlimited.
  • Default: 50MB
  • Required: No.
  • Introduced: 3.0
• logfile_backups — how many backups to keep around from activity log rotation. Set it to 0 and, well, no backups. 🗑️
  • Default: 10
  • Required: No.
  • Introduced: 3.0
• loglevel — the logging level, which decides what actually gets 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 genuinely so useful for debugging a process that isn't starting properly. See also: activity_log_levels.
  • Default: info
  • Required: No.
  • Introduced: 3.0
• pidfile — where supervisord keeps its pid file. 📌 This option can include the value %(here)s, which expands to the directory where the supervisord config 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 starts in the foreground instead of daemonizing. 🏃‍♀️
  • Default: false
  • Required: No.
  • Introduced: 3.0
• minfds — the minimum number of file descriptors that have to be available before supervisord will start successfully. A call to setrlimit will be made to try to raise the soft and hard limits of the supervisord process to satisfy minfds. 🫠 The hard limit can only be raised if supervisord is run as root. supervisord uses file descriptors liberally and will enter a failure mode when one can't be obtained from the OS, so being able to specify a minimum value is useful to make sure it doesn't run out of them during execution. This option is especially 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 have to be available before supervisord will start successfully. A call to setrlimit will be made to try to raise the soft and hard limits of the supervisord process to satisfy minprocs. 😮‍💨 The hard limit can 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 make sure enough process descriptors are available at supervisord startup.
  • Default: 200
  • Required: No.
  • Introduced: 3.0
• nocleanup — stops 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 where the supervisord config file was found.
  • Default: value of Python's tempfile.get_tempdir()
  • Required: No.
  • Introduced: 3.0
• user — tells 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 it 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 where the supervisord config file was found.
  • Default: do not cd
  • Required: No.
  • Introduced: 3.0
• strip_ansi — strip all ANSI escape sequences out of 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 get placed in the supervisord process' environment (and, as a result, in all of its child processes' environments). 🌱 This option can include the value %(here)s, which expands to the directory where the supervisord config 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

Your config file can also hold settings for the supervisorctl interactive shell program. 🐚 Here they are, bestie.

💖 [supervisorctl] Section Values

• serverurl — the URL that should be used to reach 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 the same as username from the supervisord server configuration for the port or UNIX domain socket you're trying 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 trying 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 — the string used as the 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 get kept in the file, and you can use readline (e.g. arrow-up) to invoke commands you ran in your last supervisorctl session. So iconic.
  • 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 config file must contain one or more program sections, otherwise supervisord has no idea which programs it's supposed to start and control. 🎬 The header value is a composite value. It's 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". That name gets used inside client applications that control the processes created as a result of this configuration. Creating a program section with no name is an error. 🚨 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 like, plot twist, it can also be so much more. Say you've got a [program:foo] section with a numprocs of 3 and a process_name expression of %(program_name)s_%(process_num)02d — then your foo group is literally holding three whole processes, named foo_00, foo_01, and foo_02. Slay. That's how you spin up a bunch of basically-identical processes from one single [program:x] section. And bestie, it doesn't stop there — all the logfile names, all the environment strings, and the command of programs can hold these same Python string expressions too, so you can hand each process its own slightly different lil parameters. 💅

---

🎀 [program:x] Section Values 🎀

command

The command that gets run when this program starts. It can be absolute (like /path/to/programname) or relative (like programname). If it's relative, supervisord's environment $PATH gets searched for the executable. Programs can accept arguments, e.g. /path/to/program foo bar. And you can use double quotes to group arguments that have spaces in them so they get passed along together, e.g. /path/to/program/name -p "foo bar". Also — big one — 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. Those string expressions get evaluated against a dictionary containing the keys group_name, host_node_name, process_num, program_name, here (the directory of the supervisord config file), plus all of supervisord's environment variables prefixed with ENV_.

⚠️ Controlled programs should themselves not be daemons, because supervisord assumes it is the one responsible for daemonizing its subprocesses (see nondaemonizing_of_subprocesses).

• Default: No default.
• Required: Yes.
• Introduced: 3.0

process_name

A Python string expression used to compose the supervisor process name for this process. Honestly you usually don't need to worry about setting this unless you change numprocs. The expression gets 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 numprocs says. Heads up though: if numprocs > 1, your process_name expression must include %(process_num)s inside it (or any other valid Python string expression that includes process_num).

• Default: 1
• Required: No.
• Introduced: 3.0

numprocs_start

An integer offset 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 mean programs that start first and shut down last — both at startup and when aggregate commands are used in the various clients (e.g. "start all"/"stop all"). Higher priorities mean programs that start last and shut down first.

• Default: 999
• Required: No.
• Introduced: 3.0

autostart

If true, this program starts automatically when supervisord is started.

• Default: true
• Required: No.
• Introduced: 3.0

startsecs

The total number of seconds the program needs to stay running after a startup for the start to count as successful (that's the process moving from the STARTING state to the RUNNING state). Set it to 0 to say the program needn't stay running for any particular amount of time at all.

📌 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 supervisord will allow while trying to start the program before it gives up and drops the process into an FATAL state. See process_states for the explanation of that FATAL state.

• Default: 3
• Required: No.
• Introduced: 3.0

autorestart

Specifies whether supervisord should automatically restart a process if it exits while it's in the RUNNING state. Can be one of false, unexpected, or true. If false, the process won't be autorestarted. If unexpected, the process gets 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 gets unconditionally restarted when it exits, no regard whatsoever for 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 together 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 that many seconds go by 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 it 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, then when resorting to sending 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 be 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. Don't do it bestie. 😭

• 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 the process is in "stdout capture mode" (see capture_mode). Should be an integer (suffix multipliers like "KB", "MB" and "GB" can be 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: two processes cannot share a single log file (stderr_logfile) when rotation (stderr_logfile_maxbytes) is turned on. Bestie, if you try it, the file gets corrupted. That's not a vibe, that's a crime scene. 💀

• Default: AUTO
• Required: No.
• Introduced: 3.0

---

• stderr_logfile_maxbytes — the maximum number of bytes before logfile rotation kicks in for stderr_logfile. Takes the exact same value types as stdout_logfile_maxbytes, so you already know the drill. ✨
  • Default: 50MB
  • Required: No.
  • Introduced: 3.0
• stderr_logfile_backups — how many backups you keep around from the process stderr log file rotation. Set it to 0 and no backups get kept at all (bold move, but okay).
  • Default: 10
  • Required: No.
  • Introduced: 3.0
• stderr_capture_maxbytes — max number of bytes written to the capture FIFO while the process is in "stderr capture mode" (peep capture_mode). Should be an integer (suffix multipliers like KB, MB and GB are allowed in the value). If this value is 0, process capture mode is off. 🚫
  • Default: 0
  • Required: No.
  • Introduced: 3.0
• stderr_events_enabled — if true, PROCESS_LOG_STDERR events get emitted when the process writes to its stderr file descriptor. The events only go out if the file descriptor is not in capture mode at the moment the data is received (again, see capture_mode). 🎀
  • Default: false
  • Required: No.
  • Introduced: 3.0a7
• environment — a list of key/value pairs shaped like KEY="val",KEY2="val2" that get placed into the child process' environment. The environment string can contain Python string expressions, evaluated against a dictionary holding group_name, host_node_name, process_num, program_name, and here (that's the directory of the supervisord config file). Values with non-alphanumeric characters should be quoted (like KEY="val:123",KEY2="val,456"). Otherwise quoting is optional but honestly, recommended. Heads up: the subprocess inherits the environment variables of the shell used to start "supervisord", except for the ones you override right here. See subprocess_environment. 🌸
  • Default: No extra environment
  • Required: No.
  • Introduced: 3.0
• directory — a file path representing a directory that supervisord should temporarily chdir to 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 into the subprocess' environment as SUPERVISOR_SERVER_URL (see supervisor.childutils) so the subprocess can easily talk to the internal HTTP server. If you provide it, 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 automatically constructs a server URL, giving preference to a server listening on UNIX domain sockets over one listening 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 💖

Your supervisord.conf file can have a section named [include]. If the config file does contain an [include] section, it must contain a single key named "files". The values in that key specify other configuration files to be pulled into the configuration. It's giving modular. 🧚

✨ [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's considered relative to the location of the configuration file that includes it. A "glob" is a file pattern matching a specified pattern according to the rules the Unix shell uses. No tilde expansion is done, but *, ?, and character ranges expressed with [] will be correctly matched. Recursive includes from included files are not supported, bestie, don't try it. 🙈
  • 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's 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. Squad goals, fr fr.

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's 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". That name is used within client applications that control the processes created as a result of this configuration. It is an error to create a group section that does not have a name. And 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) get placed into a "heterogeneous" group via a [group:x] section's programs line, the homogeneous groups implied by the program section will not exist at runtime in supervisor. Instead, all processes belonging to each of the homogeneous groups get 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. On top of requiring more CPU and memory resources, that process/thread per connection model can be quickly saturated by a slow resource, preventing other resources from being served. And 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 alongside a process manager such as supervisord or daemontools, but they require each FastCGI child process to bind to its own socket. The disadvantages of that 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, letting the web server and the process manager each do what they do best. Iconic behaviour, honestly.

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 gets 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 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 is the lil setting where you specify the permission mode. Default: 0700. Required: No. Introduced: 3.0

Okay so for all the other keys you're allowed to use, go peek at the [program:x] Section Settings — just subtract the constraints and additions we just listed. iykyk 💅

---

[fcgi-program:x] Section Example ✨

Here's what a whole fcgi section looks like when it's fully dressed, bestie:

[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 🎧

So supervisor lets you define these specialized, homogeneous process groups — they call them "event listener pools" — right inside the config file. These pools are full of processes whose whole job is to receive and respond to event notifications from supervisor's event system. Wanna know how events work and how to write programs that can be declared as event listeners? Go read up on events, it's giving lore. 📖

Heads up though: every single option that [program:x] sections accept is respected by eventlistener sections too — except for stdout_capture_maxbytes and stderr_capture_maxbytes, because event listeners can't emit process communication events (go see capture_mode for the tea on that). 🫶

---

[eventlistener:x] Section Values 🌸

[eventlistener:x] sections got a few keys that [program:x] sections simply do not have, and honestly? main character energy.

• buffer_size — the event listener pool's event queue buffer size. When a listener pool's event buffer overflows (which totally happens when an event listener pool can't keep up with all the events being sent its way), the oldest event in the buffer gets discarded. bye bestie 👋
• events — a comma-separated list of event type names that this listener is "interested" in getting notifications for. Wanna know which names are even valid? Check out event_types for the list. 📝
• result_handler — a pkg_resources entry point string that resolves to a Python callable. The default value is supervisor.dispatchers:default_handler. Ngl, specifying an alternate result handler is a very uncommon thing to need to do, and because of that, how to actually create one is not documented. 🙈

And for all the other allowable keys, consult the [program:x] Section Settings — minus the constraints and additions above. periodt 💅

---

[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 🔌

Real talk: throwing rpcinterface:x settings into the config file is only useful for the people who wanna extend supervisor with extra custom behavior. That's a niche, and we respect it. 💜

In the sample config file there's a section named [rpcinterface:supervisor], and by default it looks exactly like this:

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

Okay and this part is important, bestie: the [rpcinterface:supervisor] section must stay in the configuration for the standard setup of supervisor to work properly. If you don't want supervisor doing anything it doesn't already do right out of the box, that's literally all you need to know about this type of section. Slay, you're done here. ✨

BUT. If you do wanna add rpc interface namespaces to customize supervisor, you can add extra [rpcinterface:foo] sections, where "foo" is the namespace of the interface (from the web root), and the value named by supervisor.rpcinterface_factory is a factory callable. That factory should have a function signature that accepts a single positional argument supervisord plus as many keyword arguments as required to perform configuration. And any extra key/value pairs you define inside the [rpcinterface:x] section get passed as keyword arguments to that 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 here's the section in the config file that's meant to configure it:

[rpcinterface:another]
supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
retries = 1

---

[rpcinterface:x] Section Values ⭐

• supervisor.rpcinterface_factory — the pkg_resources "entry point" dotted name pointing 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 whole primary purpose is creating and managing processes based on the data in its configuration file, and it does that by creating subprocesses. Every single subprocess spawned by supervisor is managed for the entirety of its lifetime by supervisord (supervisord is the parent process of every process it creates, no cap). And when a child dies? Supervisor gets notified of its death via the SIGCHLD signal and performs the appropriate operation. 💀➡️🛠️

---

Nondaemonizing of Subprocesses 🚫🧚

Programs that are meant to run under supervisor should not daemonize themselves. Instead they should run in the foreground, and they should not detach from the terminal they were started from. fr fr.

The easiest way to tell if a program will run in the foreground is to run the command that invokes the program straight from a shell prompt. If it hands you back control of the terminal but keeps on running, it's daemonizing itself, and that is almost certainly the wrong way to run it under supervisor. What you actually want is a command that basically requires you to press Ctrl-C to get control of the terminal back. If it gives you a shell prompt back after running without you 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 have to go read the documentation for each individual program. Sorry bestie, that's just how it is. 📚

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. Okay technically those examples are for daemontools, but the premise is the same for supervisor. iykyk.

And 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) just ignore signals sent to the actual process that was spawned by supervisord. Instead, these kinds of programs create a "special" thread/process which is the one responsible for handling signals. Which is a whole problem, because supervisord can only kill a process it created itself. So if a process created by supervisord goes and creates its own child processes, supervisord cannot kill them. 🙃

Fortunately — plot twist — these types of programs typically write a "pidfile" that contains the "special" process' PID, and that pidfile is meant to be read and used in order to kill the process. So as a workaround for this case, a special pidproxy program can handle the 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 that 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 gets put into your configuration's $BINDIR when supervisor is installed (it's a "console script"). ✨

---

Subprocess Environment 🌱

Subprocesses will inherit the environment of the shell that was used to start the supervisord program. Several environment variables get set by supervisord itself in the child's environment as well, 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). 🫶

okay so these environment variables can get overridden in two places, and you gotta know which is which 💅

• the environment config option inside the [supervisord] section → this one applies to all subprocesses, every single one
• the environment config option inside a per-[program:x] section → this one applies only to the subprocess specified within that [program:x] section

and here's the tea 🫖 — these environment settings are additive. like, they stack. so each subprocess' environment ends up being built up in layers, exactly like this:

• 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

so yeah, it's giving layered cake, and the later layers win. 🎂

No shell is executed by supervisord when it runs a subprocess, so environment variables like 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.

okay now the lore on how it actually moves around 👑

• 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 💖

okay so the log levels, bestie — here's the full rundown, and they're listed from highest priority to lowest, so like, the further down you scroll, the chattier it gets. 🌈

The "Config File Value" is the string you hand to the loglevel parameter in the [supervisord] section of the config file, and the "Output Code" is the lil code that shows up in your activity log output lines. iykyk.

• 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. lowkey suspicious but not an error, you know?
• 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. it's giving maximum yapping and honestly? we respect it 💅

---

🌸 Activity Log Rotation 🌸

The activity log gets "rotated" by supervisord based on the combination of the logfile_maxbytes and the logfile_backups parameters in the [supervisord] section of the configuration file. 💫

Here's the tea: when the activity log reaches logfile_maxbytes bytes, the current log file is moved to a backup file and a brand new activity log file is created. 🎀

When that happens, if the number of existing backup files is greater than or equal to logfile_backups, the oldest backup file gets removed and the backup files are renamed accordingly.

So like, 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. the whole roster shuffles down one seat 🪑

bestie, listen: if logfile_maxbytes is 0, the logfile is never rotated (and thus backups are never made). And if logfile_backups is 0, no backups will be kept. periodt.

---

🦋 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. no pressure bestie, it's optional 💜

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. 🐍

heads up: 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. main character energy only 🫶

---

🌈 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

okay so bestie, this section HAS to stay in the config if you want the standard setup of supervisor to work properly. no cap. If you don't want supervisor to do anything it doesn't already do out of the box, then honestly? This is literally all you need to know about this type of section. 💅✨

But if you DO wanna add extra XML-RPC interface namespaces to a supervisor config, you can add more [rpcinterface:foo] sections. Here "foo" is the namespace of the interface (from the web root), and the value named by supervisor.rpcinterface_factory is a factory callable written in Python. It 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 you define inside the rpcinterface:foo section get 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 here's 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. It 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 👑

Here's the class you're working with: 💜

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 2, statename FATAL — Supervisor has experienced a serious error. 💀
• statecode 1, statename RUNNING — Supervisor is working normally. ✅
• statecode 0, statename RESTARTING — Supervisor is in the process of restarting. 🔄
• statecode -1, statename 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. 🍓

So readProcessLog is lowkey a whole vibe — it can hand you the entire log, or a certain number of characters off the tail, or a lil slice you define with the offset and length params. Here's the tea 🍵:

• offset negative, length not zero — bad arguments, bestie. This raises the fault BAD_ARGUMENTS. 💀
• offset negative, length zero — you get the tail of the log, aka offset number of characters counting back from the end. So if offset = -4 and length = 0, the last four characters come back from the end of the log. 🎀
• offset zero or positive, length negative — bad arguments again. Raises the fault BAD_ARGUMENTS. 🚫
• offset zero or positive, length zero — every character from the offset you specified comes back. ✨
• offset zero or positive, length positive — a number of characters equal to length comes back, starting 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's aliased for compatibility, but readMainLog() is deprecated and support will be dropped from Supervisor in a future version. So like… move on, she's leaving. 👋

---

🧹 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. No goodbye text, no nothing. 😭

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 the process state is running, description's value is process_id and uptime. Example: "pid 18806, uptime 0:03:12 ". If the process state is stopped, description's value is the 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

okay so we're picking back up mid-thought — here's the rest of what startProcess is serving, bestie:

• @param string name — the process name (or group:name, or group:*) 💅
• @param boolean wait — wait for the process to be fully started
• @return boolean result — always true unless there's an error

• startAllProcesses(wait=True) — starts every single process listed in the configuration file. all of them. no skips. 🫶
  • @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) — starts all the processes in the group named name. squad goals, literally ✨
  • @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) — stops a process named by name. respectfully, sit down 🪑
  • @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 returns True unless there's an error
• stopProcessGroup(name, wait=True) — stops all the processes in the process group named name. the whole group chat is being archived 💀
  • @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) — stops all processes in the process list. everyone out 🌸
  • @param boolean wait — wait for each process to be fully stopped
  • @return array result — an array of process status info structs
• sendProcessStdin(name, chars) — sends a string of chars to the stdin of the process name. if non-7-bit data is sent (unicode), it gets encoded to utf-8 before being sent to the process' stdin. if chars is not a string or is not unicode, it raises INCORRECT_PARAMETERS. if the process is not running, it raises NOT_RUNNING. and if the process' stdin cannot accept input (like, say, it was closed by the child process), it raises NO_FILE. so many ways to fail, so little time 😭
  • @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 returns True unless there's an error
• sendRemoteCommEvent(type, data) — sends an event that will be received by event listener subprocesses subscribing to the RemoteCommunicationEvent. passing notes in class, iconic behavior 📨
  • @param string type — string for the "type" key in the event header
  • @param string data — data for the event body
  • @return boolean — always returns True unless there's an error
• reloadConfig() — reloads the configuration. glow-up for your config file ✨
  • @return boolean result — always returns True unless there's an error
• addProcessGroup(name) — updates the config for a running process from the config file.
  • @param string name — name of the process group to add
  • @return boolean result — true if successful
• removeProcessGroup(name) — removes a stopped process from the active configuration. note: stopped. this is not a "yeet it while it's running" situation 🚫
  • @param string name — name of the process group to remove
  • @return boolean result — indicates whether the removal was successful

---

🎀 Process Logging 🎀

class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)

• readProcessStdoutLog(name, offset, length) — reads length bytes from name's stdout log, starting at offset. chunk-by-chunk reading, the responsible way 🧚
  • @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) — reads length bytes from name's stderr log, starting at offset. the messy sibling of the one above, still valid 💜
  • @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) — this one gives you a more efficient way to tail the (stdout) log than readProcessStdoutLog(). the vibe is: use readProcessStdoutLog() to read chunks, and tailProcessStdoutLog() to tail. two different jobs, two different queens 👑

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. the (offset) returned is always the last offset in the log +1. periodt.

• @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) — same deal but for (stderr): a more efficient way to tail the (stderr) log than readProcessStderrLog(). use readProcessStderrLog() to read chunks and tailProcessStderrLog() to tail. matching set, no notes 💅

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. the (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) — clears the stdout and stderr logs for the named process and reopens them. fresh slate, fresh me 🦋
  • @param string name — the name of the process (or 'group:name')
  • @return boolean result — always True unless there's an error
• clearAllProcessLogs() — clears all process log files. mass deletion but make it cute 🌈
  • @return array result — an array of process status info structs

---

System Methods

class supervisor.xmlrpc.SystemNamespaceRPCInterface(namespaces)

• listMethods() — returns an array listing the available method names. the menu, the lineup, the roster 📋
  • @return array result — an array of method names available (strings).
• methodHelp(name) — returns a string showing the method's documentation. it explains itself so you don't have to 🙈
  • @param string name — the name of the method.
  • @return string result — the documentation for the method name.
• methodSignature(name) — returns 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) — processes an array of calls and returns 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. efficiency is the whole aesthetic ⚡
  • @param array calls — an array of call requests
  • @return array result — an array of results

---

✨ PLUGINS ✨

okay so this section exists but there's genuinely nothing under it in this version. an empty section. it's giving reserved seating 🎀 no content, no drama.

---

📚 INDICES AND TABLES 📚

the little navigation corner of the docs, bestie:

• genindex
• modindex
• search

---

👑 AUTHOR 👑

this man page was created by Orestis Ioannou <orestis@oioannou.com> using the official documentation. credit where credit is due, we love a builder 💖

---

©️ COPYRIGHT ©️

2004-2015, Agendaless Consulting and Contributors

---

and that's a wrap on SUPERVISOR(1)! 🎉 tysm for reading the whole thing, you're genuinely so smart for that. this page is for version 3.2.0, dated December 10, 2015 — yes it's vintage, yes it still slays. go supervise something responsibly, bestie. mwah 💋