Skip to content

Document daemon IPC privilege requirements and the Windows named pipe #894

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lixmal merged 5 commits into from
Jul 30, 2026
Merged

Document daemon IPC privilege requirements and the Windows named pipe #894

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a9d5586
Document that privileged daemon operations require root or administrator
lixmal Jul 30, 2026
015edd9
Note that the desktop app needs privileges for the SSH switches
lixmal Jul 30, 2026
5f51194
Say what unprivileged users can do when the SSH switches need privileges
lixmal Jul 30, 2026
7751640
Say that only disabling SSH authentication is privileged
lixmal Jul 30, 2026
0d2cfd0
Document the debug bundle upload privilege and https requirements
lixmal Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion src/pages/client/desktop-app.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,8 @@ The settings page uses a tabbed layout that groups options by what they control.
* **Network** for connectivity, DNS, routes, and IPv6 settings.
* **Security** for inbound traffic, LAN access, and quantum-resistant encryption settings.
* **Profiles** for managing the accounts the app knows about. See [Profiles](/client/profiles).
* **SSH** for the native SSH server and its optional features.
* **SSH** for the native SSH server and its optional features. Some of these
require privileges: see the note below.
* **Advanced** for log-level and custom configuration options.
* **Troubleshoot** for [capturing a debug bundle](#capturing-a-debug-bundle).
* **About** for version information, useful links, and updating the app.
Expand All @@ -75,6 +76,18 @@ The settings page uses a tabbed layout that groups options by what they control.
<img src="/docs-static/img/client/desktop-app/settings-language.png" alt="Settings page with the General tab and Display Language picker" className="imagewrapper"/>
</p>

<Note>
The changes that decide who may obtain a shell on the machine, **Enable SSH
Server**, **Enable Root Login** and turning SSH authentication off, can only be
made by a privileged caller, because the background service runs as root on Linux and macOS
and as LocalSystem on Windows while the app runs as you. The app shows those
switches as unavailable and puts the equivalent command next to them: run it with
`sudo` on Linux and macOS, or from an elevated prompt on Windows. Without those
rights, an administrator has to run it, or push the setting through
[MDM](#mdm-driven-ui), which the client applies itself. A switch that is already
on stays operable, since turning these settings off never requires privileges.
</Note>

Comment thread
coderabbitai[bot] marked this conversation as resolved.
**Connect on Startup** controls whether the background service reconnects when it starts. **Launch NetBird UI at Login** controls only whether the graphical interface opens when you sign in to the operating system. On a fresh desktop installation, launch at login is enabled once by default. Upgrades preserve the user's existing preference. Administrators can manage this behavior with [`disableAutostart`](/client/mdm-integration#disableAutostart).

## MDM-Driven UI
Expand Down
86 changes: 79 additions & 7 deletions src/pages/client/grpc-socket.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,25 @@ The HTTP/JSON gateway is optional. The gRPC socket is available whenever the Net
| Platform | Default address |
| --------------- | ------------------------------ |
| Linux and macOS | `unix:///var/run/netbird.sock` |
| Windows | `tcp://127.0.0.1:41731` |
| Windows | `npipe://netbird` |

On Windows the daemon serves a named pipe. Which path that is depends on what the
daemon may create: running as a service or elevated it serves
`\\.\pipe\ProtectedPrefix\Administrators\netbird`, a namespace only administrators
can create in, and otherwise it falls back to `\\.\pipe\netbird`. Clients try both
and check who owns the pipe before using the plain name, so passing
`npipe://netbird` is enough. Windows installations that predate the named pipe are
migrated from `tcp://127.0.0.1:41731` automatically.

<Warning>
**Security warning:** On supported Linux installations, the default Unix
socket allows read and write access for local users. The API exposes control
operations as well as status. If you require local-user isolation, place a
custom socket inside a restricted directory and ensure that the directory is
recreated securely at boot.
**Security warning:** The default Unix socket allows read and write access for
local users, so any local user can read status and configuration and perform
operations that do not require privileges. 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](#privileged-operations). If you require local-user isolation
beyond that, place a custom socket inside a restricted directory and ensure
that the directory is recreated securely at boot.
</Warning>

On Linux installations that use an instance-specific systemd service, the socket can instead be under `/var/run/netbird/<instance>.sock`. The NetBird CLI automatically uses the only socket in that directory when the default socket does not exist. If multiple instance sockets exist, pass the intended address explicitly with `--daemon-addr`.
Expand All @@ -46,6 +57,7 @@ Use the global `--daemon-addr` option when installing or reconfiguring the servi
```text
unix:///path/to/netbird.sock
tcp://host:port
npipe://name
```

<Warning>
Expand Down Expand Up @@ -92,8 +104,56 @@ netbird --daemon-addr tcp://127.0.0.1:41731 status
TLS. Keep TCP listeners bound to a trusted interface such as `127.0.0.1` and
do not expose them to an untrusted network. The API includes operations that
can read or change the local NetBird daemon's state.

A TCP connection also carries no caller identity, so the daemon cannot tell
who is calling and refuses every [privileged
operation](#privileged-operations) on that socket, whoever runs the client.
Use a Unix socket, or `npipe://` on Windows, if your integration needs them.
</Warning>

## Privileged Operations

Any local user can reach the socket, so the daemon authorizes individual operations
by the identity of whoever calls it, 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 caller whose identity cannot be established is refused.

Since 0.76.0 the following require root, or an administrator on Windows, because
they decide who may obtain a shell on the machine:

| Change | Refused when |
| --- | --- |
| Enable the NetBird SSH server | the caller is not privileged |
| Enable SSH root login | the caller is not privileged |
| Disable SSH authentication | the caller is not privileged |
| Change the management URL | the caller is not privileged and that profile has the SSH server enabled |
| Deregister the peer (logout, profile removal) | the caller is not privileged and that profile has the SSH server enabled |

Only the direction that creates the capability is guarded. Turning any of them off
is always allowed, and restating a value that is already set is not a change, so an
integration that submits a whole settings form does not start failing once an
administrator enables SSH.

A refusal comes back as gRPC `PermissionDenied` carrying a `google.rpc.ErrorInfo`
detail, so an integration can recognise it without parsing the message:

```text
reason: PRIVILEGE_REQUIRED
domain: daemon.netbird.io
metadata: summary = "Enabling the NetBird SSH server requires root."
command = "sudo netbird down; sudo netbird up --allow-server-ssh"
```

Render `summary` and `command` rather than the raw error: `command` is the same
operation with the privileges it needs, ready to run.

<Note>
When the daemon itself runs unprivileged, as in a rootless container or on
Windows in netstack mode, a caller running as the daemon's own user is treated
as privileged. Such a caller can already rewrite the configuration the daemon
reads, so refusing it would protect nothing.
</Note>

## Service Definition

The socket provides `daemon.DaemonService`. NetBird's
Expand Down Expand Up @@ -165,7 +225,10 @@ grpcurl \

### Query Status Through a TCP Socket

For the default Windows listener or a custom loopback TCP listener:
This applies to a custom loopback TCP listener, since `grpcurl` cannot dial a
Windows named pipe and the Windows default is therefore not reachable this way. Use
a client that can open the pipe, or configure a TCP listener for testing and accept
that [privileged operations](#privileged-operations) are refused on it:

```shell
grpcurl \
Expand Down Expand Up @@ -230,6 +293,15 @@ This is expected. Supply `daemon.proto` with your tool's equivalent of the `grpc

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. For TCP, verify the host and port and ensure the listener remains bound to a trusted interface.

### A Call Is Refused With PermissionDenied

The operation is one of the [privileged operations](#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 every such operation is refused, because the transport carries no caller
identity.

### A Method or Field Is Unimplemented

The integration's generated bindings may be newer than the installed NetBird daemon. Compare the installed client version with the revision of `daemon.proto` used to generate the bindings, then use a compatible schema or upgrade NetBird.
31 changes: 26 additions & 5 deletions src/pages/client/json-socket.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,13 +35,20 @@ unix:///var/run/netbird-http.sock
```

<Warning>
**Security warning:** On supported Linux installations, the default Unix
socket allows read and write access for local users. The API exposes control
operations as well as status. If you require local-user isolation, place a
custom socket inside a restricted directory and ensure that the directory is
recreated securely at boot.
**Security warning:** The default Unix socket allows read and write access for
local users. The API exposes control operations as well as status. If you
require local-user isolation, place a custom socket inside a restricted
directory and ensure that the directory is recreated securely at boot.
</Warning>

The gateway runs inside the daemon and re-dials it locally, so it reads the identity
of its own HTTP client and forwards it, which is what lets the daemon authorize the
request as that user rather than as the daemon itself. The
[privileged operations](/client/grpc-socket#privileged-operations) therefore behave
the same over HTTP as over gRPC, and a refusal comes back as HTTP 403 with the same
`PRIVILEGE_REQUIRED` detail. Metadata headers reserved for that forwarding are
dropped when a client supplies them.

To enable it on an existing installation, reconfigure the service:

<Warning>
Expand Down Expand Up @@ -95,6 +102,11 @@ sudo netbird service reconfigure \
listeners bound to a trusted interface such as `127.0.0.1` and do not expose
them to an untrusted network. The API includes operations that can read or
change the local NetBird daemon's state.

A TCP connection carries no caller identity, so the gateway cannot tell who is
calling and every
[privileged operation](/client/grpc-socket#privileged-operations) is refused on
such a socket, whoever runs the client.
</Warning>

To disable the gateway again, run:
Expand Down Expand Up @@ -241,6 +253,15 @@ If you supplied `--json-socket` without `--enable-json-socket`, NetBird rejects

Verify that the process running the integration can access the socket and every parent directory in its path. A custom restricted directory can prevent access even when the socket itself allows it.

### A Request Is Refused With 403

The operation is one of the
[privileged operations](/client/grpc-socket#privileged-operations) and the HTTP
client is not root, or not an administrator on Windows. The response body carries a
`PRIVILEGE_REQUIRED` detail in domain `daemon.netbird.io`, with a summary and the
command that performs the same operation with the privileges it needs. On a TCP
gateway socket these operations are always refused.

### A TCP Request Cannot Connect

Confirm that the host and port in the request match the value passed to `--json-socket`. Prefer `127.0.0.1` over `0.0.0.0` unless remote access is explicitly required and protected by an additional security boundary.
12 changes: 7 additions & 5 deletions src/pages/get-started/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Below is the list of global flags:
--admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io:443")
-A, --anonymize anonymize IP addresses and non-netbird.io domains in logs and status output
-c, --config string Overrides the default profile file location. Deprecated on `up` and `login`; use `--service-env NB_CONFIG=<path>` instead.
--daemon-addr string Daemon service address to serve CLI requests [unix|tcp]://[path|host:port] (default "unix:///var/run/netbird.sock")
--daemon-addr string Daemon service address to serve CLI requests [unix|tcp|npipe]://[path|host:port|name] (default "unix:///var/run/netbird.sock", "npipe://netbird" on Windows)
-n, --hostname string Sets a custom hostname for the device
--log-file console Sets NetBird log paths written to simultaneously. If "console" is specified the log will be output to stdout. If "syslog" is specified the log will be sent to the syslog daemon. You can pass the flag multiple times or separate entries by comma (default [/var/log/netbird/client.log])
-l, --log-level string Sets NetBird log level (default "info")
Expand Down Expand Up @@ -509,9 +509,9 @@ For SFTP and SCP, use native clients (`sftp` and `scp` commands) which work with

**Connection fails:**

- Ensure SSH is enabled on the target peer:
- Ensure SSH is enabled on the target peer, which requires root or an administrator:
```shell
netbird up --allow-server-ssh
sudo netbird down; sudo netbird up --allow-server-ssh
```
- Verify SSH Access is enabled in the dashboard (Peers > your_peer > SSH Access)
- Check that an ACL policy allows TCP port 22022
Expand All @@ -520,13 +520,13 @@ For SFTP and SCP, use native clients (`sftp` and `scp` commands) which work with

- Complete the OIDC flow when prompted (browser window will open)
- Verify your IdP is properly configured
- To disable JWT authentication: `netbird up --allow-server-ssh --disable-ssh-auth`
- To disable JWT authentication, as root or an administrator: `sudo netbird down; sudo netbird up --allow-server-ssh --disable-ssh-auth`

**Port forwarding not working:**

- Ensure the server has the appropriate flags:
```shell
netbird up --allow-server-ssh \
sudo netbird up --allow-server-ssh \
--enable-ssh-local-port-forwarding \
--enable-ssh-remote-port-forwarding
```
Expand Down Expand Up @@ -833,6 +833,7 @@ This will output:
-S, --system-info Adds system information to the debug bundle (default true)
-U, --upload-bundle Uploads the debug bundle to a server
--upload-bundle-url string Service URL to get an upload URL for the debug bundle (default "https://upload.debug.netbird.io/upload-url")
--upload-bundle-insecure Allow uploading to an http or untrusted-TLS upload server (self-hosted); requires root
```

### debug for
Expand Down Expand Up @@ -872,6 +873,7 @@ Log level restored to INFO
-S, --system-info Adds system information to the debug bundle (default true)
-U, --upload-bundle Uploads the debug bundle to a server
--upload-bundle-url string Service URL to get an upload URL for the debug bundle (default "https://upload.debug.netbird.io/upload-url")
--upload-bundle-insecure Allow uploading to an http or untrusted-TLS upload server (self-hosted); requires root
```

### debug log
Expand Down
5 changes: 5 additions & 0 deletions src/pages/help/troubleshooting-client.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -308,6 +308,11 @@ Upload file key:
<Note>
The flag `--anonymize` can be used to anonymize IP addresses and non-netbird.io domains in logs and status output when needed.
</Note>

<Note>
Uploading to a custom endpoint with `--upload-bundle-url` (for example a self-hosted upload server) requires root/administrator and an `https` URL. To upload to a server that uses `http` or an untrusted TLS certificate, add `--upload-bundle-insecure`.
</Note>
Comment on lines +312 to +314

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Warn about the security impact of --upload-bundle-insecure.

This permits uploading debug bundles over HTTP or with untrusted TLS, potentially exposing logs and system/network information. State that it should be used only with a trusted endpoint, and preferably only for troubleshooting.

Suggested wording 
 <Note>
-  Uploading to a custom endpoint with `--upload-bundle-url` (for example a self-hosted upload server) requires root/administrator and an `https` URL. To upload to a server that uses `http` or an untrusted TLS certificate, add `--upload-bundle-insecure`.
+  Uploading to a custom endpoint with `--upload-bundle-url` (for example a self-hosted upload server) requires root/administrator and an `https` URL. To upload to a trusted server that uses `http` or an untrusted TLS certificate, add `--upload-bundle-insecure`; this reduces transport security and may expose bundle contents.
 </Note>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<Note>
Uploading to a custom endpoint with `--upload-bundle-url` (for example a self-hosted upload server) requires root/administrator and an `https` URL. To upload to a server that uses `http` or an untrusted TLS certificate, add `--upload-bundle-insecure`.
</Note>
<Note>
Uploading to a custom endpoint with `--upload-bundle-url` (for example a self-hosted upload server) requires root/administrator and an `https` URL. To upload to a trusted server that uses `http` or an untrusted TLS certificate, add `--upload-bundle-insecure`; this reduces transport security and may expose bundle contents.
</Note>
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/pages/help/troubleshooting-client.mdx` around lines 312 - 314, Update the
Note describing --upload-bundle-insecure to explicitly warn that it can expose
debug-bundle logs and system/network information over HTTP or untrusted TLS.
State that the flag should only be used with a trusted endpoint, preferably only
for troubleshooting.


### Debug bundle uploads with GUI
The desktop app can create and optionally upload a debug bundle without using the CLI. Open **Settings → Troubleshoot**.

Expand Down
2 changes: 1 addition & 1 deletion src/pages/manage/peers/access-infrastructure/setup-keys-add-servers-to-network.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ This feature allows you to securely access your VM with SSH without exposing it
for distributing and managing SSH keys. To enable NetBird SSH access, run the following command on your VM:

```bash
netbird up --allow-server-ssh
sudo netbird up --allow-server-ssh
```

You can then use the NetBird SSH client to connect to your VM:
Expand Down
31 changes: 28 additions & 3 deletions src/pages/manage/peers/ssh.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,22 @@ On the machine you want to access via SSH, enable the NetBird SSH server.
2. Go to **Settings → SSH**.
3. Toggle **Enable SSH Server**. Configure local forwarding, remote forwarding, SFTP, or root access only when required.

<Note>
**Enable SSH Server**, **Enable Root Login** and turning SSH authentication off
require privileges on every platform, because the background service runs as root
or LocalSystem while the desktop app runs as you. The app shows those switches as
unavailable and puts the equivalent command next to them, to run with `sudo` on
Linux and macOS or from an elevated prompt on Windows.

On a machine where you do not have those rights, which is the normal case for a
managed workstation, you cannot enable the SSH server yourself: an administrator
has to run the command, or push
[`allowServerSSH`](/client/mdm-integration#policy-keys-reference) through MDM,
which the client applies itself and so needs nothing from you. A switch that is
already on stays operable, because turning these settings off never requires
privileges.
</Note>

<p>
<img src="/docs-static/img/manage/peers/ssh/ssh-client.png" alt="SSH server settings in the NetBird desktop app"
className="imagewrapper"/>
Expand All @@ -75,20 +91,29 @@ On the machine you want to access via SSH, enable the NetBird SSH server.
**Using the CLI:**

```bash
netbird down # if NetBird is already running
netbird up --allow-server-ssh
sudo netbird down # if NetBird is already running
sudo netbird up --allow-server-ssh
```

For additional SSH server features, use these flags:

```bash
netbird up --allow-server-ssh \
sudo netbird up --allow-server-ssh \
--enable-ssh-local-port-forwarding \
--enable-ssh-remote-port-forwarding \
--enable-ssh-sftp \
--enable-ssh-root
```

<Note>
Enabling the SSH server, enabling root login, and disabling SSH
authentication require root on Linux and macOS, or an administrator on
Windows. The daemon reads the identity of whoever calls it locally and refuses
these changes to anyone else, since they decide who may obtain a shell on the
machine. Turning any of them off does not require privileges. Run the
commands with `sudo`, or from an elevated prompt on Windows.
</Note>

**Flag Reference:**

- `--allow-server-ssh`: Enable the SSH server
Expand Down
Loading