Skip to content

README.md

Latest commit

 

History

History
executable file
·
116 lines (78 loc) · 3.83 KB

README.md

File metadata and controls

executable file
·
116 lines (78 loc) · 3.83 KB

autoSSH-autoSetup

Automate reverse SSH (and VNC) tunnel setup for remote hosts behind a firewall.

The problem — you want to access new hosts on remote sites with restricted firewalls.

The solution — have each host phone home on boot and leave a connection shortcut on your management server.

How it works

  1. Run bootstrap.sh on your management (Target) server — it pushes scripts to the new host and kicks off setup.
  2. reverseSSH.sh runs on the new host: exchanges SSH keys, allocates ports, and installs a persistent reverse tunnel.
  3. On the Target, use the generated build-<PORT>.sh shortcut to connect, or run tunnel-status.sh to see all active tunnels.
  4. Optionally run reverseVNC.sh on the host to add a VNC tunnel on the second allocated port.
  5. When decommissioning a host, run teardown.sh on the remote host.

Scripts

On the Target (management) server

Script Purpose
findopenport.sh Finds 2 unused ports in the dynamic range (49152–65535). Run on the Target; called remotely by reverseSSH.sh.
bootstrap.sh Pushes all setup scripts to a new host and triggers reverseSSH.sh remotely. Run this first.
tunnel-status.sh Shows all active reverse tunnels and cross-references them against the port registry.

On the remote host

Script Purpose
reverseSSH.sh Main setup: installs autossh, exchanges keys, allocates ports, installs persistence (systemd or cron), starts the tunnel.
reverseVNC.sh Adds a reverse VNC tunnel (port 5900) using the second allocated port. Run after reverseSSH.sh.
reverseZabbix.sh Adds a reverse Zabbix agent tunnel (port 10050). Append to reverseSSH.sh if needed.
teardown.sh Cleanly removes the tunnel, persistence config, and port registry entry.
report.sh Post-install diagnostic: shows IPs, gateway, DNS, hostname, and allocated ports.

Systemd unit

File Purpose
autossh-tunnel.service Systemd unit for the SSH tunnel. Installed by reverseSSH.sh when --systemd is passed. Reads config from /etc/autossh-tunnel.conf.

Quick start

1. Prepare the Target server

# Install findopenport.sh
cp findopenport.sh /usr/local/bin/findopenport.sh
chmod +x /usr/local/bin/findopenport.sh

# Ensure your SSH keypair exists at ~/.ssh/id_rsa

2. Bootstrap a new host (from the Target)

# The new host must be reachable right now (e.g. on-site before it goes remote)
sudo bash bootstrap.sh <user> <new-host-ip>

# Use --systemd for systemd-based persistence (recommended over cron)
sudo bash bootstrap.sh --systemd <user> <new-host-ip>

3. Connect to the host

# Use the generated shortcut
./build-<PORT>.sh

# Or connect directly
ssh -p <PORT> <user>@127.0.0.1

# See all active tunnels
bash tunnel-status.sh

4. Add VNC access (optional, run on the remote host)

sudo bash reverseVNC.sh --systemd <user> <target-host>
# Then on Target: ./vnc-<PORT>.sh

5. Decommission a host (run on the remote host)

sudo bash teardown.sh <user> <target-host>

Port registry

Each time a host sets up a tunnel, reverseSSH.sh appends a record to ~/tunnel-registry.txt on the Target:

54321=build-54321,2026-04-23T10:00:00Z

tunnel-status.sh reads this file to display hostnames alongside active ports. teardown.sh removes the entry when a host is decommissioned.

Persistence options

Method When to use
systemd (--systemd) Recommended for modern Linux. Starts After=network-online.target, restarts automatically, logs to journald.
cron (default) Use on systems without systemd (older distros, containers).