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

Introduction

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.

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

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

Examples

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