Skip to content
This repository
Browse code

Add README from balabit.com - it's nice doc about TPROXY.

  • Loading branch information...
commit 778340243e09c53e73573e5e08268b9b75abfce0 1 parent 0a491b0
Leonid Evdokimov authored December 04, 2012

Showing 1 changed file with 235 additions and 0 deletions. Show diff stats Hide diff stats

  1. 235  doc/balabit-TPROXY-README.txt
235  doc/balabit-TPROXY-README.txt
... ...
@@ -0,0 +1,235 @@
  1
+
  2
+These are the Transparent Proxying patches for Linux kernel 2.6.
  3
+
  4
+The latest version can always be found at
  5
+
  6
+  http://www.balabit.com/download/files/tproxy/
  7
+
  8
+
  9
+What does the term 'proxy' mean?
  10
+--------------------------------
  11
+
  12
+   A proxy is a server-like program, receiving requests from clients,
  13
+   forwarding those requests to the real server on behalf of users,
  14
+   and returning the response as it arrives.
  15
+
  16
+   Proxies read and parse the application protocol, and reject invalid
  17
+   traffic. As most attacks violate the application protocol, disallowing
  18
+   protocol violations usually protects against attacks.
  19
+
  20
+What is transparent proxying?
  21
+-----------------------------
  22
+
  23
+   To simplify management tasks of clients sitting behind proxy
  24
+   firewalls, the technique 'transparent proxying' was invented.
  25
+   Transparent proxying means that the presence of the proxy is invisible
  26
+   to the user. Transparent proxying however requires kernel support.
  27
+
  28
+We have a 'REDIRECT' target, isn't that enough?
  29
+----------------------------------------------
  30
+
  31
+   Real transparent proxying requires the following three features from
  32
+   the IP stack of the computer it is running on:
  33
+    1. Redirect sessions destined to the outer network to a local process
  34
+       using a packet filter rule.
  35
+    2. Make it possible for a process to listen to connections on a
  36
+       foreign address.
  37
+    3. Make it possible for a process to initiate a connection with a
  38
+       foreign address as a source.
  39
+
  40
+   Item #1 is usually provided by packet filtering packages like
  41
+   Netfilter/IPTables, IPFilter. (yes, this is the REDIRECT target)
  42
+
  43
+   All three were provided in Linux kernels 2.2.x, but support for this
  44
+   was removed.
  45
+
  46
+How to install it?
  47
+------------------
  48
+
  49
+   Download the latest tproxy-kernel-<kernelversion>*.tar.bz2 tarball
  50
+   for your kernel (from v2.6.24),  with the tproxy-iptables-*.patch file.
  51
+   
  52
+   Patch your kernel using:
  53
+
  54
+      cd /usr/src/linux
  55
+      cat <path_to_tproxy>/00*.patch | patch -p1
  56
+
  57
+   then enable tproxy support, `socket' and `TPROXY' modules
  58
+   (with optional conntrack support if you need SNAT), compile your kernel
  59
+   and  modules.
  60
+
  61
+   The required modules are automatically loaded if the iptables commands
  62
+   are used.
  63
+
  64
+   The IPtables patches:
  65
+
  66
+      cd /usr/src/iptables-1.4.X
  67
+      cat <path_to_tproxy>/tproxy-iptables*.patch | patch -p1
  68
+  
  69
+   then compile it on the usual way:
  70
+ 
  71
+      ./autogen.sh
  72
+      ./configure && make && make install
  73
+
  74
+   Squid-3 has official support of TProxy v4.1:
  75
+
  76
+   checkout the source code of squid-3 as in
  77
+  
  78
+      http://wiki.squid-cache.org/Squid3VCS
  79
+
  80
+
  81
+   then compile it:
  82
+
  83
+      cd ~/source/squid
  84
+      ./bootstrap.sh
  85
+      ./configure --enable-linux-netfilter && make && make install
  86
+ 
  87
+   Of course you might need to change the path in the examples above.
  88
+
  89
+How to start using it?
  90
+----------------------
  91
+
  92
+   This implementation of transparent proxying works by marking packets and
  93
+   changing the route based on packet mark. The foreign address bind and tproxy 
  94
+   redirection is enabled via a new socket option, IP_TRANSPARENT, without it
  95
+   neither the bind nor the tproxy target works.
  96
+
  97
+   Now let's see what happens when a proxy tries to use the required tproxy
  98
+   features I outlined earlier.
  99
+
  100
+   1. Redirection
  101
+
  102
+     This is easy, as this was already supported by iptables. Redirection is
  103
+     equivalent with the following nat rule:
  104
+
  105
+       iptables -t nat -A PREROUTING -j DNAT --to-dest <localip> --to-port <proxyport>
  106
+
  107
+         <localip>   is one the IP address of the interface where the packet
  108
+                     entered the IP stack
  109
+         <proxyport> is the port where the proxy was bound to
  110
+
  111
+     To indicate that this is not simple NAT rule, a separate target, 'TPROXY'
  112
+     was created:
  113
+
  114
+       iptables -t mangle -A PREROUTING -p tcp --dport 80 -j TPROXY --on-port <proxyport>  \
  115
+              --tproxy-mark 0x1/0x1
  116
+
  117
+     The local IP address is determined automatically, but can be overridden
  118
+     by the --on-ip parameter.
  119
+
  120
+     The marked sockets has to be routed locally:
  121
+
  122
+        ip rule add fwmark 1 lookup 100
  123
+        ip route add local 0.0.0.0/0 dev lo table 100
  124
+
  125
+
  126
+   2. Listening for connections on a foreign address
  127
+
  128
+     There are protocols which use more than a single TCP channel for
  129
+     communication. The best example is FTP which uses a command channel for
  130
+     sending commands, and a data channel to transfer the body of files. The
  131
+     secondary channel can be established in both active and passive mode, 
  132
+     active meaning the server connects back to the client, passive meaning
  133
+     the client connects to the server on another port.
  134
+
  135
+     Let's see the passive case, when the client establishes a connection to
  136
+     the address returned in the response of the PASV FTP command.
  137
+
  138
+     As the presence of the proxy is transparent to the client, the target
  139
+     IP address of the secondary channel (e.g. the address in the PASV
  140
+     response) is the server (and not the firewall) and this connection must
  141
+     also be handled by the proxy. 
  142
+
  143
+     The first solution that comes to mind is to add a a TPROXY rule
  144
+     automatically (e.g. to redirect a connection destined to a given server
  145
+     on a given port to a local process), however it is not feasible, adding
  146
+     rules on the fly should not be required as it would mess the
  147
+     administrator's own rules, the NAT translation should be done
  148
+     implicitly without touching the user rulebase.
  149
+
  150
+     To do this on a Linux 2.2 kernel it was enough to call bind() on a
  151
+     socket with a foreign IP address, and if a new connection to the given
  152
+     foreign IP was routed through the firewall the connection was
  153
+     intercepted. This solution however distracted the core network kernel
  154
+     hackers and removed this feature. This implementation is similar to
  155
+     the old behaviour although it works a bit differently:
  156
+
  157
+       * the proxy sets the IP_TRANSPARENT socket option on the listening
  158
+         socket
  159
+       * the proxy then binds to the foreign address
  160
+       * the proxy accepts incoming connections
  161
+
  162
+     It requires additional iptables rules with the socket module of the
  163
+     tproxy patches:
  164
+
  165
+        iptables -t mangle -N DIVERT
  166
+        iptables -t mangle -A PREROUTING -p tcpo -m socket -j DIVERT
  167
+        iptables -t mangle -A DIVERT -j MARK --set-xmark 0x1/0xffffffff
  168
+        iptables -t mangle -A DIVERT -j ACCEPT
  169
+
  170
+    the best if the second rule is before using the TPROXY target.
  171
+
  172
+   3. Initiating connections with a foreign address as a source
  173
+
  174
+     Similarly to the case outlined above, it is sometimes necessary to be
  175
+     able to initiate a connection with a foreign IP address as a source. 
  176
+     Imagine the active FTP case when the FTP client listens for connections
  177
+     with source address equal to the server. Another example: a webserver
  178
+     in your DMZ which does access control based on client IP address. If
  179
+     the proxy could not initiate connections with foreign IP address, the
  180
+     webserver would see the inner IP address of the firewall itself.
  181
+
  182
+     In Linux 2.2 this was accomplished by bind()-ing to a foreign address
  183
+     prior calling connect(), and it worked. In this tproxy patch it is done
  184
+     somewhat similar to the case 2 outlined above.
  185
+
  186
+       * the proxy calls setsockopt with IP_TRANSPARENT
  187
+
  188
+       * the proxy bind to a foreign address
  189
+
  190
+       * the tproxy calls connect()
  191
+
  192
+     The iptables rules with the socket match are also required here.
  193
+ 
  194
+How to use it?
  195
+--------------
  196
+
  197
+    The following use-case assumes a transparent proxy listening on port
  198
+    50080 and any ip address (0.0.0.0).
  199
+
  200
+    First, set up the routing rules with iproute2:
  201
+
  202
+      ip rule add fwmark 1 lookup 100
  203
+      ip route add local 0.0.0.0/0 dev lo table 100
  204
+
  205
+    Or, if you want to use packet marking for anything else, the least
  206
+    significant bit is enough for transparent proxying.
  207
+
  208
+      ip rule add fwmark 0x1/0x1 lookup 100
  209
+      ip route add local 0.0.0.0/0 dev lo table 100
  210
+
  211
+    Note that this latter example is only working with newer versions of
  212
+    iproute2.
  213
+
  214
+    For supporting foreign address bind, the socket match is required with
  215
+    packet marking:
  216
+
  217
+      iptables -t mangle -N DIVERT
  218
+      iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
  219
+
  220
+      # DIVERT chain: mark packets and accept
  221
+      iptables -t mangle -A DIVERT -j MARK --set-mark 1
  222
+      iptables -t mangle -A DIVERT -j ACCEPT
  223
+
  224
+    The last rule is for diverting traffic to the proxy:
  225
+      
  226
+      iptables -t mangle -A PREROUTING -p tcp --dport 80 -j TPROXY \
  227
+              --tproxy-mark 0x1/0x1 --on-port 50080
  228
+
  229
+    If it is a Squid-3 proxy, in /etc/squid/squid.conf the following
  230
+    rule is necessary for transparent proxying:
  231
+
  232
+      http_port 50080 tproxy transparent
  233
+
  234
+    Then set up the ACL rules according to your local policy.
  235
+

0 notes on commit 7783402

Please sign in to comment.
Something went wrong with that request. Please try again.