VPS Jump Host and Reverse-Tunnel Deployment

1. Create a Dedicated Tunnel Key on the Mac

The tunnel runs unattended, so use a dedicated key with an empty passphrase. Its restrictions on the VPS make it useless for shell access.

ssh-keygen \
  -t ed25519 \
  -a 100 \
  -N '' \
  -f ~/.ssh/work-vps-tunnel \
  -C work-vps-tunnel

Record only the public half:

cat ~/.ssh/work-vps-tunnel.pub
ssh-keygen -lf ~/.ssh/work-vps-tunnel.pub

2. Obtain the Heeler Device Key

Copy the public-key line shown by Heeler. The private half remains in the iOS Keychain.

The same Device Key public line must be authorized:

• on the VPS Jump account, with forwarding-only restrictions; and
• on the Mac account, so the second SSH handshake can authenticate.

Authorizing the key on only one hop results in a password prompt or an authentication failure on the other hop.

On the Mac, keep PTY, exec, SFTP, and stream-local forwarding available for Heeler while disabling capabilities the app does not need:

no-agent-forwarding,no-X11-forwarding,no-user-rc DEVICE_PUBLIC_KEY

Do not add no-port-forwarding: OpenSSH also applies it to the direct-streamlocal channels Heeler uses to reach the herdr API socket.

Append that line to ~/.ssh/authorized_keys, then enforce:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

3. Create Restricted Accounts on the VPS

Run as a VPS administrator:

sudo adduser --disabled-password --gecos '' herdr-tunnel
sudo adduser --disabled-password --gecos '' herdr-jump

sudo install -d -m 700 \
  -o herdr-tunnel \
  -g herdr-tunnel \
  /home/herdr-tunnel/.ssh

sudo install -d -m 700 \
  -o herdr-jump \
  -g herdr-jump \
  /home/herdr-jump/.ssh

Do not change the administrator login policy yet. Keep the current administrator session open until the new configuration has passed validation.

4. Install Restricted Public Keys on the VPS

Install the tunnel public key:

restrict,port-forwarding,permitlisten="127.0.0.1:2222" TUNNEL_PUBLIC_KEY

Install every approved Device Key on the Jump account:

restrict,port-forwarding,permitopen="127.0.0.1:2222" DEVICE_PUBLIC_KEY

Set ownership and permissions:

sudo chown -R herdr-tunnel:herdr-tunnel /home/herdr-tunnel/.ssh
sudo chmod 700 /home/herdr-tunnel/.ssh
sudo chmod 600 /home/herdr-tunnel/.ssh/authorized_keys

sudo chown -R herdr-jump:herdr-jump /home/herdr-jump/.ssh
sudo chmod 700 /home/herdr-jump/.ssh
sudo chmod 600 /home/herdr-jump/.ssh/authorized_keys

restrict disables forwarding as part of its default restrictions. port-forwarding re-enables forwarding, then permitlisten or permitopen narrows it to the one required endpoint.

5. Apply Account-Level OpenSSH Restrictions

On Debian and Ubuntu, confirm the main configuration includes drop-ins:

grep -nE '^[[:space:]]*Include[[:space:]]+.*/sshd_config\.d/' \
  /etc/ssh/sshd_config

Create /etc/ssh/sshd_config.d/60-herdr-forwarding.conf:

# Restrict the persistent reverse-tunnel account.
Match User herdr-tunnel
    AuthenticationMethods publickey
    PubkeyAuthentication yes
    PasswordAuthentication no
    KbdInteractiveAuthentication no
    AllowTcpForwarding remote
    AllowStreamLocalForwarding no
    PermitListen 127.0.0.1:2222
    PermitOpen none
    GatewayPorts no
    PermitTTY no
    PermitTunnel no
    PermitUserRC no
    X11Forwarding no
    AllowAgentForwarding no
    MaxSessions 0

# Restrict the external Jump Host account.
Match User herdr-jump
    AuthenticationMethods publickey
    PubkeyAuthentication yes
    PasswordAuthentication no
    KbdInteractiveAuthentication no
    AllowTcpForwarding local
    AllowStreamLocalForwarding no
    PermitListen none
    PermitOpen 127.0.0.1:2222
    GatewayPorts no
    PermitTTY no
    PermitTunnel no
    PermitUserRC no
    X11Forwarding no
    AllowAgentForwarding no
    MaxSessions 0

Match all

Match all ends the second conditional block. It is especially important in a drop-in that may be included before later global directives.

Validate before reloading:

sudo /usr/sbin/sshd -t

sudo /usr/sbin/sshd -T \
  -C user=herdr-tunnel,host=localhost,addr=127.0.0.1 \
  | grep -E 'allowtcpforwarding|permitlisten|permitopen|gatewayports|maxsessions'

sudo /usr/sbin/sshd -T \
  -C user=herdr-jump,host=localhost,addr=127.0.0.1 \
  | grep -E 'allowtcpforwarding|permitlisten|permitopen|gatewayports|maxsessions'

Reload only after sshd -t succeeds:

sudo systemctl reload ssh

Some distributions name the service sshd instead.

6. Configure the Mac SSH Aliases

Add entries like these to ~/.ssh/config:

Host work-vps-tunnel
  HostName VPS_PUBLIC_IP
  User herdr-tunnel
  Port 22
  IdentityFile ~/.ssh/work-vps-tunnel
  IdentitiesOnly yes
  BatchMode yes
  ExitOnForwardFailure yes
  ServerAliveInterval 30
  ServerAliveCountMax 3
  StrictHostKeyChecking yes

Host work-vps-jump
  HostName VPS_PUBLIC_IP
  User herdr-jump
  Port 22
  IdentityFile ~/.ssh/work-client
  IdentitiesOnly yes
  BatchMode yes
  StrictHostKeyChecking yes

Host work-mac
  HostName 127.0.0.1
  User MAC_USER
  Port 2222
  IdentityFile ~/.ssh/work-client
  IdentitiesOnly yes
  ProxyJump work-vps-jump
  HostKeyAlias work-mac-via-vps
  StrictHostKeyChecking yes

The desktop client identity is only for command-line validation. Heeler uses its own Device Key.

Verify the VPS host-key fingerprint through a trusted VPS console before adding it to known_hosts. Do not use StrictHostKeyChecking no.

7. Test the Tunnel Interactively

On the Mac:

ssh -NT \
  -R 127.0.0.1:2222:127.0.0.1:22 \
  work-vps-tunnel

On the VPS:

sudo ss -ltnp | grep ':2222'

The local-address column must show:

127.0.0.1:2222

It must not show:

0.0.0.0:2222
[::]:2222

The 0.0.0.0:* value commonly shown in the peer-address column is not a public listener. Read the local-address column.

From a desktop client with the validation key:

ssh work-mac

This test proves more than process liveness: the Jump account authenticated, the direct TCP channel reached the loopback listener, the reverse tunnel reached the Mac, the Mac host key matched, and the Mac accepted the inner SSH identity.

8. Make the Mac Tunnel Persistent

Use a user LaunchAgent that runs:

/usr/bin/ssh -NT -R 127.0.0.1:2222:127.0.0.1:22 work-vps-tunnel

The LaunchAgent should define:

• a unique label;
• RunAtLoad;
• KeepAlive;
• a retry throttle;
• dedicated stdout and stderr log files.

Validate both initial startup and recovery:

launchctl print gui/$(id -u)/YOUR_LAUNCH_AGENT_LABEL

Terminate the managed SSH process once, confirm launchd starts a new PID, and repeat the end-to-end ssh work-mac test. A running process alone does not prove the reverse listener or either authentication hop works.

macOS user LaunchAgents start after that user logs in. If the Mac reboots but no user logs in, this user-level tunnel is not yet running.

9. Configure Heeler

In Hosts > Add Host, tap Add Route under Routes to enter the tunnel and Jump Host fields, tap Save on the route page, and fill in the remaining Host fields:

Tap Save on Add Host to start the Preflight checks, and confirm both host keys independently:

• the public VPS endpoint;
• the Mac host key presented through 127.0.0.1:2222.

The Jump Host does not make the Mac trusted. A changed fingerprint on either hop is a separate security event.

Phase 1: Prepare the New VPS in Parallel

1. Patch the operating system and install the maintained OpenSSH server.

2. Confirm the VPS host-key fingerprint through its provider console:

   Terminal

   Copy code

   sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

3. Allow only the VPS SSH port in the provider firewall. Do not open the reverse-forward port.

4. Create fresh restricted tunnel and Jump accounts.

5. Generate a new tunnel key for the new VPS. Do not reuse the old VPS tunnel key.

6. Authorize the existing Heeler Device Key on the new Jump account. The Device Key may remain the same because its private half never leaves iOS.

7. Apply the sshd_config restrictions and validate them with sshd -t and sshd -T.

The old VPS and its tunnel remain untouched during this phase.

Phase 2: Stage a Separate Mac Path

Create new Mac aliases rather than editing the old aliases:

new-vps-tunnel
new-vps-jump
new-mac

Create a second LaunchAgent with:

• a different label;
• the new tunnel identity;
• the new VPS alias;
• separate log files.

The same loopback port may be used on two different VPSs. If the new path shares one VPS with another Mac, allocate a unique port instead.

Start the new tunnel and validate:

ssh new-mac

On the new VPS:

sudo ss -ltnp | grep ':2222'

Confirm the listener is exactly 127.0.0.1:2222, then terminate the new tunnel process once and prove the new LaunchAgent reconnects.

Phase 3: Move Heeler

Open the Host in Heeler, tap Edit, open the route under Routes (or add a new route), and update only the Jump Host fields:

The route target and Host user remain:

Tap Save on the route (if adding a new route) and tap Save on Edit Host. Confirm the new VPS fingerprint when prompted, then complete the Preflight checks and open an Agent through Attach. This is the functional cutover point.

Phase 4: Retire the Old VPS

Only after the new path has passed command-line and app validation:

1. Stop and unload the old LaunchAgent.
2. Confirm the new LaunchAgent remains healthy.
3. Remove old SSH aliases and the old VPS host-key entry from the Mac.
4. Remove the Device Key from the old Jump account.
5. Remove the old tunnel public key and restricted accounts.
6. Close the old VPS firewall rules or destroy the old VPS.

Keep a short rollback window when practical, but do not leave two forgotten public Jump Hosts running indefinitely.

If remote port forwarding failed for listen port 2222 appears during a cutover, inspect tunnel ownership before changing security policy. It usually means two tunnel processes are competing for the same listener on one VPS. Never solve it by enabling GatewayPorts yes or publishing another unrestricted port.