📣 Upcoming Breaking Change to NetBird SSH

Announcements Community News
1

Hey folks,

We’d like to announce a major change to NetBird’s SSH feature. The changes, introduced in PR 4015, will be the first non-backward compatible client change and will be released with the next major version (most likely v0.69.0).

What’s Changing?

We’re introducing several new SSH features and enhancements:

  • Native Client Support: Support for native OpenSSH clients.
  • Windows Support: Full support for both client and server on Windows.
  • SFTP Support: You can now use SFTP and SCP.
  • Port Forwarding: Limited support for port forwarding has been added.
  • Most importantly, NetBird SSH authentication is being upgraded from machine identity (public key auth via the private key in the NetBird config) to user identity (authentication via IdP login).

How Are You Affected?

:warning: This is a breaking change, which means new and old versions are incompatible.

  • New NetBird SSH clients will not work with the old NetBird SSH server.
  • New NetBird SSH servers will not work with old NetBird SSH clients.
  • NetBird SSH authentication will require JWT authentication (login via your IdP) by default.
  • The old implicit inbound access control policy for TCP port 44338 will be removed.
  • The SSH server will now take over TCP port 22 (redirected to 22022) for traffic coming from the NetBird network when enabled and will require an explicit policy allowing the port access.
  • The browser-based SSH client in the dashboard will remain compatible with both old and new clients.

What’s the Migration Process?

  1. (Self-hosted only) Update the management server first.
  2. (Self-hosted only) Update the dashboard (this is only necessary if you use the browser-based SSH client).
  3. Add a new access control policy allowing NetBird SSH clients to access NetBird SSH servers on the new destination port, TCP/22022.
  4. Update the NetBird peers that are running the NetBird SSH server.
  5. Update the NetBird peers that you use to access these servers via netbird ssh.

If you do not want to use JWT authentication, you can disable it and allow access from any peer with network access by running the following command: netbird up --disable-ssh-auth
Updated documentation will follow shortly.
We understand that breaking changes may not be ideal, as they require you to be more mindful about when to update your clients. However, we believe these changes are necessary, given that the feature was not yet in a production-ready or widely usable state.

That said, we’d appreciate your input—please let us know if there’s anything we might have missed or if you have any additional concerns.

Slack Post: Slack

1 Like