From: Luca Toscano Date: Thu, 27 Jul 2017 12:30:20 +0000 (+0000) Subject: Clarify some mod_proxy concepts in the docs X-Git-Tag: 2.5.0-alpha~249 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=579e1799fbaef8bf32e4b202c8388a0fbe043120;p=thirdparty%2Fapache%2Fhttpd.git Clarify some mod_proxy concepts in the docs I have recently got some basic mod-proxy concepts and these simple info would have helped me a lot: - connection pooling == reuse. My brain did not pick up this simple nomenclature at first read for some reason, probably because we have parameters called "*reuse*" and not "*pooling*". I find the term "reuse" clearer than "pooling", but this is debatable :) - the concept of "Worker" needs to be read before the ProxyPass section (that people probably read directly after checking a search engine) to fully understand its power. - the fact that a worker is related to a single process (and not shared as a Balancer) is a really important concept that I tried to highlight when talking about maxconns (question popped up a lot of times from users). Hope that my understanding is correct, feedback is welcome. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1803171 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_proxy.html.en b/docs/manual/mod/mod_proxy.html.en index c85ae87cac7..48ec97314bc 100644 --- a/docs/manual/mod/mod_proxy.html.en +++ b/docs/manual/mod/mod_proxy.html.en @@ -244,7 +244,7 @@ ProxyVia On

The two default workers have a fixed configuration and will be used if no other worker matches the request. - They do not use HTTP Keep-Alive or connection pooling. + They do not use HTTP Keep-Alive or connection reuse. The TCP connections to the origin server will instead be opened and closed for each request.

@@ -345,8 +345,8 @@ ProxyPass "/examples" "http://backend.example.com/examples" timeout=10

DNS resolution for origin domains

DNS resolution happens when the socket to the origin domain is created for the first time. - When connection pooling is used, each backend domain is resolved - only once per child process, and reused for all further connections + When connection reuse is enabled, each backend domain is resolved + only once per child process, and cached for all further connections until the child is recycled. This information should to be considered while planning DNS maintenance tasks involving backend domains. Please also check ProxyPass @@ -1020,7 +1020,11 @@ through a local virtual path; url is a partial URL for the remote server and cannot include a query string.

-
Note: This directive is not supported within +
It is strongly suggested to review the concept of a + Worker before proceeding any further + with this section.
+ +
This directive is not supported within <Directory> and <Files> containers.
@@ -1133,24 +1137,26 @@ ProxyPass "/mirror/foo" "http://backend.example.com" using key=value parameters, described in the tables below.

+

Maximum connections to the backend

By default, mod_proxy will allow and retain the maximum number of connections that could be used simultaneously by that web server child process. Use the max parameter to reduce the number from - the default. Use the ttl parameter to set an optional + the default. The pool of connections is maintained per web server child + process, and max and other settings are not coordinated + among all child processes, except when only one child process is allowed + by configuration or MPM design.

+
+ +

Use the ttl parameter to set an optional time to live; connections which have been unused for at least ttl seconds will be closed. ttl can be used to avoid using a connection which is subject to closing because of the backend server's keep-alive timeout.

-

The pool of connections is maintained per web server child - process, and max and other settings are not coordinated - among all child processes, except when only one child process is allowed - by configuration or MPM design.

-

Example

ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300
-
BalancerMember parameters
+
Worker|BalancerMember parameters
@@ -1201,7 +1207,7 @@ ProxyPass "/mirror/foo" "http://backend.example.com" httpd and the backend server (regardless of protocol) tends to silently drop connections or when backends themselves may be under round- - robin DNS. To disable connection pooling reuse, + robin DNS. To disable connection reuse, set this property value to On. diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml index a97abc36d9f..3c1b49b3e64 100644 --- a/docs/manual/mod/mod_proxy.xml +++ b/docs/manual/mod/mod_proxy.xml @@ -201,7 +201,7 @@ ProxyVia On

The two default workers have a fixed configuration and will be used if no other worker matches the request. - They do not use HTTP Keep-Alive or connection pooling. + They do not use HTTP Keep-Alive or connection reuse. The TCP connections to the origin server will instead be opened and closed for each request.

@@ -307,8 +307,8 @@ ProxyPass "/examples" "http://backend.example.com/examples" timeout=10 DNS resolution for origin domains

DNS resolution happens when the socket to the origin domain is created for the first time. - When connection pooling is used, each backend domain is resolved - only once per child process, and reused for all further connections + When connection reuse is enabled, each backend domain is resolved + only once per child process, and cached for all further connections until the child is recycled. This information should to be considered while planning DNS maintenance tasks involving backend domains. Please also check ProxyPass @@ -881,7 +881,11 @@ expressions a local virtual path; url is a partial URL for the remote server and cannot include a query string.

- Note: This directive is not supported within + It is strongly suggested to review the concept of a + Worker before proceeding any further + with this section. + + This directive is not supported within Directory and Files containers. @@ -1002,27 +1006,29 @@ ProxyPass "/mirror/foo" "http://backend.example.com" using key=value parameters, described in the tables below.

+ Maximum connections to the backend

By default, mod_proxy will allow and retain the maximum number of connections that could be used simultaneously by that web server child process. Use the max parameter to reduce the number from - the default. Use the ttl parameter to set an optional + the default. The pool of connections is maintained per web server child + process, and max and other settings are not coordinated + among all child processes, except when only one child process is allowed + by configuration or MPM design.

+ + +

Use the ttl parameter to set an optional time to live; connections which have been unused for at least ttl seconds will be closed. ttl can be used to avoid using a connection which is subject to closing because of the backend server's keep-alive timeout.

-

The pool of connections is maintained per web server child - process, and max and other settings are not coordinated - among all child processes, except when only one child process is allowed - by configuration or MPM design.

- Example ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300 -
Parameter Default
enablereuse
BalancerMember parameters
+
Worker|BalancerMember parameters
@@ -1073,7 +1079,7 @@ ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300 httpd and the backend server (regardless of protocol) tends to silently drop connections or when backends themselves may be under round- - robin DNS. To disable connection pooling reuse, + robin DNS. To disable connection reuse, set this property value to On. diff --git a/docs/manual/mod/mod_proxy_fcgi.html.en b/docs/manual/mod/mod_proxy_fcgi.html.en index 1e498242706..df117bee926 100644 --- a/docs/manual/mod/mod_proxy_fcgi.html.en +++ b/docs/manual/mod/mod_proxy_fcgi.html.en @@ -95,7 +95,7 @@

The following example passes the request URI as a filesystem path for the PHP-FPM daemon to run. The request URL is implicitly added to the 2nd parameter. The hostname and port following fcgi:// are where - PHP-FPM is listening. Connection pooling is enabled.

+ PHP-FPM is listening. Connection pooling/reuse is enabled.

PHP-FPM

ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on
diff --git a/docs/manual/mod/mod_proxy_fcgi.xml b/docs/manual/mod/mod_proxy_fcgi.xml index 4bc227d18fd..f63e3985d75 100644 --- a/docs/manual/mod/mod_proxy_fcgi.xml +++ b/docs/manual/mod/mod_proxy_fcgi.xml @@ -85,7 +85,7 @@ ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on

The following example passes the request URI as a filesystem path for the PHP-FPM daemon to run. The request URL is implicitly added to the 2nd parameter. The hostname and port following fcgi:// are where - PHP-FPM is listening. Connection pooling is enabled.

+ PHP-FPM is listening. Connection pooling/reuse is enabled.

PHP-FPM ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on diff --git a/docs/manual/rewrite/flags.html.en b/docs/manual/rewrite/flags.html.en index d2621ba7c4a..722e6462c99 100644 --- a/docs/manual/rewrite/flags.html.en +++ b/docs/manual/rewrite/flags.html.en @@ -536,7 +536,7 @@ client undue influence.

Using this flag triggers the use of mod_proxy, without handling of persistent connections. This means the performance of your proxy will be better if you set it up with ProxyPass or ProxyPassMatch

-

This is because this flag triggers the use of the default worker, which does not handle connection pooling.

+

This is because this flag triggers the use of the default worker, which does not handle connection pooling/reuse.

Avoid using this flag and prefer those directives, whenever you can.

diff --git a/docs/manual/rewrite/flags.xml b/docs/manual/rewrite/flags.xml index 3c7aceef3e1..cd9fe971caf 100644 --- a/docs/manual/rewrite/flags.xml +++ b/docs/manual/rewrite/flags.xml @@ -547,7 +547,7 @@ client undue influence.

Using this flag triggers the use of mod_proxy, without handling of persistent connections. This means the performance of your proxy will be better if you set it up with ProxyPass or ProxyPassMatch

-

This is because this flag triggers the use of the default worker, which does not handle connection pooling.

+

This is because this flag triggers the use of the default worker, which does not handle connection pooling/reuse.

Avoid using this flag and prefer those directives, whenever you can.

Parameter Default
enablereuse