install/fpm/configuration.xml
f80105b4fc1196bd8d5fecb98d686b580b1ff65d
...
...
@@ -5,6 +5,7 @@
5
5
<para>
6
6
FPM uses &php.ini; syntax for its configuration file - <filename>php-fpm.conf</filename>, and pool configuration files.
7
7
</para>
8
+

8
9
<sect2>
9
10
<title>List of global <filename>php-fpm.conf</filename> directives</title>
10
11
<variablelist>
...
...
@@ -28,6 +29,7 @@
28
29
<para>
29
30
Path to error log file. Default value:
30
31
<literal>#INSTALL_PREFIX#/log/php-fpm.log</literal>.
32
+
If it's set to "syslog", log is sent to syslogd instead of being written in a local file.
31
33
</para>
32
34
</listitem>
33
35
</varlistentry>
...
...
@@ -43,6 +45,59 @@
43
45
</para>
44
46
</listitem>
45
47
</varlistentry>
48
+
<varlistentry xml:id="log-limit">
49
+
<term>
50
+
<parameter>log_limit</parameter>
51
+
<type>int</type>
52
+
</term>
53
+
<listitem>
54
+
<para>
55
+
Log limit for the logged lines which allows to log messages longer than
56
+
1024 characters without wrapping.
57
+
Default value: 1024.
58
+
Available as of PHP 7.3.0.
59
+
</para>
60
+
</listitem>
61
+
</varlistentry>
62
+
<varlistentry xml:id="log-buffering">
63
+
<term>
64
+
<parameter>log_buffering</parameter>
65
+
<type>bool</type>
66
+
</term>
67
+
<listitem>
68
+
<para>
69
+
Experimental logging without extra buffering.
70
+
Default value: yes.
71
+
Available as of PHP 7.3.0.
72
+
</para>
73
+
</listitem>
74
+
</varlistentry>
75
+
<varlistentry xml:id="syslog-facility">
76
+
<term>
77
+
<parameter>syslog.facility</parameter>
78
+
<type>string</type>
79
+
</term>
80
+
<listitem>
81
+
<para>
82
+
used to specify what type of program is logging the message.
83
+
Default value: daemon.
84
+
</para>
85
+
</listitem>
86
+
</varlistentry>
87
+
<varlistentry xml:id="syslog-ident">
88
+
<term>
89
+
<parameter>syslog.ident</parameter>
90
+
<type>string</type>
91
+
</term>
92
+
<listitem>
93
+
<para>
94
+
Prepended to every message.
95
+
If you have multiple FPM instances running on the same server,
96
+
you can change the default value which must suit common needs.
97
+
Default value: php-fpm.
98
+
</para>
99
+
</listitem>
100
+
</varlistentry>
46
101
<varlistentry xml:id="emergency-restart-threshold">
47
102
<term>
48
103
<parameter>emergency_restart_threshold</parameter>
...
...
@@ -51,7 +106,7 @@
51
106
<listitem>
52
107
<para>
53
108
If this number of child processes exit with SIGSEGV or SIGBUS within
54
-
the time interval set by <literal>emergency_restart_interval</literal>
109
+
the time interval set by <literal>emergency_restart_interval</literal>,
55
110
then FPM will restart. A value of 0 means 'Off'. Default value: 0 (Off).
56
111
</para>
57
112
</listitem>
...
...
@@ -63,7 +118,7 @@
63
118
</term>
64
119
<listitem>
65
120
<para>
66
-
Interval of time used by emergency_restart_interval to determine when
121
+
Interval of time used by <literal>emergency_restart_interval</literal> to determine when
67
122
a graceful restart will be initiated. This can be useful to work around
68
123
accidental corruptions in an accelerator's shared memory.
69
124
Available Units: s(econds), m(inutes), h(ours), or d(ays).
...
...
@@ -84,10 +139,37 @@
84
139
</para>
85
140
</listitem>
86
141
</varlistentry>
142
+
<varlistentry xml:id="process-max">
143
+
<term>
144
+
<parameter>process.max</parameter>
145
+
<type>int</type>
146
+
</term>
147
+
<listitem>
148
+
<para>
149
+
The maximum number of processes FPM will fork. This has been design
150
+
to control the global number of processes when using dynamic PM
151
+
within a lot of pools. Use it with caution.
152
+
Default value: 0.
153
+
</para>
154
+
</listitem>
155
+
</varlistentry>
156
+
<varlistentry xml:id="process-priority">
157
+
<term>
158
+
<parameter>process.priority</parameter>
159
+
<type>int</type>
160
+
</term>
161
+
<listitem>
162
+
<para>
163
+
Specify the nice(2) priority to apply to the master process (only if set).
164
+
The value can vary from -19 (highest priority) to 20 (lower priority).
165
+
Default value: not set.
166
+
</para>
167
+
</listitem>
168
+
</varlistentry>
87
169
<varlistentry xml:id="daemonize">
88
170
<term>
89
171
<parameter>daemonize</parameter>
90
-
<type>boolean</type>
172
+
<type>bool</type>
91
173
</term>
92
174
<listitem>
93
175
<para>
...
...
@@ -96,7 +178,59 @@
96
178
</para>
97
179
</listitem>
98
180
</varlistentry>
181
+
<varlistentry xml:id="rlimit-files-master">
182
+
<term>
183
+
<parameter>rlimit_files</parameter>
184
+
<type>int</type>
185
+
</term>
186
+
<listitem>
187
+
<para>
188
+
Set open file descriptor rlimit for the master process.
189
+
Default value: system defined value.
190
+
</para>
191
+
</listitem>
192
+
</varlistentry>
193
+
<varlistentry xml:id="rlimit-core-master">
194
+
<term>
195
+
<parameter>rlimit_core</parameter>
196
+
<type>int</type>
197
+
</term>
198
+
<listitem>
199
+
<para>
200
+
Set max core size rlimit for the master process.
201
+
Default value: 0.
202
+
</para>
203
+
</listitem>
204
+
</varlistentry>
205
+
<varlistentry xml:id="events-mechanism">
206
+
<term>
207
+
<parameter>events.mechanism</parameter>
208
+
<type>string</type>
209
+
</term>
210
+
<listitem>
211
+
<para>
212
+
Specify the event mechanism FPM will use.
213
+
The following is available: select, pool, epoll, kqueue (*BSD), port (Solaris).
214
+
Default value: not set (auto detection).
215
+
</para>
216
+
</listitem>
217
+
</varlistentry>
218
+
<varlistentry xml:id="systemd-interval">
219
+
<term>
220
+
<parameter>systemd_interval</parameter>
221
+
<type>int</type>
222
+
</term>
223
+
<listitem>
224
+
<para>
225
+
When FPM is build with systemd integration, specify the interval,
226
+
in second, between health report notification to systemd.
227
+
Set to 0 to disable.
228
+
Default value: 10.
229
+
</para>
230
+
</listitem>
231
+
</varlistentry>
99
232
</variablelist>
233
+

100
234
</sect2>
101
235

102
236
<sect2>
...
...
@@ -126,8 +260,9 @@
126
260
</term>
127
261
<listitem>
128
262
<para>
129
-
Set listen(2) backlog. A value of '-1' means unlimited. Default value:
130
-
-1.
263
+
Set listen(2) backlog. A value of <literal>-1</literal> means maximum on BSD systems.
264
+
Default value: <literal>-1</literal> (FreeBSD or OpenBSD) or <literal>511</literal>
265
+
(Linux and other platforms).
131
266
</para>
132
267
</listitem>
133
268
</varlistentry>
...
...
@@ -138,11 +273,11 @@
138
273
</term>
139
274
<listitem>
140
275
<para>
141
-
List of ipv4 addresses of FastCGI clients which are allowed to
142
-
connect. Equivalent to the FCGI_WEB_SERVER_ADDRS environment variable in the
143
-
original PHP FastCGI (5.2.2+). Makes sense only with a tcp listening socket.
144
-
Each address must be separated by a comma. If this value is left blank,
145
-
connections will be accepted from any ip address. Default value: any.
276
+
List of IPv4 or IPv6 addresses of FastCGI clients which are allowed to connect. Equivalent
277
+
to the FCGI_WEB_SERVER_ADDRS environment variable in the original PHP FastCGI (5.2.2+).
278
+
Makes sense only with a tcp listening socket. Each address must be separated by a comma.
279
+
If this value is left blank, connections will be accepted from any ip address.
280
+
Default value: not set (any ip address accepted).
146
281
</para>
147
282
</listitem>
148
283
</varlistentry>
...
...
@@ -182,6 +317,31 @@
182
317
</para>
183
318
</listitem>
184
319
</varlistentry>
320
+
<varlistentry xml:id="listen-acl-users">
321
+
<term>
322
+
<parameter>listen.acl_users</parameter>
323
+
<type>string</type>
324
+
</term>
325
+
<listitem>
326
+
<para>
327
+
When POSIX Access Control Lists are supported you can set them using this option.
328
+
When set, <literal>listen.owner</literal> and <literal>listen.group</literal>
329
+
are ignored. Value is a comma separated list of user names.
330
+
</para>
331
+
</listitem>
332
+
</varlistentry>
333
+
<varlistentry xml:id="listen-acl-groups">
334
+
<term>
335
+
<parameter>listen.acl_groups</parameter>
336
+
<type>string</type>
337
+
</term>
338
+
<listitem>
339
+
<para>
340
+
See <literal>listen.acl_users</literal>.
341
+
Value is a comma separated list of group names.
342
+
</para>
343
+
</listitem>
344
+
</varlistentry>
185
345
<varlistentry xml:id="user">
186
346
<term>
187
347
<parameter>user</parameter>
...
...
@@ -232,7 +392,7 @@
232
392
</para>
233
393
</listitem>
234
394
</varlistentry>
235
-
<varlistentry xml:id="pm.max-chidlren">
395
+
<varlistentry xml:id="pm.max-children">
236
396
<term>
237
397
<parameter>pm.max_children</parameter>
238
398
<type>int</type>
...
...
@@ -292,6 +452,33 @@
292
452
</para>
293
453
</listitem>
294
454
</varlistentry>
455
+
<varlistentry xml:id="pm.max-spawn-rate">
456
+
<term>
457
+
<parameter>pm.max_spawn_rate</parameter>
458
+
<type>int</type>
459
+
</term>
460
+
<listitem>
461
+
<para>
462
+
The number of rate to spawn child processes at once. Used only when
463
+
<literal>pm</literal> is set to <literal>dynamic</literal>.
464
+
Default value: 32
465
+
</para>
466
+
</listitem>
467
+
</varlistentry>
468
+
<varlistentry xml:id="pm.process-idle-timeout">
469
+
<term>
470
+
<parameter>pm.process_idle_timeout</parameter>
471
+
<type>mixed</type>
472
+
</term>
473
+
<listitem>
474
+
<para>
475
+
The number of seconds after which an idle process will be killed.
476
+
Used only when <literal>pm</literal> is set to <literal>ondemand</literal>.
477
+
Available units: s(econds)(default), m(inutes), h(ours), or d(ays).
478
+
Default value: 10s.
479
+
</para>
480
+
</listitem>
481
+
</varlistentry>
295
482
<varlistentry xml:id="pm.max-requests">
296
483
<term>
297
484
<parameter>pm.max_requests</parameter>
...
...
@@ -306,6 +493,22 @@
306
493
</para>
307
494
</listitem>
308
495
</varlistentry>
496
+
<varlistentry xml:id="pm.status-listen">
497
+
<term>
498
+
<parameter>pm.status_listen</parameter>
499
+
<type>string</type>
500
+
</term>
501
+
<listitem>
502
+
<para>
503
+
The address on which to accept FastCGI status request. This creates a new invisible pool
504
+
that can handle requests independently. This is useful if the main pool is busy with long
505
+
running requests because it is still possible to get the
506
+
<link linkend="fpm.status">FPM status page</link> before finishing the long running
507
+
requests. The syntax is the same as for <link linkend="listen">listen</link> directive.
508
+
Default value: none.
509
+
</para>
510
+
</listitem>
511
+
</varlistentry>
309
512
<varlistentry xml:id="pm.status-path">
310
513
<term>
311
514
<parameter>pm.status_path</parameter>
...
...
@@ -313,8 +516,9 @@
313
516
</term>
314
517
<listitem>
315
518
<para>
316
-
The URI to view the FPM status page. If this value is not set, no URI
317
-
will be recognized as a status page. Default value: none.
519
+
The URI to view the <link linkend="fpm.status">FPM status page</link>. This value must
520
+
start with a leading slash (/). If this value is not set, no URI will be recognized as
521
+
a status page. Default value: none.
318
522
</para>
319
523
</listitem>
320
524
</varlistentry>
...
...
@@ -345,6 +549,44 @@
345
549
</para>
346
550
</listitem>
347
551
</varlistentry>
552
+
<varlistentry xml:id="worker-process-priority">
553
+
<term>
554
+
<parameter>process.priority</parameter>
555
+
<type>int</type>
556
+
</term>
557
+
<listitem>
558
+
<para>
559
+
Specify the nice(2) priority to apply to the worker process (only if set).
560
+
The value can vary from -19 (highest priority) to 20 (lower priority).
561
+
Default value: not set.
562
+
</para>
563
+
</listitem>
564
+
</varlistentry>
565
+
<varlistentry xml:id="process-dumpable">
566
+
<term>
567
+
<parameter>process.dumpable</parameter>
568
+
<type>bool</type>
569
+
</term>
570
+
<listitem>
571
+
<para>
572
+
Set the process dumpable flag (PR_SET_DUMPABLE prctl) even if the process user
573
+
or group is different than the master process user. It allows to create process
574
+
core dump and ptrace the process for the pool user.
575
+
Default Value: no. Since PHP 7.0.29, 7.1.17 and 7.2.5.
576
+
</para>
577
+
</listitem>
578
+
</varlistentry>
579
+
<varlistentry xml:id="prefix">
580
+
<term>
581
+
<parameter>prefix</parameter>
582
+
<type>string</type>
583
+
</term>
584
+
<listitem>
585
+
<para>
586
+
Specify prefix for path evaluation
587
+
</para>
588
+
</listitem>
589
+
</varlistentry>
348
590
<varlistentry xml:id="request-terminate-timeout">
349
591
<term>
350
592
<parameter>request_terminate_timeout</parameter>
...
...
@@ -360,6 +602,22 @@
360
602
</para>
361
603
</listitem>
362
604
</varlistentry>
605
+
<varlistentry xml:id="request-terminate-timeout-track-finished">
606
+
<term>
607
+
<parameter>request_terminate_timeout_track_finished</parameter>
608
+
<type>bool</type>
609
+
</term>
610
+
<listitem>
611
+
<para>
612
+
The timeout set by
613
+
<link linkend="request-terminate-timeout">request_terminate_timeout</link> is not engaged
614
+
after a <link linkend="function.fastcgi-finish-request">fastcgi_finish_request</link> or
615
+
when application has finished and internal shutdown functions are being called. This
616
+
directive will enable timeout limit to be applied unconditionally even in such cases.
617
+
Default value: no. Since PHP 7.3.0.
618
+
</para>
619
+
</listitem>
620
+
</varlistentry>
363
621
<varlistentry xml:id="request-slowlog-timeout">
364
622
<term>
365
623
<parameter>request_slowlog_timeout</parameter>
...
...
@@ -374,6 +632,18 @@
374
632
</para>
375
633
</listitem>
376
634
</varlistentry>
635
+
<varlistentry xml:id="request-slowlog-trace-depth">
636
+
<term>
637
+
<parameter>request_slowlog_trace_depth</parameter>
638
+
<type>int</type>
639
+
</term>
640
+
<listitem>
641
+
<para>
642
+
The depth of slowlog log stack trace.
643
+
Default value: 20. Since PHP 7.2.0.
644
+
</para>
645
+
</listitem>
646
+
</varlistentry>
377
647
<varlistentry xml:id="slowlog">
378
648
<term>
379
649
<parameter>slowlog</parameter>
...
...
@@ -393,7 +663,7 @@
393
663
</term>
394
664
<listitem>
395
665
<para>
396
-
Set open file descriptor rlimit. Default value: system defined value.
666
+
Set open file descriptor rlimit for child processes in this pool. Default value: system defined value.
397
667
</para>
398
668
</listitem>
399
669
</varlistentry>
...
...
@@ -404,7 +674,7 @@
404
674
</term>
405
675
<listitem>
406
676
<para>
407
-
Set max core size rlimit. Possible Values: 'unlimited' or an integer greater or equal to 0.
677
+
Set max core size rlimit for child processes in this pool. Possible Values: 'unlimited' or an integer greater or equal to 0.
408
678
Default value: system defined value.
409
679
</para>
410
680
</listitem>
...
...
@@ -436,7 +706,7 @@
436
706
<varlistentry xml:id="catch-workers-output">
437
707
<term>
438
708
<parameter>catch_workers_output</parameter>
439
-
<type>boolean</type>
709
+
<type>bool</type>
440
710
</term>
441
711
<listitem>
442
712
<para>
...
...
@@ -446,6 +716,207 @@
446
716
</para>
447
717
</listitem>
448
718
</varlistentry>
719
+
<varlistentry xml:id="decorate-workers-output">
720
+
<term>
721
+
<parameter>decorate_workers_output</parameter>
722
+
<type>bool</type>
723
+
</term>
724
+
<listitem>
725
+
<para>
726
+
Enable the output decoration for workers output when <link
727
+
linkend="catch-workers-output">catch_workers_output</link> is enabled.
728
+
Default value: yes.
729
+
Available as of PHP 7.3.0.
730
+
</para>
731
+
</listitem>
732
+
</varlistentry>
733
+
<varlistentry xml:id="clear-env">
734
+
<term>
735
+
<parameter>clear_env</parameter>
736
+
<type>bool</type>
737
+
</term>
738
+
<listitem>
739
+
<para>
740
+
Clear environment in FPM workers.
741
+
Prevents arbitrary environment variables from reaching FPM worker processes
742
+
by clearing the environment in workers before env vars specified in this
743
+
pool configuration are added.
744
+
Default value: Yes.
745
+
</para>
746
+
</listitem>
747
+
</varlistentry>
748
+
<varlistentry xml:id="security-limit-extensions">
749
+
<term>
750
+
<parameter>security.limit_extensions</parameter>
751
+
<type>string</type>
752
+
</term>
753
+
<listitem>
754
+
<para>
755
+
Limits the extensions of the main script FPM will allow to parse.
756
+
This can prevent configuration mistakes on the web server side.
757
+
You should only limit FPM to .php extensions to prevent malicious
758
+
users to use other extensions to execute php code.
759
+
Default value: .php .phar
760
+
</para>
761
+
</listitem>
762
+
</varlistentry>
763
+
<varlistentry xml:id="apparmor-hat">
764
+
<term>
765
+
<parameter>apparmor_hat</parameter>
766
+
<type>string</type>
767
+
</term>
768
+
<listitem>
769
+
<para>
770
+
If AppArmor is enabled, it allows to change a hat.
771
+
Default value: not set
772
+
</para>
773
+
</listitem>
774
+
</varlistentry>
775
+
<varlistentry xml:id="access-log">
776
+
<term>
777
+
<parameter>access.log</parameter>
778
+
<type>string</type>
779
+
</term>
780
+
<listitem>
781
+
<para>
782
+
The access log file.
783
+
Default value: not set
784
+
</para>
785
+
</listitem>
786
+
</varlistentry>
787
+
<varlistentry xml:id="access-format">
788
+
<term>
789
+
<parameter>access.format</parameter>
790
+
<type>string</type>
791
+
</term>
792
+
<listitem>
793
+
<para>
794
+
The access log format.
795
+
Default value: <literal>"%R - %u %t \"%m %r\" %s"</literal>:
796
+
<table xml:id="fpm.configuration.access.format">
797
+
<title>Valid options</title>
798
+
<tgroup cols="2">
799
+
<thead>
800
+
<row>
801
+
<entry>Placeholder</entry>
802
+
<entry>Description</entry>
803
+
</row>
804
+
</thead>
805
+
<tbody>
806
+
<row>
807
+
<entry>
808
+
<literal>%C</literal>
809
+
</entry>
810
+
<entry>%CPU</entry>
811
+
</row>
812
+
<row>
813
+
<entry>
814
+
<literal>%d</literal>
815
+
</entry>
816
+
<entry>duration µs</entry>
817
+
</row>
818
+
<row>
819
+
<entry>
820
+
<literal>%e</literal>
821
+
</entry>
822
+
<entry>fastcgi env</entry>
823
+
</row>
824
+
<row>
825
+
<entry>
826
+
<literal>%f</literal>
827
+
</entry>
828
+
<entry>script</entry>
829
+
</row>
830
+
<row>
831
+
<entry>
832
+
<literal>%l</literal>
833
+
</entry>
834
+
<entry>content length</entry>
835
+
</row>
836
+
<row>
837
+
<entry>
838
+
<literal>%m</literal>
839
+
</entry>
840
+
<entry>method</entry>
841
+
</row>
842
+
<row>
843
+
<entry>
844
+
<literal>%M</literal>
845
+
</entry>
846
+
<entry>memory</entry>
847
+
</row>
848
+
<row>
849
+
<entry>
850
+
<literal>%n</literal>
851
+
</entry>
852
+
<entry>pool name</entry>
853
+
</row>
854
+
<row>
855
+
<entry>
856
+
<literal>%o</literal>
857
+
</entry>
858
+
<entry>header output</entry>
859
+
</row>
860
+
<row>
861
+
<entry>
862
+
<literal>%p</literal>
863
+
</entry>
864
+
<entry>PID</entry>
865
+
</row>
866
+
<row>
867
+
<entry>
868
+
<literal>%q</literal>
869
+
</entry>
870
+
<entry>query string</entry>
871
+
</row>
872
+
<row>
873
+
<entry>
874
+
<literal>%Q</literal>
875
+
</entry>
876
+
<entry>the glue between %q and %r</entry>
877
+
</row>
878
+
<row>
879
+
<entry>
880
+
<literal>%r</literal>
881
+
</entry>
882
+
<entry>request URI</entry>
883
+
</row>
884
+
<row>
885
+
<entry>
886
+
<literal>%R</literal>
887
+
</entry>
888
+
<entry>remote IP address</entry>
889
+
</row>
890
+
<row>
891
+
<entry>
892
+
<literal>%s</literal>
893
+
</entry>
894
+
<entry>status</entry>
895
+
</row>
896
+
<row>
897
+
<entry>
898
+
<literal>%T</literal>
899
+
</entry>
900
+
<entry>time</entry>
901
+
</row>
902
+
<row>
903
+
<entry>
904
+
<literal>%t</literal>
905
+
</entry>
906
+
<entry>time</entry>
907
+
</row>
908
+
<row>
909
+
<entry>
910
+
<literal>%u</literal>
911
+
</entry>
912
+
<entry>remote user</entry>
913
+
</row>
914
+
</tbody>
915
+
</tgroup>
916
+
</table>
917
+
</para>
918
+
</listitem>
919
+
</varlistentry>
449
920
</variablelist>
450
921
<para>
451
922
It's possible to pass additional environment variables and update PHP settings of a certain pool.
...
...
@@ -478,10 +949,10 @@ php_admin_value[memory_limit] = 32M
478
949
</para>
479
950
<para>
480
951
Settings defined with <literal>php_admin_value</literal> and <literal>php_admin_flag</literal>
481
-
cannot be overriden with <function>ini_set</function>.
952
+
cannot be overridden with <function>ini_set</function>.
482
953
</para>
483
954
<para>
484
-
As of 5.3.3, PHP settings are also possible to be set in webserver.
955
+
PHP settings can be set in the webserver configuration.
485
956
<example>
486
957
<title>set PHP settings in nginx.conf</title>
487
958
<programlisting role="ini">
...
...
@@ -503,6 +974,12 @@ fastcgi_param PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";
503
974
<link linkend="listen-allowed-clients">listen.allowed_clients</link>.
504
975
</para>
505
976
</caution>
977
+
<note>
978
+
<simpara>
979
+
Pools are not a security mechanism, because they do not provide full
980
+
separation; e.g. all pools would use a single OPcache instance.
981
+
</simpara>
982
+
</note>
506
983
</para>
507
984
</sect2>
508
985

509
986



Tools (Spanish Manual)