Engineering & AI

NetBird: SSH into staging over a private network

NetBird creates a private network so operations teams can grant and revoke SSH access by group and reach staging without opening a public SSH port.

Summary

  • Use the server’s NetBird address to reach staging remotely without a public SSH port.
  • Allow TCP 22 by group. Check the Default policy if a laptop outside the group still reaches OpenSSH.
  • Close the public SSH port after testing from both an allowed laptop and one outside the group.
NetBird: SSH into staging over a private network

If your team needs remote SSH access to staging, try NetBird with one server and two laptops. The on-call laptop should be able to open an SSH session at the server’s NetBird address. The other laptop should be on the same private network and unable to reach staging’s SSH port. Once both tests behave as expected, you can close the public SSH port. NetBird repository · Groups and access policies

This review draws on the official documentation and release notes for v0.83.2. The steps are a test scenario you can run on your own staging environment. Release notes

From the on-call laptop to staging

Suppose the on-call engineer moves between home and office Wi-Fi. Once NetBird reconnects, they can use the same NetBird address for staging. The devices exchange traffic over WireGuard. If they cannot connect directly, NetBird forwards encrypted traffic through a relay. Run netbird status --detail to see whether the connection to staging is P2P or Relayed. How NetBird works · CLI documentation

Access has two layers. NetBird determines which laptops can reach TCP port 22. OpenSSH on staging still checks the account and SSH key. If the laptop outside the group gets Permission denied from OpenSSH, it made it through the network layer. Check the NetBird policies before calling the network test a pass. Groups and access policies

Why can another laptop still connect after you narrow access?

New NetBird environments have a Default policy that lets devices in the All group connect to one another. Adding a rule for the on-call group leaves the original policy in effect. In the test environment, create the replacement policy first, then disable Default and try again from the laptop outside the group. Default policy

Test one server before closing the public port

  1. Keep a way back in. Choose one staging server running OpenSSH and two laptops you manage. Keep the existing console or bastion available in case the firewall change causes a problem.
  2. Join all three devices to NetBird. Install the client on both laptops. You can enroll the server with a one-time setup key. Install NetBird · Setup keys
  3. Grant access to the on-call laptop. Put it in the source group and the staging server in the destination group. Allow one-way TCP 22 from source to destination. Use the actual port if OpenSSH listens on another one. Disable Default in the test environment after the replacement policy is in place. Groups and access policies
  4. Open two new connections. From the allowed laptop, run ssh <user>@<netbird-ip> and confirm sign-in works. Try the same address and port from the laptop outside the group. The second connection should be blocked before SSH authentication.
  5. Close the public SSH port. Once both tests pass, remove public SSH access from the firewall that applies to staging. From an external network, verify the public IP no longer accepts SSH connections. Then open a fresh SSH session over the NetBird address to confirm you still have access.

When is it worth adopting?

NetBird is worth trying if on-call engineers often change networks or your team needs to grant access to specific groups of servers. Each participating laptop needs the client. NetBird Cloud lets you start without running the management service. If you self-host, your team handles the domain, TLS, updates and backups. Self-hosting guide

If your team already uses a bastion, pick one task to compare, such as how long it takes to grant access to a new on-call engineer. Check the team’s existing SSH logging requirements during the pilot. Expand once you can grant and revoke access, reach the server through a fallback path and get the expected result from both access tests.

Terms in this article (5)
NetBird
An open-source platform for private connections between devices and group-based access.
WireGuard
A VPN protocol that encrypts traffic between two endpoints.
Relay
A server that forwards encrypted traffic when two devices cannot connect directly.
Setup key
A key that enrolls a machine in NetBird without an interactive sign-in.
Bastion
A managed entry point that operators use to reach internal systems.

Frequently asked questions

Does NetBird need public port 22?

No. The laptop reaches SSH at the NetBird address. The server firewall still needs to allow SSH traffic from the NetBird network.

Do we have to change our existing SSH keys?

In this setup, OpenSSH still authenticates accounts with their existing keys. NetBird determines which devices can reach the SSH port.

Does NetBird still encrypt traffic when it uses a relay?

Yes. WireGuard encrypts traffic between the two endpoints. The relay forwards encrypted packets.

Sources

Talk with HubCom ↗