This is an old revision of the document!

Request for Comments: FPM INI Syntax

This RFC discusses the FPM configuration file syntax and it's replacement from XML to INI.

WE ARE NOT TALKING HERE ABOUT CHANGING SOMETHING INTO core/* or Zend/*. This dicussion is about sapi/fpm ONLY


FPM (FastCGI Process Manager) is under discussion for its inclusion into the PHP core distribution. See the RFC.

Until now, FPM uses a XML configuration file. It's been discussed several times with passion:

But it comes that we almost all agree to change it to INI. This RFC propose a INI syntax for FPM.


  • An include directive to include one or several files at once. This directive can be set everywhere in the configuation files.
  • A global section which include global simple directives (pid_file=, ...)
  • At least one worker section wich includes:
    • specific simple directives (user=, group=, status=, ...)
    • specific array directives (environment[PATH]=, php_define[sendmail_path]=, ...)
  • A reference system. A worker can be set as a reference and it'll never be instantiated. Classic workers can use it to define default values. For exemple, timeout directives are set once in a reference worker and normal workers will use this worker as a reference.


I propose to implement the previous requirements this way:

  • The include directive is a simple key/value. The key is named include. The value is a pattern recognized by glob(3). With glob(3), a simple file can be set, but also a bunch of file at once
  • The global section can start with an INI section named globals. This INI section is not mandatory if directives are set before any other INI sections.
  • Simple directive values are simple key/value pairs.
    daemonize = yes
  • Array directive values are arrays of key/value pairs.
    environment[PATH] = /bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin
    php_define[sendmail_path] = /bin/mini_sendmail -t -i -fwww@my.site.com
  • Workers starts with a INI section. The value of the section is named with the worker's name. All the following directives are related to this worker until another INI section starts a new worker.
    • The directive is_a_reference set the current worker as a reference. It can be set to yes or no.
      is_a_reference=yes   ; incompatible with reference
    • The directive reference set the worker to use as a reference. It's named reference and can be set to any worker set as a reference by is_a_reference.
      reference=default   ; incompatible with is_a_reference

Yet known directives

Global directives

  • daemonize. Set to yes/no. Default to yes. Does FPM run as a standalone daemon or stays in foreground (debugging purpose).
  • pid. Set to PID file location.
  • error_log. Set to error file location.
  • log_level. Set the log_level: notice, warn, error or alert.
  • process_control_timeout. Set a time value.
  • emergency_restart_interval. Set a time value.
  • emergency_restart_threshold. Set a time value.

Worker directives

  • user.
  • group.
  • pm.
  • pm.start_servers.
  • pm.min_spare_servers.
  • pm.max_spare_servers.
  • pm.max_children.
  • pm.max_requests.
  • pm.status_path.
  • listen.address.
  • listen.backlog.
  • listen.owner.
  • listen.group.
  • listen.mode.
  • ping.path.
  • ping.response.
  • chroot.
  • chdir.
  • request_terminate_timeout.
  • request_slowlog_timeout.
  • slowlog.
  • rlimit_core.
  • rlimit_files.
  • max_requests.
  • catch_worker_output.
  • php_value[].
  • php_admin_value[].
  • php_flag[].
  • php_admin_flag[].
  • allowed_client[].
  • env[].

Not yet known directives

  • include.
  • reference.
  • is_a_reference.

Rename directive proposal

In this section, I want to propose to rename some of the yet know directives.

  • pm.style to pm. Remove style and keep only pm. It's enough and clearer. It's the main option for the pm subsection.
  • pm.dynamic.start_servers to pm.start_servers. As start_servers is only used with dynamic mode, it's not necessary to precise it's dynamic.
  • pm.dynamic.min_spare_servers to pm.min_spare_servers. Same as start_servers.
  • pm.dynamic.max_spare_servers to pm.max_spare_servers. Same as start_servers.
  • status to pm.status_path. The status directive is directly related to PM as it's its status page.
  • listen_address to listen.address
  • ping and pong to a subsection:
    • ping.path to set the ping path request (/ping)
    • ping.response to set the response from the previous request
  • max_requests to pm.max_requests.. Move this directive to the PM array as it's directly related to PM.
  • environment[] to env[]. The short word env is enough to understand and closer to reality (env shell command).
  • php_define[] to php_flag[], php_value[], php_admin_flag[], php_admin_value[]. This is the same syntax as the apache sapi.
  • allowed_clients to allowed_client[] as there could be more than one allowed client.


Proposal and Patch


  • fat - 2010-03-30 - initial RFC version.
  • fat - 2010-04-13 - remove unnecessary use of arrays (for pm, ping and listen) + add examples
  • fat - 2010-04-15 - first revision of the patch has been added
  • fat - 2010-04-15 - add warning header to explain this RFC is only about sapi/fpm/*
rfc/fpm/ini_syntax.1271333025.txt.gz · Last modified: 2017/09/22 13:28 (external edit)