You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2013/04/18 11:56:53 UTC
[09/25] git commit: Fix up transparent proxy stuff
Fix up transparent proxy stuff
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/b4f2f94e
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/b4f2f94e
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/b4f2f94e
Branch: refs/heads/sphinx-docs
Commit: b4f2f94e6b0bd92cdf6e112eb652c9798a1f1e46
Parents: 550810a
Author: Igor Galić <i....@brainsware.org>
Authored: Thu Mar 14 22:33:13 2013 +0100
Committer: Igor Galić <i....@brainsware.org>
Committed: Thu Mar 14 22:33:13 2013 +0100
----------------------------------------------------------------------
doc/source/admin/transparent-proxy.en.rst | 6 +
doc/source/admin/transparent-proxy/bridge.en.rst | 203 +++++++++++++++
doc/source/admin/transparent-proxy/build.en.rst | 57 ++++
.../admin/transparent-proxy/router-inline.en.rst | 91 +++++++
.../transparent-proxy/wccp-configuration.en.rst | 154 +++++++++++
5 files changed, 511 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b4f2f94e/doc/source/admin/transparent-proxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/admin/transparent-proxy.en.rst b/doc/source/admin/transparent-proxy.en.rst
index a85a87b..74dbd61 100644
--- a/doc/source/admin/transparent-proxy.en.rst
+++ b/doc/source/admin/transparent-proxy.en.rst
@@ -21,6 +21,12 @@
.. toctree::
:maxdepth: 2
+ transparent-proxy/build.en
+ transparent-proxy/bridge.en
+ transparent-proxy/router-inline.en
+ transparent-proxy/router-inline.en
+ transparent-proxy/wccp-configuration.en
+
Transparent Proxying is the ability of a proxy (such as ATS) to
intercept connections between clients and servers without being visible.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b4f2f94e/doc/source/admin/transparent-proxy/bridge.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/admin/transparent-proxy/bridge.en.rst b/doc/source/admin/transparent-proxy/bridge.en.rst
new file mode 100644
index 0000000..c50e453
--- /dev/null
+++ b/doc/source/admin/transparent-proxy/bridge.en.rst
@@ -0,0 +1,203 @@
+:title: Inline on a Linux Bridge
+
+.. 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.
+
+
+
+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
+interface.
+
+Linux packages required:
+
+- bridge-utils
+- ebtables
+
+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.
+
+::
+
+ brctl addbr br0 # create bridge device
+ brctl stp br0 off # Disable spanning tree protocol
+ brctl addif br0 eth0 # Add eth0 to bridge
+ brctl addif br0 eth1 # Add eth1 to bridge
+
+ ifconfig eth0 0 0.0.0.0 # Get rid of interface IP addresses
+ ifconfig eth1 0 0.0.0.0 # ditto # Set the bridge IP address and enable 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.
+
+::
+
+ ip route add default via 192.168.1.1
+
+At this point it is a good idea to test connectivity to verify the basic
+bridge is functional.
+
+Once the bridge is verified to work, this is the basic traffic pattern
+of interest.
+
+.. figure:: ../_static/images/admin/ats-traffic-bridge.png
+ :align: center
+ :alt: Picture of traffic flow through a bridge with ATS
+
+ Picture of traffic flow through a bridge with ATS
+
+The green arrows are packets originating from the client and the red
+arrows are packets originating from the origin server. All traffic not
+directed to the local address will pass through the bridge. We need to
+break into some of the traffic and subject it to routing so that it can
+be routed to ATS. This requires ``ebtables``. The flows we want to
+intercept are green 1 (from client to bridge) and red 1 (origin server
+to bridge).
+
+In this example we will intercept port 80 (HTTP) traffic. We will use
+the ``BROUTING`` chain because it is traversed only for packets that
+originated externally and arrived on a (forwarding enabled) interface.
+Although it looks like this will intercept all port 80 traffic it will
+only affect the two flows described above. ``-j redirect`` marks the
+packet as being diverted to the bridge and not forwarded, and the
+``DROP`` target puts the packets in the normal ``iptables`` routing so
+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.
+
+::
+
+ ebtables -t broute -F # Flush the table
+ # inbound traffic
+ ebtables -t broute -A BROUTING -p IPv4 --ip-proto tcp --ip-dport 80 \
+ -j redirect --redirect-target DROP
+ # returning outbound traffic
+ ebtables -t broute -A BROUTING -p IPv4 --ip-proto tcp --ip-sport 80 \
+ -j redirect --redirect-target DROP
+
+Traffic Server operates at layer 3 so we need to use ``iptables`` to
+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
+ iptables -t mangle -A PREROUTING -i eth0 -p tcp -m tcp --sport 80 \
+ -j MARK --set-mark 1/1
+
+At this point the directionality of the interfaces matters. For the
+example ``eth1`` is the inbound (client side) interface, while ``eth0``
+is the outbound (origin server side) interface. We mark both flows of
+packets so that we can use policy routing on them. For inbound packets
+we need to use ``TPROXY`` to force acceptance of packets to foreign IP
+addresses. For returning outbound packets there will be a socket open
+bound to the foreign address, we need only force it to be delivered
+locally. The value for ``--on-ip`` is 0 because the target port is
+listening and not bound to a specific address. The value for
+``--on-port`` must match the Traffic Server server port. Otherwise its
+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.
+
+::
+
+ ip rule add fwmark 1/1 table 1
+ ip route add local 0.0.0.0/0 dev lo table 1
+
+The marking used is arbitrary but it must be consistent between
+``iptables`` and the routing rule. The table number must be in the range
+1..253.
+
+To configure Traffic Server set the following values in
+``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: ``=``
+
+``proxy.config.reverse_proxy.enabled``
+ ``INT``
+ Default: ``1``
+
+``proxy.config.url_remap.remap_required``
+ ``INT``
+ Default: ``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).
+
+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
+
+::
+
+ iptables -t filter --flush FORWARD
+ iptables -t filter --flush INPUT
+
+That is a bit drastic and should only be used for testing / debugging. A
+live system will likely need some filters in place but that is beyond
+the scope of this document. If this fixes the problem, then your filter
+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
+
+::
+
+ 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
+
+::
+
+ echo '1' > /proc/sys/net/ipv4/ip_forward
+
+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
+ actual packet processing is identical.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b4f2f94e/doc/source/admin/transparent-proxy/build.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/admin/transparent-proxy/build.en.rst b/doc/source/admin/transparent-proxy/build.en.rst
new file mode 100644
index 0000000..6da480e
--- /dev/null
+++ b/doc/source/admin/transparent-proxy/build.en.rst
@@ -0,0 +1,57 @@
+:title: Building ATS for transparency
+
+.. 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.
+
+
+In most cases, if your environment supports transparency then
+``configure`` will automatically enable it. For other environments you
+may need to twiddle the ``configure`` options.
+
+``--enable-posix-cap``
+ This enables POSIX capabilities, which are required for
+ transparency. These are compiled in by default. To check your
+ system, look for the header file ``sys/capability.h`` and the system
+ library ``libcap``. These are in the packages ``libcap`` and
+ ``libcap-devel`` or ``libcap-dev`` (depending on the Distribution)
+ contra-respectively.
+
+``--enable-tproxy[=value]``
+ Enable TPROXY support, which is the Linux kernel feature used for
+ transparency. This should be present in the base installation, there
+ is no package associated with it. \* ``auto`` Do automatic checks
+ for the the TPROXY header file (``linux/in.h``) and enable TPROXY
+ support if the ``IP_TRANSPARENT`` definition is present. This is the
+ default if this option is not specified or ``value`` is omitted. \*
+ ``no`` Do not check for TPROXY support, disable support for it. \*
+ ``force`` Do not check for TPROXY support, enable it using the $ats@
+ built in value for ``IP_TRANSPARENT``. This is useful for systems
+ that have it in the kernel for but some reason do not have the
+ appropriate system header file. \* *number* Do not check for TPROXY
+ support, use *number* as the ``IP_TRANSPARENT`` value. There are, at
+ present, no known standard distributions of Linux that support
+ TPROXY but use a value different from the built in ATS default.
+ However, a custom built kernel may do so and in that case the
+ specific value can be specified.
+
+In the default case, ATS configuration will automatically check for
+TPROXY support via the presence of the ``linux/in.h`` header file and
+compile in TPROXY support if it is available. If that fails, you may be
+able to recover by using one of the options above. Note that
+transparency may be built in by default but it is not active unless
+explicitly enabled in the ATS configuration files.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b4f2f94e/doc/source/admin/transparent-proxy/router-inline.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/admin/transparent-proxy/router-inline.en.rst b/doc/source/admin/transparent-proxy/router-inline.en.rst
new file mode 100644
index 0000000..1c4003b
--- /dev/null
+++ b/doc/source/admin/transparent-proxy/router-inline.en.rst
@@ -0,0 +1,91 @@
+:title: Inline on a Linux router
+
+.. 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 routed set up presumes the set of clients are on distinct networks
+behind a single physical interface. For the purposes of this example
+will we presume
+
+- The clients are on network 172.28.56.0/24
+- The router connects the networks 172.28.56.0/24 and 192.168.1.0/24
+- Interface ``eth0`` is on the network 192.168.1.0/24
+- Interface ``eth1`` is on the network 172.28.56.0/24
+- The router is already configured to route traffic correctly for the
+ clients.
+
+In this example we will intercept port 80 (HTTP) traffic that traverses
+the router. The first step is to use ``iptables`` to handle IP packets
+appropriately.
+
+::
+
+ # reflow client web traffic to TPROXY
+ 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
+ # Let locally directed traffic pass through.
+ iptables -t mangle -A PREROUTING -i eth0 --source 192.168.56.0/24 -j ACCEPT
+ iptables -t mangle -A PREROUTING -i eth0 --destination 192.168.56.0/24 -j ACCEPT
+ # Mark presumed return web traffic
+ iptables -t mangle -A PREROUTING -i eth0 -p tcp -m tcp --sport 80 -j MARK --set-mark 1/1
+
+We mark packets so that we can use policy routing on them. For inbound
+packets we use ``TPROXY`` to make it possible to accept packets sent to
+foreign IP addresses. For returning outbound packets there will be a
+socket open bound to the foreign address, we need only force it to be
+delivered locally. The value for ``--on-ip`` is 0 because the target
+port is listening and not bound to a specific address. The value for
+``--on-port`` must match the Traffic Server server port. Otherwise its
+value is arbitrary. ``--dport`` and ``--sport`` specify the port from
+the point of view of the clients and origin servers. The middle two
+lines exempt local web traffic from being marked for Traffic Server --
+these rules can be tightened or loosened as needed. They server by
+matching traffic and exiting the ``iptables`` processing via ``ACCEPT``
+before the last line is checked.
+
+Once the flows are marked we can force them to be delivered locally via
+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
+
+The marking used is arbitrary but it must be consistent between
+``iptables`` and the routing rule. The table number must be in the range
+1..253.
+
+To configure Traffic Server set the following values in
+``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: ``=``
+
+``proxy.config.reverse_proxy.enabled``
+ ``INT``
+ Default: ``1``
+
+``proxy.config.url_remap.remap_required``
+ ``INT``
+ Default: ``0``
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b4f2f94e/doc/source/admin/transparent-proxy/wccp-configuration.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/admin/transparent-proxy/wccp-configuration.en.rst b/doc/source/admin/transparent-proxy/wccp-configuration.en.rst
new file mode 100644
index 0000000..7664f90
--- /dev/null
+++ b/doc/source/admin/transparent-proxy/wccp-configuration.en.rst
@@ -0,0 +1,154 @@
+:title: WCCP Configuration
+
+.. 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.
+
+
+.. toctree::
+ :maxdepth: 2
+
+`WCCP <http://cio.cisco.com/en/US/docs/ios/12_0t/12_0t3/feature/guide/wccp.html>`_
+is de-facto semi-standard used by routers to redirect network traffic to
+caches. It is available on most Cisco™ routers although it does not
+appear to be officially supported by Cisco. The primary benefits of WCCP
+are
+
+- If already have a router that supports WCCP inline you do not not
+ have to change your network topology.
+- WCCP fails open so that if the Traffic Server machine fails, it is
+ bypassed and users continue to have Internet access.
+
+Use of WCCP only makes sense for client side transparency [1]_(#1)
+because if the clients are explicitly proxied by Traffic Server there's
+no benefit to WCCP fail open, as the clients will continue to directly
+access the unresponsive Traffic Server host. It would be better to
+adjust the routing tables on the router for explicit proxying.
+
+Because the router serves as the inline network element, Traffic Server
+must run on a separate host. This host can be located anywhere as long
+as Traffic Server is either on the same network segment or a GRE tunnel
+can be maintained between the Traffic Server host and the router.
+
+|important| This document presumes that the router is already properly
+configured to handle traffic between the clients and the origin servers.
+If you are not certain, verify it before attempting to configure Traffic
+Server with WCCP. This is also a good state to which to revert should
+the configuration go badly.
+
+Configuration overview
+======================
+
+Setting WCCP is a three step process, first configuring the router, the
+Traffic Server host, and Traffic Server.
+
+|image1| The router will **not** respond to WCCP protocol packets unless
+explicitly configured to do so. Via WCCP, the router can be made to
+perform packet interception and redirection needed by Traffic Server
+transparency. The WCCP protocol in effect acts as means of controlling a
+rough form of policy routing with positive heartbeat cutoff.
+
+The Traffic Server host system must also be configured using
+``iptables`` to accept connections on foreign addresses. This is done
+roughly the same way as the standard transparency use.
+
+Finally Traffic Server itself must be configured for transparency and
+use of WCCP. The former is again very similar to the standard use, while
+WCCP configuration is specific to WCCP and uses a separate configuration
+file, referred to by the ``records.config`` file.
+
+The primary concern for configuration in which of three basic topologies
+are to be used.
+
+- Dedicated -- Traffic Server traffic goes over an interface that is
+ not used for client nor origin server traffic.
+- Shared -- Traffic Server traffic shares an interface with client or
+ server traffic.
+- Inside Shared -- Traffic Server and client traffic share an
+ interface.
+- `Outside Shared <wccp-outside-shared.html>`_ -- Traffic Server and
+ origin server traffic share an interface.
+
+In general the dedicated topology is preferred. However, if the router
+has only two interfaces one of the shared topologies will be
+required [2]_(#2). Click the links above for more detailed configuration
+information on a specific topology.
+
+Shared interface issues
+-----------------------
+
+A shared interface topology has additional issues compared to a
+dedicated topology that must be handled. Such a topology is required if
+the router has only two interfaces, and because of these additional
+issues it is normally only used in such cases, although nothing prevents
+it use even if the router has three or more interfaces.
+
+The basic concept for a shared interface is to use a tunnel to simulate
+the dedicated interface case. This enables the packets to be
+distinguished at layer 3. For this reason, layer 2 redirection cannot be
+used because the WCCP configuration cannot distinguish between packets
+returning from the origin server and packets returning from Traffic
+Server as they are distinguished only by layer 2 addressing [3]_(#3).
+Fortunately the GRE tunnel used for packet forwarding and return can be
+used as the simulated interface for Traffic Server.
+
+Frequently encountered problems
+-------------------------------
+
+MTU and fragmentation
+~~~~~~~~~~~~~~~~~~~~~
+
+In most cases the basic configuration using a tunnel in any topology can
+fail due to issues with fragmentation. The socket logic is unable to
+know that its packets will eventually be put in to a tunnel which will
+by its nature have a smaller
+`MTU <http://en.wikipedia.org/wiki/Maximum_transmission_unit>`_ than the
+physical interface which it uses. This can lead to pathological behavior
+or outright failure as the packets sent are just a little too big. It is
+not possible to solve easily by changing the MTU on the physical
+interface because the tunnel interface uses that to compute its own MTU.
+
+References
+==========
+
+- `WCCP Router Configuration Commands - IOS
+ 12.2 <http://www.cisco.com/en/US/docs/ios/12_2/configfun/command/reference/frf018.html>`_
+
+
+
+
+
+
+
+
+.. [1]
+ Server side transparency should also be used, but it is not as
+ significant. In its absence, however, origin servers may see the
+ source address of connections suddenly change from the Traffic Server
+ address to client addresses, which could cause problems. Further, the
+ primary reason for not having server side transparency is to hide
+ client addresses which is defeated if the Traffic Server host fails.
+
+.. [2]
+ If your router has only one interface, it's hardly a *router*.
+
+.. [3]
+ This is not fundamentally impossible, as the packets are distinct in
+ layer
+
+.. |important| image:: ../_static/images/docbook/important.png
+.. |image1| image:: ../_static/images/docbook/important.png
+