[15/25] git commit: add fwd proxy

[ig...@apache.org]

add fwd proxy


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/bd361e38
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/bd361e38
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/bd361e38

Branch: refs/heads/sphinx-docs
Commit: bd361e388c9ce7452468c8c5b5cfd1d993344934
Parents: 8eb9127
Author: Igor Galić <i....@brainsware.org>
Authored: Thu Mar 14 23:07:55 2013 +0100
Committer: Igor Galić <i....@brainsware.org>
Committed: Thu Mar 14 23:07:55 2013 +0100

----------------------------------------------------------------------
 doc/source/admin/forward-proxy.en.rst |   89 ++++++++++++++++++++++++++++
 1 files changed, 89 insertions(+), 0 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bd361e38/doc/source/admin/forward-proxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/admin/forward-proxy.en.rst b/doc/source/admin/forward-proxy.en.rst
new file mode 100644
index 0000000..1b6c35f
--- /dev/null
+++ b/doc/source/admin/forward-proxy.en.rst
@@ -0,0 +1,89 @@
+:title: Forward Proxy
+
+.. 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.
+
+The Apache Traffic Server is a general purpose *proxy*. As such it can
+also be used as forward proxy.
+
+A forward proxy is can be used as a central tool in your infrastructure
+to access the web. In combination with a cache that means overall
+reduced bandwidth usage.
+
+If your forward proxy is not also configured as `transparent
+proxy <../transparent-proxy>`_ your clients will have to be configured
+to actually use it.
+
+The main difference between a forward and a transparent proxy is that
+User Agents *know* that they are accessing a proxy, thus forming their
+requests like so:
+
+::
+    GET http://example.com/index.php?id=1337 HTTP/1.1
+
+This request, then is translated by the proxy to
+
+::
+    GET /index?id=1337 HTTP/1.1
+    Host: example.com
+
+Apache Traffic Server offers two ways to User Agents: They can either be
+pointed directly to the default ``8080`` port. Alternatively, they can
+be pointed to the more dynamic
+```proxy.config.url_remap.default_to_server_pac`` <../configuration-files/records.config#proxy.config.url_remap.default_to_server_pac>`_
+
+This port will then serve a JavaScript like configuration that User
+Agents can use to determine where to send their requests to.
+
+Configuration # {#configuration}
+================================
+
+In order to configure Apache Traffic Server as forward proxy you will
+have to edit
+```records.config`` <../configuration-files/records.config>`_ and set
+
+-  ``CONFIG``
+   ```proxy.config.url_remap.remap_required`` <../configuration-files/records.config#proxy.config.url_remap.remap_required>`_
+   ``0``
+
+If your proxy is serving as *pure* forward proxy, you will also want to
+set
+
+-  ``CONFIG``
+   ```proxy.config.reverse_proxy.enabled`` <../configuration-files/records.config#proxy.config.reverse_proxy.enabled>`_
+   ``0``
+
+Other configuration variables to consider:
+
+-  ``CONFIG``
+   ```proxy.config.http.no_dns_just_forward_to_parent`` <../configuration-files/records.config#proxy.config.http.no_dns_just_forward_to_parent>`_
+-  ``CONFIG``
+   ```proxy.config.http.forward.proxy_auth_to_parent`` <../configuration-files/records.config#proxy.config.http.forward.proxy_auth_to_parent>`_
+-  ``CONFIG``
+   ```proxy.config.http.insert_squid_x_forwarded_for`` <../configuration-files/records.config#proxy.config.http.insert_squid_x_forwarded_for>`_
+
+Security Considerations
+=======================
+
+It's important to note that once your Apache Traffic Server is
+configured as forward proxy it will indiscriminately accept proxy
+requests from anyone. That means, if it's reachable on the internet, you
+have configured an *Open Proxy*. Most of the time, this is *not* what
+you want, so you'll have to make sure it's either only reachable within
+your NAT or is secured by firewall rules that permit only those clients
+to access it which you want to it to access.
+