Mailing-List: contact docs-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: docs@httpd.apache.org
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Fri, 28 Mar 2014 15:17:04 -0000
Message-ID: <20140328151704.51407.45613@eos.apache.org>
Subject: =?utf-8?q?=5BHttpd_Wiki=5D_Update_of_=22PHP-FPM=22_by_thumbs?=
Auto-Submitted: auto-generated

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Httpd Wiki" for cha=
nge notification.

The "PHP-FPM" page has been changed by thumbs:
https://wiki.apache.org/httpd/PHP-FPM?action=3Ddiff&rev1=3D3&rev2=3D4

Comment:
Added UDS comments and fixed the header hierarchy

   . php-fpm was previously found at http://php-fpm.org/
  =

  This means that we can now run secure, fast, and dependable PHP code ''us=
ing only the stock apache httpd and php.net releases''; no more messing aro=
und with '''suphp''' or '''suexec''' - or, indeed, '''mod_php'''.
- ----
  =

- =3D=3D=3D php-fpm =3D=3D=3D
+ =3D=3D php-fpm =3D=3D
-   '''prerequisites''': installing software packages, editing configuratio=
n files, controlling service daemons.
+ =

+ Prerequisites:
+ =

+  * installing software packages
+ =

+  * editing configuration files
+ =

+  * controlling service daemons.
  =

  From release 5.3.3 onwards, PHP now includes the fastCGI process manager =
(php-fpm) in the stock source code.<<BR>>
  Your distribution or OS will either include it in the stock PHP package, =
or make it available as an add-on package; you can build it from source by =
adding `--enable-fpm` to your ./configure options.
@@ -22, +28 @@

  =

  Inside this configuration file you can create an arbitrary number of fast=
cgi "pools" which are defined by the IP and port they listen on, just like =
apache virtualhosts.
  =

- The most important setting in each pool is the ''socket'' (IP and port) p=
hp-fpm will be listening on to receive fastCGI requests; this is configured=
 using the `listen` option.<<BR>>
+ The most important setting in each pool is the TCP socket (IP and port) o=
r unix domain socket (UDS) php-fpm will be listening on to receive fastCGI =
requests; this is configured using the `listen` option.<<BR>>
  The default pool, `[www]`, has this configured as `listen 127.0.0.1:9000`=
: it will only respond to requests on the local loopback network interface =
(localhost), on TCP port 9000.<<BR>>
  Also of interest are the ''per-pool'' `user` and `group` options, which a=
llow you to run that specific fpm pool under the given uid and gid; __goodb=
ye suphp__!
  =

@@ -30, +36 @@

   `/etc/init.d/php-fpm start`
  Or if not, start it manually with
   `php-fpm -y /path/to/php-fpm.conf -c /path/to/custom/php.ini`
+ If you don't provide php-fpm with its own `php.ini` file, the ''global'' =
php.ini will be used. __Remember__ this when you want to include more or le=
ss extensions than the CLI or CGI binaries use, or need to alter some other=
 values there.
- If you don't provide php-fpm with its own `php.ini` file, the ''global'' =
php.ini will be used.<<BR>>
- __Remember__ this when you want to include more or less extensions than t=
he CLI or CGI binaries use, or need to alter some other values there.
  =

  You can include per-pool `php.ini` values in the same way you would defin=
e these in apache previously for mod_php, using `php_[admin_](flag|value)`.
  =

@@ -44, +49 @@

   Side note: you can force a running php-fpm to reload its configuration  =
by sending it a SIGUSR2 signal.; SIGUSR1 will cycle the log files (perfect =
for a logrotate script!). A little experimentation goes a long way ;)
  =

  That's php-fpm taken care of; if there were no errors during startup it s=
hould be listening and ready for connections.
- ----
- =3D=3D=3D apache httpd 2.4 =3D=3D=3D
  =

-  '''prerequisites''': editing httpd.conf; understanding vhost context; un=
derstanding URL-to-filesystem namespace mapping; controlling the apache htt=
pd daemon
+ =3D=3D apache httpd 2.4 =3D=3D
  =

- The release of apache httpd 2.4 has introduced two noteworthy features: a=
 new proxy module specifically for fastCGI (mod_proxy_fcgi), and the move t=
o the '''event''' MPM as the default apache process manager.
+ prerequisites:
  =

+  * editing httpd.conf
+ =

+  * understanding the vhost context
+ =

+  * understanding URL-to-filesystem namespace mapping
+ =

+  * controlling the apache httpd daemon
+ =

+ This release of apache httpd has introduced two noteworthy features: a ne=
w proxy module specifically for fastCGI (mod_proxy_fcgi), and the move to t=
he '''event''' MPM as the default apache process manager.
+ =

- As with the worker MPM of the previous version, the threaded model of thi=
s MPM causes issues when mod_php is used with ''non-thread-safe'' 3rd-party=
 PHP extensions.<<BR>>
+ As with the worker MPM of the previous version, the threaded model of thi=
s MPM causes issues when mod_php is used with ''non-thread-safe'' third-par=
ty PHP extensions.
+ =

  This has been a bane of mod_php users ever since apache 2.2 was released,=
 practically forcing them to cobble together fastcgi solutions, or use the =
much slower and memory-hungry prefork MPM.
  =

  To work the magic with the PHP fastCGI process manager, we will be using =
a new module, '''[[http://httpd.apache.org/docs/2.4/mod/mod_proxy_fcgi.html=
|mod_proxy_fcgi]]''', which is intended specifically for communicating with=
 (possibly external) fastCGI servers.
@@ -61, +75 @@

   `LoadModule proxy_module modules/mod_proxy.so`<<BR>>
   `LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so`
  =

- Now, there are different ways to actually forward requests for .php files=
 ''to'' this module, ranging from everything (using ProxyPass) to very spec=
ific or rewritten files or patterns (using mod_rewrite with the [P] flag).<=
<BR>>
+ Now, there are different ways to actually forward requests for .php files=
 ''to'' this module, ranging from everything (using ProxyPass) to very spec=
ific or rewritten files or patterns (using mod_rewrite with the [P] flag).
+ =

- The method I chose (using ProxyPassMatch) lies somewhere in between these=
 in complexity and flexibility, since it allows you to set one rule for all=
 PHP content of a specific vhost, but will only forward .php files (or URLs=
 that contain the text `.php` somewhere in the request)
+ The method I chose (using ProxyPassMatch) lies somewhere in between these=
 in complexity and flexibility, since it allows you to set one rule for all=
 PHP content of a specific vhost, but will only proxy .php files (or URLs t=
hat contain the text `.php` somewhere in the request).
+ =

+ =3D=3D=3D TCP socket (IP and port) approach =3D=3D=3D
  =

  Edit the configuration for a vhost of your choice, and add the following =
line to it:
+ =

   `ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/path/to/your/do=
cumentroot/$1`
  =

  Look confusing ? Let's run through it:
+ =

   ProxyPassMatch:: only proxy content that matches the specified regex pat=
tern; in this case:
   ^/(.*\.php(/.*)?)$:: from the documentroot onwards, match everything end=
ing in .php (with the dot escaped), optionally followed by a slash and any =
continued path you like (some applications use this so-called '''Path``Info=
''' to pass arguments to the php script.)<<BR>>
   The `^` (caret) and `$` (dollar) signs are used to ''anchor'' both the a=
bsolute __start__ and __end__ of the URL, to make sure no characters from t=
he request escape our pattern match.<<BR>>
@@ -76, +95 @@

   fcgi://127.0.0.1:9000:: forward via mod_proxy_fcgi, using the fastCGI pr=
otocol, to the port our php-fpm daemon is listening on.<<BR>>
   This determines which fastcgi ''pool'' will serve requests proxied by th=
is rule.
   /path/to/your/documentroot/:: IMPORTANT! This must ''exactly'' match the=
 '''real''' filesystem location of your php files, because that is where th=
e php-fpm daemon will look for them.<<BR>>
-   php-fpm just interprets the php files passed to it; it is not a web ser=
ver, nor does it understand your web servers' namespace, virtualhost layout=
, or aliases.<<BR>>
+  php-fpm just interprets the php files passed to it; it is not a web serv=
er, nor does it understand your web servers' namespace, virtualhost layout,=
 or aliases.<<BR>>
   IMPORTANT! __Read the above again__
   $1:: expands to the entire request-URI from the original request, minus =
the leading slash (because we already added that above.)
- ----
  =

+ =3D=3D=3D unix domain socket (UDS) approach =3D=3D=3D
+ =

+ Edit the configuration for a vhost of your choice, and add the following =
line to it:
+ =

+  `ProxyPassMatch ^/(.*\.php(/.*)?)$ unix:/path/to/socket.sock|fcgi://127.=
0.0.1:9000/path/to/your/documentroot/`
+ =

+  unix:/path/to/socket.sock:: the path to your fpm socket
+ =

+ ''Note that with this approach, the captured request URI ($1) is not pass=
ed after the path''
+ =

- =3D=3D=3D=3D example =3D=3D=3D=3D
+ =3D=3D=3D Example =3D=3D=3D
+ =

  Say you want to be able to conjure up the standard php info page listing =
all compiled-in and loaded extensions, and all runtime configuration option=
s and script info.
  =

  We first create a file, info.php, by running the following:
+ =

   `echo "<?php phpinfo() ?>" > /var/www/info.php`
- NOTE you may need to do this as `root`, depending on the permissions set =
on /var/www.
-  I assume /var/www is the documentroot of an existing vhost; this is the =
case on most major distributions.
+ =

+ NOTE: you may need to do this as `root`, depending on the permissions set=
 on /var/www. I assume /var/www is the documentroot of an existing vhost; t=
his is the case on most major distributions.
  =

  Inside this vhost, add the following line:
+ =

   `ProxyPassMatch ^/info$ fcgi://127.0.0.1:9000/var/www/info.php`
+ =

  Reload apache with `apachectl graceful` and you can now call up the phpin=
fo page using http://your-vhost/info
    =

  This is a very simple example, mapping one unique URL to a single PHP fil=
e.
  =

  In case you want to proxy '''all''' `.php` files in your vhost to the fcg=
i server using their real php file locations, you can use a more flexible m=
atch:
+ =

   `ProxyPassMatch ^/(.*\.php)$ fcgi://127.0.0.1:9000/var/www/$1`
+ =

  Again, assuming `/var/www` is the documentroot of the vhost in question.
  =

- __Don't forget to reload apache after making any changes to a vhost or ot=
her configuration file.__
+ __Don't forget to restart apache after making any changes to a vhost or o=
ther configuration file. You can use apachectl restart or apachectl gracefu=
l.__
  =

- =3D=3D=3D=3D Performance and Pitfalls =3D=3D=3D=3D
+ =3D=3D=3D Performance and Pitfalls =3D=3D=3D
+ =

- mod_proxy_fcgi only supports network sockets ( [[https://issues.apache.or=
g/bugzilla/show_bug.cgi?id=3D54101|Unix socket support for mod_proxy_fcgi]]=
 )
+ mod_proxy_fcgi now supports network sockets since 2.4.9 ( [[https://issue=
s.apache.org/bugzilla/show_bug.cgi?id=3D54101|Unix socket support for mod_p=
roxy_fcgi]] )
  =

  It is easy to overwhelm your system's available sockets, pass over ulimit=
s, etc.  Some tips to avoid this:
  =

@@ -119, +154 @@

  =

  If apache and php-fpm run as the same user (not necessary or recommended)=
 and nproc is too small, apache will not startup with the following message=
 `(11)Resource temporarily unavailable: AH02162: setuid: unable to change t=
o uid: 600`
  =

- =3D=3D=3D=3D Caveat =3D=3D=3D=3D
+ =3D=3D=3D Caveats =3D=3D=3D
+ =

  One might be tempted to point out that a greedy ProxyPassMatch directive =
might allow some malicious content uploaded by a HTTP client to be served.
  =

  This is by no means a comprehensive security document, but instead will p=
oint out a possible injection vector that could be generated from the direc=
tives in this document.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org