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