Onboard a Gateway

Onboarding a gateway takes three steps: Register, Install and Verify.

You need a Linux machine that operators can reach on port 2222 and that can reach your endpoints.

1. Choose Switch product → PAM and select Gateways in the sidebar.
2. Click Onboard gateway. The Onboard a Gateway dialog opens.

Step 1: Register

Field	Value
Gateway name	A name for the gateway, for example prod-bastion
Address operators connect to	The host name or IP address operators use in their ssh command. Behind NAT, this is the public address
Listen port	2222. It cannot be changed

Click Create & continue.

Step 2: Install

1. On the gateway machine, run the installer:

   wget https://raw.githubusercontent.com/authnull0/windows-endpoint/main/sshproxy/install.sh
   sudo bash install.sh

2. In the dialog, click Download console.env.

3. Copy the file to the gateway machine and restart the service:

   sudo cp ~/Downloads/console.env /etc/authnull/sshproxy/console.env
   sudo systemctl restart authnull-sshproxy

warning

• Copy the file to console.env. Do not overwrite /etc/authnull/sshproxy/sshproxy.env. That file belongs to the installer.
• Run the copy after the installer. The folder does not exist before.
• console.env is a secret. It holds this gateway's client credentials. Delete your downloaded copy once it is in place.

The dialog waits for the gateway's first heartbeat. When it arrives, the dialog shows the gateway's host-key fingerprint. Share it with operators so they can check it the first time they connect.

No heartbeat? On the gateway machine, run:

systemctl status authnull-sshproxy
journalctl -u authnull-sshproxy -n 30

Check that console.env is in the right place and that the machine can reach the AuthNull server.

The usual causes are:

• The service never started: almost always a missing SSHPROXY_ORG_ID.
• SSHPROXY_CONTROL_URL unset: SSH works, but the console never hears from the gateway.
• SSHPROXY_INTERNAL_API_KEY does not match the stack's INTERNAL_API_KEY.

Step 3: Verify

This step shows what the gateway reports:

Field	Shows
Liveness	Whether the gateway is live
Last heartbeat	When it last checked in
Version	The gateway software version
Listening on	The address and port it listens on
Seen from	The address its heartbeats come from
Fingerprint	The gateway's host-key fingerprint

Click Finish. The gateway shows as Online on the Gateways list.

Enrol Machines

A new gateway reaches no endpoints yet. On the Gateways list, open the gateway's row menu and choose Enrol machines. This leads to adding endpoints behind the gateway. See Add an Endpoint.

You can also start from Targets → Endpoints → Add endpoint and pick the gateway there.

note

With no matching policy, every session through the gateway is refused. After adding endpoints, create a policy.

Optional: Restrict Which Targets a Gateway May Reach

Policies already decide who can reach which host and account. You can add an extra local bound on the gateway with SSHPROXY_BACKEND_ALLOWLIST in its env file: anything not listed is refused even if a policy grants it. Each entry is a host or host:port (no CIDR ranges). Changing it needs a restart of authnull-sshproxy, which drops live sessions.