Provided by: sshuttle_0.78.5-1_all bug

NAME

       sshuttle - sshuttle documentation

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][port[-port]].
              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’). Any of the previous examples are also
              valid if you append a port or a  port  range,  so  1.2.3.4:8000  will  only  tunnel
              traffic  that  has as the destination port 8000 of 1.2.3.4 and 1.2.3.0/24:8000-9000
              will tunnel traffic going to any port between 8000 and 9000 (inclusive) for all IPs
              in  the  1.2.3.0/24  subnet.   It  is also possible to use a name in which case the
              first IP it resolves to during startup will be routed over the VPN. Valid  examples
              are example.com, example.com:8000 and example.com:8000-9000.

       --method [auto|nat|tproxy|pf]
              Which firewall method should sshuttle use? For auto, sshuttle attempts to guess the
              appropriate method depending on what it can find in  PATH.  The  default  value  is
              auto.

       -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.  You  can
              use  any  name  resolving  to  an  IP address of the machine running sshuttle, e.g.
              --listen localhost.

              For the tproxy and pf methods this can be an IPv6 address. Use this option twice if
              required, to provide both IPv4 and IPv6 addresses.

       -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. All queries to any
              of the local system’s  DNS  servers  (/etc/resolv.conf)  will  be  intercepted  and
              resolved  on  the  remote side of the tunnel instead, there using the DNS specified
              via the --to-ns= option, if specified.

       --ns-hosts=server1[,server2[,server3[...]]]
              Capture local DNS requests to the specified server(s) and forward to the remote DNS
              server. Contrary to the --dns option, this flag allows to specify the DNS server(s)
              the queries to which to intercept, instead of intercepting all DNS traffic  on  the
              local machine. This can be useful when only certain DNS requests should be resolved
              on the remote side of the tunnel, e.g. in combination with dnsmasq.

       --to-ns=server
              The DNS to forward requests to when remote DNS resolution is enabled. If not given,
              sshuttle  will  simply  resolve  using the system configured resolver on the remote
              side (via /etc/resolv.conf on the remote side).

       --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.

       -X, --exclude-from=file
              Exclude  the subnets specified in a file, one subnet per line. Useful when you have
              lots of subnets to exclude.

       -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.

              If this option is used without --auto-hosts, then  the  listed  hostnames  will  be
              scanned and added, but no further hostnames will be added.

       --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.

       --disable-ipv6
              If using tproxy or pf methods, this will disable IPv6 support.

       --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.

       --version
              Print program version.

CONFIGURATION FILE

       All the options described above can optionally be specified in a configuration file.

       To  run  sshuttle  with options defined in, e.g., /etc/sshuttle.conf just pass the path to
       the file preceded by the @ character, e.g.  @/etc/sshuttle.conf.

       When running sshuttle with options defined in a configuration file, options can  still  be
       passed  via the command line in addition to what is defined in the file. If a given option
       is defined both in the file and in the command line, the value in the  command  line  will
       take precedence.

       Arguments read from a file must be one per line, as shown below:

          value
          --option1
          value1
          --option2
          value2

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

       Run sshuttle with a /etc/sshuttle.conf configuration file:

          $ sshuttle @/etc/sshuttle.conf

       Use the options defined in /etc/sshuttle.conf but be more verbose:

          $ sshuttle @/etc/sshuttle.conf -vvv

       Override the remote server defined in /etc/sshuttle.conf:

          $ sshuttle @/etc/sshuttle.conf -r otheruser@test.example.com

       Example configuration file:

          192.168.0.0/16
          --remote
          user@example.com

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) 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.

       SEE ALSO:
          ssh(1), python(1)

AUTHOR

       Brian May

COPYRIGHT

       2019, Brian May