[prev in list] [next in list] [prev in thread] [next in thread]
List: apache-docs
Subject: Re: balancer-manager docs
From: Tim Bannister <isoma () c8h10n4o2 ! org ! uk>
Date: 2016-02-14 18:43:10
Message-ID: 3A80634B-32DC-41A6-B41B-054A508EA4DA () c8h10n4o2 ! org ! uk
[Download RAW message or body]
On 9 Feb 2016, at 17:55, Tim Bannister <isoma@c8h10n4o2.org.uk> wrote:
>
> The module pages can document the module; I think that's appropriate for reference \
> documentation.
> What's missing is more of a "how do I set up X" guide. I think the topics could be:
>
> • forward proxy (and access control) with or without cacheing
> • reverse proxy with or without cacheing
> • balancing and high availability for reverse proxies
>
> I think this is me volunteering to at least draft some text, if people agree this \
> approach makes sense.
Draft attached. I hope it's useful.
I've not been able to get the docs build to work (having only tried it today), and my \
limited previous experience with Ant makes me suspect if it's not a quick fix it's \
going to be a much longer haul. I know the XML is valid, I don't know what it might \
look like post-transformation.
Also, there is no images/forward-proxy-arch.svg – I just put that in as a \
placeholder.
Tim
["forward_proxy.xml" (forward_proxy.xml)]
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision: 1673932 $ -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<manualpage metafile="forward_proxy.xml.meta">
<parentdocument href="./">How-To / Tutorials</parentdocument>
<title>Forward Proxy Guide</title>
<summary>
<note type="warning"><title>Warning</title>
<p>Do not enable proxying with <directive module="mod_proxy"
>ProxyRequests</directive> until you have <a href="#access"
>secured your server</a>. Open proxy servers are dangerous both to your
network and to the Internet at large.</p>
</note>
<p>Apache httpd can act as a web proxy server <dfn>forward proxy</dfn>.
A typical usage of a forward proxy is to provide Internet access to
internal clients on private networks or that are otherwise restricted
by a firewall. The forward proxy can also use caching (as provided by
<module>mod_cache</module>) to reduce network usage.</p>
<p>When using a forward proxy, the client must be specially configured to use
the proxy to access other sites. The web client makes a connection to the proxy
server and makes its request. The proxy server can parse the request and then,
rather than fulfilling the request directly, will send a similar request on to
the webserver that actually hosts the resource (the <dfn>origin \
server</dfn>).</p>
<p>In some cases, there will be a chain of web proxies. For example, a private
network of an international organisation. The client wishes to <code>GET</code> \
the resource at <code>http://www.apache.org/</code> and to do this it sends an HTTP \
request message to the web proxy for the local office (eg \
canada-proxy.example.com). canada-proxy also does not have direct access to the \
public internet, and so canada-proxy makes a request to \
external-gateway.example.com on behalf of the original client. external-gateway is \
now able to connect to the origin server and fetch \
<code>http://www.apache.org/</code></p>
<p>After the origin server responds, external-gateway sends on the response to
canada-proxy; canada-proxy repeats that response to the original client, and
the whole process is complete, as shown in the following illustration:</p>
<p class="centered"><img src="../images/forward-proxy-arch.svg" alt="Example of \
forward web proxying" /></p>
<p>Using a web proxy in this way is one of several options. There are other
ways to enable hosts on private networks to access public web services; two
common solutions are Network Address Translation (NAT), and SOCKS.</p>
<p>A forward web proxy can be misused. Before enabling forward web proxying,
consider how you will restrict access to this service. The
<a href="access.html">Access Control</a> howto discusses the
various ways to control access to your server.</p>
</summary>
<section id="related">
<title>Forward Proxy</title>
<related>
<modulelist>
<module>mod_proxy</module>
<module>mod_proxy_http</module>
<module>mod_proxy_connect</module>
<module>mod_cache</module>
<module>mod_cache_disk</module>
</modulelist>
<directivelist>
<directive module="mod_proxy">ProxyRequests</directive>
<directive module="mod_proxy">ProxyVia</directive>
<directive module="mod_cache">CacheEnable</directive>
</directivelist>
</related>
</section>
<section id="basic">
<title>Basic forward proxying</title>
<p>
The <directive module="mod_proxy">ProxyRequests</directive>
directive enables the forward-proxy function in Apache httpd.
A basic proxy which only allows access from the local host.
</p>
<highlight language="config">
ProxyRequests On
<Proxy *>
Require local
</Proxy>
</highlight>
<p>If a remote host attempts to use your forward proxy, Apache httpd
would deny access and return a <code>403</code> (Forbidden) status.</p>
<p>
The <code>Via:</code> header is useful to allow extra diagnostics. All
that it will reveal to the origin server (or upstream proxy) is the hostname
of your proxy and the fact that a proxy was used. By default, <code>Via:</code>
is not added. To enable this, add:
</p>
<highlight language="config">
ProxyVia On
</highlight>
</section>
<section>
<title>Web proxy with cache</title>
<p>If several hosts share the same proxy, and are likely to make similar
requests, adding a cache can improve performance. For example, a number
of computers in an office that fetch software updates every morning from
the same server. Using a cache can save time and avoid downloading the
same software update repeatedly.</p>
<highlight language="config">
<IfModule mod_cache_disk>
CacheQuickHandler off
CacheRoot /var/cache/webproxy
CacheEnable disk http://
CacheMinFileSize 4000
CacheMaxExpire 1209600 # 14 days
</IfModule>
</highlight>
<p>When using <module>mod_cache_disk</module>, use the tool
<program>htcacheclean</program> to manage the size of the disk cache.
If you installed Apache httpd from a distribution's package,
<program>htcacheclean</program> may have been automatically started when
you enabled <module>mod_cache_disk</module>. If not, you should set up
your own configuration to ensure that cache cleaning takes place regularly.</p>
<p><strong>Note</strong> that cleaning always happens <em>after</em> the data \
have been
written into the disk cache folder. Between request processing and the next
<program>htcacheclean</program> pass, more storage / inodes may be used
than the limits configured with <code>-l</code> and <code>-L</code>. The
proxy's behaviour will not be affected; however, the filesystem containing
/var/cache/webproxy could become temporarily full.</p>
<p>In this example, it would be a good idea to set a system level storage
limit on <code>/var/cache/webproxy</code>, or to make
<code>/var/cache/webproxy</code> its own fixed-size filesystem.</p>
<p>For a shared-cache forward proxy, consider enabling the
<directive module="mod_cache" type="section">CacheLock</directive> directive,
which helps to avoid <em>thundering herd</em> effects: when many clients
perform the same request, <module>mod_cache</module> will only attempt to cache
it once.</p>
</section>
<section>
<title>Forward proxying and HTTPS</title>
<p>HTTPS is HTTP over TLS, which provides confidentiality and integrity
protection. HTTPS prevents a <em>man-in-the-middle</em> attack by having
the server use a certificate to prove its identity to the client.</p>
<p>Using a forward proxy as described above would not work for HTTPS:
the proxy effectively is a box-in-the-middle, able to read or even alter
the traffic passing through it.</p>
<p>Client hosts can use the <code>CONNECT</code> method to access HTTPS
origin servers using a web proxy to establish a TCP tunnel connection.
This enables the client host to access a server that it cannot otherwise
reach (eg because the client host's direct access to the internet is
blocked or filtered).</p>
<p>This functionality requires <module>mod_proxy_connect</module> to be
loaded, and will then be available automatically. The web proxy does not
require SSL / TLS support.</p>
<note type="warning"><title>CONNECT and non-HTTPS traffic</title>
<p>Although the <code>CONNECT</code> method is typically used to enable access \
to HTTPS web sites, it can also be misused. Check the section on how to
<a href="#access">secure your server</a>.</p>
</note>
</section>
<section id="access"><title>Controlling Access to Your Proxy</title>
<p>You can control who can access your proxy via the <directive
module="mod_proxy" type="section">Proxy</directive> control block as in
the following example, which restricts forward proxy use to hosts with
IPv4 network addresses in the range 198.51.100.128 to 198.51.100.190</p>
<highlight language="config">
<Proxy *>
Require ip 198.51.100.128/26
</Proxy>
</highlight>
<p>For more information on access control directives, see
the <a href="access.html">Access Control</a> howto.</p>
<p>Strictly limiting access is essential if you are using a
forward proxy.
Otherwise, your server can be used by any client to access
arbitrary hosts while hiding his or her true identity. This is
dangerous both for your network and for the Internet at large.</p>
<p><strong>See Also</strong> the <a href="../mod/mod_proxy_http.html#env"
>Proxy-Chain-Auth</a> environment variable.</p>
<p>Because TLS traffic is encrypted, the <code>CONNECT</code> method \
establishes a
simple tunnel that can be carry other kinds of data. If, for example,
your organisation uses a firewall to prevent SMTP traffic on TCP port
25, be wary that your web proxy cannot be used to bypass this.</p>
<p>The <directive module="mod_proxy_connect" \
type="section">AllowCONNECT</directive>
directive specifies which TCP ports are valid for a <code>CONNECT</code> verb \
in an HTTP request. The default setting allows access to HTTPS and SNEWS;
operators may wish to restrict this just to HTTPS:</p>
<highlight language="config">
ProxyRequests On
…
AllowCONNECT 443
</highlight>
<p>HTTPS connections through a proxy can be restricted by matching on the
port, for example:</p>
<highlight language="config">
<Proxy *:443>
Require ip 198.51.100.128/26
</Proxy>
</highlight>
</section> <!-- /access -->
</manualpage>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic