scitex-tunnel 0.2.6

Persistent SSH reverse tunnel for SciTeX (NAT traversal)

SciTeX Tunnel (scitex-tunnel)

Persistent SSH (Secure Shell) reverse tunnel for NAT (Network Address Translation) traversal

Full Documentation · pip install scitex-tunnel

---

Problem

Machines behind NAT (Network Address Translation) or institutional firewalls cannot receive incoming SSH (Secure Shell) connections. Researchers running long experiments on lab workstations, HPC (High-Performance Computing) nodes, or edge devices need reliable remote access without manual port forwarding or VPN (Virtual Private Network) setup. Existing solutions (ngrok, cloudflared) often require external accounts or lack systemd integration for persistent, auto-recovering connections.

Solution

SciTeX Tunnel creates persistent reverse SSH tunnels using autossh and systemd. Each tunnel runs as a managed service that auto-restarts on failure, survives reboots, and requires only a bastion server with SSH access.

┌─────────────────────────────────────────┐     ┌──────────────────────┐     ┌──────────────────┐
│  Lab Workstation (behind NAT/firewall)  │     │   Bastion Server     │     │  Remote Client   │
│                                         │     │   (public IP)        │     │  (laptop, etc.)  │
│  ┌──────────────────────────────────┐   │     │                      │     │                  │
│  │ systemd service                  │   │     │                      │     │                  │
│  │ autossh-tunnel-{port}.service    │   │     │                      │     │                  │
│  │   ┌──────────────────────────┐   │   │     │  ┌────────────────┐  │     │                  │
│  │   │ autossh                  │   │   │     │  │ sshd listening │  │     │                  │
│  │   │ (auto-reconnect daemon)  │───┼───┼─────┼──│ on port {port} │──┼─────│  ssh -p {port}   │
│  │   │                          │   │   │     │  │                │  │     │  bastion-server  │
│  │   └──────────────────────────┘   │   │     │  └────────────────┘  │     │                  │
│  └──────────────────────────────────┘   │     │                      │     │                  │
│                                         │     │                      │     │                  │
│  localhost:22 (SSH server)              │     │                      │     │                  │
└─────────────────────────────────────────┘     └──────────────────────┘     └──────────────────┘
          ────── reverse tunnel ──────►               ◄─── SSH connection ───
     -R {port}:localhost:22 bastion-server         ssh -p {port} bastion-server

_{Figure 1. Architecture overview. The lab workstation initiates a reverse SSH tunnel to the bastion server. The remote client connects to the bastion server, which forwards the connection back through the tunnel to the lab workstation.}

How It Works

1. setup (requires sudo) writes a systemd unit file at /etc/systemd/system/autossh-tunnel-{port}.service that runs autossh with the reverse tunnel flag (-R {port}:localhost:22). The service is enabled (starts on boot) and started immediately.
2. autossh monitors the SSH connection and automatically re-establishes it if the connection drops — network interruptions, server reboots, or SSH timeouts are handled transparently.
3. systemd ensures the service survives host reboots (WantedBy=multi-user.target) and restarts on process failure (Restart=always, RestartSec=3).
4. A remote client connects to the bastion server on the forwarded port, and the connection is routed back through the tunnel to the lab workstation's SSH server (port 22).

Operation	What it does
setup	Creates a systemd service at /etc/systemd/system/autossh-tunnel-{port}.service that maintains a reverse SSH tunnel via autossh
status	Queries systemd for tunnel service state (systemctl status)
remove	Stops, disables, and deletes the systemd service file

_{Table 1. Three operations. Each maps to a CLI (Command-Line Interface) command, Python function, and MCP (Model Context Protocol) tool.}

Installation

Requires autossh on the host machine (sudo apt install autossh).

pip install scitex-tunnel

SciTeX users: pip install scitex already includes tunnel support.

Note: setup and remove require sudo privileges because they write systemd service files to /etc/systemd/system/ and run systemctl commands. You will be prompted for your password.

Disclaimer: Before setting up reverse tunnels, please check your organization's acceptable use policy and network terms of service. Reverse tunnels may bypass institutional firewalls or network policies. The authors accept no responsibility for any consequences arising from the use of this software.

Alternative: No-sudo setup via ~/.bashrc (no root access needed)

If you do not have sudo access (e.g., shared HPC nodes, university servers), you can run autossh directly from your shell profile. Add to ~/.bashrc:

# Persistent reverse tunnel without sudo — starts on every login
# Checks if tunnel is already running before starting
if ! pgrep -f "autossh.*-R 2222:localhost:22" > /dev/null 2>&1; then
    autossh -M 0 -f -N \
        -o "PubkeyAuthentication=yes" \
        -o "PasswordAuthentication=no" \
        -o "ServerAliveInterval=30" \
        -o "ServerAliveCountMax=3" \
        -i ~/.ssh/id_rsa \
        -R 2222:localhost:22 [e-mail]
fi

Trade-offs vs. systemd approach:

• No sudo required
• Starts on user login (not on boot — requires an active login session)
• No automatic restart if autossh crashes between logins
• -f runs autossh in the background; -M 0 relies on SSH keepalives

Alternative: Persistent session via screen, tmux, or nohup (no root, survives logout)

For long-running sessions on HPC or shared servers where you want the tunnel to survive logout:

# Option 1: screen (detaches from terminal)
screen -dmS tunnel autossh -M 0 -N \
    -o "ServerAliveInterval=30" -o "ServerAliveCountMax=3" \
    -i ~/.ssh/id_rsa -R 2222:localhost:22 [e-mail]

# Reattach:  screen -r tunnel
# Kill:      screen -S tunnel -X quit

# Option 2: tmux
tmux new-session -d -s tunnel "autossh -M 0 -N \
    -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
    -i ~/.ssh/id_rsa -R 2222:localhost:22 [e-mail]"

# Reattach:  tmux attach -t tunnel
# Kill:      tmux kill-session -t tunnel

# Option 3: nohup (simplest, no terminal multiplexer needed)
nohup autossh -M 0 -N \
    -o "ServerAliveInterval=30" -o "ServerAliveCountMax=3" \
    -i ~/.ssh/id_rsa -R 2222:localhost:22 [e-mail] \
    > /dev/null 2>&1 &

# Kill:      pkill -f "autossh.*-R 2222:localhost:22"

Trade-offs: No sudo needed. Survives logout (unlike ~/.bashrc approach). Does not survive reboot — you must restart manually or add the command to a cron @reboot job.

Alternative: Direct shell scripts (no Python required)

If you have sudo access but prefer not to install Python, use the shell scripts directly:

# Download the scripts (one-time)
curl -o ~/.local/bin/setup-autossh-service.sh \
  https://raw.githubusercontent.com/ywatanabe1989/scitex-tunnel/main/src/scitex_tunnel/scripts/setup-autossh-service.sh
curl -o ~/.local/bin/remove-autossh-service.sh \
  https://raw.githubusercontent.com/ywatanabe1989/scitex-tunnel/main/src/scitex_tunnel/scripts/remove-autossh-service.sh
chmod +x ~/.local/bin/setup-autossh-service.sh ~/.local/bin/remove-autossh-service.sh

# Usage (requires sudo)
setup-autossh-service.sh -p 2222 -b [e-mail] -s ~/.ssh/id_rsa
remove-autossh-service.sh -p 2222

Quick Start

# Set up a persistent reverse tunnel
scitex-tunnel setup -p 2222 -b [e-mail] -s ~/.ssh/id_rsa

# Check tunnel status
scitex-tunnel status

# Remove a tunnel
scitex-tunnel remove -p 2222

Three Interfaces

Python API (Application Programming Interface)

import scitex_tunnel

# Set up tunnel
result = scitex_tunnel.setup(2222, "[e-mail]", "~/.ssh/id_rsa")

# Check status
result = scitex_tunnel.status()
result = scitex_tunnel.status(port=2222)

# Remove tunnel
result = scitex_tunnel.remove(2222)

Full API reference

CLI Commands

scitex-tunnel --help-recursive                # Show all commands
scitex-tunnel setup -p 2222 -b user@host -s ~/.ssh/id_rsa
scitex-tunnel status                          # All tunnels
scitex-tunnel status -p 2222                  # Specific port
scitex-tunnel remove -p 2222                  # Remove tunnel
scitex-tunnel list-python-apis                # List Python APIs
scitex-tunnel mcp list-tools                  # List MCP (Model Context Protocol) tools

Full CLI reference

MCP (Model Context Protocol) Server — for AI Agents

AI agents can manage tunnels autonomously.

Tool	Description
tunnel_setup	Set up a persistent SSH reverse tunnel
tunnel_status	Check status of SSH reverse tunnels
tunnel_remove	Remove a persistent SSH reverse tunnel

_{Table 2. Three MCP tools. All tools accept JSON (JavaScript Object Notation) parameters and return JSON results.}

scitex-tunnel mcp start

Full MCP specification

Environment Variables

Variable	Description	Example
SCITEX_TUNNEL_BASTION_SERVER	Default bastion server	[e-mail]
SCITEX_TUNNEL_SECRET_KEY_PATH	Default SSH (Secure Shell) private key path	~/.ssh/id_rsa
SCITEX_TUNNEL_DEBUG_MODE	Enable verbose output (1)	0

_{Table 3. Environment variables. CLI flags take precedence when provided.}

Set these in .env or your shell profile to avoid repeating -b and -s flags:

export SCITEX_TUNNEL_BASTION_SERVER=[e-mail]
export SCITEX_TUNNEL_SECRET_KEY_PATH=~/.ssh/id_rsa

# Now just specify the port
scitex-tunnel setup -p 2222

Part of SciTeX

Tunnel is part of SciTeX. When used inside the SciTeX framework, tunnel management integrates with the orchestrator:

import scitex

# Manage tunnels through the unified interface
result = scitex.tunnel.setup(2222, "[e-mail]", "~/.ssh/id_rsa")
scitex.tunnel.status()

The SciTeX system follows the Four Freedoms for Research below, inspired by the Free Software Definition:

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.

---