Request for Comments: FPM INI Syntax

• Version: 1.2
• Date: 2010-04-21
• Author: Jérôme Loyet <jerome.at.loyet.dot.net>
• Status: Implemented in PHP 5.3
• First Published at: http://wiki.php.net/rfc/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 main/* 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:

• http://marc.info/?l=php-internals&m=126936264101067&w=2
• http://marc.info/?l=php-internals&m=126021179101625&w=2

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]=, ...)

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

  include=/etc/fpm.d/www.my.site.com.conf
  include=/etc/fpm.d/*.conf

• 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.

  [globals]

• 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.

  [www.my.site.com]

• 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.

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

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
• allowed_clients to listen.allowed_clients
• 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.

• The previous XML syntax
• The new INI syntax

• The first version of the patch is available at http://www.fatbsd.com/fpm/fpm-ini-v1.patch. The include function is not YET implemented, so as the reference system which is maybe too complicated.

• 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/*
• fat - 2010-04-21 - commit the patch (revision 298281)