netdata-support-bundle — the Netdata support bundle

netdata-support-bundle collects a sanitized diagnostic bundle (tarball on POSIX systems, zip on Windows) that users attach to support tickets, so support gets everything it needs on first contact instead of asking for it over multiple round trips.

• POSIX systems (Linux, Docker, static installs, macOS/BSD best-effort): netdata-support-bundle
• Windows: netdata-support-bundle.ps1

The POSIX file is intentionally extension-less (netdata-support-bundle, not .sh): the installed command and its repository path stay implementation-neutral, so a future reimplementation (e.g. in Rust) can replace it at the same path and command name without changing any build/packaging reference. It is a /bin/sh script today (see the shebang). The Windows counterpart keeps .ps1 because PowerShell requires the extension to execute a script; on Windows a future replacement is shipped through the MSI packaging instead.

# installed with the agent (in PATH, like netdatacli):
sudo netdata-support-bundle

# static installs:
sudo /opt/netdata/usr/sbin/netdata-support-bundle

# For an older agent, download from an immutable release tag that contains the
# tool. Never pipe a URL into a root shell and never use the mutable master ref.
tag='<TRUSTED_NETDATA_RELEASE_TAG>'
t=$(mktemp "${TMPDIR:-/tmp}/netdata-support-bundle.XXXXXX")
trap 'rm -f "$t"' EXIT HUP INT TERM
curl -fsSL -o "$t" "https://raw.githubusercontent.com/netdata/netdata/$tag/packaging/installer/netdata-support-bundle" \
  || wget -qO "$t" "https://raw.githubusercontent.com/netdata/netdata/$tag/packaging/installer/netdata-support-bundle"

Inspect the downloaded script. Only after that separate review, run:

sudo sh "$t"

# Windows (elevated PowerShell):
powershell -ExecutionPolicy Bypass -File "C:\Program Files\Netdata\usr\libexec\netdata\netdata-support-bundle.ps1"

Both scripts implement the same bundle contract: same directory layout, same MANIFEST.json schema (netdata-support-bundle/v1), same sanitization rules. If you change one script, mirror the change in the other and update this document.

Design contract (do not regress these)

Platform support

Portability rules the POSIX script obeys (keep them when editing):

• POSIX sh only — no bashisms (users run it with sh, dash, BusyBox ash).
• No {n,m} regex intervals inside the awk sanitizer — older BSD awks treat them as literal braces, which would silently disable redaction. Character classes are written out explicitly instead.
• Feature-detect, never assume: usable ionice, journalctl, coredumpctl, curl/wget, ss/sockstat/netstat, free/sysctl, /proc availability are all probed before use.
• Every external command is optional: a missing tool degrades that one file, never the run.

Why this exists (evidence)

Analysis of the full Freshdesk ticket history (443 tickets, 2026-07) and 287 maintainer comments across 79 GitHub bug threads showed:

• 24% of support tickets required at least one "please provide X" round trip (average 1.7 per ticket; some needed 3+), each adding a day or more of latency and eroding customer confidence.
• The asks are highly repetitive. Everything ranked below the top-20 asks fits in one automated collection pass.

Every item collected maps to a recurring support ask. That mapping is the "why" column in the tables below. When adding a new item, add its why.

What is collected, and why

summary.txt, MANIFEST.json, README.md (bundle root)

01-system/ — platform context

02-install/ — how netdata got here

03-process/ — the running agent

04-config/ — configuration

05-logs/ — history

06-state/ — persistent state

07-runtime/ — live agent state (only when API responds)

Local API reads target 127.0.0.1:19999 directly and bypass any configured proxy, so diagnostic data cannot leave the host through a forced proxy.

08-network/ — connectivity

What is NEVER collected

These are excluded by design. Do not add them.

• cloud.d/private.pem (ACLK private key), cloud.d/token (claim token)
• bearer_tokens/ (the filenames are live API tokens), netdata.api.key, mcp_dev_preview_api_key, netdata_random_session_id
• /etc/netdata/ssl/ and any *.pem / *.key
• dbengine data files (metric data, GBs), ml.db, registry.db (person GUIDs and dashboard URLs)
• metric values other than netdata's own bounded self-monitoring charts
• anything outside netdata's own scope (no full system journals, no other services' logs, no packet captures)

Redaction philosophy

This tool follows the same proportionate posture as established support-bundle tools (sosreport, supportconfig, kubectl cluster-info dump, Elastic's diagnostics): redact the well-defined, high-value cases robustly, and treat redaction as best-effort defense-in-depth — not a guarantee.

Two facts do the heavy lifting and are why we do not chase completeness:

1. the tool runs on the user's own host, under their own account; and
2. the output is plain-text, organized, and the user is told to review the bundle before sending it (summary.txt and this document say so).

Concretely, we redact credential-bearing config keys, URL/DSN credentials, JWT/Bearer/Basic tokens, PEM key blocks, stream.conf API-key sections, and PII (IPs, MACs, emails, hostnames, usernames); and we never collect files that are pure secrets at all (the never-collect list). We deliberately do not try to parse arbitrary nested structure to prove no secret can ever slip through — a line-based tool cannot balance nested JSON brackets or detect indentation-based YAML block-scalar boundaries reliably, and every attempt adds fragile regex for encodings that do not occur in the data this bundle collects. A brittle sanitizer that tries to do everything is worse than a stable one that does the common cases well; the durable place for structure-aware, schema-driven redaction is inside the agent, not a portable shell/PowerShell script. When extending the tool, prefer this restraint.

Sanitization

Two passes, one sweep, applied to every collected file:

1. Secrets — always on, not configurable:
   • values of any key whose punctuation-normalized name contains a secret word or phrase: api key, apikey, token, password, passwd, pwd, secret, community, bearer, webhook, license key, auth, credential, cookie, passphrase, proxy user, proxy pass, username, dsn, private key, access key, session, recipient, account sid, priv key — in ini (k = v), yaml (k: v), env (K=V) and JSON ("k": "v") forms, covering escaped JSON strings and numeric/scalar JSON values. (Aliases are matched as substrings, so only unambiguous secret tokens are on the list — e.g. pat is deliberately NOT, because it matches path.) Keys must look like real config keys (≤64 chars, no sentence punctuation) so prose containing "token" is not mangled. Exemptions are decided by the KEY, never the value: keys ending in file path dir directory protection support mode level port timeout cookies secure log size options format type describe secrets rather than being secrets, so bearer token protection = no and api key file = /path stay readable while TOKEN=false and PASSWORD=/x are redacted;
   • argv/env-style secrets mid-line (-token=X, --password "X", CLAIM_TOKEN=X, api key = X inside captured process command lines), including single- and double-quoted values;
   • URL-embedded credentials (scheme://user:pass@) and Go DSN credentials (user:pass@tcp(...));
   • JWTs; Bearer <value> where the value contains a digit (real tokens do; this avoids mangling config prose like bearer token protection = no), Basic <value>, and Authorization: header values;
   • secrets in URL query parameters (?token=, &api_key=, ... — request lines in access logs);
   • private-key PEM blocks — the WHOLE multi-line block is withheld from the BEGIN marker through the END marker (fail closed if END never arrives);
   • stream.conf parent-side [<UUID>] section headers (they ARE the API keys);
   • bearer_tokens/ directory listings show a file COUNT only — the filenames are the tokens.
2. PII — on by default, --no-obfuscate / -NoObfuscate to disable:
   • non-loopback IPv4 addresses → ip-N and IPv6 → ip6-N (stable per bundle; compressed, lettered, and numeric-only uncompressed forms; validated so timestamps, file.c:123 refs and ::1 are left alone);
   • MAC addresses → [MAC]; email addresses → [EMAIL];
   • this host's hostname/FQDN → redacted-host; the invoking user's name → redacted-user;
   • ordinary FQDNs → private-host-N; only public Netdata service domains and a small exact allowlist of known Netdata filenames are preserved (a broad suffix exemption would leak names such as customer.key);
   • child/mirrored node hostnames (pre-seeded from the local API before collection, so they pseudonymize consistently in every file) and stream.conf destination hosts regardless of TLD → private-host-N;
   • resolv.conf search/domain values → [SEARCH-DOMAINS-WITHHELD] (corporate search domains are rarely under private TLDs).

The private map is written next to the bundle (*.pseudonym-map.tsv) so the user can decode references if support asks "what is private-host-2?" — it is never included in the bundle itself. Pseudonym mappings are capped at 4096 entries; past the cap, values get a non-correlating placeholder so hostile high-cardinality input cannot grow memory or the private map without bound.

Redaction here is defense in depth, not a substitute for exclusion: files that are pure secrets (see exclusion list) are never read at all. Files containing NUL bytes (binary or BOM-less UTF-16 input) are withheld rather than run through byte-unsafe line redaction. A source file whose leaf is itself a symlink is withheld (a swapped link must not redirect collection to another target); symlinked parent directories resolve normally. Do not extend collection to a directory writable by any other identity. Each run uses a newly created, unpredictable staging directory and never reuses a pre-existing path. POSIX staging is created under umask 077 on POSIX and under the per-user %TEMP% tree on Windows, with an unpredictable random name. Final artifacts (tarball, zip, pseudonym map) are published with a no-overwrite move so a pre-existing file or symlink at the target is never followed or clobbered.

The agent itself provides no redaction anywhere — GET /netdata.conf and netdatacli dumpconfig print secrets verbatim. Everything must be sanitized by these scripts.

How to extend it (checklist for future contributors)

1. Map the new item to a real support ask (link the ticket/issue class) and add it to the right section table above with its why.
2. Use the existing helpers — collect_cmd / collect_file / collect_api (Save-Cmd / Save-File / Save-Api / Save-CmdRaw on Windows). They enforce timeouts, size caps, sanitization, and manifest registration. Never write into the bundle directly.
3. Respect the cost budget: nothing unbounded, nothing that queries metric data without a tight window, nothing that can block longer than the per-command timeout.
4. If the item can contain credentials of a NEW shape, extend the sanitizer in both scripts and add the pattern to the Sanitization section above.
5. Mirror the change in the other script (.sh ↔ .ps1) or record explicitly in your PR why it is platform-specific.
6. Test the redaction: add a vector to the built-in regression suite and run netdata-support-bundle --selftest (netdata-support-bundle.ps1 -SelfTest on Windows) — it must pass on GNU awk, mawk, BusyBox awk, and PowerShell. CI executes both suites. For new collection sources also plant a sentinel secret in the source, run a collection, and grep -r the extracted bundle. Zero hits or it does not ship.
7. Never add anything from the "What is NEVER collected" list, and never make the tool write, restart, reconfigure, or otherwise mutate the system.

Bundle format contract

• Schema id: netdata-support-bundle/v1 (in MANIFEST.json). Bump the suffix on breaking layout changes; downstream ticket tooling may parse it.
• Command captures are .txt files starting with a # netdata-support-bundle v<version> | command: ... | captured: <utc> header; on POSIX they also end with an # exit: N | duration: Ns trailer. PowerShell command captures carry the provenance header only (background jobs do not surface a meaningful process exit code).
• Copied files and API responses are sanitized without provenance headers (and remain parseable when they fit their cap); their provenance lives in MANIFEST.json, not in the files.