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.

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

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

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

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)