sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-10-16 18:49:04 +02:00
Code Issues Packages Projects Releases Wiki Activity

Adjust preview documentation

Browse Source
This commit is contained in:
Theodor S. Midtlien
2026-10-08 12:03:22 +02:00
parent aed305ac11
commit 0ab64d421c
1 changed files with 147 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PROFILE-OWNERSHIP-PREVIEW.md
+147 -260
View File
@@ -1,50 +1,38 @@
# Profile ownership and daemon access (preview)
# Daemon IPC authorization and profile ownership (preview)
> **Status: preview of unreleased client behavior.** This file consolidates every
> documentation change proposed in [netbirdio/docs#998](https://github.com/netbirdio/docs/pull/998),
> which documents the client changes in
> [netbirdio/netbird#7407](https://github.com/netbirdio/netbird/pull/7407).
> Both pull requests were open and unmerged when this file was written. The file
> exists to support early testing of the behavior. It is not part of the published
> documentation, it is not linked from the site navigation, and it will be removed
> once the pages land.
Rendered preview of the proposed pages: <https://docs-git-ipc-authz-profile-ownership-net-bird-77c7f821.vercel.app/client/profile-ownership>
Links in this file point to the published documentation at <https://docs.netbird.io>
for pages that already exist, and to sections of this file for content that the
pull request adds.
> **Status:** preview of unreleased changes in
> [netbirdio/netbird#7407](https://github.com/netbirdio/netbird/pull/7407) and
> [netbirdio/netbird#7704](https://github.com/netbirdio/netbird/pull/7704).
> This file exists to support early testing of the behavior.
## Contents
- [What changes at a glance](#what-changes-at-a-glance)
- [What changes](#what-changes)
- [Profile ownership and daemon access](#profile-ownership-and-daemon-access)
- [How the daemon identifies a caller](#how-the-daemon-identifies-a-caller)
- [Access levels](#access-levels)
- [Profile ownership](#profile-ownership)
- [Restrict daemon access to a group](#restrict-daemon-access-to-a-group)
- [Environment variables](#environment-variables)
- [Upgrade from an earlier version](#upgrade-from-an-earlier-version)
- [Troubleshooting profile ownership](#troubleshooting-profile-ownership)
- [Environment variables](#environment-variables)
- [Restrict daemon access to a group](#restrict-daemon-access-to-a-group)
- [Daemon sockets: TCP is deprecated](#daemon-sockets-tcp-is-deprecated)
- [Profiles: storage layout and CLI changes](#profiles-storage-layout-and-cli-changes)
- [Troubleshooting](#troubleshooting)
- [Configuration reference changes](#configuration-reference-changes)
- [Verification checklist for early testers](#verification-checklist-for-early-testers)
- [Files changed by the pull request](#files-changed-by-the-pull-request)
- [Report a problem](#report-a-problem)
## What changes at a glance
## What changes
| Area | Before | After |
| 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. The active profile was marked with `✓`. | Lists only the profiles you own. The active profile is marked with `*`. New `--show-owner` flag. |
| `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 | None for this area. | `NB_DISABLE_PROFILE_OWNERSHIP` and `NB_DISABLE_DEFAULT_PROFILE_CLAIM`. |
| 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`. |
@@ -56,11 +44,9 @@ To prevent this, the daemon identifies each caller and gives each profile an own
### How the daemon identifies a caller
The daemon gets the identity of the caller from the operating system, not from the request. If the daemon cannot identify the caller, it refuses the request.
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.
The identity is read from the kernel rather than supplied by the client: `SO_PEERCRED` on Linux, `LOCAL_PEERCRED` on macOS, and the named-pipe client token on Windows.
A TCP socket does not carry an identity, so the daemon refuses every request on it. TCP sockets are deprecated. For more information, see [Daemon sockets: TCP is deprecated](#daemon-sockets-tcp-is-deprecated).
A TCP socket does not carry an identity, so the daemon refuses every request on it. See [Daemon sockets: TCP is deprecated](#daemon-sockets-tcp-is-deprecated).
### Access levels
@@ -75,15 +61,7 @@ The daemon gives each request one of four access levels. Each level can do all t
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.
The operations that decide who may obtain a shell on the machine (enabling the SSH server, enabling SSH root login, disabling SSH authentication, and changing the management URL or deregistering while the SSH server is enabled) keep their existing rule: they require root, or an administrator on Windows. See [Privileged operations](https://docs.netbird.io/client/grpc-socket#privileged-operations).
### 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.
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](https://docs.netbird.io/client/grpc-socket#privileged-operations).
#### Commands and required access
@@ -96,7 +74,45 @@ When you add a profile, you become its owner. Root and administrators can see an
| `netbird debug bundle` | Session holder |
| `netbird profile claim` | Privileged |
`netbird profile list` shows only the profiles that you own. To show the owner of each profile, add `--show-owner`:
### 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:
```shell
netbird profile list
```
```text
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`:
```shell
netbird profile list --show-id
```
```text
ID NAME ACTIVE
a1b2c3d4 work *
default default
e5f6a7b8 home
```
To show the owner of each profile, add `--show-owner`:
```shell
sudo netbird profile list --show-owner
@@ -119,6 +135,12 @@ sudo netbird down
#### Claim a profile
The `profile` command gains a `claim` subcommand:
```shell
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:
```shell
@@ -129,46 +151,6 @@ The `<owner>` value is an account name, a `uid:<id>` value, or a `sid:<SID>` val
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.
### 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:
```shell
sudo netbird service install --allow-group netbird-users
```
The operating system then refuses connections from users outside the group. This restriction also applies to the [HTTP/JSON daemon socket](https://docs.netbird.io/client/json-socket).
- 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.
- The installer resolves group names to IDs, including LDAP, SSSD, and Active Directory groups. If a name does not resolve, the installation stops.
- `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](https://docs.netbird.io/client/mdm-integration). 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.
### Environment variables
Set these variables on the daemon. For instructions, see [Client environment variables](https://docs.netbird.io/client/environment-variables#setting-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. Use only on a device with one user or legacy use cases. |
| `NB_DISABLE_DEFAULT_PROFILE_CLAIM` | Linux, macOS, Windows, FreeBSD | Set to `true` to stop the [automatic claim](#automatic-claims) 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.
### 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.
@@ -186,68 +168,54 @@ If the migration fails, the daemon writes the error to the log and tries again a
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 session is not at the console.
- **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 server, the default profile keeps no owner. To give it an owner, run:
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:
```shell
sudo netbird profile claim default --owner <owner>
```
### Troubleshooting profile ownership
### Environment variables
#### Another user has this machine connected
Set these variables on the daemon. For instructions, see [Client environment variables](https://docs.netbird.io/client/environment-variables#setting-environment-variables).
**Symptom:** A command fails with a message that says another user has the machine connected.
| 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](#automatic-claims) of the default profile. The default profile then has no owner until an administrator runs `netbird profile claim`. |
**Cause:** Another user started the current connection.
> **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.
**Fix:** Ask that user to disconnect, or run `sudo netbird down`.
### Restrict daemon access to a group
#### The profile belongs to another user
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:
**Symptom:** A command fails with a message that says the profile belongs to another user.
```shell
sudo netbird service install --allow-group netbird-users
```
**Cause:** You do not own the profile.
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.
**Fix:** Use a profile that you own. Or, ask an administrator to run `sudo netbird profile claim <profile> --owner <your-user>`.
- 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 ""`.
#### The profile has no owner on record
> **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.
**Symptom:** A command fails with a message that says the profile has no owner on record.
#### Set allowed groups with MDM
**Cause:** The profile was not claimed. This is usual on a device with no console, or when you connect over SSH.
On managed Windows and macOS devices, use the `allowGroups` [MDM policy key](https://docs.netbird.io/client/mdm-integration). On Windows, the Group Policy name is **Restrict the daemon sockets**.
**Fix:** Run the `netbird profile claim` command that the error message shows.
- 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.
#### 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.
#### 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](https://docs.netbird.io/help/troubleshooting-client).
> **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
@@ -286,103 +254,94 @@ sudo netbird service reconfigure \
--json-socket unix:///var/run/netbird-integration-http.sock
```
> **Warning:** Reconfiguring the service restarts NetBird and can briefly interrupt tunnel connectivity, routes, and DNS.
## Troubleshooting
The following documented examples were removed because they no longer work: `netbird service reconfigure --daemon-addr tcp://127.0.0.1:41731`, `netbird --daemon-addr tcp://127.0.0.1:41731 status`, `netbird service reconfigure --enable-json-socket --json-socket tcp://127.0.0.1:8080`, the `grpcurl` example against `127.0.0.1:41731`, and the `curl` example against `http://127.0.0.1:8080`.
### Profile ownership
### Who can use the default socket
#### Another user has this machine connected
The default Unix socket allows read and write access for local users. Each local user can read basic status and use the profiles that they own. Operations that decide who may obtain a shell on the machine are refused unless the caller is root, or an administrator on Windows. To let only one group connect, see [Restrict daemon access to a group](#restrict-daemon-access-to-a-group).
**Symptom:** A command fails with a message that says another user has the machine connected.
Most operations also require the caller to own the profile, or to hold the active connection. See [Access levels](#access-levels).
**Cause:** Another user started the current connection.
The earlier recommendation to place a custom socket inside a restricted directory for local-user isolation is replaced by `--allow-group`.
**Fix:** Ask that user to disconnect, or run `sudo netbird down`.
### Windows and grpcurl
#### The profile belongs to another user
`grpcurl` cannot connect to a Windows named pipe. Use a client that can open a named pipe. Do not use a TCP socket, because the daemon refuses every request on it.
**Symptom:** A command fails with a message that says the profile belongs to another user.
### Build an integration
**Cause:** You do not own the profile.
When you create a local gRPC channel for an integration, connect it to the configured Unix socket or named pipe without TLS. TCP is no longer an option for the channel.
**Fix:** Use a profile that you own. Or, ask an administrator to run `sudo netbird profile claim <profile> --owner <your-user>`.
### Troubleshooting daemon sockets
#### 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](#automatic-claims).
**Fix:** Claim the default profile once as root or as an administrator:
```shell
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://`, change it to a Unix socket or a named pipe. The daemon refuses every request on a TCP socket.
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-tcp-request-is-refused).
#### A call is refused with PermissionDenied (gRPC) or 403 (HTTP/JSON)
The operation is one of the [privileged operations](https://docs.netbird.io/client/grpc-socket#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. On a TCP socket the daemon refuses every request, because TCP carries no caller identity. TCP sockets are deprecated.
The operation is one of the [privileged operations](https://docs.netbird.io/client/grpc-socket#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.
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](#migrate-a-service-that-uses-a-tcp-socket).
## Profiles: storage layout and CLI changes
#### The daemon does not start after you set allowed groups
These changes apply to the [Profiles](https://docs.netbird.io/client/profiles) page.
**Possible causes:**
### Storage layout
- 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.
The default profile is stored as `default.json` in NetBird's state directory. New profiles are stored in the `profiles.v1` subdirectory as `<id>.json`:
**Fix:** Read the daemon log. The log shows which of these causes stopped the daemon.
| OS | Default state directory | Additional profile example |
| --- | --- | --- |
| Linux and macOS | `/var/lib/netbird/` | `/var/lib/netbird/profiles.v1/<id>.json` |
| FreeBSD | `/var/db/netbird/` | `/var/db/netbird/profiles.v1/<id>.json` |
| Windows | `%ProgramData%\Netbird\` | `%ProgramData%\Netbird\profiles.v1\<id>.json` |
### Collect information for support
Profiles from earlier versions stay in their per-user subdirectory, for example `/var/lib/netbird/<username>/<id>.json`.
Each profile has an owner, and only the owner can use it. See [Profile ownership](#profile-ownership).
`NB_STATE_DIR` overrides the default state directory. Treat profile files as credentials: stop the service before manual maintenance, restrict access, and prefer the GUI or CLI for normal profile management.
### Profile CLI commands
The `profile` command gains a `claim` subcommand:
```shell
netbird profile <add|list|select|rename|remove|claim> [name|handle]
```
### List profiles
```shell
netbird profile list
```
```text
NAME ACTIVE
work *
default
home
```
The list shows only the profiles that you own. A `*` in the `ACTIVE` column marks the active profile; inactive profiles are left blank. Earlier versions marked the active profile with `✓`.
With `--show-id`:
```shell
netbird profile list --show-id
```
```text
ID NAME ACTIVE
a1b2c3d4 work *
default default
e5f6a7b8 home
```
To show the owner of each profile, add `--show-owner`. To claim a profile for a user, see [Claim a profile](#claim-a-profile).
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](https://docs.netbird.io/help/troubleshooting-client).
## 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](https://docs.netbird.io/client/environment-variables) reference. See [Environment variables](#environment-variables) above for the full description.
Two variables are added to the **Other** table of the [Client environment variables](https://docs.netbird.io/client/environment-variables) reference. See [Environment variables](#environment-variables).
| Variable | Platform |
| --- | --- |
@@ -397,78 +356,6 @@ The [MDM integration](https://docs.netbird.io/client/mdm-integration) policy key
| --- | --- | --- |
| `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](#restrict-daemon-access-to-a-group). |
### CLI global flag `--daemon-addr`
The help text of the global `--daemon-addr` flag on the [CLI](https://docs.netbird.io/get-started/cli) page changes to:
```text
--daemon-addr string Daemon service address to serve CLI requests [unix|npipe]://[path|name]. tcp://host:port is deprecated: it carries no caller identity, so the daemon refuses every request on it (default "unix:///var/run/netbird.sock", "npipe://netbird" on Windows)
```
The environment variable example on the same page changes from a TCP address to the default Unix socket:
```shell
# Set custom daemon address
export NB_DAEMON_ADDR="unix:///var/run/netbird.sock"
```
### Service flag `--allow-group`
New flag on `netbird service install` and `netbird service reconfigure`. See [Restrict daemon access to a group](#restrict-daemon-access-to-a-group).
## Verification checklist for early testers
Each item restates a behavior that the documentation above claims. Test on a device with at least two local user accounts.
Profile ownership
- [ ] `netbird profile add` run as a regular user records that user as the owner. `sudo netbird profile list --show-owner` shows the account name.
- [ ] `netbird profile add` run with `sudo` records root as the owner.
- [ ] `netbird profile list` run as user A does not show profiles owned by user B.
- [ ] User B cannot rename, remove, or deregister a profile owned by user A. The error says the profile belongs to another user.
- [ ] `sudo netbird profile claim <profile> --owner <user>` changes the owner. Without `--owner`, the owner becomes the user who ran `sudo` on Linux and macOS. In a root shell without `sudo`, and on Windows, the command requires `--owner`.
- [ ] A `uid:` or `sid:` value that matches no account is accepted by `claim`.
Session holder
- [ ] While user A is connected, `netbird down`, `netbird up`, `netbird login`, and `netbird profile select` run by user B fail with a message that another user has the machine connected.
- [ ] While user A is connected, `netbird status` run by user B shows `Detailed status is unavailable: the connection belongs to another user.` and only the daemon status.
- [ ] `sudo netbird down` stops user A's connection.
- [ ] `netbird debug bundle` requires the session holder. The bundle contains `profiles.txt` and `active_profile.json`.
Migration and automatic claims
- [ ] After upgrading a device with profiles under `<state-dir>/<username>/`, the profiles are still listed, the `profiles.v1` directory exists, and the owners of the last active user's profiles and of the default profile are recorded.
- [ ] Two profiles with the same ID in different user directories receive distinct IDs after migration.
- [ ] A profile left in a user directory with no owner is claimed by the user whose name matches the directory on their first request.
- [ ] The default profile is claimed by the first user logged in at the console. A user connected only over SSH does not claim it, and the error says the profile has no owner on record and shows the `claim` command to run.
- [ ] On a device with no console, the default profile stays unowned until an administrator claims it.
- [ ] With `NB_DISABLE_DEFAULT_PROFILE_CLAIM=true` on the daemon, the default profile is not claimed automatically.
- [ ] With `NB_DISABLE_PROFILE_OWNERSHIP=true` on the daemon, every identified user can use every profile and control the connection.
TCP sockets
- [ ] A daemon configured with `--daemon-addr tcp://127.0.0.1:41731` refuses every request, including `netbird status`, with a message about caller identity.
- [ ] An HTTP/JSON gateway configured with `--json-socket tcp://127.0.0.1:8080` refuses every request.
- [ ] A daemon configured with both a TCP socket and `--allow-group` does not start.
Group restriction
- [ ] `sudo netbird service install --allow-group <group>` lets members of the group connect and refuses everyone else at the operating-system level, on both the gRPC socket and the HTTP/JSON socket.
- [ ] A group name that does not resolve stops the installation.
- [ ] On Linux and macOS, more than one group is rejected. On Windows, a comma-separated list is accepted, and LocalSystem, elevated administrators, and the daemon's account keep access.
- [ ] `sudo netbird service reconfigure --allow-group ""` removes the restriction.
- [ ] The `allowGroups` MDM key overrides `--allow-group`, an empty MDM value removes an installer-set restriction, and an unreadable policy or unresolvable value stops the daemon from starting.
## Files changed by the pull request
| File | Change |
| --- | --- |
| `src/pages/client/profile-ownership.mdx` | New page. Reproduced in full under [Profile ownership and daemon access](#profile-ownership-and-daemon-access). |
| `src/pages/client/grpc-socket.mdx` | TCP sockets marked deprecated and refused for every request. Security warning reworded for per-user access. Privileged operations section links to profile ownership. TCP examples removed. |
| `src/pages/client/json-socket.mdx` | TCP sockets marked deprecated and refused for every request. TCP setup and `curl` examples removed. Troubleshooting updated. |
| `src/pages/client/profiles.mdx` | Storage layout moves new profiles to `profiles.v1`. `claim` subcommand added. `profile list` shows only owned profiles, marks the active profile with `*`, and gains `--show-owner`. |
| `src/pages/client/environment-variables.mdx` | Adds `NB_DISABLE_PROFILE_OWNERSHIP` and `NB_DISABLE_DEFAULT_PROFILE_CLAIM`. |
| `src/pages/client/mdm-integration.mdx` | Adds the `allowGroups` policy key. Key count becomes 21. |
| `src/pages/get-started/cli.mdx` | `--daemon-addr` help text documents the TCP deprecation. `NB_DAEMON_ADDR` example uses the Unix socket. |
| `src/components/NavigationDocs.jsx` | Adds **Profile Ownership** to the Client sidebar. |