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
[program:x] Section Settings 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. |
| -s, --silent | No output directed to stdout. |
| -h, --help | Show supervisord command help. |
| -u USER, --user=USER | |
| UNIX username or numeric user id. If supervisord is started as the root user, setuid to this user as soon as possible during startup. | |
| -m OCTAL, --umask=OCTAL | |
| Octal number (e.g. 022) representing the umask that should be used by supervisord after it starts. | |
| -d PATH, --directory=PATH | |
| When supervisord is run as a daemon, cd to this directory before daemonizing. | |
| -l FILE, --logfile=FILE | |
| Filename path to use as the supervisord activity log. | |
| -y BYTES, --logfile_maxbytes=BYTES | |
| Max size of the supervisord activity log file before a rotation occurs. The value is suffix-multiplied, e.g “1” is one byte, “1MB” is 1 megabyte, “1GB” is 1 gigabyte. | |
| -z NUM, --logfile_backups=NUM | |
Number of backup copies of the supervisord activity log to keep
around. Each logfile will be of size logfile_maxbytes. | |
| -e LEVEL, --loglevel=LEVEL | |
The logging level at which supervisor should write to the activity
log. Valid levels are trace, debug, info, warn,
error, and critical. | |
| -j FILE, --pidfile=FILE | |
| The filename to which supervisord should write its pid file. | |
| -i STRING, --identifier=STRING | |
| Arbitrary string identifier exposed by various client UIs for this instance of supervisor. | |
| -q PATH, --childlogdir=PATH | |
A path to a directory (it must already exist) where supervisor will
write its AUTO -mode child process logs. | |
| -k, --nocleanup | |
Prevent supervisord from performing cleanup (removal of
old AUTO process log files) at startup. | |
| -a NUM, --minfds=NUM | |
| The minimum number of file descriptors that must be available to the supervisord process before it will start successfully. | |
| -t, --strip_ansi | |
| Strip ANSI escape sequences from all child log process. | |
| -v, --version | Print the supervisord version number out to stdout and exit. |
| --profile_options=LIST | |
Comma-separated options list for profiling. Causes
supervisord to run under a profiler, and output results
based on the options, which is a comma-separated list of the
following: cumulative, calls, callers.
E.g. cumulative,callers. | |
| --minprocs=NUM | The minimum number of OS process slots that must be available to the supervisord process before it will start successfully. |
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 with a code of 0 for success or running and non-zero for
error. An example: supervisorctl status all would return non-zero
if any single process was not running.
If supervisorctl is invoked in interactive mode against a supervisord that requires authentication, you will be asked for authentication credentials.
supervisorctl Command-Line Options¶
| -c, --configuration | |
| Configuration file path (default /etc/supervisord.conf) | |
| -h, --help | Print usage message and exit |
| -i, --interactive | |
| Start an interactive shell after executing commands | |
| -s, --serverurl URL | |
| URL on which supervisord server is listening (default “http://localhost:9001”). | |
| -u, --username | Username to use for authentication with server |
| -p, --password | Password to use for authentication with server |
| -r, --history-file | |
| Keep a readline history (if readline is available) | |
action [arguments]
Actions are commands like “tail” or “stop”. If -i is specified or no action is specified on the command line, a “shell” interpreting actions typed interactively is started. Use the action “help” to find out about available actions.
supervisorctl Actions¶
help
Print a list of available actions
help <action>
Print help for <action>
add <name> […]
Activates any updates in config for process/group
remove <name> […]
Removes process/group from active config
update
Reload config and add/remove as necessary, and will restart affected programs
update all
Reload config and add/remove as necessary, and will restart affected programs
update <gname> […]
Update specific groups, and will restart affected programs
clear <name>
Clear a process’ log files.
clear <name> <name>
Clear multiple process’ log files
clear all
Clear all process’ log files
fg <process>
Connect to a process in foreground mode Press Ctrl+C to exit foreground
pid
Get the PID of supervisord.
pid <name>
Get the PID of a single child process by name.
pid all
Get the PID of every child process, one per line.
reload
Restarts the remote supervisord
reread
Reload the daemon’s configuration files, without add/remove (no restarts)
restart <name>
Restart a process Note: restart does not reread config files. For that, see reread and update.
restart <gname>:*
Restart all processes in a group Note: restart does not reread config files. For that, see reread and update.
restart <name> <name>
Restart multiple processes or groups Note: restart does not reread config files. For that, see reread and update.
restart all
Restart all processes Note: restart does not reread config files. For that, see reread and update.
signal
No help on signal
start <name>
Start a process
start <gname>:*
Start all processes in a group
start <name> <name>
Start multiple processes or groups
start all
Start all processes
status
Get all process status info.
status <name>
Get status on a single process by name.
status <name> <name>
Get status on multiple named processes.
stop <name>
Stop a process
stop <gname>:*
Stop all processes in a group
stop <name> <name>
Stop multiple processes or groups
stop all
Stop all processes
tail [-f] <name> [stdout|stderr] (default stdout)
Output the last part of process logs Ex: tail -f <name> Continuous tail of named process stdout Ctrl-C to exit. tail -100 <name> last 100 bytes of process stdout tail <name> stderr last 1600 bytes of process stderr
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 start all processes.
SIGUSR2
supervisord will close and reopen the main activity log and all child log files.
Runtime Security¶
The developers have done their best to assure that use of a
supervisord process running as root cannot lead to
unintended privilege escalation. But caveat emptor. Supervisor
is not as paranoid as something like DJ Bernstein’s
daemontools, inasmuch as supervisord allows for
arbitrary path specifications in its configuration file to which data
may be written. Allowing arbitrary path selections can create
vulnerabilities from symlink attacks. Be careful when specifying
paths in your configuration. Ensure that the supervisord
configuration file cannot be read from or written to by unprivileged
users and that all files installed by the supervisor package have
“sane” file permission protection settings. Additionally, ensure that
your PYTHONPATH is sane and that all Python standard
library files have adequate file permission protections.
Running supervisord automatically on startup¶
If you are using a distribution-packaged version of Supervisor, it should already be integrated into the service management infrastructure of your distribution.
There are user-contributed scripts for various operating systems at: https://github.com/Supervisor/initscripts
There are some answers at Serverfault in case you get stuck: How to automatically start supervisord on Linux (Ubuntu)