Provided by: sshuttle_0.54-1_all bug

NAME

       sshuttle - a transparent proxy-based VPN using ssh

SYNOPSIS

       sshuttle [options...] [-r [username@]sshserver[:port]] <subnets...>

DESCRIPTION

       sshuttle allows you to create a VPN connection from your machine to any remote server that
       you can connect to via ssh, as long as that server has python 2.3 or higher.

       To work, you must have root access on the local machine, but you can have a normal account
       on the server.

       It's  valid  to  run  sshuttle  more  than once simultaneously on a single client machine,
       connecting to a different server every time, so you can be on more than one VPN at once.

       If run on a router, sshuttle can forward traffic for your entire subnet to the VPN.

OPTIONS

       <subnets...>
              a list of subnets to route over  the  VPN,  in  the  form  a.b.c.d[/width].   Valid
              examples  are  1.2.3.4  (a  single IP address), 1.2.3.4/32 (equivalent to 1.2.3.4),
              1.2.3.0/24 (a 24-bit subnet, ie.  with a 255.255.255.0  netmask),  and  0/0  (`just
              route everything through the VPN').

       -l, —listen=[ip:]port
              use  this  ip  address  and  port number as the transparent proxy port.  By default
              sshuttle finds  an  available  port  automatically  and  listens  on  IP  127.0.0.1
              (localhost),  so  you  don't  need to override it, and connections are only proxied
              from the local  machine,  not  from  outside  machines.   If  you  want  to  accept
              connections  from other machines on your network (ie.  to run sshuttle on a router)
              try enabling IP Forwarding in your kernel, then using --listen 0.0.0.0:0.

       -H, —auto-hosts
              scan for remote hostnames and  update  the  local  /etc/hosts  file  with  matching
              entries  for as long as the VPN is open.  This is nicer than changing your system's
              DNS (/etc/resolv.conf) settings, for several reasons.  First, hostnames  are  added
              without  domain  names attached, so you can ssh thatserver without worrying if your
              local domain matches the remote one.  Second, if you sshuttle into  more  than  one
              VPN  at a time, it's impossible to use more than one DNS server at once anyway, but
              sshuttle correctly merges /etc/hosts entries between all running copies.  Third, if
              you're  only  routing a few subnets over the VPN, you probably would prefer to keep
              using your local DNS server for everything else.

       -N, —auto-nets
              in addition to the subnets provided on the  command  line,  ask  the  server  which
              subnets  it thinks we should route, and route those automatically.  The suggestions
              are taken automatically from the server's routing table.

       —dns   capture local DNS requests and forward to the remote DNS server.

       —python
              specify the name/path of the  remote  python  interpreter.   The  default  is  just
              python,  which  means  to use the default python interpreter on the remote system's
              PATH.

       -r, —remote=[username@]sshserver[:port]
              the remote hostname and optional username and ssh port number to use for connecting
              to   the   remote   server.    For   example,   example.com,  testuser@example.com,
              testuser@example.com:2222, or example.com:2244.

       -x, —exclude=subnet
              explicitly exclude this subnet from forwarding.  The format of this option  is  the
              same  as  the  <subnets>  option.   To exclude more than one subnet, specify the -x
              option more than once.  You can say something  like  0/0 -x 1.2.3.0/24  to  forward
              everything except the local subnet over the VPN, for example.

       -v, —verbose
              print  more  information about the session.  This option can be used more than once
              for increased verbosity.  By default, sshuttle prints only error messages.

       -e, —ssh-cmd
              the command to use to connect to the remote server.  The default is just ssh.   Use
              this  if your ssh client is in a non-standard location or you want to provide extra
              options to the ssh command, for example, -e 'ssh -v'.

       —seed-hosts
              a comma-separated list of hostnames to use  to  initialize  the  --auto-hosts  scan
              algorithm.  --auto-hosts does things like poll local SMB servers for lists of local
              hostnames, but can speed things up if you use this option to give it a few names to
              start from.

       —no-latency-control
              sacrifice  latency  to  improve  bandwidth  benchmarks.  ssh uses really big socket
              buffers, which can overload the connection if you start doing large file transfers,
              thus  making  all  your other sessions inside the same tunnel go slowly.  Normally,
              sshuttle tries to avoid this problem using a “fullness check” that  allows  only  a
              certain amount of outstanding data to be buffered at a time.  But on high-bandwidth
              links, this can leave a  lot  of  your  bandwidth  underutilized.   It  also  makes
              sshuttle  seem  slow  in bandwidth benchmarks (benchmarks rarely test ping latency,
              which is what sshuttle is trying to control).  This  option  disables  the  latency
              control feature, maximizing bandwidth usage.  Use at your own risk.

       -D, —daemon
              automatically  fork  into  the  background  after  connecting to the remote server.
              Implies --syslog.

       —syslog
              after connecting, send all log messages to the syslog(3) service instead of stderr.
              This is implicit if you use --daemon.

       —pidfile=pidfilename
              when   using  --daemon,  save  sshuttle's  pid  to  pidfilename.   The  default  is
              sshuttle.pid in the current directory.

       —server
              (internal use only) run the sshuttle server on  stdin/stdout.   This  is  what  the
              client runs on the remote end.

       —firewall
              (internal  use  only)  run the firewall manager.  This is the only part of sshuttle
              that must run as root.   If  you  start  sshuttle  as  a  non-root  user,  it  will
              automatically  run  sudo  or  su  to  start  the  firewall manager, but the core of
              sshuttle still runs as a normal user.

       —hostwatch
              (internal use only) run the hostwatch daemon.  This process runs on the server side
              and  collects  hostnames  for the --auto-hosts option.  Using this option by itself
              makes it a lot easier to debug and test the --auto-hosts feature.

EXAMPLES

       Test locally by proxying all local connections, without using ssh:

              $ sshuttle -v 0/0

              Starting sshuttle proxy.
              Listening on ('0.0.0.0', 12300).
              [local sudo] Password:
              firewall manager ready.
              c : connecting to server...
               s: available routes:
               s:   192.168.42.0/24
              c : connected.
              firewall manager: starting transproxy.
              c : Accept: 192.168.42.106:50035 -> 192.168.42.121:139.
              c : Accept: 192.168.42.121:47523 -> 77.141.99.22:443.
                  ...etc...
              ^C
              firewall manager: undoing changes.
              KeyboardInterrupt
              c : Keyboard interrupt: exiting.
              c : SW#8:192.168.42.121:47523: deleting
              c : SW#6:192.168.42.106:50035: deleting

       Test connection to a remote server, with automatic hostname and subnet guessing:

              $ sshuttle -vNHr example.org

              Starting sshuttle proxy.
              Listening on ('0.0.0.0', 12300).
              firewall manager ready.
              c : connecting to server...
               s: available routes:
               s:   77.141.99.0/24
              c : connected.
              c : seed_hosts: []
              firewall manager: starting transproxy.
              hostwatch: Found: testbox1: 1.2.3.4
              hostwatch: Found: mytest2: 5.6.7.8
              hostwatch: Found: domaincontroller: 99.1.2.3
              c : Accept: 192.168.42.121:60554 -> 77.141.99.22:22.
              ^C
              firewall manager: undoing changes.
              c : Keyboard interrupt: exiting.
              c : SW#6:192.168.42.121:60554: deleting

DISCUSSION

       When it starts, sshuttle creates an ssh session to the server specified by the -r  option.
       If  -r  is  omitted,  it will start both its client and server locally, which is sometimes
       useful for testing.

       After connecting to the remote server, sshuttle uploads its (python) source  code  to  the
       remote  end and executes it there.  Thus, you don't need to install sshuttle on the remote
       server, and there are never sshuttle version conflicts between client and server.

       Unlike most VPNs, sshuttle forwards sessions,  not  packets.   That  is,  it  uses  kernel
       transparent  proxying  (iptables REDIRECT  rules  on  Linux,  or ipfw fwd rules on BSD) to
       capture outgoing TCP sessions, then creates entirely separate  TCP  sessions  out  to  the
       original destination at the other end of the tunnel.

       Packet-level  forwarding (eg.  using the tun/tap devices on Linux) seems elegant at first,
       but it results in several problems, notably the `tcp over tcp' problem.  The tcp  protocol
       depends  fundamentally  on  packets  being  dropped  in  order to implement its congestion
       control agorithm; if you pass tcp packets through a tcp-based tunnel (such  as  ssh),  the
       inner  tcp packets will never be dropped, and so the inner tcp stream's congestion control
       will be completely broken, and performance will  be  terrible.   Thus,  packet-based  VPNs
       (such  as  IPsec  and openvpn) cannot use tcp-based encrypted streams like ssh or ssl, and
       have to implement their own encryption from scratch,  which  is  very  complex  and  error
       prone.

       sshuttle's  simplicity  comes  from  the  fact  that  it  can  safely use the existing ssh
       encrypted tunnel without incurring a performance penalty.  It does  this  by  letting  the
       client-side  kernel  manage the incoming tcp stream, and the server-side kernel manage the
       outgoing tcp stream; there is no need for congestion control to be shared between the  two
       separate streams, so a tcp-based tunnel is fine.

BUGS

       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.

SEE ALSO

       ssh(1), python(1)

AUTHORS

       Avery Pennarun <apenwarr@gmail.com>.