.\" Man page generated from reStructuredText.
.
.TH "SSHUTTLE" "1" "Aug 06, 2016" "0.78.1" "sshuttle"
.SH NAME
sshuttle \- sshuttle documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBsshuttle\fP [\fIoptions\fP] [\fB\-r\fP \fI[username@]sshserver[:port]\fP] <\fIsubnets\fP ...>
.SH DESCRIPTION
.sp
\fBsshuttle\fP 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.
.sp
To work, you must have root access on the local machine,
but you can have a normal account on the server.
.sp
It\(aqs valid to run \fBsshuttle\fP 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.
.sp
If run on a router, \fBsshuttle\fP can forward traffic for your
entire subnet to the VPN.
.SH OPTIONS
.INDENT 0.0
.TP
.B subnets
A list of subnets to route over the VPN, in the form
\fBa.b.c.d[/width]\fP\&.  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 (\(aqjust route everything through the
VPN\(aq).
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-listen=[ip:]port
Use this ip address and port number as the transparent
proxy port.  By default \fBsshuttle\fP finds an available
port automatically and listens on IP 127.0.0.1
(localhost), so you don\(aqt 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 \fBsshuttle\fP on a router) try enabling IP Forwarding in
your kernel, then using \fB\-\-listen 0.0.0.0:0\fP\&.
.sp
For the tproxy method this can be an IPv6 address. Use this option twice if
required, to provide both IPv4 and IPv6 addresses.
.UNINDENT
.INDENT 0.0
.TP
.B \-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\(aqs DNS
(/etc/resolv.conf) settings, for several reasons.  First,
hostnames are added without domain names attached, so
you can \fBssh thatserver\fP without worrying if your local
domain matches the remote one.  Second, if you \fBsshuttle\fP
into more than one VPN at a time, it\(aqs impossible to
use more than one DNS server at once anyway, but
\fBsshuttle\fP correctly merges /etc/hosts entries between
all running copies.  Third, if you\(aqre only routing a
few subnets over the VPN, you probably would prefer to
keep using your local DNS server for everything else.
.UNINDENT
.INDENT 0.0
.TP
.B \-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\(aqs routing
table.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dns
Capture local DNS requests and forward to the remote DNS
server.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-python
Specify the name/path of the remote python interpreter.
The default is just \fBpython\fP, which means to use the
default python interpreter on the remote system\(aqs PATH.
.UNINDENT
.INDENT 0.0
.TP
.B \-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, \fI\%testuser@example.com\fP,
\fI\%testuser@example.com\fP:2222, or example.com:2244.
.UNINDENT
.INDENT 0.0
.TP
.B \-x, \-\-exclude=subnet
Explicitly exclude this subnet from forwarding.  The
format of this option is the same as the \fB<subnets>\fP
option.  To exclude more than one subnet, specify the
\fB\-x\fP option more than once.  You can say something like
\fB0/0 \-x 1.2.3.0/24\fP to forward everything except the
local subnet over the VPN, for example.
.UNINDENT
.INDENT 0.0
.TP
.B \-X, \-\-exclude\-from=file
Exclude the subnets specified in a file, one subnet per
line. Useful when you have lots of subnets to exclude.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Print more information about the session.  This option
can be used more than once for increased verbosity.  By
default, \fBsshuttle\fP prints only error messages.
.UNINDENT
.INDENT 0.0
.TP
.B \-e, \-\-ssh\-cmd
The command to use to connect to the remote server. The
default is just \fBssh\fP\&.  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, \fB\-e \(aqssh \-v\(aq\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-seed\-hosts
A comma\-separated list of hostnames to use to
initialize the \fI\%\-\-auto\-hosts\fP scan algorithm.
\fI\%\-\-auto\-hosts\fP 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.
.sp
If this option is used \fIwithout\fP \fI\%\-\-auto\-hosts\fP,
then the listed hostnames will be scanned and added, but
no further hostnames will be added.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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, \fBsshuttle\fP 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
\fBsshuttle\fP seem slow in bandwidth benchmarks (benchmarks
rarely test ping latency, which is what \fBsshuttle\fP is
trying to control).  This option disables the latency
control feature, maximizing bandwidth usage.  Use at
your own risk.
.UNINDENT
.INDENT 0.0
.TP
.B \-D, \-\-daemon
Automatically fork into the background after connecting
to the remote server.  Implies \fI\%\-\-syslog\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-syslog
after connecting, send all log messages to the
\fBsyslog(3)\fP service instead of stderr.  This is
implicit if you use \fI\%\-\-daemon\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pidfile=pidfilename
when using \fI\%\-\-daemon\fP, save \fBsshuttle\fP\(aqs pid to
\fIpidfilename\fP\&.  The default is \fBsshuttle.pid\fP in the
current directory.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-disable\-ipv6
If using the tproxy method, this will disable IPv6 support.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-firewall
(internal use only) run the firewall manager.  This is
the only part of \fBsshuttle\fP that must run as root.  If
you start \fBsshuttle\fP as a non\-root user, it will
automatically run \fBsudo\fP or \fBsu\fP to start the firewall
manager, but the core of \fBsshuttle\fP still runs as a
normal user.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-hostwatch
(internal use only) run the hostwatch daemon.  This
process runs on the server side and collects hostnames for
the \fI\%\-\-auto\-hosts\fP option.  Using this option by itself
makes it a lot easier to debug and test the \fI\%\-\-auto\-hosts\fP
feature.
.UNINDENT
.SH EXAMPLES
.sp
Test locally by proxying all local connections, without using ssh:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sshuttle \-v 0/0

Starting sshuttle proxy.
Listening on (\(aq0.0.0.0\(aq, 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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Test connection to a remote server, with automatic hostname
and subnet guessing:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sshuttle \-vNHr example.org

Starting sshuttle proxy.
Listening on (\(aq0.0.0.0\(aq, 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
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DISCUSSION
.sp
When it starts, \fBsshuttle\fP creates an ssh session to the
server specified by the \fB\-r\fP option.  If \fB\-r\fP is omitted,
it will start both its client and server locally, which is
sometimes useful for testing.
.sp
After connecting to the remote server, \fBsshuttle\fP uploads its
(python) source code to the remote end and executes it
there.  Thus, you don\(aqt need to install \fBsshuttle\fP on the
remote server, and there are never \fBsshuttle\fP version
conflicts between client and server.
.sp
Unlike most VPNs, \fBsshuttle\fP forwards sessions, not packets.
That is, it uses kernel transparent proxying (\fIiptables
REDIRECT\fP 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.
.sp
Packet\-level forwarding (eg. using the tun/tap devices on
Linux) seems elegant at first, but it results in
several problems, notably the \(aqtcp over tcp\(aq 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\(aqs 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.
.sp
\fBsshuttle\fP\(aqs 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.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBssh(1)\fP, \fBpython(1)\fP
.UNINDENT
.UNINDENT
.SH AUTHOR
Brian May
.SH COPYRIGHT
2016, Brian May
.\" Generated by docutils manpage writer.
.