[program:x] Section Settings

The configuration file must contain one or more program sectionsin order for supervisord to know which programs it should start andcontrol. The header value is composite value. It is the word“program”, followed directly by a colon, then the program name. Aheader value of [program:foo] describes a program with the name of“foo”. The name is used within client applications that control theprocesses that are created as a result of this configuration. It isan error to create a program section that does not have a name.The name must not include a colon character or a bracket character.The value of the name is used as the value for the%(program_name)s string expression expansion within other valueswhere specified.

Note

A [program:x] section actually represents a “homogeneousprocess group” to supervisor (as of 3.0). The members of the groupare defined by the combination of the numprocs andprocess_name parameters in the configuration. By default, ifnumprocs and process_name are left unchanged from their defaults,the group represented by [program:x] will be named x andwill have a single process named x in it. This provides amodicum of backwards compatibility with older supervisor releases,which did not treat program sections as homogeneous process groupdefinitions.

But for instance, if you have a [program:foo] section with anumprocs of 3 and a processname expression of%(program_name)s%(process_num)02d, the “foo” group willcontain three processes, named foo_00, foo_01, andfoo_02. This makes it possible to start a number of verysimilar processes using a single [program:x] section. Alllogfile names, all environment strings, and the command of programscan also contain similar Python string expressions, to passslightly different parameters to each process.

[program:x] Section Values

command

The command that will be run when this program is started. Thecommand can be either absolute (e.g. /path/to/programname) orrelative (e.g. programname). If it is relative, thesupervisord’s environment $PATH will be searched for theexecutable. Programs can accept arguments, e.g. /path/to/programfoo bar. The command line can use double quotes to grouparguments with spaces in them to pass to the program,e.g. /path/to/program/name -p "foo bar". Note that the value ofcommand may include Python string expressions,e.g. /path/to/programname —port=80%(processnum)02d mightexpand to /path/to/programname —port=8000 at runtime. Stringexpressions are evaluated against a dictionary containing the keysgroup_name, host_node_name, process_num, program_name,here (the directory of the supervisord config file), and allsupervisord’s environment variables prefixed with ENV. Controlledprograms should themselves not be daemons, as supervisord assumes it isresponsible for daemonizing its subprocesses (seeNondaemonizing of Subprocesses).

Note

The command will be truncated if it looks like a config file comment,e.g. command=bash -c 'foo ; bar' will be truncated tocommand=bash -c 'foo. Quoting will not prevent this behavior,since the configuration file reader does not parse the command likea shell would.

Default: No default.

Required: Yes.

Introduced: 3.0

process_name

A Python string expression that is used to compose the supervisorprocess name for this process. You usually don’t need to worryabout setting this unless you change numprocs. The stringexpression is evaluated against a dictionary that includesgroup_name, host_node_name, process_num, program_name,and here (the directory of the supervisord config file).

Default: %(program_name)s

Required: No.

Introduced: 3.0

numprocs

Supervisor will start as many instances of this program as named bynumprocs. Note that if numprocs > 1, the process_nameexpression must include %(process_num)s (or any othervalid Python string expression that includes process_num) withinit.

Default: 1

Required: No.

Introduced: 3.0

numprocs_start

An integer offset that is used to compute the number at whichnumprocs starts.

Default: 0

Required: No.

Introduced: 3.0

priority

The relative priority of the program in the start and shutdownordering. Lower priorities indicate programs that start first andshut down last at startup and when aggregate commands are used invarious clients (e.g. “start all”/”stop all”). Higher prioritiesindicate programs that start last and shut down first.

Default: 999

Required: No.

Introduced: 3.0

autostart

If true, this program will start automatically when supervisord isstarted.

Default: true

Required: No.

Introduced: 3.0

startsecs

The total number of seconds which the program needs to stay runningafter a startup to consider the start successful (moving the processfrom the STARTING state to the RUNNING state). Set to 0to indicate that the program needn’t stay running for any particularamount of time.

Note

Even if a process exits with an “expected” exit code (seeexitcodes), the start will still be considered a failureif the process exits quicker than startsecs.

Default: 1

Required: No.

Introduced: 3.0

startretries

The number of serial failure attempts that supervisordwill allow when attempting to start the program before giving up andputting the process into an FATAL state. SeeProcess States for explanation of the FATAL state.

Default: 3

Required: No.

Introduced: 3.0

autorestart

Specifies if supervisord should automatically restart aprocess if it exits when it is in the RUNNING state. May beone of false, unexpected, or true. If false, theprocess will not be autorestarted. If unexpected, the processwill be restarted when the program exits with an exit code that isnot one of the exit codes associated with this process’ configuration(see exitcodes). If true, the process will be unconditionallyrestarted when it exits, without regard to its exit code.

Note

autorestart controls whether supervisord willautorestart a program if it exits after it has successfully startedup (the process is in the RUNNING state).

supervisord has a different restart mechanism for when theprocess is starting up (the process is in the STARTING state).Retries during process startup are controlled by startsecsand startretries.

Default: unexpected

Required: No.

Introduced: 3.0

exitcodes

The list of “expected” exit codes for this program used with autorestart.If the autorestart parameter is set to unexpected, and the processexits in any other way than as a result of a supervisor stoprequest, supervisord will restart the process if it exitswith an exit code that is not defined in this list.

Default: 0

Required: No.

Introduced: 3.0

Note

In Supervisor versions prior to 4.0, the default was 0,2. InSupervisor 4.0, the default was changed to 0.

stopsignal

The signal used to kill the program when a stop is requested. Thiscan 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 SIGCHLD tosupervisord after the program has been sent a stopsignal.If this number of seconds elapses before supervisordreceives a SIGCHLD from the process, supervisord willattempt 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 thewhole process group and implies killasgroup is true. This is usefulfor programs, such as Flask in debug mode, that do not propagatestop signals to their children, leaving them orphaned.

Default: false

Required: No.

Introduced: 3.0b1

killasgroup

If true, when resorting to send SIGKILL to the program to terminateit send it to its whole process group instead, taking care of itschildren as well, useful e.g with Python programs usingmultiprocessing.

Default: false

Required: No.

Introduced: 3.0a11

user

Instruct supervisord to use this UNIX user account as theaccount which runs the program. The user can only be switched ifsupervisord is run as the root user. If supervisordcan’t switch to the specified user, the program will not be started.

Note

The user will be changed using setuid only. This does not starta login shell and does not change environment variables likeUSER 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 tosupervisord on its stdout file descriptor (in UNIX shellterms, 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 withsupervisord. If stderr is redirected, output fromstderr 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 istrue, also place stderr output in this file). If stdout_logfileis unset or set to AUTO, supervisor will automatically choose afile location. If this is set to NONE, supervisord will createno log file. AUTO log files and their backups will be deletedwhen supervisord restarts. The stdout_logfile valuecan contain Python string expressions that will evaluated against adictionary that contains the keys group_name, host_node_name,process_num, program_name, and here (the directory of thesupervisord 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.

Note

If stdout_logfile is set to a special file like /dev/stdoutthat is not seekable, log rotation must be disabled by settingstdout_logfile_maxbytes = 0.

Default: AUTO

Required: No.

Introduced: 3.0, replaces 2.0’s logfile

stdout_logfile_maxbytes

The maximum number of bytes that may be consumed bystdout_logfile before it is rotated (suffix multipliers like“KB”, “MB”, and “GB” can be used in the value). Set this value to 0to 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 resultingfrom process stdout log file rotation. If set to 0, no backupswill be kept.

Default: 10

Required: No.

Introduced: 3.0, replaces 2.0’s logfile_backups

stdout_capture_maxbytes

Max number of bytes written to capture FIFO when process is in“stdout capture mode” (see Capture Mode). Should be aninteger (suffix multipliers like “KB”, “MB” and “GB” can used in thevalue). If this value is 0, process capture mode will be off.

Default: 0

Required: No.

Introduced: 3.0

stdout_events_enabled

If true, PROCESS_LOG_STDOUT events will be emitted when the processwrites to its stdout file descriptor. The events will only beemitted if the file descriptor is not in capture mode at the timethe data is received (see Capture Mode).

Default: 0

Required: No.

Introduced: 3.0a7

stdout_syslog

If true, stdout will be directed to syslog along with the process name.

Default: False

Required: No.

Introduced: 4.0.0

stderr_logfile

Put process stderr output in this file unless redirect_stderr istrue. Accepts the same value types as stdout_logfile and maycontain the same Python string expressions.

Note

It is not possible for two processes to share a single log file(stderr_logfile) when rotation (stderr_logfile_maxbytes)is enabled. This will result in the file being corrupted.

Note

If stderr_logfile is set to a special file like /dev/stderrthat is not seekable, log rotation must be disabled by settingstderr_logfile_maxbytes = 0.

Default: AUTO

Required: No.

Introduced: 3.0

stderr_logfile_maxbytes

The maximum number of bytes before logfile rotation forstderr_logfile. Accepts the same value types asstdout_logfile_maxbytes.

Default: 50MB

Required: No.

Introduced: 3.0

stderr_logfile_backups

The number of backups to keep around resulting from process stderrlog file rotation. If set to 0, no backups will be kept.

Default: 10

Required: No.

Introduced: 3.0

stderr_capture_maxbytes

Max number of bytes written to capture FIFO when process is in“stderr capture mode” (see Capture Mode). Should be aninteger (suffix multipliers like “KB”, “MB” and “GB” can used in thevalue). If this value is 0, process capture mode will be off.

Default: 0

Required: No.

Introduced: 3.0

stderr_events_enabled

If true, PROCESS_LOG_STDERR events will be emitted when the processwrites to its stderr file descriptor. The events will only beemitted if the file descriptor is not in capture mode at the timethe data is received (see Capture Mode).

Default: false

Required: No.

Introduced: 3.0a7

stderr_syslog

If true, stderr will be directed to syslog along with the process name.

Default: False

Required: No.

Introduced: 4.0.0

environment

A list of key/value pairs in the form KEY="val",KEY2="val2" thatwill be placed in the child process’ environment. The environmentstring may contain Python string expressions that will be evaluatedagainst a dictionary containing group_name, host_node_name,process_num, program_name, and here (the directory of thesupervisord config file). Values containing non-alphanumeric charactersshould be quoted (e.g. KEY="val:123",KEY2="val,456"). Otherwise,quoting the values is optional but recommended. Note that thesubprocess will inherit the environment variables of the shell used tostart “supervisord” except for the ones overridden here. SeeSubprocess Environment.

Default: No extra environment

Required: No.

Introduced: 3.0

directory

A file path representing a directory to which supervisordshould temporarily chdir before exec’ing the child.

Default: No chdir (inherit supervisor’s)

Required: No.

Introduced: 3.0

umask

An octal number (e.g. 002, 022) representing the umask of theprocess.

Default: No special umask (inherit supervisor’s)

Required: No.

Introduced: 3.0

serverurl

The URL passed in the environment to the subprocess process asSUPERVISOR_SERVER_URL (see supervisor.childutils) toallow the subprocess to easily communicate with the internal HTTPserver. If provided, it should have the same syntax and structureas the [supervisorctl] section option of the same name. If thisis set to AUTO, or is unset, supervisor will automatically constructa server URL, giving preference to a server that listens on UNIXdomain sockets over one that listens on an internet socket.

Default: AUTO

Required: No.

Introduced: 3.0

[program:x] Section Example

[program:cat]
command=/bin/cat
process_name=%(program_name)s
numprocs=1
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=10
startretries=3
exitcodes=0
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