From ae138dde4b2f9d24f6fa0b982006269c4c54fe89 Mon Sep 17 00:00:00 2001 From: riccardom Date: Thu, 3 Sep 2026 13:17:44 +0200 Subject: [PATCH] Document where debug bundles are uploaded A debug bundle carries the peer's logs, routes, DNS and firewall state, and the client now takes the upload destination from the management server rather than compiling in the service NetBird runs. Document the new Clients setting, the `DebugUpload.URL` fallback in management.json, and what an unset destination means for cloud and self-hosted deployments. Pairs with the netbird change that publishes the destination to peers. --- src/pages/manage/peers/remote-jobs.mdx | 4 ++++ src/pages/manage/settings/clients.mdx | 28 +++++++++++++++++++++++++- 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/src/pages/manage/peers/remote-jobs.mdx b/src/pages/manage/peers/remote-jobs.mdx index e9b0b013..1d19586d 100644 --- a/src/pages/manage/peers/remote-jobs.mdx +++ b/src/pages/manage/peers/remote-jobs.mdx @@ -62,6 +62,10 @@ The Debug Bundle job remotely collects diagnostic information from a peer, inclu On success, the job returns an **upload key** that can be used to retrieve the debug bundle. Share this key with NetBird support via GitHub Issues, Slack, or your support channel. +**Where the bundle goes:** + +The bundle is uploaded to the destination configured for your account under [Settings > Clients](/manage/settings/clients#debug-bundle-upload), or to the upload service NetBird runs when no destination is configured. Set that setting if the bundles must stay inside your own infrastructure. + ## Using the Dashboard ### Creating a Remote Job diff --git a/src/pages/manage/settings/clients.mdx b/src/pages/manage/settings/clients.mdx index ef70039d..8cade453 100644 --- a/src/pages/manage/settings/clients.mdx +++ b/src/pages/manage/settings/clients.mdx @@ -1,5 +1,5 @@ export const description = - 'Configure account-wide client behavior: automatic updates, lazy connections, and exposing services from the CLI.' + 'Configure account-wide client behavior: automatic updates, lazy connections, exposing services from the CLI, and where debug bundles are uploaded.' # Client Settings @@ -23,6 +23,32 @@ When enabled, you must select at least one peer group under `Allowed peer groups See [Expose Services from the CLI](/manage/reverse-proxy/expose-from-cli) for command usage and examples. +## Debug Bundle Upload + +`Debug Bundle Upload` sets the upload service your peers send debug bundles to. A bundle carries the peer's logs, routes, DNS configuration and firewall state, so this setting decides whose infrastructure that data lands on. It applies to every path that uploads a bundle without someone typing a destination: [remote jobs](/manage/peers/remote-jobs), the mobile clients, the desktop client, and `netbird debug bundle -U`. + +Enter the upload service's URL, for example `https://upload.example.com/upload-url`. The URL must use `https`: the peer asks this endpoint for an upload URL and then uploads the bundle to whatever it returns, so a plaintext hop would expose both. Self-hosted deployments can run the [upload server](https://github.com/netbirdio/netbird/tree/main/upload-server) that ships with NetBird, or point this at any service exposing the same endpoint. + +Leaving it empty means the account publishes no destination, and peers upload to the service NetBird runs — on a self-hosted deployment as much as on NetBird Cloud. That keeps the everyday flow working: collect a bundle, get an upload key, share it with support. If the bundles must not leave your own infrastructure, set this to your own upload service; until you do, they go to NetBird. + +A self-hosted deployment can set the destination for every account at once with `DebugUpload.URL` in `management.json`: + +```json +{ + "DebugUpload": { + "URL": "https://upload.example.com/upload-url" + } +} +``` + +The account setting overrides that value when set. An MDM-managed client overrides both, through the `debugBundleUploadURL` policy key — see [MDM integration](/client/mdm-integration). So the order is: + +```text +MDM policy > --upload-bundle-url (or a remote job's Upload URL) > account setting > management.json > NetBird's service +``` + +`netbird debug bundle` without `-U` never uploads at all: it writes the bundle locally and prints the path. + ## Lazy Connections Instead of maintaining always-on connections, NetBird can activate peer connections on demand based on activity or signaling. Enable the `Enable Lazy Connections` toggle to turn this on for compatible clients. This requires NetBird client v0.50.1 or higher.