⚠️ Upcoming breaking Changes to NetBird SSH

Announcements
1

Hey folks,

We’d like to announce another (upcoming) major change to NetBird’s SSH feature. These changes will introduce fine-grained access control for SSH, allowing you to specify exactly which users can access which peers and which OS accounts they can log into. This will be the second breaking change to SSH and will be released with an upcoming version.

What’s Changing?

v0.61.0 will introduce fine-grained SSH access control:

  • Per-User Authorization: Instead of account-level SSH enabled/disabled, you can now specify exactly which users are authorized to SSH into each peer.
  • OS User Mapping: Control which NetBird users can log in as which OS usernames (e.g., allow user A to log in as root, but user B only as deploy).

How Are You Affected?

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

  • New peers expect the management server to send an SSHAuth structure containing authorized user lists and OS user mappings.
  • An older management server won’t send this data.
  • The new client uses a fail-closed security design - if authorization data is missing, all SSH connections are denied.
  • If you update peers before the management server, SSH will stop working.

What’s the Migration Process?

  1. Update NetBird peers.
  2. (Self-hosted only) Update the management server.
  3. (Self-hosted only) Update the dashboard

Detailed process here: SSH Access - NetBird Docs

We understand that breaking changes require you to be more mindful about when to update your clients. However, we believe these changes are necessary to provide proper access control for SSH, allowing admins to define exactly who can access what.

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.

1 Like