Sshuttle Documentation Release 1.0.5
Total Page:16
File Type:pdf, Size:1020Kb
sshuttle documentation Release 1.0.5 Brian May Dec 28, 2020 Contents 1 Overview 3 2 Requirements 5 2.1 Client side Requirements.........................................5 2.2 Server side Requirements........................................6 2.3 Additional Suggested Software.....................................6 3 Installation 9 3.1 Optionally after installation.......................................9 4 Usage 11 4.1 Usage Notes............................................... 12 4.2 Sudoers File............................................... 12 5 Platform Specific Notes 15 5.1 Google ChromeOS............................................ 15 5.2 TPROXY................................................. 15 5.3 Microsoft Windows........................................... 16 5.4 OpenWRT................................................ 16 6 sshuttle 17 6.1 Synopsis................................................. 17 6.2 Description................................................ 17 6.3 Options.................................................. 17 6.4 Configuration File............................................ 20 6.5 Examples................................................. 20 6.6 Discussion................................................ 21 7 How it works 23 8 Support 25 9 Useless Trivia 27 10 Change log 29 10.1 1.0.5 - 2020-12-29............................................ 29 10.2 1.0.4 - 2020-08-24............................................ 30 10.3 1.0.3 - 2020-07-12............................................ 30 i 10.4 1.0.2 - 2020-06-18............................................ 30 10.5 1.0.1 - 2020-06-05............................................ 31 10.6 1.0.0 - 2020-06-05............................................ 31 10.7 0.78.5 - 2019-01-28........................................... 32 10.8 0.78.4 - 2018-04-02........................................... 33 10.9 0.78.3 - 2017-07-09........................................... 34 10.10 0.78.2 - 2017-07-09........................................... 34 10.11 0.78.1 - 2016-08-06........................................... 35 10.12 0.78.0 - 2016-04-08........................................... 35 10.13 0.77.2 - 2016-03-07........................................... 35 10.14 0.77.1 - 2016-03-07........................................... 35 10.15 0.77 - 2016-03-03............................................ 36 10.16 0.76 - 2016-01-17............................................ 36 10.17 0.75 - 2016-01-12............................................ 36 10.18 0.74 - 2016-01-10............................................ 36 11 Indices and tables 37 Index 39 ii sshuttle documentation, Release 1.0.5 Date Dec 28, 2020 Version 1.0 Contents: Contents 1 sshuttle documentation, Release 1.0.5 2 Contents CHAPTER 1 Overview As far as I know, sshuttle is the only program that solves the following common case: • Your client machine (or router) is Linux, MacOS, FreeBSD, OpenBSD or pfSense. • You have access to a remote network via ssh. • You don’t necessarily have admin access on the remote network. • The remote network has no VPN, or only stupid/complex VPN protocols (IPsec, PPTP, etc). Or maybe you are the admin and you just got frustrated with the awful state of VPN tools. • You don’t want to create an ssh port forward for every single host/port on the remote network. • You hate openssh’s port forwarding because it’s randomly slow and/or stupid. • You can’t use openssh’s PermitTunnel feature because it’s disabled by default on openssh servers; plus it does TCP-over-TCP, which has terrible performance (see below). 3 sshuttle documentation, Release 1.0.5 4 Chapter 1. Overview CHAPTER 2 Requirements 2.1 Client side Requirements • sudo, or root access on your client machine. (The server doesn’t need admin access.) • Python 3.6 or greater. 2.1.1 Linux with NAT method Supports: • IPv4 TCP • IPv4 DNS Requires: • iptables DNAT, REDIRECT, and ttl modules. 2.1.2 Linux with nft method Supports • IPv4 TCP • IPv4 DNS • IPv6 TCP • IPv6 DNS Requires: • nftables 5 sshuttle documentation, Release 1.0.5 2.1.3 Linux with TPROXY method Supports: • IPv4 TCP • IPv4 UDP (requires recvmsg - see below) • IPv6 DNS (requires recvmsg - see below) • IPv6 TCP • IPv6 UDP (requires recvmsg - see below) • IPv6 DNS (requires recvmsg - see below) 2.1.4 MacOS / FreeBSD / OpenBSD / pfSense Method: pf Supports: • IPv4 TCP • IPv4 DNS • IPv6 TCP • IPv6 DNS Requires: • You need to have the pfctl command. 2.1.5 Windows Not officially supported, however can be made to work with Vagrant. Requires cmd.exe with Administrator access. See Microsoft Windows for more information. 2.2 Server side Requirements • Python 3.6 or greater. 2.3 Additional Suggested Software • If you are using systemd, sshuttle can notify it when the connection to the remote end is established and the firewall rules are installed. For this feature to work you must configure the process start-up type for the sshuttle service unit to notify, as shown in the example below. [Unit] Description=sshuttle After=network.target [Service] Type=notify (continues on next page) 6 Chapter 2. Requirements sshuttle documentation, Release 1.0.5 (continued from previous page) ExecStart=/usr/bin/sshuttle --dns --remote <user>@<server> <subnets...> [Install] WantedBy=multi-user.target 2.3. Additional Suggested Software 7 sshuttle documentation, Release 1.0.5 8 Chapter 2. Requirements CHAPTER 3 Installation • From PyPI: pip install sshuttle • Debain package manager: sudo apt install sshuttle • Clone: git clone https://github.com/sshuttle/sshuttle.git cd sshuttle ./setup.py install 3.1 Optionally after installation • Add to sudoers file: sshuttle--sudoers 9 sshuttle documentation, Release 1.0.5 10 Chapter 3. Installation CHAPTER 4 Usage Note: For information on usage with Windows, see the Microsoft Windows section. For information on using the TProxy method, see the TPROXY section. Forward all traffic: sshuttle-r username @sshserver 0.0.0.0/0 • Use the sshuttle -r parameter to specify a remote server. • By default sshuttle will automatically choose a method to use. Override with the sshuttle --method parameter. • There is a shortcut for 0.0.0.0/0 for those that value their wrists: sshuttle-r username @sshserver 0/0 • For ‘My VPN broke and need a temporary solution FAST to access local IPv4 addresses’: sshuttle--dns-NHr username @sshserver 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 If you would also like your DNS queries to be proxied through the DNS server of the server you are connect to: sshuttle--dns-r username @sshserver 0/0 The above is probably what you want to use to prevent local network attacks such as Firesheep and friends. See the documentation for the sshuttle --dns parameter. (You may be prompted for one or more passwords; first, the local password to become root using sudo, and then the remote ssh password. Or you might have sudo and ssh set up to not require passwords, in which case you won’t be prompted at all.) 11 sshuttle documentation, Release 1.0.5 4.1 Usage Notes That’s it! Now your local machine can access the remote network as if you were right there. And if your “client” machine is a router, everyone on your local network can make connections to your remote network. You don’t need to install sshuttle on the remote server; the remote server just needs to have python available. sshuttle will automatically upload and run its source code to the remote python interpreter. This creates a transparent proxy server on your local machine for all IP addresses that match 0.0.0.0/0. (You can use more specific IP addresses if you want; use any number of IP addresses or subnets to change which addresses get proxied. Using 0.0.0.0/0 proxies everything, which is interesting if you don’t trust the people on your local network.) Any TCP session you initiate to one of the proxied IP addresses will be captured by sshuttle and sent over an ssh session to the remote copy of sshuttle, which will then regenerate the connection on that end, and funnel the data back and forth through ssh. Fun, right? A poor man’s instant VPN, and you don’t even have to have admin access on the server. 4.2 Sudoers File sshuttle can auto-generate the proper sudoers.d file using the current user for Linux and OSX. Doing this will allow sshuttle to run without asking for the local sudo password and to give users who do not have sudo access ability to run sshuttle: sshuttle--sudoers DO NOT run this command with sudo, it will ask for your sudo password when it is needed. A costume user or group can be set with the : option:sshuttle –sudoers –sudoers-username {user_descriptor} option. Valid values for this vary based on how your system is configured. Values such as usernames, groups pre-pended with % and sudoers user aliases will work. See the sudoers manual for more information on valid user specif actions. The options must be used with –sudoers: sshuttle--sudoers--sudoers-user mike sshuttle--sudoers--sudoers-user%sudo The name of the file to be added to sudoers.d can be configured as well. This is mostly not necessary but can be useful for giving more than one user access to sshuttle. The default is sshuttle_auto: sshuttle--sudoer--sudoers-filename sshuttle_auto_mike sshuttle--sudoer--sudoers-filename sshuttle_auto_tommy You can also see what configuration will be added to your system without modifying anything. This can be helpfull is the auto feature does not work, or you want more control. This option also works with –sudoers-username. –sudoers- filename has no effect with this option: sshuttle--sudoers-no-modify This will simply sprint the generated configuration to STDOUT. Example: 08:40 PM william$ sshuttle --sudoers-no-modify Cmnd_Alias SSHUTTLE304 = /usr/bin/env PYTHONPATH=/usr/local/lib/python2.7/dist- ,!packages/sshuttle-0.78.5.dev30+gba5e6b5.d20180909-py2.7.egg /usr/bin/python /usr/ ,!local/bin/sshuttle --method auto --firewall (continues on next page) 12 Chapter 4. Usage sshuttle documentation, Release 1.0.5 (continued from previous page) william ALL=NOPASSWD: SSHUTTLE304 4.2. Sudoers File 13 sshuttle documentation, Release 1.0.5 14 Chapter 4. Usage CHAPTER 5 Platform Specific Notes Contents: 5.1 Google ChromeOS Currently there is no built in support for running sshuttle directly on Google ChromeOS/Chromebooks.