Update documentation.

README.rst

@@ -26,59 +26,88 @@ common case:
   TCP-over-TCP, which has terrible performance (see below).
 
 
-Prerequisites
+Client side Requirements
--------------
+------------------------
 
-- sudo, su, or logged in as root on your client machine.
+- sudo, or logged in as root on your client machine.
   (The server doesn't need admin access.)
+- Python 2.7 or Python 3.5.
 
-- If you use Linux on your client machine:
++-------+--------+------------+-----------------------------------------------+
-  iptables installed on the client, including at
+| OS    | Method | Features   | Requirements                                  |
-  least the iptables DNAT, REDIRECT, and ttl modules. 
++=======+========+============+===============================================+
-  These are installed by default on most Linux distributions. 
+| Linux | NAT    | * IPv4 TCP + iptables DNAT, REDIRECT, and ttl modules.     |
-  (The server doesn't need iptables and doesn't need to be
++       +--------+------------+-----------------------------------------------+
-  Linux.)
+|       | TPROXY | * IPv4 TCP + Linux with TPROXY support.                    |
+|       |        | * IPv4 UDP + Python 3.5 preferred (see below).             |
+|       |        | * IPv6 TCP +                                               |
+|       |        | * IPv6 UDP +                                               |
++-------+--------+------------+-----------------------------------------------+
+| BSD   | IPFW   | * IPv4 TCP | Your kernel needs to be compiled with         |
+|       |        |            | `IPFIREWALL_FORWARD` and you need to have ipfw|
+|       |        |            | available.                                    |
++-------+--------+------------+-----------------------------------------------+
+| MacOS | PF     | * IPv4 TCP + You need to have the pfctl command.           |
++-------+--------+------------+-----------------------------------------------+
 
-- If you use MacOS or BSD on your client machine:
+Server side Requirements
-  Your kernel needs to be compiled with `IPFIREWALL_FORWARD`
+------------------------
-  (MacOS has this by default) and you need to have ipfw
+Python 2.7 or Python 3.5. This should match what is used on the client side.
-  available. (The server doesn't need to be MacOS or BSD.)
-
-- Python 2.x, both locally and the remote system. Python 3.x is not yet
-  supported.
-
-*WARNING*:
-On MacOS 10.6 (at least up to 10.6.6), your network will
-stop responding about 10 minutes after the first time you
-start sshuttle, because of a MacOS kernel bug relating to
-arp and the net.inet.ip.scopedroute sysctl.  To fix it,
-just switch your wireless off and on. Sshuttle makes the
-kernel setting it changes permanent, so this won't happen
-again, even after a reboot.
 
 
 Additional Suggested Software
 -----------------------------
 
-- You may want to need autossh, available in various package management
+- You may want to use autossh, available in various package management
   systems
 
-- For Linux only tproxy support, you need PyXAPI, available here:
+
+Additional information for TPROXY
+---------------------------------
+TPROXY is the only method that supports full support of IPv6 and UDP.
+
+Full UDP or DNS support with the TPROXY method requires the `recvmsg()`
+syscall. This is not available in Python 2.7, however is in Python 3.5 and
+later.
+
+- For Python 2.7, you need PyXAPI, available here:
   http://www.pps.univ-paris-diderot.fr/~ylg/PyXAPI/
 
+There are some things you need to consider for TPROXY to work:
+
+1. The following commands need to be run first as root. This only needs to be
+   done once after booting up::
+
+       ip route add local default dev lo table 100
+       ip rule add fwmark 1 lookup 100
+       ip -6 route add local default dev lo table 100
+       ip -6 rule add fwmark 1 lookup 100
+
+2. The client needs to be run as root. e.g.::
+
+       sudo SSH_AUTH_SOCK="$SSH_AUTH_SOCK" $HOME/tree/sshuttle.tproxy/sshuttle  --method=tproxy ...
+
+3. You do need the `--method=tproxy` parameter, as above.
+
+4. The routes for the outgoing packets must already exist. For example, if your
+   connection does not have IPv6 support, no IPv6 routes will exist, IPv6
+   packets will not be generated and sshuttle cannot intercept them. Add some
+   dummy routes to external interfaces. Make sure they get removed however
+   after sshuttle exits.
+
 
 Obtaining sshuttle
 ------------------
 
+- From PyPI::
+
+      pip install sshuttle
+
 - Clone::
 
       git clone https://github.com/sshuttle/sshuttle.git
       ./setup.py install
 
-- From PyPI::
-
-      pip install sshuttle
-
 
 Usage
 -----
@@ -87,6 +116,9 @@ Usage
 
       sshuttle -r username@sshserver 0.0.0.0/0 -vv
 
+- By default sshuttle will automatically choose a method to use. Override with
+  the `--method=` parameter.
+
 - There is a shortcut for 0.0.0.0/0 for those that value
   their wrists::
 
@@ -100,10 +132,9 @@ Usage
   The above is probably what you want to use to prevent
   local network attacks such as Firesheep and friends.
 
-(You may be prompted for one or more passwords; first, the
+(You may be prompted for one or more passwords; first, the local password to
-local password to become root using either sudo or su, and
+become root using sudo, and then the remote ssh password.  Or you might have
-then the remote ssh password.  Or you might have sudo and ssh set
+sudo and ssh set up to not require passwords, in which case you won't be
-up to not require passwords, in which case you won't be
 prompted at all.)
 
 
@@ -163,11 +194,12 @@ doesn't care about individual connections; ie. it's "stateless" with respect
 to the traffic.  sshuttle is the opposite of stateless; it tracks every
 single connection.
 
-You could compare sshuttle to something like the old `Slirp <http://en.wikipedia.org/wiki/Slirp>`_ program, which was a
+You could compare sshuttle to something like the old `Slirp
-userspace TCP/IP implementation that did something similar.  But it
+<http://en.wikipedia.org/wiki/Slirp>`_ program, which was a userspace TCP/IP
-operated on a packet-by-packet basis on the client side, reassembling the
+implementation that did something similar.  But it operated on a
-packets on the server side.  That worked okay back in the "real live serial
+packet-by-packet basis on the client side, reassembling the packets on the
-port" days, because serial ports had predictable latency and buffering.
+server side.  That worked okay back in the "real live serial port" days,
+because serial ports had predictable latency and buffering.
 
 But you can't safely just forward TCP packets over a TCP session (like ssh),
 because TCP's performance depends fundamentally on packet loss; it
@@ -187,14 +219,15 @@ safe.
 
 Useless Trivia
 --------------
+This section written by Avery Pennarun <apenwarr@gmail.com>.
 
-Back in 1998 (12 years ago!  Yikes!), I released the first version of `Tunnel Vision <http://alumnit.ca/wiki/?TunnelVisionReadMe>`_, a
+Back in 1998 (12 years ago!  Yikes!), I released the first version of `Tunnel
-semi-intelligent VPN client for Linux.  Unfortunately, I made two big mistakes: 
+Vision <http://alumnit.ca/wiki/?TunnelVisionReadMe>`_, a semi-intelligent VPN
-I implemented the key exchange myself (oops), and I ended up doing
+client for Linux.  Unfortunately, I made two big mistakes: I implemented the
-TCP-over-TCP (double oops).  The resulting program worked okay - and people
+key exchange myself (oops), and I ended up doing TCP-over-TCP (double oops).
-used it for years - but the performance was always a bit funny.  And nobody
+The resulting program worked okay - and people used it for years - but the
-ever found any security flaws in my key exchange, either, but that doesn't
+performance was always a bit funny.  And nobody ever found any security flaws
-mean anything. :)
+in my key exchange, either, but that doesn't mean anything. :)
 
 The same year, dcoombs and I also released Fast Forward, a proxy server
 supporting transparent proxying.  Among other things, we used it for
@@ -202,21 +235,19 @@ automatically splitting traffic across more than one Internet connection (a
 tool we called "Double Vision").
 
 I was still in university at the time.  A couple years after that, one of my
-professors was working with some graduate students on the technology that
+professors was working with some graduate students on the technology that would
-would eventually become `Slipstream Internet Acceleration <http://www.slipstream.com/>`_.  He asked me to do a contract for him to build an
+eventually become `Slipstream Internet Acceleration
-initial prototype of a transparent proxy server for mobile networks.  The
+<http://www.slipstream.com/>`_.  He asked me to do a contract for him to build
+an initial prototype of a transparent proxy server for mobile networks.  The
 idea was similar to sshuttle: if you reassemble and then disassemble the TCP
 packets, you can reduce latency and improve performance vs.  just forwarding
-the packets over a plain VPN or mobile network.  (It's unlikely that any of
+the packets over a plain VPN or mobile network.  (It's unlikely that any of my
-my code has persisted in the Slipstream product today, but the concept is
+code has persisted in the Slipstream product today, but the concept is still
-still pretty cool.  I'm still horrified that people use plain TCP on
+pretty cool.  I'm still horrified that people use plain TCP on complex mobile
-complex mobile networks with crazily variable latency, for which it was
+networks with crazily variable latency, for which it was never really
-never really intended.)
+intended.)
 
 That project I did for Slipstream was what first gave me the idea to merge
 the concepts of Fast Forward, Double Vision, and Tunnel Vision into a single
 program that was the best of all worlds.  And here we are, at last, 10 years
 later.  You're welcome.
-
---
-Avery Pennarun <apenwarr@gmail.com>