Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tutorial/sshuttle #486

Merged
merged 6 commits into from
Nov 28, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Binary file added wiki/Tutorials/Sshuttle/images/privsubnet.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
91 changes: 91 additions & 0 deletions wiki/Tutorials/Sshuttle/index.md
Original file line number Diff line number Diff line change
@@ -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 [email protected] 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 [email protected] 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.
* `[email protected]` 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`.