ondemand-ssh-tunnel

KO | EN

gitlite — search

#javascript #python #react #ai #machine-learning #deep-learning #macos #java #windows #cli #kubernetes #awesome-list #pytorch #mcp

ondemand-ssh-tunnel

(★ 18)

No description available.

ondemand-ssh-tunnel Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ondemand-ssh-tunnel (ssh-odt)

**ssh-odt** is a lightweight, systemd socket-activated SSH TCP tunnel with **multi-instance** support. Each tunnel instance stays dormant until inbound traffic arrives on its listen port, and shuts down automatically after a configurable idle timeout.

## Quick start

```bash
# 1. Create instance config (first run copies template and exits)
sudo bash install.sh install fra1-https-443

# 2. Edit /etc/ssh-odt.d/fra1-https-443.conf — set REMOTE_HOST, ports, etc.

# 3. Install (validates config, renders units, starts socket)
sudo bash install.sh install fra1-https-443
```

## Components

| File | Installed to | Purpose |
|---|---|---|
| `ssh-odt@.service` | `/etc/systemd/system/` | Template systemd service unit |
| `ssh-odt@<name>.socket` | `/etc/systemd/system/` | Per-instance socket unit (rendered by installer) |
| `ssh-odt.sh` | `/usr/local/bin/` | Tunnel runtime (SSH forward + `systemd-socket-proxyd`) |
| `ssh-odt.conf` | `/etc/ssh-odt.d/<name>.conf` | Per-instance configuration |
| `install.sh` | — | Installer / instance manager |
| `ssh-odt.socket` | — | Socket template reference (not installed directly) |

## Requirements

- Linux with systemd ≥ 232
- OpenSSH client
- `systemd-socket-proxyd` (auto-installed from `systemd-container` if missing)

## Install

```bash
sudo bash install.sh <command> [options]
```

| Command | Description |
|---|---|
| `install <name>` | Install or update a tunnel instance |
| `remove <name>` | Remove a tunnel instance |
| `list` | List all instances and their status |
| `migrate [name]` | Migrate from single-instance v1 setup |

### Examples

```bash
# Install two independent tunnels
sudo bash install.sh install fra1-https-443
sudo bash install.sh install nyc3-sql-3306

# List all instances
sudo bash install.sh list

# Remove an instance
sudo bash install.sh remove nyc3-sql-3306

# Migrate from v1 (single-instance) setup
sudo bash install.sh migrate
```

## Configuration

Each instance has its own configuration file: `/etc/ssh-odt.d/<name>.conf`

| Parameter | Default | Description |
|---|---|---|
| `REMOTE_HOST` | — | SSH relay host (**required**) |
| `REMOTE_USER` | `root` | SSH user |
| `REMOTE_PORT` | `22` | SSH port |
| `LISTEN_ADDRESS` | `0.0.0.0` | Local socket bind address |
| `LISTEN_PORT` | `443` | Local socket listen port (**must be unique per instance**) |
| `TARGET_HOST` | `127.0.0.1` | Forward target host (on remote side) |
| `TARGET_PORT` | `443` | Forward target port (on remote side) |
| `TUNNEL_BIND_ADDRESS` | `127.0.0.1` | Local SSH `-L` bind address |
| `TUNNEL_LOCAL_PORT` | `8443` | Local SSH `-L` bind port (**must be unique per instance**) |
| `SSH_KEY_PATH` | `/root/.ssh/id_rsa` | SSH identity file |
| `IDLE_TIMEOUT` | `120` | Seconds of inactivity before shutdown |
| `CHECK_INTERVAL` | `10` | Activity polling interval (seconds) |
| `KNOWN_HOSTS_PATH` | `/root/.ssh/known_hosts` | SSH known hosts file |
| `CONTROL_SOCKET_PATH` | `/run/ssh-odt-<name>-control` | SSH control socket (auto) |
| `PID_FILE_PATH` | `/run/ssh-odt-<name>.pid` | PID file (auto) |
| `ACTIVITY_FILE_PATH` | `/run/ssh-odt-<name>-activity` | Activity timestamp file (auto) |

### Multi-instance example

```bash
# /etc/ssh-odt.d/fra1-https-443.conf
REMOTE_HOST=relay.example.com
LISTEN_PORT=443
TARGET_PORT=443
TUNNEL_LOCAL_PORT=8443

# /etc/ssh-odt.d/nyc3-sql-3306.conf
REMOTE_HOST=relay.example.com
LISTEN_PORT=3306
TARGET_PORT=3306
TUNNEL_LOCAL_PORT=13306
```

## Operations

```bash
# List all instances
sudo bash install.sh list

# Instance socket status
systemctl status ssh-odt@fra1-https-443.socket

# Instance service logs (follow)
journalctl -u ssh-odt@fra1-https-443.service -f

# Restart instance after config change
systemctl daemon-reload && systemctl restart ssh-odt@fra1-https-443.socket

# Manual tunnel stop (socket re-arms automatically)
systemctl stop ssh-odt@fra1-https-443.service

# Stop everything for an instance
systemctl stop ssh-odt@fra1-https-443.socket ssh-odt@fra1-https-443.service
```

## How it works

1. `ssh-odt@<name>.socket` listens on `LISTEN_ADDRESS:LISTEN_PORT`.
2. First inbound connection triggers `ssh-odt@<name>.service`.
3. Service runs `ssh-odt.sh <name>`, loading `/etc/ssh-odt.d/<name>.conf`.
4. SSH local forward (`-L`) connects to `TARGET_HOST:TARGET_PORT` via `REMOTE_HOST`.
5. `systemd-socket-proxyd` bridges the activated socket to the SSH tunnel.
6. Idle monitor polls active connections every `CHECK_INTERVAL` seconds.
7. After `IDLE_TIMEOUT` seconds with zero connections, the tunnel exits.
8. `ExecStopPost` re-arms the socket for the next activation cycle.

Each instance operates independently — separate processes, separate sockets,
separate idle timers. Instances can use different SSH relay hosts or forward
to different targets through the same relay.

## License

MIT — see [LICENSE](LICENSE).

ondemand-ssh-tunnel

ondemand-ssh-tunnel Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ondemand-ssh-tunnel

ondemand-ssh-tunnel Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README