From 3c1d85b82acb55476844e7656a6bad137dcae9af Mon Sep 17 00:00:00 2001
From: Daniel Gruno
Date: Fri, 27 Apr 2012 05:03:19 +0000
Subject: [PATCH] Syntax updates for mod_p*.xml
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1331217 13f79535-47bb-0310-9956-ffa450edef68
---
docs/manual/mod/mod_policy.xml | 172 ++++++++-------
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 | 2 +-
docs/manual/mod/mod_proxy_scgi.xml | 28 ++-
7 files changed, 299 insertions(+), 281 deletions(-)
diff --git a/docs/manual/mod/mod_policy.xml b/docs/manual/mod/mod_policy.xml
index dbd905a394a..e0c35639f3d 100644
--- a/docs/manual/mod/mod_policy.xml
+++ b/docs/manual/mod/mod_policy.xml
@@ -193,50 +193,44 @@
A typical configuration protecting a server serving static content
might be as follows:
-
- <Location />
-
- SetOutputFilter POLICY_TYPE;POLICY_LENGTH;POLICY_KEEPALIVE;POLICY_VARY;POLICY_VALIDATION; \
-
- POLICY_CONDITIONAL;POLICY_NOCACHE;POLICY_MAXAGE;POLICY_VERSION
-
-
- # content type must be present and valid, but can be anything
- PolicyType enforce */*
-
- # reject if no explicitly declared content length
- PolicyLength enforce
-
- # covered by the policy length filter
- PolicyKeepalive ignore
-
- # reject if User-Agent appears within Vary headers
- PolicyVary enforce User-Agent
-
- # we want to enforce validation
- PolicyValidation enforce
-
- # non-functional conditional responses should be rejected
- PolicyConditional enforce
-
- # no-cache responses should be rejected
- PolicyNocache enforce
-
- # maxage must be at least a day
- PolicyMaxage enforce 86400
-
- # request version can be anything
- PolicyVersion ignore HTTP/1.1
-
- </Location>
-
- # suppress policy protection for server-status
- <Location /server-status>
-
- PolicyFilter off
-
- </Location>
-
+
+<Location />
+ SetOutputFilter POLICY_TYPE;POLICY_LENGTH;POLICY_KEEPALIVE;POLICY_VARY;POLICY_VALIDATION; \
+ POLICY_CONDITIONAL;POLICY_NOCACHE;POLICY_MAXAGE;POLICY_VERSION
+
+ # content type must be present and valid, but can be anything
+ PolicyType enforce */*
+
+ # reject if no explicitly declared content length
+ PolicyLength enforce
+
+ # covered by the policy length filter
+ PolicyKeepalive ignore
+
+ # reject if User-Agent appears within Vary headers
+ PolicyVary enforce User-Agent
+
+ # we want to enforce validation
+ PolicyValidation enforce
+
+ # non-functional conditional responses should be rejected
+ PolicyConditional enforce
+
+ # no-cache responses should be rejected
+ PolicyNocache enforce
+
+ # maxage must be at least a day
+ PolicyMaxage enforce 86400
+
+ # request version can be anything
+ PolicyVersion ignore HTTP/1.1
+</Location>
+
+# suppress policy protection for server-status
+<Location /server-status>
+ PolicyFilter off
+</Location>
+
@@ -255,19 +249,17 @@ later.
Master switch to enable or disable policies for a given URL space.
Example
- # enabled by default
- <Location />
-
- PolicyFilter on
-
- </Location>
-
- # suppress policy protection for server-status
- <Location /server-status>
-
- PolicyFilter off
-
- </Location>
+
+# enabled by default
+<Location />
+ PolicyFilter on
+</Location>
+
+# suppress policy protection for server-status
+<Location /server-status>
+ PolicyFilter off
+</Location>
+
@@ -292,8 +284,10 @@ later.
be ignored.
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:
- 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
- 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:
- In the last example, the proxy will forward FTP requests, encapsulated
@@ -697,30 +691,28 @@ expressions
ProxyPass directive.
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 below is the 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 10f25ccdbf4..ad604f875c8 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 3520c5bd013..f8f097ec6a2 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 5de04b121ef..ca32557e8c8 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 7a7c7b19f6b..fefed11856e 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
diff --git a/docs/manual/mod/mod_proxy_scgi.xml b/docs/manual/mod/mod_proxy_scgi.xml
index 4fd0b532505..602c211664b 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.47.3