Skip to content

network.md

Latest commit

 

History

History
75 lines (56 loc) · 3.28 KB

network.md

File metadata and controls

75 lines (56 loc) · 3.28 KB
Raw

net - connection status & VPN awareness

Some hosts are only reachable over a VPN (a campus/corporate git server, a private VPS, a host on an HTTPS-style port like :443). Without the VPN those hosts don't just fail - a naive ssh can hang on the banner exchange. authama makes every network action reachability-aware so it fails fast with an actionable message instead of hanging, and gives you a status indicator you can check first.

Mark a host as VPN-gated

Add requires_vpn (and optionally vpn_name) to the host in the manifest:

{"alias": "hpc", "hostname": "hpc.example.edu", "user": "researcher", "port": 443,
 "key_name": "work_hpc-ed25519",
 "requires_vpn": true, "vpn_name": "Campus VPN", "vpn_url": "https://vpn.example.edu"}

view <alias> then shows a reminder, and any unreachable network action names the VPN (and links its vpn_url if set).

authama ssh net [selector]

Shows the connection status of every host (filter by alias, profile, or key), plus a VPN/tunnel indicator:

authama ssh net
# PROFILE  HOST        ADDRESS              STATUS     NOTE
# work     hpc         hpc.example.edu:443   ○ offline  needs VPN (Campus VPN)
# personal github.com  github.com:22        ● online
# ...
# VPN/tunnel interface: detected

Exit code is non-zero if a requires_vpn host is unreachable, so it works as a pre-flight gate in scripts. The check is a fast TCP probe; it never changes anything. Hosts are probed up to eight at a time, so a few unreachable hosts cost one timeout (4 seconds), not one each; rows keep the manifest's order.

In the web UI

Check connections, on the Overview and Hosts pages, runs ssh net and shows each host's status in the command's own words, with a warning when a host that needs a VPN does not answer (the case that makes the command exit non-zero). A host's page has Check connection for that host alone (ssh net <alias>). The result opens in the side panel, and Check again probes the same hosts again.

No page probes as it loads; only the check does, when you ask, so the pages never wait on the network. The check takes a host alias or a profile name from the manifest, nothing else, and a read-only server offers it too, since it writes nothing.

Fail-fast on every network action

deploy and rotate run a bounded reachability probe before touching the network:

  • Unreachable host -> the action stops immediately with <host>:<port> unreachable - this host requires a VPN (<name>); connect it and retry (for a requires_vpn host) or a generic "check your network connection" message. Nothing is staged or changed.
  • The probe is SSH-level: a VPN-gated host that accepts the TCP connection on :443 but never speaks SSH is detected as unreachable (a plain ssh would hang there - ConnectTimeout only covers the TCP connect, not the banner).
  • As a backstop, every underlying ssh / ssh-copy-id call is bounded by a hard timeout, so no network operation can hang indefinitely.

So if you forget the VPN, authama ssh rotate work_hpc-ed25519 returns in a few seconds with "cannot rotate - ... requires a VPN (Campus VPN); connect it and retry" rather than wedging your terminal.

See also deploy, rotate, vps.

← Docs index