This is an old revision of the document!
Request for Comments: FPM INI Syntax
- Version: 1.1
- Date: 2010-04-13
- Author: Jérôme Loyet <jerome.at.loyet.dot.net>
- Status: Under Discussion
- 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 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 -email@example.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
- 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.
Not yet known directives
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
- 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/*