From 40dac077aa544161cf5de96acccf2c459d38a5d5 Mon Sep 17 00:00:00 2001 From: Daniel Gruno Date: Fri, 4 May 2012 15:12:56 +0000 Subject: [PATCH] Backporting syntax highlighting for mod_p*.xml git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1334022 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_proxy.xml | 286 ++++++++++++------------- docs/manual/mod/mod_proxy_ajp.xml | 24 ++- docs/manual/mod/mod_proxy_balancer.xml | 50 +++-- docs/manual/mod/mod_proxy_fcgi.xml | 18 +- docs/manual/mod/mod_proxy_ftp.xml | 6 +- docs/manual/mod/mod_proxy_html.xml | 37 ++++ docs/manual/mod/mod_proxy_scgi.xml | 28 ++- 7 files changed, 245 insertions(+), 204 deletions(-) diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml index 0be2c0bd1d..e1f8dffe1b 100644 --- a/docs/manual/mod/mod_proxy.xml +++ b/docs/manual/mod/mod_proxy.xml @@ -151,19 +151,21 @@ the documentation from mod_cache.

Reverse Proxy - ProxyPass /foo http://foo.example.com/bar
- ProxyPassReverse /foo http://foo.example.com/bar + +ProxyPass /foo http://foo.example.com/bar +ProxyPassReverse /foo http://foo.example.com/bar + Forward Proxy - ProxyRequests On
- ProxyVia On
-
- <Proxy *>
- - Require host internal.example.com
- - </Proxy> + +ProxyRequests On +ProxyVia On + +<Proxy *> + Require host internal.example.com +</Proxy> + @@ -187,29 +189,27 @@ ProxyPassMatch when used for a reverse proxy:

- + ProxyPass /example http://backend.example.com connectiontimeout=5 timeout=30 - +

This will create a worker associated with the origin server URL http://backend.example.com and using the given timeout values. When used in a forward proxy, workers are usually defined via the ProxySet directive:

- + ProxySet http://backend.example.com connectiontimeout=5 timeout=30 - +

or alternatively using Proxy and ProxySet:

- - <Proxy http://backend.example.com>
- - ProxySet connectiontimeout=5 timeout=30 - - </Proxy> - + +<Proxy http://backend.example.com> + ProxySet connectiontimeout=5 timeout=30 +</Proxy> +

Using explicitly configured workers in the forward mode is not very common, because forward proxies usually communicate with many @@ -225,10 +225,10 @@

The URL identifying a direct worker is the URL of its origin server including any path components given:

- - ProxyPass /examples http://backend.example.com/examples
- ProxyPass /docs http://backend.example.com/docs - + +ProxyPass /examples http://backend.example.com/examples +ProxyPass /docs http://backend.example.com/docs +

This example defines two different workers, each using a separate connection pool and configuration.

@@ -238,10 +238,10 @@ the URL of some worker is a leading substring of the URL of another worker defined later in the configuration file. In the following example

- - ProxyPass /apps http://backend.example.com/ timeout=60
- ProxyPass /examples http://backend.example.com/examples timeout=10 - + +ProxyPass /apps http://backend.example.com/ timeout=60 +ProxyPass /examples http://backend.example.com/examples timeout=10 +

the second worker isn't actually created. Instead the first worker is used. The benefit is, that there is only one connection pool, @@ -288,13 +288,11 @@ module="mod_proxy" type="section">Proxy control block as in the following example:

- - <Proxy *>
- - Require ip 192.168.0
- - </Proxy> - + +<Proxy *> + Require ip 192.168.0 +</Proxy> +

For more information on access control directives, see mod_authz_host.

@@ -358,15 +356,13 @@

These are the force-proxy-request-1.0 and proxy-nokeepalive notes.

- - <Location /buggyappserver/>
- - ProxyPass http://buggyappserver:7001/foo/
- SetEnv force-proxy-request-1.0 1
- SetEnv proxy-nokeepalive 1
- - </Location> - + +<Location /buggyappserver/> + ProxyPass http://buggyappserver:7001/foo/ + SetEnv force-proxy-request-1.0 1 + SetEnv proxy-nokeepalive 1 +</Location> + @@ -452,25 +448,21 @@ yournetwork.example.com to access content via your proxy server:

- - <Proxy *>
- - Require host yournetwork.example.com
- - </Proxy> - + +<Proxy *> + Require host yournetwork.example.com +</Proxy> +

The following example will process all files in the foo directory of example.com through the INCLUDES filter when they are sent through the proxy server:

- - <Proxy http://example.com/foo/*>
- - SetOutputFilter INCLUDES
- - </Proxy> - + +<Proxy http://example.com/foo/*> + SetOutputFilter INCLUDES +</Proxy> + ProxyMatch @@ -605,9 +597,11 @@ context in 2.3.3 and later. are forwarded through the remote proxy using the HTTP CONNECT method.

Example - ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000
- ProxyRemote * http://cleverproxy.localdomain
- ProxyRemote ftp http://ftpproxy.mydomain:8080 + +ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000 +ProxyRemote * http://cleverproxy.localdomain +ProxyRemote ftp http://ftpproxy.mydomain:8080 +

In the last example, the proxy will forward FTP requests, encapsulated @@ -697,30 +691,28 @@ expressions ProxyPass directive.

- <Proxy balancer://hotcluster>
- - BalancerMember http://www2.example.com:8080 loadfactor=1
- BalancerMember http://www3.example.com:8080 loadfactor=2
- ProxySet lbmethod=bytraffic
- - </Proxy> + +<Proxy balancer://hotcluster> + BalancerMember http://www2.example.com:8080 loadfactor=1 + BalancerMember http://www3.example.com:8080 loadfactor=2 + ProxySet lbmethod=bytraffic +</Proxy> + - - <Proxy http://backend>
- - ProxySet keepalive=On
- - </Proxy> - + +<Proxy http://backend> + ProxySet keepalive=On +</Proxy> + - + ProxySet balancer://foo lbmethod=bytraffic timeout=15 - + - + ProxySet ajp://backend:7001 timeout=15 - + Warning

Keep in mind that the same parameter key can have a different meaning @@ -757,13 +749,11 @@ expressions

Suppose the local server has address http://example.com/; then

- - <Location /mirror/foo/>
- - ProxyPass http://backend.example.com/
- - </Location>
- + +<Location /mirror/foo/> + ProxyPass http://backend.example.com/ +</Location> +

will cause a local request for http://example.com/mirror/foo/bar to be internally converted @@ -774,9 +764,9 @@ expressions the below syntax is that it allows for dynamic control via the Balancer Manager interface:

- + ProxyPass /mirror/foo/ http://backend.example.com/ - +

If the first argument ends with a trailing /, the second @@ -789,23 +779,19 @@ expressions

The ! directive is useful in situations where you don't want to reverse-proxy a subdirectory, e.g.

- - <Location /mirror/foo/>
- - ProxyPass http://backend.example.com/
- - </Location>
- <Location /mirror/foo/i>
- - ProxyPass !
- - </Location>
- + +<Location /mirror/foo/> + ProxyPass http://backend.example.com/ +</Location> +<Location /mirror/foo/i> + ProxyPass ! +</Location> + - - ProxyPass /mirror/foo/i !
- ProxyPass /mirror/foo http://backend.example.com - + +ProxyPass /mirror/foo/i ! +ProxyPass /mirror/foo http://backend.example.com +

will proxy all requests to /mirror/foo to backend.example.com except requests made to @@ -1116,33 +1102,29 @@ expressions

A sample balancer setup

- - ProxyPass /special-area http://special.example.com smax=5 max=10
- ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On
- <Proxy balancer://mycluster>
- - BalancerMember ajp://1.2.3.4:8009
- BalancerMember ajp://1.2.3.5:8009 loadfactor=20
- # Less powerful server, don't send as many requests there,
- BalancerMember ajp://1.2.3.6:8009 loadfactor=5
- - </Proxy> - + +ProxyPass /special-area http://special.example.com smax=5 max=10 +ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On +<Proxy balancer://mycluster> + BalancerMember ajp://1.2.3.4:8009 + BalancerMember ajp://1.2.3.5:8009 loadfactor=20 + # Less powerful server, don't send as many requests there, + BalancerMember ajp://1.2.3.6:8009 loadfactor=5 +</Proxy> +

Setting up a hot-standby, that will only be used if no other members are available

- - ProxyPass / balancer://hotcluster/
- <Proxy balancer://hotcluster>
- - BalancerMember ajp://1.2.3.4:8009 loadfactor=1
- BalancerMember ajp://1.2.3.5:8009 loadfactor=2
- # The below is the hot standby
- BalancerMember ajp://1.2.3.6:8009 status=+H
- ProxySet lbmethod=bytraffic - - </Proxy> - + +ProxyPass / balancer://hotcluster/ +<Proxy balancer://hotcluster> + BalancerMember ajp://1.2.3.4:8009 loadfactor=1 + BalancerMember ajp://1.2.3.5:8009 loadfactor=2 + # The server below is on hot standby + BalancerMember ajp://1.2.3.6:8009 status=+H + ProxySet lbmethod=bytraffic +</Proxy> +

Normally, mod_proxy will canonicalise ProxyPassed URLs. But this may be incompatible with some backends, particularly those @@ -1204,9 +1186,9 @@ expressions

Suppose the local server has address http://example.com/; then

- + ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com$1 - +

will cause a local request for http://example.com/foo/bar.gif to be internally converted @@ -1215,15 +1197,15 @@ expressions

The URL argument must be parsable as a URL before regexp substitutions (as well as after). This limits the matches you can use. For instance, if we had used

- + ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com:8000$1 - +

in our previous example, it would fail with a syntax error at server startup. This is a bug (PR 46665 in the ASF bugzilla), and the workaround is to reformulate the match:

- + ProxyPassMatch ^/(.*\.gif)$ http://backend.example.com:8000/$1 - +

The ! directive is useful in situations where you don't want to reverse-proxy a subdirectory.

@@ -1282,12 +1264,12 @@ proxied server

For example, suppose the local server has address http://example.com/; then

- - ProxyPass /mirror/foo/ http://backend.example.com/
- ProxyPassReverse /mirror/foo/ http://backend.example.com/
- ProxyPassReverseCookieDomain backend.example.com public.example.com
- ProxyPassReverseCookiePath / /mirror/foo/ - + +ProxyPass /mirror/foo/ http://backend.example.com/ +ProxyPassReverse /mirror/foo/ http://backend.example.com/ +ProxyPassReverseCookieDomain backend.example.com public.example.com +ProxyPassReverseCookiePath / /mirror/foo/ +

will not only cause a local request for the http://example.com/mirror/foo/bar to be internally converted @@ -1369,9 +1351,9 @@ reverse proxy. This directive rewrites the path string in In the example given with ProxyPassReverse, the directive:

- + ProxyPassReverseCookiePath / /mirror/foo/ - +

will rewrite a cookie with backend path / (or /example or, in fact, anything) to /mirror/foo/. @@ -1398,7 +1380,9 @@ proxied well. That may slow down the startup time of the server.

Example + ProxyBlock news.example.com auctions.example.com friends.example.com +

Note that example would also be sufficient to match any @@ -1408,9 +1392,9 @@ proxied

Note also that

- + ProxyBlock * - +

blocks connections to all sites.

@@ -1433,7 +1417,9 @@ connections be used.

Example + ProxyReceiveBufferSize 2048 + @@ -1482,7 +1468,9 @@ through be set to prevent infinite proxy loops, or a DoS attack.

Example + ProxyMaxForwards 15 +

Note that setting ProxyMaxForwards is a @@ -1512,8 +1500,10 @@ directly ProxyRemote proxy server(s).

Example - ProxyRemote * http://firewall.example.com:81
- NoProxy .example.com 192.168.112.0/21 + +ProxyRemote * http://firewall.example.com:81 +NoProxy .example.com 192.168.112.0/21 +

The host arguments to the NoProxy @@ -1652,9 +1642,11 @@ directly will be generated.

Example + ProxyRemote * http://firewall.example.com:81
NoProxy .example.com 192.168.112.0/21
ProxyDomain .example.com + diff --git a/docs/manual/mod/mod_proxy_ajp.xml b/docs/manual/mod/mod_proxy_ajp.xml index 10f25ccdbf..ad604f875c 100644 --- a/docs/manual/mod/mod_proxy_ajp.xml +++ b/docs/manual/mod/mod_proxy_ajp.xml @@ -57,19 +57,21 @@ an HTTP reverse proxy, but uses the ajp:// prefix:

Simple Reverse Proxy + ProxyPass /app ajp://backend.example.com:8009/app +

Balancers may also be used:

Balancer Reverse Proxy - <Proxy balancer://cluster>
- - BalancerMember ajp://app1.example.com:8009 loadfactor=1
- BalancerMember ajp://app2.example.com:8009 loadfactor=2
- ProxySet lbmethod=bytraffic
- - </Proxy>
- ProxyPass /app balancer://cluster/app + +<Proxy balancer://cluster> + BalancerMember ajp://app1.example.com:8009 loadfactor=1 + BalancerMember ajp://app2.example.com:8009 loadfactor=2 + ProxySet lbmethod=bytraffic +</Proxy> +ProxyPass /app balancer://cluster/app +

Note that usually no @@ -85,8 +87,10 @@ original host URL (not the backend ajp:// URL), for example:

Rewriting Proxied Path - ProxyPass /apps/foo ajp://backend.example.com:8009/foo
- ProxyPassReverse /apps/foo http://www.example.com/foo + +ProxyPass /apps/foo ajp://backend.example.com:8009/foo +ProxyPassReverse /apps/foo http://www.example.com/foo +

However, it is usually better to deploy the application on the backend server at the same path as the proxy rather than to take this approach. diff --git a/docs/manual/mod/mod_proxy_balancer.xml b/docs/manual/mod/mod_proxy_balancer.xml index 3520c5bd01..f8f097ec6a 100644 --- a/docs/manual/mod/mod_proxy_balancer.xml +++ b/docs/manual/mod/mod_proxy_balancer.xml @@ -91,31 +91,30 @@ load balancing between two back-end servers:

- - <Proxy balancer://mycluster>
- BalancerMember http://192.168.1.50:80
- BalancerMember http://192.168.1.51:80
- </Proxy>
- ProxyPass /test balancer://mycluster
- ProxyPassReverse /test balancer://mycluster - + +<Proxy balancer://mycluster> + BalancerMember http://192.168.1.50:80 + BalancerMember http://192.168.1.51:80 +</Proxy> +ProxyPass /test balancer://mycluster +ProxyPassReverse /test balancer://mycluster +

Another example of how to provide load balancing with stickyness using mod_headers, even if the back-end server does not set a suitable session cookie:

- - Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" - env=BALANCER_ROUTE_CHANGED
- <Proxy balancer://mycluster>
- BalancerMember http://192.168.1.50:80 route=1
- BalancerMember http://192.168.1.51:80 route=2
- ProxySet stickysession=ROUTEID
- </Proxy>
- ProxyPass /test balancer://mycluster
- ProxyPassReverse /test balancer://mycluster - + +Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED +<Proxy balancer://mycluster> + BalancerMember http://192.168.1.50:80 route=1 + BalancerMember http://192.168.1.51:80 route=2 + ProxySet stickysession=ROUTEID +</Proxy> +ProxyPass /test balancer://mycluster +ProxyPassReverse /test balancer://mycluster +
@@ -188,13 +187,12 @@

To enable load balancer management for browsers from the example.com domain add this code to your httpd.conf configuration file

- - <Location /balancer-manager>
- SetHandler balancer-manager
-
- Require host example.com
- </Location> - + +<Location /balancer-manager> + SetHandler balancer-manager + Require host example.com +</Location> +

You can now access load balancer manager by using a Web browser to access the page diff --git a/docs/manual/mod/mod_proxy_fcgi.xml b/docs/manual/mod/mod_proxy_fcgi.xml index 5de04b121e..ca32557e8c 100644 --- a/docs/manual/mod/mod_proxy_fcgi.xml +++ b/docs/manual/mod/mod_proxy_fcgi.xml @@ -61,7 +61,9 @@ enable mod_proxy and mod_proxy_fcgi.

Single application instance + ProxyPass /myapp/ fcgi://localhost:4000/ +

This application should be able to handle multiple concurrent @@ -76,7 +78,9 @@ the following example:

Single application instance, no connection reuse + ProxyPass /myapp/ fcgi://localhost:4000/ disablereuse=on +

The balanced gateway needs mod_proxy_balancer and @@ -86,13 +90,13 @@ default, and will be used for this example configuration.

Balanced gateway to multiple application instances - ProxyPass /myapp/ balancer://myappcluster/
- <Proxy balancer://myappcluster/>
- - BalancerMember fcgi://localhost:4000/
- BalancerMember fcgi://localhost:4001/
- - </Proxy> + +ProxyPass /myapp/ balancer://myappcluster/ +<Proxy balancer://myappcluster/> + BalancerMember fcgi://localhost:4000/ + BalancerMember fcgi://localhost:4001/ +</Proxy> +
diff --git a/docs/manual/mod/mod_proxy_ftp.xml b/docs/manual/mod/mod_proxy_ftp.xml index 77582e711b..fefed11856 100644 --- a/docs/manual/mod/mod_proxy_ftp.xml +++ b/docs/manual/mod/mod_proxy_ftp.xml @@ -59,7 +59,7 @@

Alternatively you may prefer to default everything to binary:

-
ForceType application/octet-stream
+ ForceType application/octet-stream @@ -100,7 +100,7 @@
How can I hide the FTP cleartext password in my browser's URL line?

To log in to an FTP server by username and password, Apache uses - different strategies. In absense of a user name and password in the URL + different strategies. In absence of a user name and password in the URL altogether, Apache sends an anonymous login to the FTP server, i.e.,

@@ -139,7 +139,7 @@ a base64-encoded cleartext string, and between the Apache proxy and the FTP server as plaintext. You should therefore think twice before accessing your FTP server via HTTP (or before accessing your personal - files via FTP at all!) When using unsecure channels, an eavesdropper + files via FTP at all!) When using insecure channels, an eavesdropper might intercept your password on its way.

diff --git a/docs/manual/mod/mod_proxy_html.xml b/docs/manual/mod/mod_proxy_html.xml index f18a55e39a..41c5ef77ae 100644 --- a/docs/manual/mod/mod_proxy_html.xml +++ b/docs/manual/mod/mod_proxy_html.xml @@ -41,6 +41,43 @@ extensive documentation may be useful to users.

+ +ProxyHTMLMeta +Turns on or off extra pre-parsing of metadata in HTML +<head> sections. +ProxyHTMLMeta On|Off +server config +virtual hostdirectory + +Version 2.4 and later; available as a third-party +module for earlier 2.x versions. + + +

This turns on or off pre-parsing of metadata in HTML + <head> sections.

+

If not required, turning ProxyHTMLMeta Off will give a small + performance boost by skipping this parse step. However, it + is sometimes necessary for internationalisation to work correctly.

+

ProxyHTMLMeta has two effects. Firstly and most importantly + it enables detection of character encodings declared in the form

+ 
<meta http-equiv="Content-Type" content="text/html;charset=foo">
+

or, in the case of an XHTML document, an XML declaration. + It is NOT required if the charset is declared in a real HTTP header + (which is always preferable) from the backend server, nor if the + document is utf-8 (unicode) or a subset such as ASCII. + You may also be able to dispense with it where documents use a + default declared using xml2EncDefault, but that risks propagating an + incorrect declaration. A ProxyHTMLCharsetOut + can remove that risk, but is likely to be a bigger processing + overhead than enabling ProxyHTMLMeta.

+

The other effect of enabling ProxyHTMLMeta is to parse all + <meta http-equiv=...> declarations and convert + them to real HTTP headers, in keeping with the original purpose + of this form of the HTML <meta> element.

+ + + ProxyHTMLEnable Turns the proxy_html filter on or off. diff --git a/docs/manual/mod/mod_proxy_scgi.xml b/docs/manual/mod/mod_proxy_scgi.xml index 4fd0b53250..602c211664 100644 --- a/docs/manual/mod/mod_proxy_scgi.xml +++ b/docs/manual/mod/mod_proxy_scgi.xml @@ -55,7 +55,9 @@ enable mod_proxy and mod_proxy_scgi.

Simple gateway + ProxyPass /scgi-bin/ scgi://localhost:4000/ +

The balanced gateway needs mod_proxy_balancer and @@ -65,13 +67,13 @@ default, and will be used for this example configuration.

Balanced gateway - ProxyPass /scgi-bin/ balancer://somecluster/
- <Proxy balancer://somecluster/>
- - BalancerMember scgi://localhost:4000/
- BalancerMember scgi://localhost:4001/
- - </Proxy> + +ProxyPass /scgi-bin/ balancer://somecluster/ +<Proxy balancer://somecluster/> + BalancerMember scgi://localhost:4000/ + BalancerMember scgi://localhost:4001/ +</Proxy> + @@ -124,11 +126,13 @@ header Example - # Use the default header (X-Sendfile)
- ProxySCGISendfile On
-
- # Use a different header
+ + # Use the default header (X-Sendfile) + ProxySCGISendfile On + + # Use a different header ProxySCGISendfile X-Send-Static + @@ -156,7 +160,9 @@ backend feature.

Example + ProxySCGIInternalRedirect Off + -- 2.40.0