XSSG / ENGINEERING / PREVENT SSH LOCKOUT

SSH LOCKOUT PREVENTION / RECOVERY BY DESIGN

Harden SSH. Keep a way back in.

Avoid SSH lockouts during firewall and sshd changes. Understand preflight tests, approved subnets, independent login checks and rollback limitations.

THE SHORT ANSWER. To reduce the risk of an SSH lockout, establish a working recovery path before disabling password login or changing firewall rules. Validate the new key from a separate connection, review allowed source networks, test sshd configuration, keep console access available, and confirm a rollback mechanism is armed before applying restrictions.

Why do SSH lockouts happen?

The server may be healthy while the administrator is stranded. A firewall can accept the wrong source subnet; an SSH configuration may disable the only working authentication method; a VPN path may have a different address than the local network; or a fresh connection may fail even while an existing session stays open. A syntactically correct configuration is not proof that the operator can still reach the machine.

The Raspberry Pi documentation explicitly cautions operators to allow remote access before enabling UFW. Ubuntu's OpenSSH guidance similarly advises checking the server configuration before restart, because losing SSH may mean losing server access.

What to check before changing SSH or UFW

Record the SSH service port, gateway account, present authentication policy, current authorized-keys state, and existing firewall allowances. Confirm the exact network source from which you will reconnect. Someone using both a home LAN and a VPN might need to review multiple CIDR ranges. The two paths should be tested separately; a positive local test does not prove a VPN connection will work.

For the OpenSSH daemon, the documented sshd -t validates configuration syntax and host-key sanity, while sshd -T reports effective settings. Context-sensitive Match rules may require connection-specific inputs, so a single output should not be mistaken for a universal guarantee. See the upstream sshd manual.

The reversible-change sequence

  1. Leave your current session open. Do not use that session as the only proof of future access.
  2. Verify the recovery key independently. Demonstrate a fresh connection using the actual restored key and expected account.
  3. Stage rollback before a risky edit. Confirm what will be restored, when the watchdog will act, and what it cannot cover.
  4. Apply reviewed rules in the intended order. Allow the desired source networks before introducing a deny policy that could block the operator.
  5. Start a new SSH connection. Confirm actual authentication and source-route behavior, then explicitly commit only after the proof passes.

This is a mental model and evaluation checklist, not an instruction to edit a production firewall blindly. Never tighten access remotely without an independently reachable console or other recovery option.

How XSSG approaches rollback

The documented beta stages SSH and UFW changes as a guarded operation and prepares a systemd-backed rollback mechanism. Its sequence checks recovery and new login success before committing. That is different from merely saving a copy of sshd_config; a useful rollback must be pre-armed and capable of running when the original controller is no longer connected.

There is an important evidence boundary: the current security claims record does not establish that a deliberately induced lockout has been recovered by timed rollback across every relevant failure mode. Power loss, firewall policy conflicts, external network failures and host-specific service changes can exceed any one rollback mechanism.

Practical principle.

A successful SSH login from one network does not prove that unauthorized networks are denied. Positive and negative connection tests, plus effective configuration inspection, answer different questions.

What should the post-change receipt contain?

A useful receipt identifies the host and test context, notes the tested authentication method, records relevant firewall and sshd state, and distinguishes what was measured from what was assumed. It should not expose private keys, passwords or tokens. XSSG's recovery-first method is built around these separately testable steps.

Read the operator manual, understand encrypted recovery vaults, and review the FAQ before attempting privileged changes.

Explore the system, not just the slogan.

See the operator manual, documented security limits, complementary tools, and the Coming Soon release page.

XSSG / TECHNICAL GUIDE

SSH key management

From the first key to independently verified recovery

Read this guide →
XSSG / TECHNICAL GUIDE

Encrypted SSH key backup

Understand per-gateway vaults, secret separation and restoration proof

Read this guide →
XSSG / TECHNICAL GUIDE

Raspberry Pi SSH security

Key-first homelab security without invented board support

Read this guide →