Updated Branches: refs/heads/master a9ca0bbb3 -> 2b91482fe
Fixing links and formatting in Forward/transparent Proxy docs. I am leaving the bigger part of the transparent-proxy docs for amc as there have been a number of changes to the code, which will need deeper reviews of this than I have the capacity for. Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/3e6b316d Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/3e6b316d Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/3e6b316d Branch: refs/heads/master Commit: 3e6b316d6fe06fb91679c27eb150da3bb007818a Parents: a9ca0bb Author: Igor GaliÄ <[email protected]> Authored: Sun Aug 18 21:15:19 2013 +0200 Committer: Igor GaliÄ <[email protected]> Committed: Sun Aug 18 21:15:19 2013 +0200 ---------------------------------------------------------------------- doc/admin/forward-proxy.en.rst | 36 ++++-------- doc/admin/transparent-proxy.en.rst | 8 ++- doc/admin/transparent-proxy/bridge.en.rst | 62 +++++--------------- doc/admin/transparent-proxy/build.en.rst | 2 + .../configuration/records.config.en.rst | 6 ++ 5 files changed, 42 insertions(+), 72 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/3e6b316d/doc/admin/forward-proxy.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/forward-proxy.en.rst b/doc/admin/forward-proxy.en.rst index cc606d0..e130c73 100644 --- a/doc/admin/forward-proxy.en.rst +++ b/doc/admin/forward-proxy.en.rst @@ -1,3 +1,5 @@ +.. _forward-proxy: + Forward Proxy ************* @@ -25,27 +27,23 @@ 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. +If your forward proxy is not also configured as :ref:`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: +requests like so: :: -:: GET http://example.com/index.php?id=1337 HTTP/1.1 -This request, then is translated by the proxy to +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>`_ +be pointed to the more dynamic :ts:cv:`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. @@ -54,28 +52,20 @@ Configuration ============= In order to configure Apache Traffic Server as forward proxy you will -have to edit -`:file:`records.config` <../configuration-files/records.config>`_ and set +have to edit `:file:`records.config` and set -- ``CONFIG`` - ```proxy.config.url_remap.remap_required`` <../configuration-files/records.config#proxy.config.url_remap.remap_required>`_ - ``0`` +- :ts:cv:`proxy.config.url_remap.remap_required` to ``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`` +- :ts:cv:`proxy.config.reverse_proxy.enabled` to ``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>`_ +- :ts:cv:`proxy.config.http.no_dns_just_forward_to_parent` +- :ts:cv:`proxy.config.http.forward.proxy_auth_to_parent` +- :ts:cv:`proxy.config.http.insert_squid_x_forwarded_for` Security Considerations ======================= http://git-wip-us.apache.org/repos/asf/trafficserver/blob/3e6b316d/doc/admin/transparent-proxy.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/transparent-proxy.en.rst b/doc/admin/transparent-proxy.en.rst index e32f91d..750fdf4 100644 --- a/doc/admin/transparent-proxy.en.rst +++ b/doc/admin/transparent-proxy.en.rst @@ -1,3 +1,5 @@ +.. _transparent-proxy: + Transparent Proxying ******************** @@ -64,7 +66,7 @@ proxy, i.e. a connection initiated by the proxy to an origin server In most treatments these two types of transparency are treated as unitarily but that is not required. This implementation supports transparency independently on the two (client, origin server) sides -(`use cases <half-transparency-use-cases>`_). +(`use cases <half-transparency-use-cases>`_. It is critical to note that any transparency requires specialized routing and cannot be done solely by configuring ATS. ATS transparency @@ -79,10 +81,10 @@ In addition the specialized routing will require using ``iptables`` and in some cases ``ebtables``. Standard build procedures should work for transparency support but if -not consult these `more detailed instructions <build>`_ +not consult these :ref:`more detailed instructions <building-ats-for-transparency>` Transparency is configured per server port not globally. This is done -via the configuration values ``proxy.config.http.server_port_attr``. +via the configuration values :ts:cv:`proxy.config.http.server_ports`. In addition, :ts:cv:`proxy.config.reverse_proxy.enabled` must be enabled if the client side is transparent. That should be fixed in a future patch. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/3e6b316d/doc/admin/transparent-proxy/bridge.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/transparent-proxy/bridge.en.rst b/doc/admin/transparent-proxy/bridge.en.rst index 2341422..45d0074 100644 --- a/doc/admin/transparent-proxy/bridge.en.rst +++ b/doc/admin/transparent-proxy/bridge.en.rst @@ -20,8 +20,7 @@ Inline on a Linux Bridge -A Linux can be configured to operate in `*bridge -mode* <http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge>`_. +A Linux can be configured to operate in `bridge mode <http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge>`_. Two or more physical interfaces are assigned to the bridge. A single IP address is shared across the interfaces. By default any packet that arrives on one interface is immediately routed out another bridge @@ -36,9 +35,7 @@ In our example of setting up bridge mode we will use a local address of 192.168.1.11/24 and interfaces ``eth0`` and ``eth1`` as the bridge interfaces (more detailed documentation is available `here <http://www.tldp.org/HOWTO/BRIDGE-STP-HOWTO/preparing-the-bridge.html>`_). -You may omit the '#' character and everything after it. - -:: +You may omit the '#' character and everything after it.:: brctl addbr br0 # create bridge device brctl stp br0 off # Disable spanning tree protocol @@ -50,9 +47,7 @@ You may omit the '#' character and everything after it. ifconfig br0 192.168.1.11 netmask 255.255.255.0 up If you have not already done so, remember to add a default route, such -as this one for a gateway of 192.168.1.1. - -:: +as this one for a gateway of 192.168.1.1.:: ip route add default via 192.168.1.1 @@ -86,9 +81,7 @@ packet as being diverted to the bridge and not forwarded, and the that we can use standard device tests on them [1]_(#1). Although this example handles only port 80, other ports are the same except for the port value. Note also the port here is the port from the point of view -of the clients and origin servers, not the Traffic Server server port. - -:: +of the clients and origin servers, not the Traffic Server server port.:: ebtables -t broute -F # Flush the table # inbound traffic @@ -99,9 +92,7 @@ of the clients and origin servers, not the Traffic Server server port. -j redirect --redirect-target DROP Traffic Server operates at layer 3 so we need to use ``iptables`` to -handle IP packets appropriately. - -:: +handle IP packets appropriately.:: iptables -t mangle -A PREROUTING -i eth1 -p tcp -m tcp --dport 80 \ -j TPROXY --on-ip 0.0.0.0 --on-port 8080 --tproxy-mark 1/1 @@ -122,9 +113,7 @@ value is arbitrary. ``--dport`` and ``--sport`` specify the port from the point of view of the clients and origin servers. Once the flows are marked we can force them to be delivered locally via -the loopback interface via a policy routing table. - -:: +the loopback interface via a policy routing table.:: ip rule add fwmark 1/1 table 1 ip route add local 0.0.0.0/0 dev lo table 1 @@ -136,26 +125,14 @@ The marking used is arbitrary but it must be consistent between To configure Traffic Server set the following values in :file:`records.config` -``proxy.config.http.server_port`` - ``STRING`` - Default: *value from* ```--on-port`` <#on_port>`_ - -proxy.config.http.server_port_attr -{#proxy.config.http.server_port_attr} - ``STRING`` - Default: ``=`` +- :ts:cv:`proxy.config.http.server_ports` *value from* ``--on-port`` (see below) -``proxy.config.reverse_proxy.enabled`` - ``INT`` - Default: ``1`` +- :ts:cv:`proxy.config.reverse_proxy.enabled` ``1`` -``proxy.config.url_remap.remap_required`` - ``INT`` - Default: ``0`` +- :ts:cv:`proxy.config.url_remap.remap_required` ``0`` -You may also need to set ``proxy.config.cluster.ethernet_interface`` to -"br0" (the name of the bridge interface from the -```brctl`` <#bridge_commands>`_ command). +You may also need to set :ts:cv:`proxy.config.cluster.ethernet_interface` to +"br0" (the name of the bridge interface from the `<Bridge Commands>`_). Additional troubleshooting ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -163,9 +140,7 @@ Additional troubleshooting * Check to make sure that ``iptables`` is not filtering (blocking) incoming HTTP connections. It is frequently the case that the default tables prevent incoming HTTP. You can clear all filters with the -commands - -:: +commands:: iptables -t filter --flush FORWARD iptables -t filter --flush INPUT @@ -178,26 +153,21 @@ set is too restrictive. Note that this problem will prevent the basic bridge (without ATS) from allowing HTTP traffic through. -* Verify that IP packet forwarding is enabled. You can check this with - -:: +* Verify that IP packet forwarding is enabled. You can check this with:: cat /proc/sys/net/ipv4/ip_forward The output should be a non-zero value (usually '1'). If it is zero, you -can set it with - -:: +can set it with:: echo '1' > /proc/sys/net/ipv4/ip_forward -This can setting can be persisted by putting it in ``/etc/sysctl.conf``: - -:: +This can setting can be persisted by putting it in ``/etc/sysctl.conf``: :: net/ipv4/ip_forward=1 + .. [1] The ``--redirect-target`` can be omitted, but then the ``iptables`` rules would need to use ``--physdev`` instead of just ``-i``. The http://git-wip-us.apache.org/repos/asf/trafficserver/blob/3e6b316d/doc/admin/transparent-proxy/build.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/transparent-proxy/build.en.rst b/doc/admin/transparent-proxy/build.en.rst index 8200f80..e547a06 100644 --- a/doc/admin/transparent-proxy/build.en.rst +++ b/doc/admin/transparent-proxy/build.en.rst @@ -1,3 +1,5 @@ +.. _building-ats-for-transparency: + Building ATS for transparency ***************************** http://git-wip-us.apache.org/repos/asf/trafficserver/blob/3e6b316d/doc/reference/configuration/records.config.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst index 669b0a6..64eacd9 100644 --- a/doc/reference/configuration/records.config.en.rst +++ b/doc/reference/configuration/records.config.en.rst @@ -608,6 +608,11 @@ Parent Proxy Configuration Configures Traffic Server to send proxy authentication headers on to the parent cache. +.. ts:cv:: CONFIG proxy.config.http.no_dns_just_forward_to_parent INT 0 + :reloadable: + + Don't try to resolve DNS, forward all DNS requests to the parent. This is off (``0``) by default. + HTTP Connection Timeouts ======================== @@ -814,6 +819,7 @@ Proxy User Variables This is useful for minimizing cached alternates of documents (e.g. ``gzip, deflate`` vs. ``deflate, gzip``). Enabling this option is recommended if your origin servers use no encodings other than ``gzip``. + Security ========
