netbird-docs/PROFILE-OWNERSHIP-PREVIEW.md

Daemon IPC authorization and profile ownership (preview)

Status: preview of unreleased changes in netbirdio/netbird#7407 and netbirdio/netbird#7704. This file exists to support early testing of the behavior.

Contents

• What changes
• Profile ownership and daemon access
  • How the daemon identifies a caller
  • Access levels
  • Profile ownership
  • Upgrade from an earlier version
  • Environment variables
  • Restrict daemon access to a group
• Daemon sockets: TCP is deprecated
• Troubleshooting
• Configuration reference changes
• Report a problem

What changes

What	Before	After
Daemon authorization	Any local user with socket access could read status and configuration and perform every operation that did not require privileges. Only the SSH-related operations were gated on root or administrator (since 0.76.0).	The daemon identifies every caller from the operating system and applies four access levels: Identified, Profile owner, Session holder, Privileged.
Profile ownership	Profiles recorded no owner.	Each profile records one owner (uid:<id> on Linux and macOS, sid:<SID> on Windows). Only the owner, or a privileged user, can use it.
Active connection	Any local user could disconnect or switch profiles.	The connection belongs to the user who started it. Other users cannot connect, disconnect, or switch profiles until it stops. sudo netbird down stops it.
netbird profile list	Listed every profile.	Lists only the profiles you own. New --show-owner flag.
netbird profile claim	Did not exist.	New privileged subcommand that assigns an owner to a profile.
Profile storage	New profiles were stored under <state-dir>/<username>/<id>.json.	New profiles are stored under <state-dir>/profiles.v1/<id>.json. Profiles from earlier versions stay in their per-user directory and are migrated in place.
TCP daemon sockets	tcp://host:port was a supported address for --daemon-addr and --json-socket. Only privileged operations were refused on it.	TCP is deprecated and the daemon refuses every request on a TCP socket. Use unix:// on Linux and macOS, or npipe:// on Windows.
Socket access restriction	Not available. The documented workaround was a custom socket in a restricted directory.	New --allow-group service flag and allowGroups MDM policy key restrict who can connect to the daemon sockets at the operating-system level.
Environment variables	N/A	NB_DISABLE_PROFILE_OWNERSHIP and NB_DISABLE_DEFAULT_PROFILE_CLAIM.
MDM policy keys	20 keys.	21 keys. Adds allowGroups.
Debug bundle	No profile inventory.	Includes profiles.txt and active_profile.json.

Profile ownership and daemon access

The NetBird daemon runs as root, or as LocalSystem on Windows. Each local user can connect to its socket. Without a check, one user can read or change the profile of another user, or stop that user's connection.

To prevent this, the daemon identifies each caller and gives each profile an owner. A user can use only the profiles that they own. A connection belongs to the user who started it.

How the daemon identifies a caller

The daemon gets the identity of the caller from the operating system, not from the request. It reads the identity from the kernel: SO_PEERCRED on Linux, LOCAL_PEERCRED on macOS, and the named-pipe client token on Windows. If the daemon cannot identify the caller, it refuses the request.

A TCP socket does not carry an identity, so the daemon refuses every request on it. See Daemon sockets: TCP is deprecated.

Access levels

The daemon gives each request one of four access levels. Each level can do all the operations of the levels above it in this table.

Level	Who	Operations
Identified	Any user that the daemon can identify	Read basic status. List your profiles. Add a profile.
Profile owner	The owner of the profile	Read and change the profile configuration. Rename, remove, or deregister the profile.
Session holder	The owner of the active profile and the connection is up	Disconnect. Log in. Switch profiles. Select networks. Read detailed status. Create a debug bundle.
Privileged	Root, an elevated administrator, or the user that the daemon runs as	All operations on all profiles. Claim a profile.

The daemon lets the user that it runs as act as a privileged user only when the daemon itself is not privileged. An example is a rootless container.

Operations that decide who may obtain a shell on the machine are refused unless the caller is root, or an administrator on Windows. See privileged operations.

Commands and required access

Command	Required level
netbird status	Identified. Detailed status requires session holder.
netbird profile list, netbird profile add	Identified
netbird profile rename, netbird profile remove, netbird deregister	Profile owner
netbird up, netbird down, netbird login, netbird profile select	Session holder
netbird debug bundle	Session holder
netbird profile claim	Privileged

Profile ownership

Each profile records one owner. On Linux and macOS, the owner is a user ID, for example uid:1000. On Windows, the owner is a security identifier (SID), for example sid:S-1-5-21-....

When you add a profile, you become its owner. Root and administrators can see and use all profiles.

Warning: If you add a profile with sudo, root becomes the owner. Run netbird profile add as your own user.

List profiles

netbird profile list shows only the profiles that you own:

netbird profile list

NAME     ACTIVE
work     *
default
home

A * in the ACTIVE column marks the active profile. Inactive profiles are left blank. Earlier versions marked the active profile with ✓.

To show the ID of each profile, add --show-id:

netbird profile list --show-id

ID        NAME     ACTIVE
a1b2c3d4  work     *
default   default
e5f6a7b8  home

To show the owner of each profile, add --show-owner:

sudo netbird profile list --show-owner

NAME     ACTIVE  OWNER
default  *       alice
work             bob
lab              unowned

Connections of other users

When a user connects, the active profile and its connection belong to that user. Other users cannot connect, disconnect, or switch profiles until the connection stops. To stop the connection of another user, run:

sudo netbird down

Claim a profile

The profile command gains a claim subcommand:

netbird profile <add|list|select|rename|remove|claim> [name|handle]

To give a profile an owner, run netbird profile claim as root or as an administrator:

sudo netbird profile claim <profile> --owner <owner>

The <owner> value is an account name, a uid:<id> value, or a sid:<SID> value. The daemon does not check that a uid or sid value belongs to an existing account.

On Linux and macOS, if you do not set --owner, the owner is the user who ran sudo. If you run the command in a root shell without sudo, --owner is required. On Windows, --owner is required.

Upgrade from an earlier version

Earlier versions kept profiles in one directory for each user, for example /var/lib/netbird/<username>/, and recorded no owner. When the new daemon starts for the first time, it migrates these profiles. Your profiles stay in their directories.

The migration does these steps:

1. Gives a new unique ID to profiles that have the same ID in different user directories.
2. Records the owner of the profiles of the last active user and of the default profile.
3. Creates the profiles.v1 directory in the state directory. This directory shows that the migration is complete.

If the migration fails, the daemon writes the error to the log and tries again at the next start. The daemon saves new profiles in the profiles.v1 directory.

Automatic claims

After the migration, some profiles can still have no owner. The daemon gives them an owner when a user sends a request:

• Profiles in a user directory. The daemon records the user whose name matches the directory as the owner.
• Default profile. The daemon records the first user who is logged in at the console of the device as the owner. A console is a local graphical session, or a local seat on Linux. A user in a remote SSH or RDP session is not at the console.

Root and administrators never become owners through an automatic claim.

On a device with no console, for example a headless server, the default profile keeps no owner. Only root and administrators can use it. To give it an owner, run:

sudo netbird profile claim default --owner <owner>

Environment variables

Set these variables on the daemon. For instructions, see Client environment variables.

Variable	Platform	Description
NB_DISABLE_PROFILE_OWNERSHIP	Linux, macOS, Windows, FreeBSD	Set to true to turn off profile ownership. All identified local users can use all profiles and control all connections. Android and iOS always work this way.
NB_DISABLE_DEFAULT_PROFILE_CLAIM	Linux, macOS, Windows, FreeBSD	Set to true to stop the automatic claim of the default profile. The default profile then has no owner until an administrator runs netbird profile claim.

Warning: NB_DISABLE_PROFILE_OWNERSHIP removes the isolation between local users. Use it only on a device with one user or for legacy use cases.

Restrict daemon access to a group

By default, all local users can connect to the daemon socket. To let only one group connect, set --allow-group when you install the service:

sudo netbird service install --allow-group netbird-users

The operating system then refuses connections from users outside the group. This flag replaces the earlier recommendation to place a custom socket inside a restricted directory.

• On Linux and macOS, you can set only one group. The value is a group name or a group ID.
• On Windows, you can set a comma-separated list of groups or accounts. LocalSystem, elevated administrators, and the account that the daemon runs as always keep access.
• netbird service reconfigure resolves the names again.
• To remove the restriction, run sudo netbird service reconfigure --allow-group "".

Note: A TCP socket cannot carry the restriction. If you set --allow-group for a daemon on a TCP socket, the daemon does not start.

Set allowed groups with MDM

On managed Windows and macOS devices, use the allowGroups MDM policy key. On Windows, the Group Policy name is Restrict the daemon sockets.

• The MDM value replaces the --allow-group value. An empty value removes a restriction that the installer set.
• On macOS, set exactly one group ID, for example gid:1001.
• On Windows, set a comma-separated list of SIDs, for example sid:S-1-5-21-....
• Use IDs, not names. The daemon reads this value when it starts. It waits a maximum of 5 seconds to resolve names.

Warning: If the daemon cannot read the MDM policy or resolve the value, it does not start. This behavior prevents an open socket on a device that must be restricted.

Daemon sockets: TCP is deprecated

These changes apply to both the gRPC daemon socket and the HTTP/JSON daemon socket.

Supported address formats

The --daemon-addr option accepts these formats:

unix:///path/to/netbird.sock
npipe://name

The tcp://host:port format is deprecated. A future release removes it.

A TCP connection does not carry a caller identity. The daemon cannot identify the caller, so it refuses every request on a TCP socket. Use a Unix socket on Linux and macOS, or a named pipe on Windows.

Before this change, the daemon accepted requests on a TCP socket and refused only the privileged operations. After this change, every request on a TCP socket is refused.

Migrate a service that uses a TCP socket

If your service uses a TCP socket for the gRPC daemon socket, change it to the default address:

sudo netbird service reconfigure --daemon-addr unix:///var/run/netbird.sock

On Windows, use --daemon-addr npipe://netbird.

If the HTTP/JSON gateway uses a TCP socket, change --json-socket to a Unix socket:

sudo netbird service reconfigure \
  --enable-json-socket \
  --json-socket unix:///var/run/netbird-integration-http.sock

Troubleshooting

Profile ownership

Another user has this machine connected

Symptom: A command fails with a message that says another user has the machine connected.

Cause: Another user started the current connection.

Fix: Ask that user to disconnect, or run sudo netbird down.

The profile belongs to another user

Symptom: A command fails with a message that says the profile belongs to another user.

Cause: You do not own the profile.

Fix: Use a profile that you own. Or, ask an administrator to run sudo netbird profile claim <profile> --owner <your-user>.

The profile has no owner on record

Symptom: A command fails with a message that says the profile has no owner on record.

Cause: The profile was not claimed. This is usual on a device with no console, or when you connect over SSH.

Fix: Run the netbird profile claim command that the error message shows.

A headless machine cannot use the default profile

Symptom: On a server or other device with no console, a regular user cannot connect after a new install or an upgrade.

Cause: No user is logged in at the console, so the daemon cannot claim the default profile automatically. This happens both during the migration and on a new install. See Automatic claims.

Fix: Claim the default profile once as root or as an administrator:

sudo netbird profile claim default --owner <owner>

A profile is missing from the profile list

Cause: netbird profile list shows only the profiles that you own.

Fix: To see all profiles and their owners, run sudo netbird profile list --show-owner.

Detailed status is unavailable

Symptom: netbird status shows Detailed status is unavailable: the connection belongs to another user.

Cause: Another user holds the connection. You can see only the daemon status.

Daemon sockets

A client receives an Unavailable or connection-refused error

Confirm that the daemon is running and that the integration uses the same socket address as the service. For a Unix socket, also verify access to the socket and each parent directory. If the address uses tcp://, see A TCP request is refused.

A call is refused with PermissionDenied (gRPC) or 403 (HTTP/JSON)

The operation is one of the privileged operations and the caller is not root, or not an administrator on Windows. Check the ErrorInfo detail on the error: PRIVILEGE_REQUIRED in domain daemon.netbird.io means the daemon identified the caller and refused the change, rather than failing to reach it.

A TCP request is refused

TCP sockets are deprecated, and the daemon refuses every request on them. Change --daemon-addr to a Unix socket or a named pipe, and --json-socket to a Unix socket. See Migrate a service that uses a TCP socket.

The daemon does not start after you set allowed groups

Possible causes:

• A group name does not resolve.
• You set more than one group on Linux or macOS.
• The daemon or the JSON socket uses a TCP socket.
• The daemon cannot read the MDM policy.

Fix: Read the daemon log. The log shows which of these causes stopped the daemon.

Collect information for support

A debug bundle includes profiles.txt and active_profile.json. These files show each profile, its owner, and the active profile. For instructions, see Troubleshooting client issues.

Configuration reference changes

These changes update existing reference pages. Each entry links to the section above that describes the behavior.

Client environment variables

Two variables are added to the Other table of the Client environment variables reference. See Environment variables.

Variable	Platform
NB_DISABLE_PROFILE_OWNERSHIP	Linux, macOS, Windows, FreeBSD
NB_DISABLE_DEFAULT_PROFILE_CLAIM	Linux, macOS, Windows, FreeBSD

MDM policy key

The MDM integration policy keys reference grows from 20 to 21 keys with the addition of allowGroups. As with the other keys, the name is camelCase in the managed-configuration payload and the Windows ADMX template renders the PascalCase variant.

Key	Type	Description
allowGroups	string	Let only the listed groups connect to the daemon socket. Overrides --allow-group. An empty value removes the restriction. On macOS, set one gid:<id> value. On Windows, set comma-separated sid:<SID> values. See Restrict daemon access to a group.

Service flag --allow-group

New flag on netbird service install and netbird service reconfigure. See Restrict daemon access to a group.