====== 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**

===== Introduction =====

FPM (FastCGI Process Manager) is under discussion for its inclusion into the PHP core distribution. See the [[rfc/fpm|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 <del>almost</del> all agree to change it to INI. This RFC propose a INI syntax for FPM.

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

===== Implementation =====
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 [[http://www.cl.cam.ac.uk/cgi-bin/manpage?3+glob|glob(3)]]. With glob(3), a simple file can be set, but also a bunch of file at once<code>include=/etc/fpm.d/www.my.site.com.conf
include=/etc/fpm.d/*.conf</code>
  * 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. <code>[globals]</code>
  * Simple directive values are simple key/value pairs.<code>daemonize = yes</code>
  * Array directive values are arrays of key/value pairs.<code>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</code>
  * 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.<code>[www.my.site.com]</code>

===== 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**.
  * **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**.
===== 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**
  * **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.

===== Examples =====
  * [[http://www.fatbsd.com/fpm/xml.html|The previous XML syntax]]
  * [[http://www.fatbsd.com/fpm/fpm_ini.html|The new INI syntax]]
===== Proposal and Patch =====

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

===== Changelog =====

  * 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)