[fcgi-program:x] Section Settings

Supervisor can manage groups of FastCGIprocesses that all listen on the same socket. Until now, deploymentflexibility for FastCGI was limited. To get full process management,you could use mod_fastcgi under Apache but then you were stuck withApache’s inefficient concurrency model of one process or thread perconnection. In addition to requiring more CPU and memory resources,the process/thread per connection model can be quickly saturated by aslow resource, preventing other resources from being served. In orderto take advantage of newer event-driven web servers such as lighttpdor nginx which don’t include a built-in process manager, you had touse scripts like cgi-fcgi or spawn-fcgi. These can be used inconjunction with a process manager such as supervisord or daemontoolsbut require each FastCGI child process to bind to its own socket.The disadvantages of this are: unnecessarily complicated web serverconfiguration, ungraceful restarts, and reduced fault tolerance. Withfewer sockets to configure, web server configurations are much smallerif groups of FastCGI processes can share sockets. Shared socketsallow for graceful restarts because the socket remains bound by theparent process while any of the child processes are being restarted.Finally, shared sockets are more fault tolerant because if a givenprocess fails, other processes can continue to serve inboundconnections.

With integrated FastCGI spawning support, Supervisor gives you thebest of both worlds. You get full-featured process management withgroups of FastCGI processes sharing sockets without being tied to aparticular web server. It’s a clean separation of concerns, allowingthe web server and the process manager to each do what they do best.

Note

The socket manager in Supervisor was originally developed to supportFastCGI processes but it is not limited to FastCGI. Other protocols maybe used as well with no special configuration. Any program that canaccess an open socket from a file descriptor (e.g. withsocket.fromfdin Python) can use the socket manager. Supervisor will automaticallycreate the socket, bind, and listen before forking the first child in agroup. The socket will be passed to each child on file descriptornumber 0 (zero). When the last child in the group exits,Supervisor will close the socket.

Note

Prior to Supervisor 3.4.0, FastCGI programs ([fcgi-program:x])could not be referenced in groups ([group:x]).

All the options available to [program:x] sections arealso respected by fcgi-program sections.

[fcgi-program:x] Section Values

[fcgi-program:x] sections have a few keys which [program:x]sections do not have.

socket

The FastCGI socket for this program, either TCP or UNIX domainsocket. 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 thekeys “program_name” and “here” (the directory of the supervisordconfig file).

Default: No default.

Required: Yes.

Introduced: 3.0

socket_backlog

Sets socket listen(2) backlog.

Default: socket.SOMAXCONN

Required: No.

Introduced: 3.4.0

socket_owner

For UNIX domain sockets, this parameter can be used to specify the userand group for the FastCGI socket. May be a UNIX username (e.g. chrism)or a UNIX username and group separated by a colon (e.g. chrism:wheel).

Default: Uses the user and group set for the fcgi-program

Required: No.

Introduced: 3.0

socket_mode

For UNIX domain sockets, this parameter can be used to specify thepermission mode.

Default: 0700

Required: No.

Introduced: 3.0

Consult [program:x] Section Settings for other allowable keys, delta theabove constraints and additions.

[fcgi-program:x] Section Example

  1. [fcgi-program:fcgiprogramname]
  2. command=/usr/bin/example.fcgi
  3. socket=unix:///var/run/supervisor/%(program_name)s.sock
  4. socket_owner=chrism
  5. socket_mode=0700
  6. process_name=%(program_name)s_%(process_num)02d
  7. numprocs=5
  8. directory=/tmp
  9. umask=022
  10. priority=999
  11. autostart=true
  12. autorestart=unexpected
  13. startsecs=1
  14. startretries=3
  15. exitcodes=0
  16. stopsignal=QUIT
  17. stopasgroup=false
  18. killasgroup=false
  19. stopwaitsecs=10
  20. user=chrism
  21. redirect_stderr=true
  22. stdout_logfile=/a/path
  23. stdout_logfile_maxbytes=1MB
  24. stdout_logfile_backups=10
  25. stdout_events_enabled=false
  26. stderr_logfile=/a/path
  27. stderr_logfile_maxbytes=1MB
  28. stderr_logfile_backups=10
  29. stderr_events_enabled=false
  30. environment=A="1",B="2"
  31. serverurl=AUTO