rfc:fpm:ini_syntax

Request for Comments: 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

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)
rfc/fpm/ini_syntax.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1