diff --git a/config.yml b/config.yml index 69baaf82..e3042f9d 100644 --- a/config.yml +++ b/config.yml @@ -78,6 +78,7 @@ nav: - 'Tutorials' : - 'Access de.NBI Virtual Machines from Windows 10' : Tutorials/Win10_SSH/index.md - 'Access a SimpleVM with Mosh' : Tutorials/Mosh/index.md + - 'Access project infrastructure with sshuttle' : Tutorials/Sshuttle/index.md - 'Ansible Automation' : Tutorials/Ansible/index.md - 'Bibigrid' : Tutorials/BiBiGrid/index.md - 'Blast on BiBiGrid' : Tutorials/BlastOnBiBiGrid/index.md diff --git a/wiki/Tutorials/Sshuttle/images/privsubnet.png b/wiki/Tutorials/Sshuttle/images/privsubnet.png new file mode 100644 index 00000000..db4a80fa Binary files /dev/null and b/wiki/Tutorials/Sshuttle/images/privsubnet.png differ diff --git a/wiki/Tutorials/Sshuttle/images/sshuttle.drawio.png b/wiki/Tutorials/Sshuttle/images/sshuttle.drawio.png new file mode 100644 index 00000000..273c91a0 Binary files /dev/null and b/wiki/Tutorials/Sshuttle/images/sshuttle.drawio.png differ diff --git a/wiki/Tutorials/Sshuttle/index.md b/wiki/Tutorials/Sshuttle/index.md new file mode 100644 index 00000000..153a01de --- /dev/null +++ b/wiki/Tutorials/Sshuttle/index.md @@ -0,0 +1,91 @@ +# Sshuttle Tutorial + +## Quick Introduction + +[Sshuttle](https://github.com/sshuttle/sshuttle) is a small application, which sets up +a transparent proxy/VPN connection to a remote and private network. This can also +be a private network inside an OpenStack-Project. +It provides a secure and direct way to access a private network from a local +client, like e.g. a laptop. + +## Requirements + +* Linux or Mac based System. Windows is currently not supported. +* An OpenStack-Project +* One running instance, which has a Floating IP address associated to it +* SSH access to that instance + +## Installing sshuttle + +There is support for various Linux distributions as well as Mac. +The [project](https://github.com/sshuttle/sshuttle) includes installation +guides for all kinds of systems. + +For Debian based systems: + +`sudo apt-get install sshuttle` + +For Fedora: + +`sudo dnf install sshuttle` + +For Mac (via brew): + +`brew install sshuttle` + +## Sshuttle overview + +![sshuttle_overview](images/sshuttle.drawio.png) + +In this example, `sshuttle` is connected to a single instance of an OpenStack project +which holds a publicly reachable Floating IP. This instance acts as a +forwarder. + +When the `sshuttle` tunnel is established, it intercepts all traffic designated +for the private network of the OpenStack project and sends it to the instance with a +Floating IP. Afterwards, the request is forwarded to the target instance within +the private network. + +The effect is, that the local client becomes part of the private network. +The process of intercepting and forwarding traffic is hidden in the background. +This enables a secure way of interacting with all instances via a secure SSH tunnel. +Therefore, there is no need to open additional ports in a Security Group and expose +possibly insecure services to the internet. + +In this example, the `sshuttle`-Tunnel is created on a local client (ex. Laptop): + +```bash +sshuttle -r ubuntu@129.70.51.160 192.168.199.0/24 +c : Connected to server. +``` + +In some scenarios you may have to extend the command to select a specific private SSH key: + +```bash +sshuttle -e "ssh -i ~/.ssh/os-bibi.key" -r ubuntu@129.70.51.160 192.168.199.0/24 +c : Connected to server. +``` + +Afterwards, you can open a new terminal on your local client and directly access all instances +in your private network. Don't close the session where the `sshuttle` process has been established. + +```bash +[johndoe@myLaptop ~]$ ping 192.169.199.52 +PING 192.169.199.52 (192.169.199.52) 56(84) Bytes of data. +64 Bytes from 192.169.199.52: icmp_seq=1 ttl=50 time=176 ms +64 Bytes from 192.169.199.52: icmp_seq=2 ttl=50 time=174 ms +64 Bytes from 192.169.199.52: icmp_seq=3 ttl=50 time=174 ms +``` + +The components in the command explained: + +* `sshuttle -r` indicates to connect to a remote instance. +* `ubuntu@129.70.51.160` is the remote user followed by the FloatingIP address, similar to a regular SSH-Connection. +* `192.168.199.0/24` defines the private network in your OpenStack project for which `sshuttle` will forward traffic to the instance with the Floating IP. + +If you are struggling to find the definition of your private network, you can look it up +on the OpenStack Dashboard: + +![privsubnet](images/privsubnet.png) + +In order to shut down the `sshuttle` process, switch back to the terminal where the session is running and press `Ctrl+c`.