PHP: Hypertext Preprocessor

配置

FPM 使用类似 php.ini 语法的 php-fpm.conf 和进程池配置文件。

`php-fpm.conf` 全局配置段

pid string: PID 文件的位置。默认为空。
error_log string: 错误日志的位置。默认：#INSTALL_PREFIX#/log/php-fpm.log。如果设置为 "syslog"，日志将不会写入本地文件，而是发送到 syslogd。
log_level string: 错误级别。可用级别为：alert（必须立即处理），error（错误情况），warning（警告情况），notice（一般重要信息），debug（调试信息）。默认：notice。
log_limit int: 日志记录行的限制，允许记录超过 1024 个字符的消息而不需要换行。默认值：1024。 PHP 7.3.0 起可用。
log_buffering bool: 实验性：没有额外缓冲的日志记录。默认值：yes。 PHP 7.3.0 后可用。
syslog.facility string: 设置何种程序记录消息，默认值：daemon。
syslog.ident string: 为每条信息添加前缀。如果在同一台服务器上运行了多个 FPM 实例，可以修改此默认值来满足需求。默认值：php-fpm。
emergency_restart_threshold int: 如果子进程在 emergency_restart_interval 设定的时间内收到该参数设定次数的 SIGSEGV 或者 SIGBUS退出信息号，则FPM会重新启动。0 表示“关闭该功能”。默认值：0（关闭）。
emergency_restart_interval mixed: emergency_restart_interval 用于设定平滑重启的间隔时间。这么做有助于解决加速器中共享内存的使用问题。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：s（秒）。默认值：0（关闭）。
process_control_timeout mixed: 设置子进程接受主进程复用信号的超时时间。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：s（秒）。默认值：0（关闭）。
process.max int: Fork 的最大 FPM 进程数。使用动态管理进程数时，此设计可以控制在一个进程池内的全局进程数量。使用需谨慎。默认值：0。
process.priority int: 设置 master 进程的 nice(2) 优先级（如果设置了此值）。可以是 -19（最高优先级）到 20 （更低优先级）。默认值：不设置。
daemonize bool: 设置 FPM 在后台运行。设置“no”将 FPM 保持在前台运行用于调试。默认值：yes。
rlimit_files int: 设置 master 进程的打开文件描述符 rlimit 数。默认值：系统定义值。
rlimit_core int: 设置 master 进程最大 core 的 rlimit 尺寸。默认值：0。
events.mechanism string: 设置 FPM 使用的事件机制。可用以下选项：select、pool、epoll、kqueue (*BSD)、port (Solaris)。默认值：不设置（自动检测）
systemd_interval int: 使用 systemd 集成的 FPM 时，设置间歇秒数，报告健在通知给 systemd。设置为 0 表示禁用。默认值：10。

运行配置区段

在FPM中，可以使用不同的设置来运行多个进程池。这些设置可以针对每个进程池单独设置。

listen string

设置接受 FastCGI 请求的地址。可用格式为：'ip:port'，'port'，'/path/to/unix/socket'。每个进程池都需要设置。

listen.backlog int

设置 listen(2) backlog 的值。在 BSD 系统上 -1 表示无限制。默认值：-1（FreeBSD 或 OpenBSD）或者 511（Linux 或其他平台）。

listen.allowed_clients string

设置允许连接到 FastCGI 客户端的 IPv4 或 IPv6 地址列表。等同于 PHP FastCGI (5.2.2+) 中的 FCGI_WEB_SERVER_ADDRS 环境变量。仅对 TCP 监听起作用。每个地址是用逗号分隔，如果没有设置或者为空，则允许任何服务器请求连接。默认值：未设置（接受任何 IP 地址）。

listen.owner string

如果使用了 Unix 套接字，表示它的权限。在 Linux 中必须设置读/写权限，以便用于 WEB 服务器连接。在很多 BSD 派生的系统中可以忽略权限允许自由连接。默认值：运行所使用的用户和组，权限为 0660。

listen.group string

参见 listen.owner。

listen.mode string

参见 listen.owner。

listen.acl_users string

当系统支持 POSIX ACL（Access Control Lists）时，可以设置使用此选项。当设置了的时候，将会忽略 listen.owner 和 listen.group。值是逗号分割的用户名列表。

listen.acl_groups string

参见 listen.acl_users。值是逗号分割的用户组名称列表。

user string

FPM 进程运行的Unix用户。必须设置。

group string

FPM 进程运行的 Unix 用户组。如果不设置，就使用默认用户的用户组。

pm string

设置进程管理器如何管理子进程。可用值：static，ondemand，dynamic。必须设置。

static - 子进程的数量是固定的（pm.max_children）。

ondemand - 进程在有需求时才产生（当请求时才启动。与 dynamic 相反，在服务启动时 pm.start_servers 就启动了。

dynamic - 子进程的数量在下面配置的基础上动态设置：pm.max_children，pm.start_servers，pm.min_spare_servers，pm.max_spare_servers。

pm.max_children int

pm 设置为 static 时表示创建的子进程的数量，pm 设置为 dynamic 时表示最大可创建的子进程的数量。必须设置。

该选项设置可以同时提供服务的请求数限制。类似 Apache 的 mpm_prefork 中 MaxClients 的设置和普通PHP FastCGI中的 PHP_FCGI_CHILDREN 环境变量。

pm.start_servers in

设置启动时创建的子进程数目。仅在 pm 设置为 dynamic 时使用。默认值：min_spare_servers + (max_spare_servers - min_spare_servers) / 2。

pm.min_spare_servers int

设置空闲服务进程的最低数目。仅在 pm 设置为 dynamic 时使用。必须设置。

pm.max_spare_servers int

设置空闲服务进程的最大数目。仅在 pm 设置为 dynamic 时使用。必须设置。

pm.max_spawn_rate int

同时生成子进程的速率。仅当 pm 设置为 dynamic 时使用。默认值： 32

pm.process_idle_timeout mixed

秒数，多久之后结束空闲进程。仅当设置 pm 为 ondemand。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：10s。

pm.max_requests int

设置每个子进程重生之前服务的请求数。对于可能存在内存泄漏的第三方模块来说是非常有用的。如果设置为 '0' 则一直接受请求，等同于 PHP_FCGI_MAX_REQUESTS 环境变量。默认值：0。

pm.status_listen string

接受 FastCGI 状态请求的地址。会创建一个新不可见池用来独立处理请求。如果主池处理长时间运行的请求时很繁忙，那么对长时间运行的请求结束之前能够获得 FPM 状态页面会非常有用。语法与 listen 指令相同。默认值：none。

pm.status_path string

查看 FPM 状态页面的 URI。此值必须以斜线（/）开头。如果没有设置，则无法访问状态页面，默认值：无。

ping.path string

FPM 监控页面的 ping 网址。如果没有设置，则无法访问 ping 页面。该页面用于外部检测 FPM 是否存活并且可以响应请求。请注意必须以斜线开头（/）。

ping.response string

用于定义 ping 请求的返回响应。返回为 HTTP 200 的 text/plain 格式文本。默认值：pong。

process.priority int

设置 worker 的 nice(2)优先级（如果设置了的话）。该值从 -19（最高优先级）到 20（更低优先级）。默认值：不设置

process.dumpable bool

即使进程用户或者组跟主进程用户是不同的，也设置进程可转储标志 (PR_SET_DUMPABLE prctl)。它允许为用户池创建进程 core dump 和 ptrace 进程。默认值：no。自 PHP 7.0.29、7.1.17 和 7.2.5 起可用。

prefix string

检测路径时使用的前缀。

request_terminate_timeout mixed

设置单个请求的超时中止时间。该选项可能会对 php.ini 设置中的 'max_execution_time' 因为某些特殊原因没有中止运行的脚本有用。设置为 '0' 表示 'Off'。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：s（秒）。默认值：0（关闭）。

request_terminate_timeout_track_finished bool

在 fastcgi_finish_request 之后或当应用程序结束且调用内部关闭命令时，不会使用通过 request_terminate_timeout 设置的超时时间。但即使在这种情况下，该指令也可以无条件应用超时限制。默认值：no。自 PHP 7.3.0 启用。

request_slowlog_timeout mixed

当一个请求该设置的超时时间后，就会将对应的 PHP 调用堆栈信息完整写入到慢日志中。设置为 '0' 表示 'Off'。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：s（秒）。默认值：0（关闭）。

request_slowlog_trace_depth int

slowlog 日志堆栈追踪的深度。默认值：20。自 PHP 7.2.0 起可用。

slowlog string

慢请求的记录日志。默认值：#INSTALL_PREFIX#/log/php-fpm.log.slow。

rlimit_files int

设置文件打开描述符的 rlimit 限制。默认值：系统定义值。

rlimit_core int

设置核心 rlimit 最大限制值。可用值：'unlimited'，0 或者正整数。默认值：系统定义值。

chroot string

启动时的 Chroot 目录。所定义的目录需要是绝对路径。如果没有设置，则 chroot 不被使用。

chdir string

设置启动目录，启动时会自动 Chdir 到该目录。所定义的目录需要是绝对路径。默认值：当前目录，或者根目录（chroot时）。

catch_workers_output bool

重定向运行过程中的 stdout 和 stderr 到主要的错误日志文件中。如果没有设置，stdout 和 stderr 将会根据 FastCGI 的规则被重定向到 /dev/null。默认值：无。

decorate_workers_output bool

当 catch_workers_output 启用时，为 worker 输出启用输出装饰。默认值：yes。自 PHP 7.3.0 起可用。

clear_env bool

为 FPM worker 进程清除环境变量。在进程池配置文件里设置环境变量前，阻止任意系统的环境变量进入 FPM worker 进程。默认值：Yes

security.limit_extensions string

限制 FPM 允许解析的脚本扩展名。此设置可以预防 web 服务器配置的错误。应当限制 FPM 仅仅解析 .php 扩展名，阻止恶意用户使用其他扩展名运行 php 代码。默认值： .php .phar

apparmor_hat string

如果启用 AppArmor，允许更换帽子（hat）。默认值：未设置

access.log string

Access log 文件。默认值：不设置

access.format string

access log 的格式。默认: "%R - %u %t \"%m %r\" %s"：

**可用选项**
占位符	描述
`%C`	%CPU
`%d`	持续时间。接受以下精度格式：`%{seconds}d`（默认）`%{milliseconds}d`、`%{microseconds}d`。
`%e`	fastcgi 环境变量
`%f`	脚本文件
`%l`	内容长度
`%m`	请求方法
`%M`	内存
`%n`	进程池（pool）名称
`%o`	header 输出
`%p`	PID
`%q`	查询字符串
`%Q`	%q 和 %r 之间的连接字符
`%r`	请求 URI
`%R`	远程 IP 地址
`%s`	状态码
`%T`	时间
`%t`	时间
`%u`	远程用户

还可以在为一个运行池传递附加的环境变量，或者更新 PHP 的配置值。可以在进程池配置文件中如下面的配置参数来做到：

示例 #1 给运行池传递环境变量和设置 PHP 的配置值

env[HOSTNAME] = $HOSTNAME
env[PATH] = /usr/local/bin:/usr/bin:/bin
env[TMP] = /tmp
env[TMPDIR] = /tmp
env[TEMP] = /tmp

php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
php_flag[display_errors] = off
php_admin_value[error_log] = /var/log/fpm-php.www.log
php_admin_flag[log_errors] = on
php_admin_value[memory_limit] = 32M

PHP配置值通过 php_value 或者 php_flag 设置，并且会覆盖以前的值。请注意 disable_functions 或者 disable_classes 在 php.ini 之中定义的值不会被覆盖掉，但是会将新的设置附加在原有值的后面。

使用 php_admin_value 或者 php_admin_flag 定义的值，不能被 PHP 代码中的 ini_set() 覆盖。

可以通过 web 服务器设置 PHP 的设定。

示例 #2 在 nginx.conf 中设定 PHP

set $php_value "pcre.backtrack_limit=424242";
set $php_value "$php_value \n pcre.recursion_limit=99999";
fastcgi_param  PHP_VALUE $php_value;

fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";

警告

由于这些设定是以 FastCGI 标头传递给 php-fpm，php-fpm 不应绑定到外部网可以访问的地址上，否则任何人都能修改 PHP 的配置选项了。参见 listen.allowed_clients。

注意: 进程池不是种安全机制，因为它们不会完全隔离；例如：所有的进程池会使用单个 Opcache 实例。

改进此页面

了解如何改进此页面 • 提交拉取请求 • 报告一个错误

＋添加备注

用户贡献的备注 9 notes

down

ikrabbe ¶

6 years ago

It seems there is no way to get informed about the access log format codes that are used or can be used. All I found is the source code.

It would really help, not to have open questions when deploying php-fpm. I constantly struggle with file paths for example, but that is another topic.

                                case '%': /* '%' */
                                case 'C': /* %CPU */
                                case 'd': /* duration µs */
                                case 'e': /* fastcgi env  */
                                case 'f': /* script */
                                case 'l': /* content length */
                                case 'm': /* method */
                                case 'M': /* memory */
                                case 'n': /* pool name */
                                case 'o': /* header output  */
                                case 'p': /* PID */
                                case 'P': /* PID */
                                case 'q': /* query_string */
                                case 'Q': /* '?' */
                                case 'r': /* request URI */
                                case 'R': /* remote IP address */
                                case 's': /* status */
                                case 'T':
                                case 't': /* time */
                                case 'u': /* remote user */

down

rob at librobert dot net ¶

3 years ago

The 'include' directive that is used in php-fpm.conf is not documented here. However, this directive can also be used in the pool configurations. In the included file, the $pool variable is substituted correctly.



This means that, if you have multiple pools with similar configurations, you can create a file 'default-values.inc' like so:



-----

listen.allowed_clients = 127.0.0.1



pm = dynamic

pm.max_children = X

pm.min_spare_servers = X

pm.max_spare_servers = X



access.log = /var/log/php-fpm/$pool.access

access.format = "%R %u [%t] \"%m %r\" %s %d %l"

slowlog = /var/log/php-fpm/$pool.slow



php_flag[short_open_tag] = off

-----



And then include that file in each pool configuration like so:



-----

[vhost1.example.com]

user = www-vhost1

group = www-vhost1



listen = 127.0.0.1:9001



include = /usr/local/etc/php-fpm.d/default-values.inc

-----



This makes things a bit more transparent, and it could potentially save some time if you decide to change settings.



Make sure the name of the included file does not end in '.conf', because all files with that extension are loaded from php-fpm.conf.

down

gadnet at aqueos dot com ¶

10 years ago

the doc is lacking a lot of things it seems.

  The php fpm exemple config file indicate different thing, more option etc... I wonder why the main documentation is less verbose that the configuration file that user can have .. or not have ?

down

Frank DENIS ¶

13 years ago

The default value for listen.backlog isn't exactly "unlimited".

It's 128 on some operating systems, and -1 (which doesn't mean "unlimited" as well, but is an alias to a hard limit) on other systems.

Check for a sysctl value like kern.somaxconn (OpenBSD) or net.core.somaxconn (Linux).

Crank it up if you need more PHP workers than the default value. Then adjust listen.backlog in your php-fpm configuration file to the same value.

-Frank.

down

antonfedonyuk at gmail dot com ¶

3 years ago

NOTE: "access.format" containing "%o" generate error in PHP 7.4 (don't tested in other versions)

down

antonfedonyuk at gmail dot com ¶

3 years ago

; The access log format.
; The following syntax is allowed
;  %%: the '%' character
;  %C: %CPU used by the request
;      it can accept the following format:
;      - %{user}C for user CPU only
;      - %{system}C for system CPU only
;      - %{total}C  for user + system CPU (default)
;  %d: time taken to serve the request
;      it can accept the following format:
;      - %{seconds}d (default)
;      - %{milliseconds}d
;      - %{milli}d
;      - %{microseconds}d
;      - %{micro}d
;  %e: an environment variable (same as $_ENV or $_SERVER)
;      it must be associated with embraces to specify the name of the env
;      variable. Some examples:
;      - server specifics like: %{REQUEST_METHOD}e or %{SERVER_PROTOCOL}e
;      - HTTP headers like: %{HTTP_HOST}e or %{HTTP_USER_AGENT}e
;  %f: script filename
;  %l: content-length of the request (for POST request only)
;  %m: request method
;  %M: peak of memory allocated by PHP
;      it can accept the following format:
;      - %{bytes}M (default)
;      - %{kilobytes}M
;      - %{kilo}M
;      - %{megabytes}M
;      - %{mega}M
;  %n: pool name
;  %o: output header
;      it must be associated with embraces to specify the name of the header:
;      - %{Content-Type}o
;      - %{X-Powered-By}o
;      - %{Transfert-Encoding}o
;      - ....
;  %p: PID of the child that serviced the request
;  %P: PID of the parent of the child that serviced the request
;  %q: the query string
;  %Q: the '?' character if query string exists
;  %r: the request URI (without the query string, see %q and %Q)
;  %R: remote IP address
;  %s: status (response code)
;  %t: server time the request was received
;      it can accept a strftime(3) format:
;      %d/%b/%Y:%H:%M:%S %z (default)
;      The strftime(3) format must be encapsulated in a %{<strftime_format>}t tag
;      e.g. for a ISO8601 formatted timestring, use: %{%Y-%m-%dT%H:%M:%S%z}t
;  %T: time the log has been written (the request has finished)
;      it can accept a strftime(3) format:
;      %d/%b/%Y:%H:%M:%S %z (default)
;      The strftime(3) format must be encapsulated in a %{<strftime_format>}t tag
;      e.g. for a ISO8601 formatted timestring, use: %{%Y-%m-%dT%H:%M:%S%z}t
;  %u: remote user
;
; Default: "%R - %u %t \"%m %r\" %s"
access.format = "%R - %u %t \"%m %r%Q%q\" %s %f %{milli}d %{kilo}M %C%%"

https://github.com/php/php-src/blob/master/sapi/fpm/www.conf.in#L257-L318

down

frederic at juliana-multimedia dot com ¶

6 years ago

With Apache, mod_proxy_fcgi and php-fpm, if you want to have a generic pool and several vhost with different php configuration, you can use the ProxyFCGISetEnvIf directive and the PHP_ADMIN_VALUE environment variable. It does not work with PHP_ADMIN_FLAG even for boolean directives.

PHP directives must be separated by spaces and a \n.

ProxyFCGISetEnvIf "true" PHP_ADMIN_VALUE "open_basedir=/var/www/toto/:/tmp/ \n session.save_path=/var/www/toto/session \n display_errors=On \n error_reporting=-1"

down

jon dot phpnetdonotspam at langevin dot me ¶

1 year ago

PHP-FPM configuration page apparently doesn't see the need to specify what options are available with each version of PHP.

It claims that pm.status_listen is a valid directive, but that directive only exists as of php 8.0.0, which is a bummer for those of us still using PHP 7.4.

Noting this for anyone else fighting with this.

down

david dot cancalon at proxeem dot fr ¶

4 years ago

Be very carrefull when using ProxyFCGISetEnvIf within a Apache virtual host configuration using a shared PHP-FPM pool. Values defined like this are shared across all the Apache virtual hosts within a pool worker, may resulting in strange behaviours depending on the requests chronology.

See full explanation here:
https://serverfault.com/questions/817020/stop-reusing-php-value-for-different-sites-with-php-fpm/817905#817905

配置

php-fpm.conf 全局配置段

运行配置区段

改进此页面

用户贡献的备注 9 notes

`php-fpm.conf` 全局配置段