# SSH Tunnelling

## Overview

SSH tunnelling allows secure access to devices on a remote LAN through a JBox without exposing those devices directly to the internet.

Typical uses within Juggle systems:

* Accessing EMS/BESS web interfaces
* Accessing inverter or meter web UIs
* Forwarding Modbus TCP devices
* Temporary remote diagnostics and commissioning

The JBox acts as the secure gateway into the remote site network.

---

# Basic Syntax

```bash
ssh -L <local_port>:<remote_ip>:<remote_port> <user>@<jbox_ip>
```

Example:

```bash
ssh -L 12345:10.172.152.60:80 admin@10.172.152.1
```

This forwards:

```text
localhost:12345 → 10.172.152.60:80
```

You can then open:

```text
http://localhost:12345
```

in your browser.

---

# Multiple Tunnels

Multiple devices can be forwarded through a single SSH session:

```bash
ssh \
-L 12344:10.172.152.60:80 \
-L 12345:10.172.152.23:80 \
-L 12346:10.172.152.24:80 \
-L 12347:10.172.152.22:80 \
admin@10.172.152.1
```

| Local URL                | Remote Device   |
| ------------------------ | --------------- |
| `http://localhost:12344` | `10.172.152.60` |
| `http://localhost:12345` | `10.172.152.23` |
| `http://localhost:12346` | `10.172.152.24` |
| `http://localhost:12347` | `10.172.152.22` |

---

# Recommended Options

## No Interactive Shell

```bash
ssh -N -L 12345:10.172.152.60:80 admin@10.172.152.1
```

`-N` creates the tunnel without opening a terminal session.

---

## Verbose Debugging

```bash
ssh -vvv -L 12345:10.172.152.60:80 admin@10.172.152.1
```

Useful for diagnosing connection issues.

---

# Windows Usage

SSH tunnelling works in:

* Windows Terminal
* PowerShell
* Command Prompt
* VSCode terminal

Modern Windows versions include OpenSSH by default.

## Administrator Terminal

Some ports or network configurations may require an elevated terminal.

Open:

```text
Right Click → Run as Administrator
```

on:

* Windows Terminal
* PowerShell
* Command Prompt

before running SSH commands.

---

# Common Windows Issues

## Port Already In Use

Error:

```text
bind: Address already in use
```

Check usage:

```powershell
netstat -ano | findstr 12345
```

Use another local port if needed.

---

## Browser Certificate Warnings

When forwarding HTTPS devices:

```bash
ssh -L 12443:10.172.152.40:443 admin@10.172.152.1
```

Open:

```text
https://localhost:12443
```

Certificate warnings are expected because the device certificate hostname will not match `localhost`.

---

# Modbus TCP Forwarding

Example:

```bash
ssh -L 1502:10.172.152.50:502 admin@10.172.152.1
```

Local software can then connect to:

```text
localhost:1502
```

as though the remote Modbus device were local.

---

# Useful Tips

* Keep local port allocations consistent where possible
* Use high local ports (e.g. 12000+)
* Close tunnels when no longer needed
* Use `-vvv` when troubleshooting
* Multiple tunnels can share one SSH session

---

# Quick Examples

## Single Tunnel

```bash
ssh -N -L 12345:10.172.152.60:80 admin@10.172.152.1
```

## Multiple Tunnels

```bash
ssh -N \
-L 12344:10.172.152.60:80 \
-L 12345:10.172.152.23:80 \
-L 12346:10.172.152.24:80 \
admin@10.172.152.1
```

## HTTPS Device

```bash
ssh -N -L 12443:10.172.152.40:443 admin@10.172.152.1
```

Open:

```text
https://localhost:12443
```

# How SSH Tunnelling Works

SSH tunnelling forwards traffic through an encrypted connection to a device reachable from the JBox.

Example:

```bash
ssh -L 12345:10.172.152.60:80 admin@10.172.152.1
```

This creates a path:

```text
Your Browser
    ↓
localhost:12345
    ↓
Encrypted SSH Tunnel
    ↓
JBox (10.172.152.1)
    ↓
10.172.152.60:80
```

Opening:

```text
http://localhost:12345
```

actually sends traffic to:

```text
10.172.152.60:80
```

through the JBox.

---

# Key Concept

The remote IP is resolved from the JBox side, not your laptop side.

Example:

```bash
ssh -L 12345:10.172.152.60:80 admin@10.172.152.1
```

means:

```text
"Ask the JBox to connect to 10.172.152.60:80"
```

Your laptop does not need direct access to the remote subnet.

Only the JBox does.

---

# Important Notes

* `12345` only exists on your local machine
* The remote device still receives traffic on port `80`
* The SSH session must remain open for the tunnel to work
* Each `-L` adds another forwarding rule
* Multiple tunnels can share one SSH connection

Example:

```bash
ssh \
-L 12344:10.172.152.60:80 \
-L 12345:10.172.152.23:80 \
admin@10.172.152.1
```

creates two independent tunnels over one SSH session.