Skip to main content

How to Onboard a Gateway?

Onboard a Gateway​

A gateway is AuthNull's SSH jump server (see Gateways). Onboarding is a one-time setup in three steps: Register, Install and Verify.

You need a Linux jump box that operators can reach over SSH and that can reach your endpoints.

  1. In the admin console, open Switch product → PAM and select Gateways in the sidebar.
  2. Click Onboard gateway in the top right corner. The Onboard a Gateway dialog opens.

Step 1: Register​

Fill in these fields:

Gateway name -> A name for the gateway, for example prod-bastion (required) Address operators connect to -> The host name or IP address operators use in their ssh command (required). Behind NAT this is the public address, not the machine's own IP. Listen port -> 2222 (fixed)

Click Create & continue. The console creates the gateway record and shows "Gateway created".

Step 2: Install​

  1. On the jump box, run the installer:

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

  2. Back in the dialog, click Download console.env.

  3. Copy the file to the jump box and restart the service:

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

    • Copy it to /etc/authnull/sshproxy/console.env, not over /etc/authnull/sshproxy/sshproxy.env. That file belongs to the installer and holds the key that signs session recordings.
    • Run the copy after the installer. The /etc/authnull/sshproxy/ folder does not exist until then.
    • console.env is a secret: it carries the gateway's internal API key. Delete your downloaded copy once it is on the jump box.

  4. Wait for the gateway's first heartbeat. The dialog checks automatically and moves on when the gateway reports in. Once it does, the dialog shows the gateway's host-key fingerprint. Use Copy fingerprint and share it with operators so they can verify the gateway the first time they connect.

Not seeing a heartbeat? On the jump box run:

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

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​

When the gateway is live, this step shows what the gateway reports about itself: Liveness, Last heartbeat, Version, Listening on, Seen from and the host-key fingerprint.

Click Finish. The gateway's page opens, and the gateway appears on the Gateways list as Online.

Before anyone can connect​

A new gateway has no policy, and the gateway refuses any session that no policy covers. Before operators can connect:

  1. Onboard your machines. Either:
    • add one at a time from Targets → Endpoints → Add endpoint → Linux server (via SSH gateway), choosing this gateway in the Gateway field, or
    • enrol many at once from the gateway row's ⋯ → Enrol machines. This creates an enrolment command you run on each machine (by hand, Ansible, cloud-init or SSM). Machines then appear under Endpoints by themselves.
  2. Write a policy. Under Policies, create a policy that names the person, the host and the account. A policy that leaves accounts empty grants nothing.
  3. Connect. See How to connect to an endpoint through a gateway.

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.