Mastering Supervisor: Install, Configure, and Control Daemon Processes on Linux

Overview

Supervisor is a Python‑based general‑purpose process manager that can daemonize ordinary command‑line programs, monitor their status and automatically restart them on failure.

Installation

Source code: https://github.com/Supervisor/supervisor

Debian/Ubuntu:

sudo apt-get install supervisor

Configuration Files

Typical directory layout:

supervisor
├── conf.d
│   └── echo_time.conf   -- business config file
└── supervisord.conf    -- main config file (usually unchanged)

Main config location: /etc/supervisor/supervisord.conf Program‑specific configs go in /etc/supervisor/conf.d/*.conf.

supervisord vs supervisorctl

supervisord (the daemon)

Start with default config: supervisord Specify config: supervisord -c /etc/supervisord.conf Run as a specific user: supervisord -u user Systemd service commands (status, start, stop, restart, enable) using sudo systemctl … supervisor.service Systemd unit file /etc/systemd/system/supervisor.service includes ExecStart, ExecStop, ExecReload, Restart, etc.

supervisorctl (the client)

Interact with the running supervisord via commands such as supervisorctl status, start, stop, restart, reload, update, etc.

# stop a specific program
supervisorctl stop program_name

# start a program
supervisorctl start program_name

# restart a program
supervisorctl restart program_name

# stop all programs
supervisorctl stop all

# reload configuration and restart changed programs
supervisorctl reload

# apply new configuration without restarting unchanged programs
supervisorctl update

After editing a program’s config file, run sudo systemctl restart supervisor.service to reload.

Example: Running a Simple Bash Script

#/bin/bash
while true; do
    echo date +%Y-%m-%d,%H:%M:%S
    sleep 2
done

Create /etc/supervisor/conf.d/echo_time.conf:

[program:echo_time]
command=/usr/bin/env sh /home/www/python/echo_time.sh
directory=/home/www/python
user=www
startsecs=3
redirect_stderr=true
stdout_logfile=/home/www/python/log/echo_time.log
stdout_logfile_maxbytes=50MB
stdout_logfile_backups=10

Start or update the program:

supervisorctl update   # reload config and start new/changed programs
supervisorctl status   # view running status

View logs with tail -f /home/www/python/log/echo_time.log or via supervisorctl status.

Web Interface

Enable the [inet_http_server] section in /etc/supervisor/supervisord.conf (uncomment and set port, optional username/password). Then access http://myip:9001 in a browser.

Note: Enabling authentication in the web UI also requires authentication for the CLI client.

Common Issues

Port conflict error: “Another program is already listening on a port …” – stop the conflicting service before starting supervisord.

References

Supervisor GitHub: https://github.com/Supervisor/supervisor

Systemd service management guide

Supervisor tutorial (Chinese)

Python supervisor usage