From 68ee78e586ff421d1b1508a535c5dd60890b13c8 Mon Sep 17 00:00:00 2001 From: PizzaLovingNerd Date: Wed, 15 Jul 2026 19:55:53 -0700 Subject: [PATCH 1/3] Documentation for GRPC and JSON Sockets --- src/components/NavigationDocs.jsx | 2 + src/pages/client/grpc-socket.mdx | 210 +++++++++++++++++++++++++++++ src/pages/client/json-socket.mdx | 212 ++++++++++++++++++++++++++++++ 3 files changed, 424 insertions(+) create mode 100644 src/pages/client/grpc-socket.mdx create mode 100644 src/pages/client/json-socket.mdx diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 13a4b6794..d36c1cba5 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -804,6 +804,8 @@ export const docsNavigation = [ links: [ { title: 'Desktop App', href: '/client/desktop-app' }, { title: 'Profiles', href: '/client/profiles' }, + { title: 'gRPC Daemon Socket', href: '/client/grpc-socket' }, + { title: 'HTTP/JSON Daemon Socket', href: '/client/json-socket' }, { title: 'Environment Variables', href: '/client/environment-variables' }, { title: 'MDM Integration', href: '/client/mdm-integration' }, { diff --git a/src/pages/client/grpc-socket.mdx b/src/pages/client/grpc-socket.mdx new file mode 100644 index 000000000..1666ae136 --- /dev/null +++ b/src/pages/client/grpc-socket.mdx @@ -0,0 +1,210 @@ +import { Note, Warning } from '@/components/mdx' + +export const description = + 'Connect applications and development tools to the local NetBird daemon through its gRPC socket.' + +# gRPC Daemon Socket + +The NetBird daemon exposes a local gRPC API that the NetBird CLI and desktop app use. Your integration can use the same socket to check status, manage the connection, inspect configuration, work with profiles and networks, and call other local daemon operations. + +The gRPC socket is the primary local daemon API. If your integration cannot use gRPC or generated Protocol Buffer bindings, use the [HTTP/JSON daemon socket](/client/json-socket) instead. + + + The gRPC socket controls the **local NetBird daemon**. It is separate from the + NetBird Management API and does not replace it. + + +## Default Addresses + +The HTTP/JSON gateway is optional. The gRPC socket is available whenever the NetBird daemon is running. + +| Platform | Default address | +| --------------- | ------------------------------ | +| Linux and macOS | `unix:///var/run/netbird.sock` | +| Windows | `tcp://127.0.0.1:41731` | + +On Linux installations that use an instance-specific systemd service, the socket can instead be under `/var/run/netbird/.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`. + +You can see the address option in the CLI help: + +```shell +netbird --help +``` + +## Configure the Address + +Use the global `--daemon-addr` option when installing or reconfiguring the service. The address must use one of these formats: + +```text +unix:///path/to/netbird.sock +tcp://host:port +``` + +### Use a Custom Unix Socket + +```shell +sudo netbird service reconfigure \ + --daemon-addr unix:///run/netbird/integration.sock +``` + +The parent directory must already exist and be writable by the NetBird service. + +After changing the socket, pass the same address to NetBird CLI commands that need to contact the daemon: + +```shell +netbird --daemon-addr unix:///run/netbird/integration.sock status +``` + +### Use a TCP Socket + +```shell +sudo netbird service reconfigure \ + --daemon-addr tcp://127.0.0.1:41731 +``` + +Then specify that address when using the CLI on platforms where it is not the default: + +```shell +netbird --daemon-addr tcp://127.0.0.1:41731 status +``` + + + The daemon gRPC server does not add authentication or 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. + + +## Service Definition + +The socket provides `daemon.DaemonService`. NetBird's +[`client/proto/daemon.proto`](https://github.com/netbirdio/netbird/blob/main/client/proto/daemon.proto) +file lists the available methods, streaming types, and request and response schemas. + +Here are a few common methods. Check `daemon.proto` for the full list. + +| Method | Type | Purpose | +| ----------------- | ---------------- | --------------------------------------------------------- | +| `Status` | Unary | Read connection status and peer information. | +| `SubscribeStatus` | Server streaming | Receive the current status and subsequent status changes. | +| `GetConfig` | Unary | Read the active daemon configuration. | +| `ListNetworks` | Unary | List networks available to the client. | +| `Up` | Unary | Start the NetBird connection. | +| `Down` | Unary | Stop the NetBird connection. | +| `ListProfiles` | Unary | List configured client profiles. | +| `SubscribeEvents` | Server streaming | Receive daemon system events. | + +The service also includes methods that change configuration, profiles, network selection, logging, and other daemon state. Only give socket access to processes that you trust to control the local NetBird client. + + + The daemon does not enable gRPC server reflection. Tools and integrations must + use `daemon.proto`, generated client bindings, or a compiled descriptor set to + learn the service schema. + + +## Test the Socket with grpcurl + +[`grpcurl`](https://github.com/fullstorydev/grpcurl) is a command-line tool for invoking gRPC methods. Clone the NetBird repository so `grpcurl` can load the daemon's Protocol Buffer definition: + +```shell +git clone --depth 1 https://github.com/netbirdio/netbird.git +``` + +Run the following examples from the directory that contains the cloned `netbird` directory. + +### Query Status Through the Unix Socket + +```shell +grpcurl \ + -plaintext \ + -unix \ + -import-path ./netbird/client/proto \ + -proto daemon.proto \ + -d '{}' \ + /var/run/netbird.sock \ + daemon.DaemonService/Status +``` + +To request full peer status, set fields from `StatusRequest` in the JSON request body: + +```shell +grpcurl \ + -plaintext \ + -unix \ + -import-path ./netbird/client/proto \ + -proto daemon.proto \ + -d '{"getFullPeerStatus": true}' \ + /var/run/netbird.sock \ + daemon.DaemonService/Status +``` + +### Query Status Through a TCP Socket + +For the default Windows listener or a custom loopback TCP listener: + +```shell +grpcurl \ + -plaintext \ + -import-path ./netbird/client/proto \ + -proto daemon.proto \ + -d '{}' \ + 127.0.0.1:41731 \ + daemon.DaemonService/Status +``` + +`-plaintext` is required because the local daemon socket does not use TLS. For a Unix socket, pass the filesystem path without the `unix://` prefix to `grpcurl` and include its `-unix` option. + +### Subscribe to Status Changes + +Server-streaming methods remain connected and print each response as it arrives. For example: + +```shell +grpcurl \ + -plaintext \ + -unix \ + -import-path ./netbird/client/proto \ + -proto daemon.proto \ + -d '{}' \ + /var/run/netbird.sock \ + daemon.DaemonService/SubscribeStatus +``` + +Press `Ctrl+C` to end the stream. + +## Build an Integration + +For a long-running integration, generate a gRPC client from the same `daemon.proto` revision as the installed NetBird client: + +1. Download or vendor `client/proto/daemon.proto` from the NetBird repository. +2. Generate client bindings with the Protocol Buffer and gRPC tools for your language. +3. Create a local gRPC channel to the configured Unix or TCP address without TLS. That does not make the socket safe to expose remotely. +4. Create a `daemon.DaemonService` client from that channel. +5. Call unary methods or consume server streams using the generated request and response types. + +Use a protobuf definition and generated bindings that match your deployed NetBird version. A newer client may call methods or use fields that an older daemon does not support. + +The HTTP/JSON gateway exposes this service for environments where generated gRPC clients are unavailable. See [HTTP/JSON Daemon Socket](/client/json-socket) for setup and HTTP examples. + +## Troubleshooting + +### The Unix Socket Does Not Exist + +Check that the service is running: + +```shell +sudo netbird service status +``` + +If you use an instance-specific service, inspect `/var/run/netbird/` for its socket or pass the configured address with `--daemon-addr`. + +### A Tool Reports That Reflection Is Unsupported + +This is expected. Supply `daemon.proto` with your tool's equivalent of the `grpcurl -proto` and `-import-path` options, or use a descriptor set generated from that file. + +### 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. For TCP, verify the host and port and ensure the listener remains bound to a trusted interface. + +### 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. diff --git a/src/pages/client/json-socket.mdx b/src/pages/client/json-socket.mdx new file mode 100644 index 000000000..29e6c1c05 --- /dev/null +++ b/src/pages/client/json-socket.mdx @@ -0,0 +1,212 @@ +import { Note, Warning } from '@/components/mdx' + +export const description = + 'Use the NetBird daemon HTTP/JSON socket to build local integrations in environments where gRPC is unavailable.' + +# HTTP/JSON Daemon Socket + +The NetBird daemon can expose its local API over HTTP with JSON request and response bodies. A [gRPC-Gateway](https://grpc-ecosystem.github.io/grpc-gateway/) receives those HTTP/JSON requests and passes them to the daemon's gRPC API. + +The daemon's primary local API is documented in [gRPC Daemon Socket](/client/grpc-socket). Use that socket when your integration supports gRPC and generated Protocol Buffer bindings. + +Use the JSON socket when your integration cannot use gRPC. For example, it works well in runtimes that only have an HTTP client, local monitoring agents, and application sandboxes where adding a gRPC client and generated protobuf bindings is not practical. + + + The HTTP/JSON socket controls the **local NetBird daemon**. It is separate + from the NetBird Management API and does not replace it. + + +## Enable the JSON Socket + +The JSON socket is disabled by default. To enable it while installing the NetBird service, run: + +```shell +sudo netbird service install --enable-json-socket +``` + +The default address is: + +```text +unix:///var/run/netbird-http.sock +``` + +To enable it on an existing installation, reconfigure the service: + +```shell +sudo netbird service reconfigure --enable-json-socket +``` + +NetBird saves this setting with the service configuration, so it stays enabled after a restart. + +### Use a Custom Unix Socket + +Pass an address with the `unix://` scheme to change the socket path: + +```shell +sudo netbird service reconfigure \ + --enable-json-socket \ + --json-socket unix:///run/netbird/integration.sock +``` + +The parent directory must already exist and be writable by the NetBird service. + +### Use a TCP Socket + +Pass an address with the `tcp://` scheme to expose the gateway over TCP: + +```shell +sudo netbird service reconfigure \ + --enable-json-socket \ + --json-socket tcp://127.0.0.1:8080 +``` + + + The gateway does not add authentication or 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. + + +To disable the gateway again, run: + +```shell +sudo netbird service reconfigure --enable-json-socket=false +``` + +## Make Requests + +Each daemon RPC is exposed as an HTTP `POST` endpoint using this path format: + +```text +/daemon.DaemonService/ +``` + +Send the request message as JSON with the `Content-Type: application/json` header. If an RPC has no required request fields, send an empty JSON object (`{}`). Responses use the standard [Protocol Buffers JSON mapping](https://protobuf.dev/programming-guides/json/). + +### Query Status Through the Unix Socket + +With the default socket path: + +```shell +curl --unix-socket /var/run/netbird-http.sock \ + --request POST \ + --header 'Content-Type: application/json' \ + --data '{}' \ + http://localhost/daemon.DaemonService/Status +``` + +The response is a JSON representation of the daemon's status response. For example, it includes the daemon status and version: + +```json +{ + "status": "Connected", + "daemonVersion": "..." +} +``` + +The exact fields and values depend on the client version and current connection state. + +### Query Status Through a TCP Socket + +If the gateway is listening on `tcp://127.0.0.1:8080`, use a normal HTTP request: + +```shell +curl --request POST \ + --header 'Content-Type: application/json' \ + --data '{}' \ + http://127.0.0.1:8080/daemon.DaemonService/Status +``` + +### Call the API from an Integration + +The following Python example calls the status endpoint over a Unix socket using only the standard library: + +```python +import http.client +import json +import socket + + +class UnixHTTPConnection(http.client.HTTPConnection): + def __init__(self, socket_path): + super().__init__("localhost") + self.socket_path = socket_path + + def connect(self): + self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self.sock.connect(self.socket_path) + + +connection = UnixHTTPConnection("/var/run/netbird-http.sock") +connection.request( + "POST", + "/daemon.DaemonService/Status", + body=json.dumps({}), + headers={"Content-Type": "application/json"}, +) +response = connection.getresponse() + +if response.status != 200: + raise RuntimeError(f"NetBird returned HTTP {response.status}: {response.read().decode()}") + +status = json.load(response) +print(status["status"]) +connection.close() +``` + +For a TCP listener, any standard HTTP client can call the same path and JSON body without Unix-socket support. + +## Map gRPC Methods to HTTP + +The gateway exposes every method in `daemon.DaemonService`, and every endpoint uses +`POST`. Add the method name to the service path: + +```text +daemon.DaemonService/Status + ↓ +/daemon.DaemonService/Status +``` + +For example: + +| gRPC method | HTTP endpoint | +| -------------- | ------------------------------------ | +| `Status` | `/daemon.DaemonService/Status` | +| `GetConfig` | `/daemon.DaemonService/GetConfig` | +| `ListNetworks` | `/daemon.DaemonService/ListNetworks` | +| `Up` | `/daemon.DaemonService/Up` | +| `Down` | `/daemon.DaemonService/Down` | + +The [`DaemonService` protobuf definition](https://github.com/netbirdio/netbird/blob/main/client/proto/daemon.proto) +is the complete API reference for method names and request and response schemas. +See [gRPC Daemon Socket](/client/grpc-socket#service-definition) for an overview of +the service and guidance on using the protobuf definition. + +### Server-Streaming Methods + +Server-streaming RPCs use the same path. The HTTP request stays open and returns +JSON messages until the stream ends or the caller closes the connection. Check the +protobuf definition for streaming methods and their response types. + +The gateway exposes control operations as well as read-only methods. Only give +socket access to processes that you trust to control the local NetBird client. + +## Troubleshooting + +### The Socket File Does Not Exist + +Confirm that the service was installed or reconfigured with `--enable-json-socket`, then check the service status: + +```shell +sudo netbird service status +``` + +If you supplied `--json-socket` without `--enable-json-socket`, NetBird rejects the configuration. Setting a custom address does not enable the gateway on its own. + +### Curl Reports Permission Denied + +Verify that the process running the integration can access the socket and every parent directory in its path. NetBird creates its Unix socket with read and write permissions for all users, but directory permissions can still prevent access. + +### 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. From 342dd235a398da56326a44278ce6ea2c1fda5594 Mon Sep 17 00:00:00 2001 From: PizzaLovingNerd Date: Fri, 17 Jul 2026 18:25:24 -0700 Subject: [PATCH 2/3] improve gRPC and HTTP/JSON socket documentation --- src/pages/client/grpc-socket.mdx | 67 +++++++++++++++++++++++--------- src/pages/client/json-socket.mdx | 66 +++++++++++++++++++++++-------- 2 files changed, 99 insertions(+), 34 deletions(-) diff --git a/src/pages/client/grpc-socket.mdx b/src/pages/client/grpc-socket.mdx index 1666ae136..89af18d7e 100644 --- a/src/pages/client/grpc-socket.mdx +++ b/src/pages/client/grpc-socket.mdx @@ -23,6 +23,14 @@ The HTTP/JSON gateway is optional. The gRPC socket is available whenever the Net | Linux and macOS | `unix:///var/run/netbird.sock` | | Windows | `tcp://127.0.0.1:41731` | + + **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. + + On Linux installations that use an instance-specific systemd service, the socket can instead be under `/var/run/netbird/.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`. You can see the address option in the CLI help: @@ -40,21 +48,32 @@ unix:///path/to/netbird.sock tcp://host:port ``` + + **Connectivity warning:** Reconfiguring the service restarts NetBird and can + briefly interrupt tunnel connectivity, routes, and DNS. + + ### Use a Custom Unix Socket ```shell sudo netbird service reconfigure \ - --daemon-addr unix:///run/netbird/integration.sock + --daemon-addr unix:///var/run/netbird-integration-grpc.sock ``` -The parent directory must already exist and be writable by the NetBird service. +The parent directory must already exist and be writable by the NetBird service. If you use a dedicated directory to restrict access, configure systemd or tmpfiles to recreate it securely because directories under `/run` do not persist across reboots. After changing the socket, pass the same address to NetBird CLI commands that need to contact the daemon: ```shell -netbird --daemon-addr unix:///run/netbird/integration.sock status +netbird --daemon-addr unix:///var/run/netbird-integration-grpc.sock status ``` + + This `--daemon-addr` command only works after configuring the custom gRPC + listener above. If the daemon uses its default listener, run `netbird status` + instead. Do not pass an HTTP/JSON socket to `--daemon-addr`. + + ### Use a TCP Socket ```shell @@ -69,10 +88,10 @@ netbird --daemon-addr tcp://127.0.0.1:41731 status ``` - The daemon gRPC server does not add authentication or 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. + **Security warning:** The daemon gRPC server does not add authentication or + 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. ## Service Definition @@ -104,13 +123,23 @@ The service also includes methods that change configuration, profiles, network s ## Test the Socket with grpcurl -[`grpcurl`](https://github.com/fullstorydev/grpcurl) is a command-line tool for invoking gRPC methods. Clone the NetBird repository so `grpcurl` can load the daemon's Protocol Buffer definition: +[`grpcurl`](https://github.com/fullstorydev/grpcurl) is a command-line tool for invoking gRPC methods. First, check the installed NetBird version: ```shell -git clone --depth 1 https://github.com/netbirdio/netbird.git +netbird version ``` -Run the following examples from the directory that contains the cloned `netbird` directory. +Clone the matching release tag so `grpcurl` uses the same Protocol Buffer definition as the installed daemon. The tag below is an example; replace `v0.75.0-rc.6` with the release tag reported by your installed client. For a development build without a release tag, check out its matching source commit. + +```shell +NETBIRD_VERSION=v0.75.0-rc.6 +git clone --depth 1 \ + --branch "$NETBIRD_VERSION" \ + https://github.com/netbirdio/netbird.git +cd netbird +``` + +Run the following examples from the root of the cloned `netbird` repository. ### Query Status Through the Unix Socket @@ -118,23 +147,25 @@ Run the following examples from the directory that contains the cloned `netbird` grpcurl \ -plaintext \ -unix \ - -import-path ./netbird/client/proto \ + -import-path ./client/proto \ -proto daemon.proto \ -d '{}' \ - /var/run/netbird.sock \ + unix:///var/run/netbird.sock \ daemon.DaemonService/Status ``` To request full peer status, set fields from `StatusRequest` in the JSON request body: +**Sensitive output:** Full peer status may contain network topology, endpoint, route, and peer information. Review or redact it before sharing the output. + ```shell grpcurl \ -plaintext \ -unix \ - -import-path ./netbird/client/proto \ + -import-path ./client/proto \ -proto daemon.proto \ -d '{"getFullPeerStatus": true}' \ - /var/run/netbird.sock \ + unix:///var/run/netbird.sock \ daemon.DaemonService/Status ``` @@ -145,14 +176,14 @@ For the default Windows listener or a custom loopback TCP listener: ```shell grpcurl \ -plaintext \ - -import-path ./netbird/client/proto \ + -import-path ./client/proto \ -proto daemon.proto \ -d '{}' \ 127.0.0.1:41731 \ daemon.DaemonService/Status ``` -`-plaintext` is required because the local daemon socket does not use TLS. For a Unix socket, pass the filesystem path without the `unix://` prefix to `grpcurl` and include its `-unix` option. +`-plaintext` is required because the local daemon socket does not use TLS. For a Unix socket, pass the full `unix:///...` URI and include `-unix`. The URI form also avoids a Unix-socket regression in some `grpcurl` 1.9.x builds. ### Subscribe to Status Changes @@ -162,10 +193,10 @@ Server-streaming methods remain connected and print each response as it arrives. grpcurl \ -plaintext \ -unix \ - -import-path ./netbird/client/proto \ + -import-path ./client/proto \ -proto daemon.proto \ -d '{}' \ - /var/run/netbird.sock \ + unix:///var/run/netbird.sock \ daemon.DaemonService/SubscribeStatus ``` diff --git a/src/pages/client/json-socket.mdx b/src/pages/client/json-socket.mdx index 29e6c1c05..36aca8282 100644 --- a/src/pages/client/json-socket.mdx +++ b/src/pages/client/json-socket.mdx @@ -11,6 +11,10 @@ The daemon's primary local API is documented in [gRPC Daemon Socket](/client/grp Use the JSON socket when your integration cannot use gRPC. For example, it works well in runtimes that only have an HTTP client, local monitoring agents, and application sandboxes where adding a gRPC client and generated protobuf bindings is not practical. + + The HTTP/JSON daemon socket requires NetBird client v0.75.0 or later. + + The HTTP/JSON socket controls the **local NetBird daemon**. It is separate from the NetBird Management API and does not replace it. @@ -30,8 +34,22 @@ The default address is: unix:///var/run/netbird-http.sock ``` + + **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. + + To enable it on an existing installation, reconfigure the service: + + **Connectivity warning:** Every `netbird service reconfigure` command on this + page restarts NetBird and can briefly interrupt tunnel connectivity, routes, + and DNS. + + ```shell sudo netbird service reconfigure --enable-json-socket ``` @@ -45,10 +63,22 @@ Pass an address with the `unix://` scheme to change the socket path: ```shell sudo netbird service reconfigure \ --enable-json-socket \ - --json-socket unix:///run/netbird/integration.sock + --json-socket unix:///var/run/netbird-integration-http.sock ``` -The parent directory must already exist and be writable by the NetBird service. +The parent directory must already exist and be writable by the NetBird service. If you use a dedicated directory to restrict access, configure systemd or tmpfiles to recreate it securely because directories under `/run` do not persist across reboots. + +`--json-socket` configures an HTTP endpoint. Query it with an HTTP client such as `curl`; do not pass this address to `netbird --daemon-addr`. + +```shell +curl --silent --show-error \ + --unix-socket /var/run/netbird-integration-http.sock \ + --request POST \ + --header 'Content-Type: application/json' \ + --data '{}' \ + --write-out '\n' \ + http://localhost/daemon.DaemonService/Status +``` ### Use a TCP Socket @@ -61,10 +91,10 @@ sudo netbird service reconfigure \ ``` - The gateway does not add authentication or 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. + **Security warning:** The gateway does not add authentication or 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. To disable the gateway again, run: @@ -88,10 +118,12 @@ Send the request message as JSON with the `Content-Type: application/json` heade With the default socket path: ```shell -curl --unix-socket /var/run/netbird-http.sock \ +curl --silent --show-error \ + --unix-socket /var/run/netbird-http.sock \ --request POST \ --header 'Content-Type: application/json' \ --data '{}' \ + --write-out '\n' \ http://localhost/daemon.DaemonService/Status ``` @@ -111,9 +143,11 @@ The exact fields and values depend on the client version and current connection If the gateway is listening on `tcp://127.0.0.1:8080`, use a normal HTTP request: ```shell -curl --request POST \ +curl --silent --show-error \ + --request POST \ --header 'Content-Type: application/json' \ --data '{}' \ + --write-out '\n' \ http://127.0.0.1:8080/daemon.DaemonService/Status ``` @@ -122,18 +156,18 @@ curl --request POST \ The following Python example calls the status endpoint over a Unix socket using only the standard library: ```python -import http.client -import json -import socket +from http import client +from json import dumps, load +from socket import AF_UNIX, SOCK_STREAM, socket -class UnixHTTPConnection(http.client.HTTPConnection): +class UnixHTTPConnection(client.HTTPConnection): def __init__(self, socket_path): super().__init__("localhost") self.socket_path = socket_path def connect(self): - self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self.sock = socket(AF_UNIX, SOCK_STREAM) self.sock.connect(self.socket_path) @@ -141,7 +175,7 @@ connection = UnixHTTPConnection("/var/run/netbird-http.sock") connection.request( "POST", "/daemon.DaemonService/Status", - body=json.dumps({}), + body=dumps({}), headers={"Content-Type": "application/json"}, ) response = connection.getresponse() @@ -149,7 +183,7 @@ response = connection.getresponse() if response.status != 200: raise RuntimeError(f"NetBird returned HTTP {response.status}: {response.read().decode()}") -status = json.load(response) +status = load(response) print(status["status"]) connection.close() ``` @@ -205,7 +239,7 @@ If you supplied `--json-socket` without `--enable-json-socket`, NetBird rejects ### Curl Reports Permission Denied -Verify that the process running the integration can access the socket and every parent directory in its path. NetBird creates its Unix socket with read and write permissions for all users, but directory permissions can still prevent access. +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 TCP Request Cannot Connect From abc9650e67b1b06a3f6f5ef91bf28e1b796a2f6c Mon Sep 17 00:00:00 2001 From: PizzaLovingNerd Date: Tue, 21 Jul 2026 20:24:17 -0700 Subject: [PATCH 3/3] Update src/pages/client/grpc-socket.mdx Co-authored-by: Nicolas Frati --- src/pages/client/grpc-socket.mdx | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/src/pages/client/grpc-socket.mdx b/src/pages/client/grpc-socket.mdx index 89af18d7e..20d4b71c5 100644 --- a/src/pages/client/grpc-socket.mdx +++ b/src/pages/client/grpc-socket.mdx @@ -123,16 +123,10 @@ The service also includes methods that change configuration, profiles, network s ## Test the Socket with grpcurl -[`grpcurl`](https://github.com/fullstorydev/grpcurl) is a command-line tool for invoking gRPC methods. First, check the installed NetBird version: +[`grpcurl`](https://github.com/fullstorydev/grpcurl) is a command-line tool for invoking gRPC methods. Because it needs access to the `.proto` files to perform requests, we need to download the repository at the same version that the daemon to not have a mismatch on the Protocol Buffer definition. ```shell -netbird version -``` - -Clone the matching release tag so `grpcurl` uses the same Protocol Buffer definition as the installed daemon. The tag below is an example; replace `v0.75.0-rc.6` with the release tag reported by your installed client. For a development build without a release tag, check out its matching source commit. - -```shell -NETBIRD_VERSION=v0.75.0-rc.6 +export NETBIRD_VERSION=v$(netbird version) git clone --depth 1 \ --branch "$NETBIRD_VERSION" \ https://github.com/netbirdio/netbird.git