From 637670d1b069976a3da4e9f86a5026f148fb16da Mon Sep 17 00:00:00 2001 From: netdatabot <43409846+netdatabot@users.noreply.github.com> Date: Sat, 20 Jun 2026 17:54:52 +0000 Subject: [PATCH] Ingest new documentation --- .../Alert Configuration Ordering.mdx | 12 +- .../Alerts & Notifications.mdx | 189 ++++++++++++++---- .../Overriding Stock Alerts.mdx | 93 ++++++--- .../Networking/SNMP trap listener.mdx | 16 +- docs/Collecting Metrics/StatsD.mdx | 30 ++- .../External Plugins/External Plugins.mdx | 12 +- .../MCP/MCP Clients/Claude Code.mdx | 2 +- docs/Netdata AI/MCP/MCP Clients/Crush.mdx | 2 +- .../Netdata AI/MCP/MCP Clients/Gemini CLI.mdx | 2 +- .../MCP/MCP Clients/OpenAI Codex CLI.mdx | 2 +- docs/Netdata AI/MCP/MCP Clients/OpenCode.mdx | 2 +- docs/Netdata AI/MCP/MCP.mdx | 28 ++- .../Bearer Token Protection.mdx | 11 + .../Securing Agents/Securing Agents.mdx | 3 + .../Securing Agents/Web Server Reference.mdx | 11 +- docs/Netdata Agent/Database.mdx | 9 +- .../Role-based access model.mdx | 4 + .../Enrichment Methods/AWS IP Ranges.mdx | 4 +- .../Enrichment Methods/Azure IP Ranges.mdx | 4 +- .../BMP BGP Monitoring Protocol.mdx | 4 +- .../CAIDA Routeviews Prefix-to-AS.mdx | 4 +- .../Enrichment Methods/Classifiers.mdx | 4 +- .../Custom MMDB Database.mdx | 4 +- .../DB-IP IP Intelligence.mdx | 4 +- .../Enrichment Methods/Decapsulation.mdx | 4 +- .../Enrichment Methods/GCP IP Ranges.mdx | 4 +- .../Generic JSON-over-HTTP IPAM.mdx | 4 +- .../IP2Location LITE IP-Country.mdx | 4 +- .../IPDeny Country Zones.mdx | 4 +- .../IPIP Country Database.mdx | 4 +- .../Enrichment Methods/IPtoASN.mdx | 4 +- .../MaxMind GeoIP GeoLite2.mdx | 4 +- .../Enrichment Methods/NetBox.mdx | 4 +- .../Enrichment Methods/Static Metadata.mdx | 4 +- .../Enrichment Methods/bio-rd RIPE RIS.mdx | 4 +- docs/Network Flows/Flow Protocols/IPFIX.mdx | 4 +- docs/Network Flows/Flow Protocols/NetFlow.mdx | 4 +- docs/Network Flows/Flow Protocols/sFlow.mdx | 4 +- docs/Network Flows/Installation.mdx | 2 +- docs/SNMP Traps/Configuration.mdx | 6 +- docs/SNMP Traps/Forwarding to SIEM.mdx | 2 +- docs/SNMP Traps/Installation.mdx | 8 +- docs/SNMP Traps/SNMP Trap Profile Format.mdx | 10 +- .../Validation and Data Quality.mdx | 2 +- ...ccess Control and Feature Availability.mdx | 2 + 45 files changed, 366 insertions(+), 178 deletions(-) diff --git a/docs/Alerts & Notifications/Alert Configuration Ordering.mdx b/docs/Alerts & Notifications/Alert Configuration Ordering.mdx index ba9c11d035..abeb4fa65f 100644 --- a/docs/Alerts & Notifications/Alert Configuration Ordering.mdx +++ b/docs/Alerts & Notifications/Alert Configuration Ordering.mdx @@ -88,18 +88,20 @@ Both have the **same name** (`disk_space_usage`), so precedence applies: Netdata loads alert configurations from two directories: -1. **User config** (loaded first): `/etc/netdata/health.d/` (default) -2. **Stock config** (loaded second): `/usr/lib/netdata/conf.d/health.d/` (default) +1. **User config** (loaded first): your `health.d/` directory under the [Netdata config directory](/docs/netdata-agent/configuration) +2. **Stock config** (loaded second): the stock `health.d/` directory -These paths can vary by installation. Check your `netdata.conf` `[directories]` section for exact paths. +:::note +Config paths vary by install prefix. Run `sudo ./edit-config health.d/` to resolve the correct user path automatically, or check the `[directories]` section of `netdata.conf` (keys `health config` and `stock health config`) for exact locations. +::: ### File Shadowing If a file with the **same name** exists in both directories, only the user file is loaded. The stock file is completely ignored. **Example:** -- Stock: `/usr/lib/netdata/conf.d/health.d/cpu.conf` -- User: `/etc/netdata/health.d/cpu.conf` +- Stock: `cpu.conf` in the stock config directory +- User: `cpu.conf` in your user config directory - Result: Only the user file is loaded This means if you copy a stock file to override it, you must include **all** alerts you want from that file, not just the ones you're modifying. diff --git a/docs/Alerts & Notifications/Alerts & Notifications.mdx b/docs/Alerts & Notifications/Alerts & Notifications.mdx index e2e968732f..99fea42ecb 100644 --- a/docs/Alerts & Notifications/Alerts & Notifications.mdx +++ b/docs/Alerts & Notifications/Alerts & Notifications.mdx @@ -48,6 +48,7 @@ Your Netdata Agents treat notifications as **actions** triggered by alert status When you claim Agents to Netdata Cloud, they send their alert configurations and transitions to Cloud, which deduplicates them (merging multiple transitions from different Agents for the same host). Netdata Cloud triggers notifications centrally through its integrations (Slack, Microsoft Teams, Amazon SNS, PagerDuty, OpsGenie). Netdata Cloud's intelligent deduplication works by: + - **Consolidating multiple Agents** reporting the same alert - **Prioritizing highest severity**: CRITICAL > WARNING > CLEAR - **Creating unique keys**: Alert name + Instance + Node @@ -55,6 +56,7 @@ Netdata Cloud's intelligent deduplication works by: Your Agents and Netdata Cloud trigger actions independently using their own configurations and integrations. This design enables you to: + 1. **Maintain team independence**: Different teams run their own Parents with custom alerts 2. **Implement edge intelligence**: Critical alerts trigger automations directly on nodes 3. **Scale naturally**: Alert evaluation distributes with your infrastructure @@ -88,22 +90,26 @@ Each level operates independently while Netdata Cloud provides a coherent, dedup You configure Netdata alerts in 3 layers: -1. **Stock Alerts**: Netdata provides hundreds of alert definitions in `/usr/lib/netdata/conf.d/health.d` to detect common issues. Don't edit these directly - updates will overwrite your changes. -2. **Your Custom Alerts**: Create your own definitions in `/etc/netdata/health.d`. +1. **Stock Alerts**: Netdata provides hundreds of alert definitions in the stock `health.d/` directory to detect common issues. Don't edit these directly - updates will overwrite your changes. +2. **Your Custom Alerts**: Create your own definitions in your [Netdata config directory](/docs/netdata-agent/configuration) under `health.d/`. 3. **Dynamic UI Configuration**: Use Netdata dashboards to edit, add, enable, or disable alerts on any node through the streaming transport. +:::note +Config paths vary by install prefix. Run `sudo ./edit-config health.d/` from your Netdata config directory to resolve the correct user path automatically, or check the `[directories]` section of `netdata.conf` (keys `health config` and `stock health config`) for exact locations. +::: + ## Managing Notification Configuration You can configure notifications for any infrastructure node at 3 levels: -| Level | What It Evaluates | Where Notifications Come From | Use Case | Documentation | -|--------------------|-----------------------------|--------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| **Netdata Agent** | Local Metrics | Netdata Agent | Edge automation | [Agent integrations](https://learn.netdata.cloud/docs/alerts-&-notifications/notifications/agent-dispatched-notifications) | -| **Netdata Parent** | Local and Children Metrics | Netdata Parent | Edge automation | [Agent integrations](https://learn.netdata.cloud/docs/alerts-&-notifications/notifications/agent-dispatched-notifications) | -| **Netdata Cloud** | Receives Transitions | Netdata Cloud | Web-hooks, role/room based | [Cloud integrations](https://learn.netdata.cloud/docs/alerts-&-notifications/notifications/centralized-cloud-notifications) | +| Level | What It Evaluates | Where Notifications Come From | Use Case | Documentation | +|--------------------|----------------------------|-------------------------------|----------------------------|-----------------------------------------------------------------------------------------------------------------------------| +| **Netdata Agent** | Local Metrics | Netdata Agent | Edge automation | [Agent integrations](https://learn.netdata.cloud/docs/alerts-&-notifications/notifications/agent-dispatched-notifications) | +| **Netdata Parent** | Local and Children Metrics | Netdata Parent | Edge automation | [Agent integrations](https://learn.netdata.cloud/docs/alerts-&-notifications/notifications/agent-dispatched-notifications) | +| **Netdata Cloud** | Receives Transitions | Netdata Cloud | Web-hooks, role/room based | [Cloud integrations](https://learn.netdata.cloud/docs/alerts-&-notifications/notifications/centralized-cloud-notifications) | :::note -When using Parents and Cloud with default settings, you may receive duplicate email notifications. Agents send emails by default when an MTA exists on their systems. Disable email notifications on Agents and Parents when using Cloud by setting `SEND_EMAIL="NO"` in `/etc/netdata/health_alarm_notify.conf` [using `edit-config`](/docs/netdata-agent/configuration). +When using Parents and Cloud with default settings, you may receive duplicate email notifications. Agents send emails by default when an MTA exists on their systems. Disable email notifications on Agents and Parents when using Cloud by setting `SEND_EMAIL="NO"` in `health_alarm_notify.conf`, edited with `sudo ./edit-config health_alarm_notify.conf` from your [Netdata config directory](/docs/netdata-agent/configuration). ::: ### Best Practices for Large Deployments @@ -111,14 +117,16 @@ When using Parents and Cloud with default settings, you may receive duplicate em #### Central Alerting Strategy When you: + - Don't need edge automation (no scripts reacting to alerts) - Use highly available Parents for all nodes - Use Netdata Cloud (at least for Parents) Follow these steps: + 1. Disable health monitoring on child nodes 2. Share the same alert configuration across Parents (use git repo or CI/CD) -3. Disable Parent notifications (`SEND_EMAIL="NO"` in `/etc/netdata/health_alarm_notify.conf`) +3. Disable Parent notifications (`SEND_EMAIL="NO"` in `health_alarm_notify.conf`) 4. Keep only Cloud notifications This emulates traditional monitoring tools where you configure alerts centrally and dispatch notifications centrally. @@ -126,12 +134,14 @@ This emulates traditional monitoring tools where you configure alerts centrally #### Edge Flexible Alerting Strategy When you: + - Need edge automation (scale out, restart processes) - Use Parents - Use Cloud for all nodes Follow these steps: -- Disable stock alerts on children (`enable stock health configuration` to `no` in `/etc/netdata/netdata.conf` `[health]` section) + +- Disable stock alerts on children (set `enable stock health configuration` to `no` in the `[health]` section of `netdata.conf`; edit with `sudo ./edit-config netdata.conf`) - Configure only automation-required alerts on children - Keep stock alerts on Parents but disable notifications (`SEND_EMAIL="NO"`) - Keep only Cloud notifications @@ -150,11 +160,13 @@ This enables edge automation on children while maintaining central alerting cont ## Set Up Alerts via Netdata Agent 1. Open notification config: + ```bash sudo ./edit-config health_alarm_notify.conf ``` 2. Enable your method (example: email): + ```ini SEND_EMAIL="YES" DEFAULT_RECIPIENT_EMAIL="you@example.com" @@ -163,6 +175,7 @@ This enables edge automation on children while maintaining central alerting cont 3. Verify your system can send mail (sendmail, SMTP relay) 4. Restart the agent: + ```bash sudo systemctl restart netdata ``` @@ -172,17 +185,20 @@ This enables edge automation on children while maintaining central alerting cont ## Core Alerting Concepts Netdata supports two alert types: + - **Alarms**: Attach to specific instances (specific network interface, database instance) - **Templates**: Apply to all matching instances (all network interfaces, all databases) ### Alert Lifecycle and States Your alerts produce more than threshold checks. Each generates: + - **A value**: Combines metrics or other alerts using time-series lookups and expressions - **A unit**: Makes alerts meaningful ("seconds", "%", "requests/s") - **A name**: Identifies the alert This enables sophisticated alerts like: + - `out of disk space time: 450 seconds` - Predicts when disk fills based on current rate - `3xx redirects: 12.5 percent` - Calculates redirects as percentage of total - `response time vs yesterday: 150%` - Compares current to historical baseline @@ -191,21 +207,23 @@ This enables sophisticated alerts like: Your alerts exist in one of these states: -| State | Description | Trigger | -|-------------------|---------------------------------------------------|--------------------------------------------------------------------------| -| **CLEAR** | Normal - conditions exist but not triggered | Warning and critical conditions evaluate to zero | -| **WARNING** | Warning threshold exceeded | Warning condition evaluates to non-zero | -| **CRITICAL** | Critical threshold exceeded | Critical condition evaluates to non-zero | -| **UNDEFINED** | Cannot evaluate | No conditions defined, or value is NaN/Inf | -| **UNINITIALIZED** | Never evaluated | Alert just created | -| **REMOVED** | Alert deleted | Child disconnected, agent exit, or health reload | +| State | Description | Trigger | +|-------------------|---------------------------------------------|--------------------------------------------------| +| **CLEAR** | Normal - conditions exist but not triggered | Warning and critical conditions evaluate to zero | +| **WARNING** | Warning threshold exceeded | Warning condition evaluates to non-zero | +| **CRITICAL** | Critical threshold exceeded | Critical condition evaluates to non-zero | +| **UNDEFINED** | Cannot evaluate | No conditions defined, or value is NaN/Inf | +| **UNINITIALIZED** | Never evaluated | Alert just created | +| **REMOVED** | Alert deleted | Child disconnected, agent exit, or health reload | Alerts transition freely between states based on: + - **Calculated value** (including NaN, Inf, or valid numbers) - **Warning/critical conditions** (evaluation results) - **External events** (disconnections, reloads, exits) Key behaviors: + - Alerts jump directly from CLEAR to CRITICAL (no WARNING required) - WARNING and CRITICAL evaluate independently - Alerts return to appropriate state when data becomes available @@ -227,6 +245,7 @@ Your alerts perform complex calculations: ``` Examples: + ```yaml # Simple threshold calc: $used @@ -268,11 +287,13 @@ crit: $this > 90 OR $failures > 5 #### 3. Determine State Each condition evaluates to: + - NaN or Inf → UNDEFINED - Non-zero → RAISED - Zero → CLEAR Final status: + - Critical RAISED → **CRITICAL** (priority) - Warning RAISED → **WARNING** - Either CLEAR → **CLEAR** @@ -303,19 +324,24 @@ Data Collection Alert Evaluation Netdata prevents alert flapping through: #### 1. Hysteresis + ```yaml warn: ($status < $WARNING) ? ($this > 80) : ($this > 50) ``` + Triggers at 80, clears at 50, preventing flapping between 50-80. #### 2. Dynamic Delays + Alerts transition immediately in dashboards but notifications use exponential backoff. #### 3. Duration Requirements + ```yaml lookup: average -10m of used warn: $this > 80 ``` + Requires 10 minutes of data before triggering. ### Multi-Stage Alerts @@ -350,29 +376,29 @@ Variables resolve in order (first match wins): #### 1. Built-in Variables -| Variable | Description | Value | -|---------------------|---------------------------|--------------------| -| `$this` | Current calculated value | Result from lookup/calc | -| `$after` | Query start timestamp | Unix timestamp | -| `$before` | Query end timestamp | Unix timestamp | -| `$now` | Current time | Unix timestamp | -| `$last_collected_t` | Last collection time | Unix timestamp | -| `$update_every` | Collection frequency | Seconds | -| `$status` | Current status code | -2 to 3 | -| `$REMOVED` | Status constant | -2 | -| `$UNINITIALIZED` | Status constant | -1 | -| `$UNDEFINED` | Status constant | 0 | -| `$CLEAR` | Status constant | 1 | -| `$WARNING` | Status constant | 2 | -| `$CRITICAL` | Status constant | 3 | +| Variable | Description | Value | +|---------------------|--------------------------|-------------------------| +| `$this` | Current calculated value | Result from lookup/calc | +| `$after` | Query start timestamp | Unix timestamp | +| `$before` | Query end timestamp | Unix timestamp | +| `$now` | Current time | Unix timestamp | +| `$last_collected_t` | Last collection time | Unix timestamp | +| `$update_every` | Collection frequency | Seconds | +| `$status` | Current status code | -2 to 3 | +| `$REMOVED` | Status constant | -2 | +| `$UNINITIALIZED` | Status constant | -1 | +| `$UNDEFINED` | Status constant | 0 | +| `$CLEAR` | Status constant | 1 | +| `$WARNING` | Status constant | 2 | +| `$CRITICAL` | Status constant | 3 | #### 2. Dimension Values -| Syntax | Description | Example | -|------------------------------------|----------------------------------|------------------| -| `$dimension_name` | Last normalized value | `$used` | -| `$dimension_name_raw` | Last raw collected value | `$used_raw` | -| `$dimension_name_last_collected_t` | Collection timestamp | `$used_last_collected_t` | +| Syntax | Description | Example | +|------------------------------------|--------------------------|--------------------------| +| `$dimension_name` | Last normalized value | `$used` | +| `$dimension_name_raw` | Last raw collected value | `$used_raw` | +| `$dimension_name_last_collected_t` | Collection timestamp | `$used_last_collected_t` | ```yaml template: disk_usage_percent @@ -382,16 +408,19 @@ template: disk_usage_percent ``` #### 3. Chart Variables + ```yaml calc: $used > $threshold # If chart defines 'threshold' ``` #### 4. Host Variables + ```yaml warn: $connections > $max_connections * 0.8 # If host defines 'max_connections' ``` #### 5. Other Alerts + ```yaml # Alert 1 template: cpu_baseline @@ -404,6 +433,7 @@ template: cpu_check ``` #### 6. Cross-Context References + ```yaml template: disk_io_vs_iops on: disk.io @@ -420,6 +450,7 @@ When alerts reference variables matching multiple instances, Netdata uses label 3. **Select best match** - highest label overlap Example: Alert on `disk.io` (labels: `device=sda`, `mount=/data`) references `${disk.iops.reads}`: + - `disk.iops` for sda (labels match) → Score: 2 - `disk.iops` for sdb (no match) → Score: 0 Result: Uses sda's value @@ -427,6 +458,7 @@ Result: Uses sda's value ### Missing Data Handling During lookups with missing data: + - **All values NULL**: `$this` becomes `NaN` - **Some values exist**: Ignores NULL, continues calculation - **Dimension doesn't exist**: `$this` becomes `NaN` @@ -438,23 +470,27 @@ This handles intermittent collection, dynamic dimensions, and partial outages. Determine frequency by: 1. **With lookup**: Defaults to window duration + ```yaml lookup: average -5m # Evaluates every 5 minutes ``` 2. **Without lookup**: Set explicitly + ```yaml every: 10s calc: $system + $user ``` 3. **Custom interval**: Override default + ```yaml lookup: average -1m every: 10s # Check every 10s despite 1m window ``` Constraints: + - Cannot exceed data collection frequency - High frequency impacts performance - Use larger intervals with `unaligned` for efficiency @@ -463,7 +499,7 @@ Constraints: ### Netdata Assistant -The [Netdata Assistant](https://learn.netdata.cloud/docs/machine-learning-and-anomaly-detection/ai-powered-troubleshooting-assistant) provides AI-powered troubleshooting when alerts trigger: +The [Netdata Assistant](/docs/netdata-ai/troubleshooting/alert-troubleshooting) provides AI-powered troubleshooting when alerts trigger: 1. Click the alert in your dashboard 2. Press the Assistant button @@ -471,6 +507,81 @@ The [Netdata Assistant](https://learn.netdata.cloud/docs/machine-learning-and-an The Assistant window follows you through dashboards for easy reference while investigating. +### Missing or No Stock Alerts + +If your node has no stock alerts (the built-in alerts that ship with Netdata), check these common causes in order. The commands below use default install paths; adjust them if your Netdata was installed with a non-standard prefix (see [Managing Alert Configuration](#managing-alert-configuration) above). + +#### 1. Health monitoring disabled entirely + +When `enabled = no` is set in the `[health]` section of `netdata.conf`, the Agent stops evaluating all alerts. + +Check: + +```bash +grep 'enabled' /etc/netdata/netdata.conf +``` + +No output means the setting uses its default value (`yes`) — health monitoring is enabled. + +Restore: set `enabled = yes` in the `[health]` section (or remove the line to use the default), then restart the Agent: + +```bash +sudo systemctl restart netdata +``` + +#### 2. Stock health configuration disabled + +The `enable stock health configuration = no` setting in the `[health]` section of `netdata.conf` disables all stock alerts while keeping custom alerts active. + +Check: + +```bash +grep 'enable stock health configuration' /etc/netdata/netdata.conf +``` + +Restore: set `enable stock health configuration = yes` (or remove the line to use the default), then restart the Agent — `netdatacli reload-health` does not reload `netdata.conf`: + +```bash +sudo systemctl restart netdata +``` + +#### 3. File shadowing + +If a file in your user config directory has the same filename as a stock file (e.g., both contain `cpu.conf`), the stock file is **completely ignored** — only the user copy is loaded. If the user copy contains only a subset of the original alerts, the rest are missing. + +This is different from overriding individual alerts by name. With file shadowing, you must include **all** alerts you want from that file. See [Alert Configuration Ordering](/docs/alerts-&-notifications/alert-configuration-ordering) for the conceptual explanation. + +Check — compare filenames between your user and stock directories: + +```bash +comm -12 <(ls /etc/netdata/health.d/ | sort) <(ls /usr/lib/netdata/conf.d/health.d/ | sort) +``` + +Restore: if the user copy is no longer needed, remove it from your user health config directory: + +```bash +sudo rm /etc/netdata/health.d/.conf +sudo netdatacli reload-health +``` + +If you need a modified version, ensure it includes all desired alerts from the stock file. + +#### 4. Dynamic UI/API configuration override + +Editing an alert through the Cloud dashboard or Agent UI creates a dynamic configuration (DynCfg) override that replaces the file-based definition. The override persists even if the underlying file changes. + +Restore: use the **Reset to default** option in the UI for each affected alert, or remove the dynamic config via the API. See [Overriding Stock Alerts](/docs/alerts-&-notifications/overriding-stock-alerts) for full override documentation. + +#### Verify stock alerts are active + +After any fix, confirm the number of active alerts: + +```bash +curl -s "http://localhost:19999/api/v1/alarms?all" | jq '.alarms | to_entries[].value.name' | sort -u | wc -l +``` + +A healthy Netdata Agent typically has hundreds of stock alerts. If the count is very low, one of the causes above may still apply. + ### Community Resources Visit our [Alerts Troubleshooting space](https://community.netdata.cloud/c/alerts/28) for complex issues. Get help through [GitHub](https://github.com/netdata/netdata) or [Discord](https://discord.gg/kUk3nCmbtx). Share your solutions to help others. diff --git a/docs/Alerts & Notifications/Overriding Stock Alerts.mdx b/docs/Alerts & Notifications/Overriding Stock Alerts.mdx index fbe8525a7c..3c8bf34d18 100644 --- a/docs/Alerts & Notifications/Overriding Stock Alerts.mdx +++ b/docs/Alerts & Notifications/Overriding Stock Alerts.mdx @@ -15,12 +15,12 @@ This guide explains how to customize Netdata's stock alerts. User configurations ## Quick Reference -| Goal | Method | -|------|--------| +| Goal | Method | +|-------------------------------------|--------------------------------------| | Change thresholds for ALL instances | Create a template with the same name | -| Change thresholds for ONE instance | Create an alarm with the same name | -| Disable an alert completely | Use `enabled alarms` in netdata.conf | -| Silence notifications only | Set `to: silent` | +| Change thresholds for ONE instance | Create an alarm with the same name | +| Disable an alert completely | Use `enabled alarms` in netdata.conf | +| Silence notifications only | Set `to: silent` | ## Understanding Overrides @@ -32,11 +32,11 @@ See [Alert Configuration Ordering](/docs/alerts-&-notifications/alert-configurat ## Where to Put Your Overrides -**User config directory** (default): `/etc/netdata/health.d/` +Put your overrides in your [Netdata config directory](/docs/netdata-agent/configuration) under `health.d/` — files there survive upgrades. The **stock config directory** holds Netdata's built-in alert definitions and is replaced during updates. -Files here survive upgrades. Stock files in `/usr/lib/netdata/conf.d/health.d/` are replaced during updates. - -Check your `netdata.conf` `[directories]` section for exact paths on your system. +:::note +Config paths vary by install prefix. Run `sudo ./edit-config health.d/` from your Netdata config directory to resolve the correct user path automatically, or check the `[directories]` section of `netdata.conf` (keys `health config` and `stock health config`) for exact locations. +::: ## Method 1: Override All Instances (Template) @@ -44,24 +44,42 @@ Create a template with the same name to change thresholds for ALL instances. **Example: Raise CPU steal thresholds globally** -Stock alert in `/usr/lib/netdata/conf.d/health.d/cpu.conf`: +Stock alert from `cpu.conf` (in the stock config directory): + ```yaml -template: 20min_steal_cpu - on: system.cpu - lookup: average -20m unaligned of steal - units: % - every: 5m - warn: $this > (($status >= $WARNING) ? (5) : (10)) + template: 20min_steal_cpu + on: system.cpu + class: Latency + type: System + component: CPU +host labels: _os=linux + lookup: average -20m unaligned of steal + units: % + every: 5m + warn: $this > (($status >= $WARNING) ? (5) : (10)) + delay: down 1h multiplier 1.5 max 2h + summary: System CPU steal time + info: Average CPU steal time over the last 20 minutes + to: silent ``` -Your override in `/etc/netdata/health.d/my-overrides.conf`: +Your override (create it with `sudo ./edit-config health.d/my-overrides.conf`): + ```yaml -template: 20min_steal_cpu - on: system.cpu - lookup: average -20m unaligned of steal - units: % - every: 5m - warn: $this > (($status >= $WARNING) ? (10) : (20)) + template: 20min_steal_cpu + on: system.cpu + class: Latency + type: System + component: CPU +host labels: _os=linux + lookup: average -20m unaligned of steal + units: % + every: 5m + warn: $this > (($status >= $WARNING) ? (10) : (20)) + delay: down 1h multiplier 1.5 max 2h + summary: System CPU steal time + info: Average CPU steal time over the last 20 minutes + to: silent ``` **Why it works:** Same name + same context. Your template is processed first, creating the alert. The stock template is then skipped. @@ -75,6 +93,7 @@ Create an alarm to override thresholds for ONE specific instance while keeping s **Example: Different disk space threshold for `/mnt/data`** Stock template (applies to all disks): + ```yaml template: disk_space_usage on: disk.space @@ -83,7 +102,8 @@ template: disk_space_usage crit: $this < 10 ``` -Your override in `/etc/netdata/health.d/my-overrides.conf`: +Your override (create it with `sudo ./edit-config health.d/my-overrides.conf`): + ```yaml alarm: disk_space_usage on: disk_space._mnt_data @@ -93,6 +113,7 @@ alarm: disk_space_usage ``` **Why it works:** + - Both have the **same name** (`disk_space_usage`) - Your **alarm** targets the specific chart ID `disk_space._mnt_data` - Alarms are processed before templates (when names match) @@ -125,6 +146,7 @@ chart labels: mount_point=/mnt/data ``` Use labels when: + - You want to target multiple instances sharing a label - Chart IDs are dynamic or unpredictable @@ -133,7 +155,7 @@ Use labels when: If you want to modify many alerts in one stock file, copy it entirely: ```bash -cd /etc/netdata +# from your Netdata config directory: sudo ./edit-config health.d/cpu.conf ``` @@ -145,7 +167,7 @@ This means your copy must include ALL alerts you want—not just the ones you're ### Option A: Global Disable -In `/etc/netdata/netdata.conf`: +In your `netdata.conf` (edit it with `sudo ./edit-config netdata.conf`): ```ini [health] @@ -195,11 +217,13 @@ If `netdatacli` isn't available, send `SIGUSR2` to the Netdata process. ### Verify Your Override Check via API: + ```bash curl -s "http://localhost:19999/api/v1/alarms?all" | jq '.alarms | to_entries[] | select(.value.name == "20min_steal_cpu") | .value' ``` Key fields to check: + - `source`: confirms which config file is active (user override vs stock) - `lookup_*`: data query parameters - `warn`, `crit`: threshold expressions @@ -219,6 +243,7 @@ grep -i health /var/log/netdata/error.log | tail -20 ``` Common issues: + - Syntax errors in configuration - Alert name doesn't match exactly (case-sensitive) - File permissions prevent Netdata from reading your config @@ -235,6 +260,7 @@ Common issues: ### Both Stock and Override Alerts Appear This happens when matching criteria don't overlap. For example: + - Your override has `host labels: production` - Stock alert has no host labels restriction @@ -274,17 +300,20 @@ Both can coexist because they match different hosts. ### How do I find what stock alerts exist? -List all stock alert files: +List the stock alert files (the command below uses the default stock directory): + ```bash ls /usr/lib/netdata/conf.d/health.d/ ``` View a specific stock alert: + ```bash cat /usr/lib/netdata/conf.d/health.d/cpu.conf ``` -Or use the API to list all alert names: +Or use the API to list all alert names without dealing with paths: + ```bash curl -s "http://localhost:19999/api/v1/alarms?all" | jq '.alarms | to_entries[].value.name' | sort -u ``` @@ -303,13 +332,14 @@ template: my_custom_disk_alert ### What happens to my overrides after a Netdata upgrade? -User config files in `/etc/netdata/health.d/` are preserved. Stock files in `/usr/lib/netdata/conf.d/health.d/` are replaced. +User config files are preserved across upgrades. Stock files are replaced. Your overrides continue working. However, if a stock alert is renamed or removed in a new version, your override may become orphaned (still works, but no longer overriding anything). ### How do I override for multiple specific instances? Option 1: Create multiple alarms (one per instance): + ```yaml alarm: disk_space_usage on: disk_space._mnt_data @@ -321,6 +351,7 @@ alarm: disk_space_usage ``` Option 2: Use chart labels if instances share a label: + ```yaml template: disk_space_usage on: disk.space @@ -331,6 +362,7 @@ chart labels: storage_tier=bulk ### Can I see what overrides are currently active? Check which config files Netdata loaded: + ```bash # systemd journal: journalctl --namespace netdata -g "health.*load\|health.*read" --no-pager @@ -339,7 +371,8 @@ journalctl --namespace netdata -g "health.*load\|health.*read" --no-pager grep -iE "health.*(load|read)" /var/log/netdata/error.log ``` -Compare your active alert config vs stock: +Compare your active alert config vs stock (default locations shown): + ```bash # Your override cat /etc/netdata/health.d/my-overrides.conf diff --git a/docs/Collecting Metrics/Collectors/Networking/SNMP trap listener.mdx b/docs/Collecting Metrics/Collectors/Networking/SNMP trap listener.mdx index 9657d8a2eb..64ea518c41 100644 --- a/docs/Collecting Metrics/Collectors/Networking/SNMP trap listener.mdx +++ b/docs/Collecting Metrics/Collectors/Networking/SNMP trap listener.mdx @@ -36,7 +36,7 @@ This collector listens for incoming SNMP Trap and INFORM notifications from netw - **Deduplication**: Optional configurable per-job dedup that suppresses repeated identical traps within a window. The first matching trap is journaled immediately; subsequent matches increment a summary counter and a periodic summary entry is written. - **Per-OID overrides**: Operators can override the profile-assigned category, severity, and labels for specific OIDs without editing profiles. - **Profile-defined trap metrics**: Operators can define trap-to-metric rules in custom trap profiles, then enable selected rules per listener job with `profile_metrics`. Profile metrics are emitted per source device, using vnode host scope when enrichment finds an unambiguous vnode and bounded source labels for chart identity and fallback attribution. -- **Direct journal storage**: Enabled by default for explicit jobs. Stores traps under the configured Netdata log directory (`/var/log/netdata/traps//` by default) and exposes the embedded `snmp:traps` Function. Direct-journal jobs appear as `__logs_sources` options. +- **Direct journal storage**: Enabled by default for explicit jobs. Stores traps under the configured Netdata log directory (`${NETDATA_LOG_DIR}/traps//`; package installs usually use `/var/log/netdata`, and static installs commonly use `/opt/netdata/var/log/netdata`) and exposes the embedded `snmp:traps` Function. Direct-journal jobs appear as `__logs_sources` options. - **OTLP/gRPC export**: Optional backend that exports traps as OTLP LogRecords. When `otlp.enabled` is `true`, traps are exported through OTLP regardless of `journal.enabled`; if direct journal storage is also enabled, both backends receive traps. - **Self-metrics**: Per-job pipeline counters, trap events (by category and severity), processing errors (by type), dedup suppression (when enabled), bounded per-source receiver health, and profile-metric diagnostics. @@ -102,14 +102,12 @@ Example conversion for a MIB module not shipped in the OOB pack: ``` -This collector is only supported on the following platforms: - -- linux +This collector is supported on all platforms. This collector supports collecting metrics from multiple instances of this integration, including remote instances. -Binding to the standard SNMP trap port (UDP/162) requires `CAP_NET_BIND_SERVICE` or root. -Netdata packages grant this capability to `go.d.plugin` and allow it in `netdata.service`. +Binding to the standard SNMP trap port (UDP/162) requires elevated bind privileges on many platforms. +On Linux, this means `CAP_NET_BIND_SERVICE` or root. Netdata packages grant this capability to `go.d.plugin` and allow it in `netdata.service`. ### Default Behavior @@ -162,7 +160,7 @@ Configure the network devices sending traps: #### Verify Netdata log directory access -Direct-journal jobs write under the configured Netdata log directory (`/var/log/netdata/traps/` by default, or `${NETDATA_LOG_DIR}/traps/` at runtime). +Direct-journal jobs write under the configured Netdata log directory (`${NETDATA_LOG_DIR}/traps/`). Package installs usually use `/var/log/netdata`; static installs commonly use `/opt/netdata/var/log/netdata`. Job creation fails if the configured Netdata log directory is missing or unusable. For OTLP-only jobs, set `journal.enabled: false` and `otlp.enabled: true`. @@ -263,7 +261,7 @@ Each user has: ##### journal -- `enabled`: Write traps to local direct journal files under the configured Netdata log directory (`/var/log/netdata/traps//` by default, or `${NETDATA_LOG_DIR}/traps//` at runtime) and expose the job as a `__logs_sources` option in the embedded `snmp:traps` Function. +- `enabled`: Write traps to local direct journal files under the configured Netdata log directory (`${NETDATA_LOG_DIR}/traps//`) and expose the job as a `__logs_sources` option in the embedded `snmp:traps` Function. Package installs usually use `/var/log/netdata`; static installs commonly use `/opt/netdata/var/log/netdata`. - Set `enabled: false` only when another output backend, such as OTLP, is enabled. @@ -619,7 +617,7 @@ Metrics: | snmp.trap.pipeline | received, decoded, accepted, committed, dedup_suppressed, dropped, write_failed | events/s | | snmp.trap.events | state_change, config_change, security, auth, license, mobility, diagnostic, unknown | events/s | | snmp.trap.severity | emerg, alert, crit, err, warning, notice, info, debug | events/s | -| snmp.trap.errors | unknown_oid, decode_failed, template_unresolved, malformed_pdu, dropped_allowlist, rate_limited, auth_failures, usm_failures, unknown_engine_id, inform_response_failed, binary_encoded, profile_load_failed, journal_write_failed, otlp_export_failed, listener_read_failed | errors/s | +| snmp.trap.errors | unknown_oid, decode_failed, template_unresolved, malformed_pdu, dropped_allowlist, rate_limited, auth_failures, usm_failures, unknown_engine_id, inform_response_failed, binary_encoded, profile_load_failed, journal_write_failed, otlp_export_failed, listener_read_failed, listener_buffer_degraded | errors/s | | snmp.trap.dedup_suppressed | suppressed | events/s | | snmp.trap.sources | active | sources | | snmp.trap.source_attribution | vnode, fallback, ambiguous, failed, overflow_dropped, source_transitions | events/s | diff --git a/docs/Collecting Metrics/StatsD.mdx b/docs/Collecting Metrics/StatsD.mdx index 7edc6ef7a0..ab21dfb0a8 100644 --- a/docs/Collecting Metrics/StatsD.mdx +++ b/docs/Collecting Metrics/StatsD.mdx @@ -508,7 +508,13 @@ For example, to monitor the application `myapp` using StatsD and Netdata, create Using this configuration, `myapp` gets its own dashboard section with one chart containing two [dimensions](https://learn.netdata.cloud/docs/developer-and-contributor-corner/glossary#d). -When you send metrics like `foo:10|g` and `bar:20|g`, you'll see both private charts and your synthetic chart. +When you send metrics like `myapp.metric1:10|g` and `myapp.metric2:20|g`, you'll see both private charts and your synthetic chart. These metric names must match the pattern defined in the `[app]` section (e.g., `myapp.*`) for them to appear in your synthetic charts. + +:::note + +**Synthetic chart appears empty or is missing?** This happens when the metric names you send don't match the `metrics` pattern in your `[app]` section. StatsD matches incoming metric names against the `metrics` pattern using Netdata's [simple pattern](/docs/developer-and-contributor-corner/libnetdata/simple-patterns) syntax — if a metric name doesn't match, it is never linked to the app's synthetic charts. For example, with `metrics = myapp.*`, sending bare names like `foo:10|g` creates a private chart for `foo` but never feeds the synthetic chart. To fix this, send metric names that include the prefix matching the pattern (e.g., `myapp.foo:10|g`). + +:::
Synthetic Chart Example @@ -523,14 +529,22 @@ Example of a synthetic chart combining multiple metrics: The `[app]` section defines the application and has these options: +:::warning + +The `[app]` section is a **namespace/container** — it groups metrics and sets defaults, but does **not** create any dashboard charts by itself. To see synthetic charts on the dashboard, you **must** add one or more chart definition sections (e.g., `[mychart]`) below the `[app]` section. If you only define an `[app]` section without chart definitions, the only visible charts will be private charts for individual metrics (if `private charts = yes` or the global default is enabled). + +Settings like `private charts`, `gaps when not collected`, and `history` configure how the app's metrics and charts behave — they are not chart-level settings. The `memory mode` setting under `[app]` is currently ignored. See [Chart Definitions](#chart-definitions) below for how to create charts. + +::: + :::note - **name** - Defines the application name - **metrics** - [Simple pattern](/docs/developer-and-contributor-corner/libnetdata/simple-patterns) matching all metrics for this app - **private charts** - Enable/disable private charts for matched metrics (yes|no) - **gaps when not collected** - Show gaps when no metrics are collected (yes|no) -- **memory mode** - Sets memory mode for application charts (optional, default is global Netdata setting) -- **history** - Size of round-robin database (optional, only relevant with `memory mode = save`) +- **memory mode** - Ignored in the `[app]` section; application charts use the host's default memory mode +- **history** - Size of round-robin database for application charts (optional, minimum 5) ::: @@ -690,6 +704,14 @@ To rename methods automatically: This adds dimensions named `GET`, `ADD`, and `DELETE`.
+### Scope of StatsD Chart Configuration + +All chart and dimension configuration directives in `/etc/netdata/statsd.d/*.conf` control **local agent behavior only** — they define how the local Netdata agent processes, names, and visualizes statsd metrics it receives. + +The dimension `TYPE` field (see [Dimension Format](#dimension-format) above) selects which computed value of a metric a single agent displays. It does **not** control how that metric is combined across multiple Netdata instances. + +Cross-node aggregation — how metrics from multiple agents are combined in Netdata Cloud dashboards — is governed by the Cloud query engine, not by statsd configuration files. To choose Sum, Average, or another aggregation for a chart in Netdata Cloud, use the [aggregate function](/docs/dashboards-and-charts/charts#aggregate-functions-dropdown) on that chart. There is no `aggregation = SUM` or `aggregation = AVG` directive in statsd.d configuration. + ## Using StatsD with Different Languages
@@ -925,7 +947,6 @@ Start with this basic configuration: metrics = k6* private charts = yes gaps when not collected = no - memory mode = dbengine ```
@@ -963,7 +984,6 @@ Here's a complete configuration for k6: metrics = k6* private charts = yes gaps when not collected = no - memory mode = dbengine [dictionary] http_req_blocked = Blocked HTTP Requests diff --git a/docs/Developer and Contributor Corner/External Plugins/External Plugins.mdx b/docs/Developer and Contributor Corner/External Plugins/External Plugins.mdx index 20bd2440e1..6ffaebf159 100644 --- a/docs/Developer and Contributor Corner/External Plugins/External Plugins.mdx +++ b/docs/Developer and Contributor Corner/External Plugins/External Plugins.mdx @@ -129,12 +129,12 @@ Netdata parses lines starting with: - `CLABEL` - add a label to a chart - `CLABEL_COMMIT` - commit added labels to the chart - `FUNCTION` - define a function that can be called later to execute it +- `FUNCTION_DEL` - unregister a function - `BEGIN` - initialize data collection for a chart - `SET` - set the value of a dimension for the initialized chart - `END` - complete data collection for the initialized chart - `FLUSH` - ignore the last collected values - `DISABLE` - disable this plugin -- `FUNCTION` - define functions - `FUNCTION_PROGRESS` - report the progress of a function execution - `FUNCTION_RESULT_BEGIN` - to initiate the transmission of function results - `FUNCTION_RESULT_END` - to end the transmission of function result @@ -500,6 +500,16 @@ Both node and chart functions are exactly the same, but chart functions allow Ne Users can get a list of all the registered functions using the `/api/v1/functions` endpoint of Netdata and call functions using the `/api/v1/function` API call of Netdata. +#### FUNCTION_DEL + +The plugin can unregister a previously registered function while continuing to run: + +> FUNCTION_DEL [GLOBAL] "name of the function" + +- Use `GLOBAL` for host-level functions (the same scope as `FUNCTION GLOBAL`). +- Unregistered functions disappear from `/api/v1/functions` and return 503 on calls. +- Functions can be re-registered later with a new `FUNCTION` line. + Once a function is called, the plugin will receive at its standard input a command that looks like this: ``` diff --git a/docs/Netdata AI/MCP/MCP Clients/Claude Code.mdx b/docs/Netdata AI/MCP/MCP Clients/Claude Code.mdx index a70de45d19..26d8e9339d 100644 --- a/docs/Netdata AI/MCP/MCP Clients/Claude Code.mdx +++ b/docs/Netdata AI/MCP/MCP Clients/Claude Code.mdx @@ -30,7 +30,7 @@ Claude Code supports multiple MCP transport types, giving you flexibility in how - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge - **v2.7.2+**: Direct HTTP/SSE support available (recommended) 3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/netdata-ai/mcp#finding-the-nd-mcp-bridge). Not needed for direct HTTP connections on v2.7.2+. -4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) +4. **Netdata MCP API key** - required when `[web].bearer token protection = yes`. When bearer protection is disabled, it is optional and unlocks sensitive observability data (protected functions, full access to logs). Each Netdata Agent or Parent has its own unique MCP API key - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) ## Configuration Methods diff --git a/docs/Netdata AI/MCP/MCP Clients/Crush.mdx b/docs/Netdata AI/MCP/MCP Clients/Crush.mdx index 9261af5a73..aecd63d4cf 100644 --- a/docs/Netdata AI/MCP/MCP Clients/Crush.mdx +++ b/docs/Netdata AI/MCP/MCP Clients/Crush.mdx @@ -30,7 +30,7 @@ Crush has comprehensive MCP transport support, making it highly flexible for con - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge - **v2.7.2+**: Direct HTTP/SSE support available (recommended) 3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/netdata-ai/mcp#finding-the-nd-mcp-bridge). Not needed for direct HTTP/SSE connections on v2.7.2+. -4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) +4. **Netdata MCP API key** - required when `[web].bearer token protection = yes`. When bearer protection is disabled, it is optional and unlocks sensitive observability data (protected functions, full access to logs). Each Netdata Agent or Parent has its own unique MCP API key - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) > Export `ND_MCP_BEARER_TOKEN` with your MCP key before launching Crush so credentials never appear in command-line arguments or config files: > ```bash diff --git a/docs/Netdata AI/MCP/MCP Clients/Gemini CLI.mdx b/docs/Netdata AI/MCP/MCP Clients/Gemini CLI.mdx index 9bea835183..a47a25889e 100644 --- a/docs/Netdata AI/MCP/MCP Clients/Gemini CLI.mdx +++ b/docs/Netdata AI/MCP/MCP Clients/Gemini CLI.mdx @@ -30,7 +30,7 @@ Gemini CLI supports all major MCP transport types, giving you maximum flexibilit - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge - **v2.7.2+**: Direct HTTP/SSE support available (recommended) 3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/netdata-ai/mcp#finding-the-nd-mcp-bridge). Not needed for direct HTTP/SSE connections on v2.7.2+. -4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) +4. **Netdata MCP API key** - required when `[web].bearer token protection = yes`. When bearer protection is disabled, it is optional and unlocks sensitive observability data (protected functions, full access to logs). Each Netdata Agent or Parent has its own unique MCP API key - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) ## Installation diff --git a/docs/Netdata AI/MCP/MCP Clients/OpenAI Codex CLI.mdx b/docs/Netdata AI/MCP/MCP Clients/OpenAI Codex CLI.mdx index 78d5b892ee..8c21dc4093 100644 --- a/docs/Netdata AI/MCP/MCP Clients/OpenAI Codex CLI.mdx +++ b/docs/Netdata AI/MCP/MCP Clients/OpenAI Codex CLI.mdx @@ -31,7 +31,7 @@ Codex CLI supports both stdio launchers and direct Streamable HTTP when the RMCP - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge - **v2.7.2+**: Can use `npx mcp-remote` bridge for HTTP/SSE support 3. **Launcher** – Run Netdata through `nd-mcp` (always) or `npx mcp-remote` (useful when you want a single stdio launcher for multiple MCP clients). Direct HTTP is also available for v2.7.2+ when you enable the RMCP client. -4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) +4. **Netdata MCP API key** - required when `[web].bearer token protection = yes`. When bearer protection is disabled, it is optional and unlocks sensitive observability data (protected functions, full access to logs). Each Netdata Agent or Parent has its own unique MCP API key - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) ## Installation diff --git a/docs/Netdata AI/MCP/MCP Clients/OpenCode.mdx b/docs/Netdata AI/MCP/MCP Clients/OpenCode.mdx index a53eb43a71..652c01f441 100644 --- a/docs/Netdata AI/MCP/MCP Clients/OpenCode.mdx +++ b/docs/Netdata AI/MCP/MCP Clients/OpenCode.mdx @@ -32,7 +32,7 @@ OpenCode supports both local and remote MCP servers: - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge - **v2.7.2+**: Direct HTTP/SSE support available (recommended) 3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/netdata-ai/mcp#finding-the-nd-mcp-bridge). Not needed for direct HTTP connections on v2.7.2+. -4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) +4. **Netdata MCP API key** - required when `[web].bearer token protection = yes`. When bearer protection is disabled, it is optional and unlocks sensitive observability data (protected functions, full access to logs). Each Netdata Agent or Parent has its own unique MCP API key - [Find your Netdata MCP API key](/docs/netdata-ai/mcp#finding-your-api-key) > Export `ND_MCP_BEARER_TOKEN` with your MCP key before launching OpenCode to keep secrets out of configuration files: > ```bash diff --git a/docs/Netdata AI/MCP/MCP.mdx b/docs/Netdata AI/MCP/MCP.mdx index 2ccfda42ea..9bfd4325a0 100644 --- a/docs/Netdata AI/MCP/MCP.mdx +++ b/docs/Netdata AI/MCP/MCP.mdx @@ -44,7 +44,7 @@ AI assistants have different visibility depending on where they connect: | **Scope** | All nodes | Single agent/parent | | **Endpoint** | `app.netdata.cloud/api/v1/mcp` | `YOUR_IP:19999/mcp` | | **Transport** | Streamable HTTP | HTTP, SSE, WebSocket | -| **Authentication** | Cloud API token (`scope:mcp`) | Local MCP API key | +| **Authentication** | Cloud API token (`scope:mcp`) | Local MCP API key (mandatory when bearer protection is enabled) | | **Network access** | Internet only | Direct access to Netdata IP required | | **Local setup** | None | Bridge may be needed for some clients | @@ -187,7 +187,10 @@ Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your Connect directly to any Netdata Agent or Parent on your network. All Netdata Agents and Parents (v2.6.0+) include a built-in MCP server at `http://YOUR_IP:19999/mcp`. -Some MCP features — such as live process information, network connections, and full log access — are considered sensitive. These are protected by a local API key that Netdata generates automatically on startup. Without this key, AI assistants can still access metrics, alerts, and node information, but sensitive functions remain locked. +Netdata generates a local MCP API key automatically on startup. Authentication behavior depends on `[web].bearer token protection`: + +- **Bearer protection disabled (`no`)**: anonymous MCP access works for non-sensitive operations (metrics, alerts, node info). The API key unlocks sensitive operations. +- **Bearer protection enabled (`yes`)**: anonymous MCP access is rejected on all MCP transports (HTTP, SSE, WebSocket). The API key is required for all MCP requests. ### Transport Options @@ -201,6 +204,25 @@ Netdata implements the MCP protocol with multiple transport options: - **Direct Connection** (v2.7.2+): AI clients that support HTTP or SSE transports can connect directly to Netdata - **Bridge Required**: AI clients that only support stdio need the `nd-mcp` (stdio-to-websocket) or `mcp-remote` (stdio-to-http or stdio-to-sse) bridge +- **Preferred authentication**: pass the MCP API key via `Authorization: Bearer `. +- **Backward compatibility**: WebSocket also accepts `?api_key=`. Keep this only for legacy clients, since URL query strings are more likely to be logged by proxies and tools. + +### MCP Access Control in `netdata.conf` + +Use a dedicated MCP ACL to control network-level MCP access independently from dashboard and streaming: + +```ini +[web] + allow connections from = 10.* 192.168.* localhost + allow dashboard from = 10.* 192.168.* localhost + allow mcp from = 10.* 192.168.* localhost + allow streaming from = * + allow mcp by dns = heuristic +``` + +- `allow mcp from` controls `/mcp`, `/sse`, and MCP WebSocket protocol access. +- `allow connections from` is still the global first gate for all features. +- For internet-facing Parents, keep `allow mcp from` restricted to trusted networks. #### Official MCP Remote Client (mcp-remote) @@ -495,7 +517,7 @@ For more details, see the [official mcp-remote documentation](https://github.com ### Finding Your API Key -To access sensitive functions like logs and live system information, you need an API key. Netdata automatically generates an API key on startup. The key is stored in a file on the Netdata server you want to connect to. +You need the MCP API key when bearer protection is enabled. When bearer protection is disabled, the key is still needed for sensitive functions like logs and live system information. Netdata automatically generates an API key on startup. The key is stored in a file on the Netdata server you want to connect to. You need the API key of the Netdata you will connect to (usually a Netdata Parent). diff --git a/docs/Netdata Agent/Configuration/Securing Agents/Bearer Token Protection.mdx b/docs/Netdata Agent/Configuration/Securing Agents/Bearer Token Protection.mdx index f91215174d..65be7aa2a0 100644 --- a/docs/Netdata Agent/Configuration/Securing Agents/Bearer Token Protection.mdx +++ b/docs/Netdata Agent/Configuration/Securing Agents/Bearer Token Protection.mdx @@ -70,6 +70,8 @@ When enabled, bearer token protection secures **all data APIs**, including: - Functions (`/api/v3/function`, `/api/v3/functions`) - Dynamic configuration (`/api/v3/config`) +It also changes local MCP behavior: MCP requests over HTTP, SSE, and WebSocket require the local MCP API key when bearer token protection is enabled. + ## What Remains Public **Static web files** (HTML, CSS, JavaScript) in Netdata's web directory are **not protected**. This means: @@ -96,6 +98,15 @@ These APIs are required for the authentication flow and dashboard initialization **Note:** Other v1 and v2 APIs (like `/api/v2/info`, `/api/v3/versions`, `/api/v3/progress`) **are protected** by bearer token - only the specific endpoints listed above bypass protection. +## MCP Behavior with Bearer Protection + +For local Agent/Parent MCP endpoints (`/mcp`, `/sse`, MCP WebSocket): + +- If `[web].bearer token protection = yes`: anonymous MCP requests are rejected, and clients must pass the local MCP API key (`Authorization: Bearer `). +- If `[web].bearer token protection = no`: anonymous MCP requests continue to work with the default open-source access model (the MCP API key is still supported and unlocks sensitive operations). + +MCP network exposure is still controlled independently by `[web].allow mcp from`. + ## Requirements - Agent must be claimed to Netdata Cloud diff --git a/docs/Netdata Agent/Configuration/Securing Agents/Securing Agents.mdx b/docs/Netdata Agent/Configuration/Securing Agents/Securing Agents.mdx index d486bc35bb..a1d7ab5bec 100644 --- a/docs/Netdata Agent/Configuration/Securing Agents/Securing Agents.mdx +++ b/docs/Netdata Agent/Configuration/Securing Agents/Securing Agents.mdx @@ -157,12 +157,15 @@ While `allow connections from` globally controls access to all Netdata services, [web] allow connections from = localhost * allow dashboard from = localhost * + allow mcp from = localhost * allow badges from = * allow streaming from = * allow netdata.conf from = localhost fd* 10.* 192.168.* 172.16.* 172.17.* 172.18.* 172.19.* 172.20.* 172.21.* 172.22.* 172.23.* 172.24.* 172.25.* 172.26.* 172.27.* 172.28.* 172.29.* 172.30.* 172.31.* allow management from = localhost ``` +When `[web].bearer token protection = yes` is enabled, MCP requests also require the local MCP API key (`Authorization: Bearer `). Without the key, anonymous MCP requests are rejected. + **Additional Security Options:** - Review detailed access list options in the [Web Server documentation](/docs/netdata-agent/configuration/securing-agents/web-server-reference#access-lists) diff --git a/docs/Netdata Agent/Configuration/Securing Agents/Web Server Reference.mdx b/docs/Netdata Agent/Configuration/Securing Agents/Web Server Reference.mdx index b579ecdbd6..369299711e 100644 --- a/docs/Netdata Agent/Configuration/Securing Agents/Web Server Reference.mdx +++ b/docs/Netdata Agent/Configuration/Securing Agents/Web Server Reference.mdx @@ -47,6 +47,8 @@ You can modify web server behavior by editing the `[web]` section in `netdata.co | `allow connections by dns` | `heuristic` | See the [access list section](#access-lists) for details on using `allow` settings | | `allow dashboard from` | `localhost *` | Controls dashboard and API access | | `allow dashboard by dns` | `heuristic` | DNS resolution setting for dashboard access | +| `allow mcp from` | (defaults to the value of `allow dashboard from`, or `localhost *` if that is unset) | Controls MCP access (`/mcp`, `/sse`, MCP WebSocket protocol). When not explicitly set, this option inherits the value of `allow dashboard from` (falling back to `localhost *` only if `allow dashboard from` is unset) | +| `allow mcp by dns` | `heuristic` | DNS resolution setting for MCP access | | `allow badges from` | `*` | Controls badge API access | | `allow badges by dns` | `heuristic` | DNS resolution setting for badge access | | `allow streaming from` | `*` | Controls metric streaming from child agents | @@ -83,6 +85,8 @@ Once a connection is allowed globally, these settings control access to specific - **`allow dashboard from`** - receives the request and examines if it is a static dashboard file or an API call the dashboards do. +- **`allow mcp from`** - checks if the client is allowed to use MCP endpoints (`/mcp`, `/sse`) and MCP WebSocket protocol. + - **`allow badges from`** - checks if the API request is for a badge. Badges aren't matched by `allow dashboard from`. - **`allow streaming from`** - checks if the child willing to stream metrics to this Netdata is allowed. This can be controlled per API KEY and MACHINE GUID in `stream.conf`. The setting in `netdata.conf` is checked before the ones in `stream.conf`. @@ -98,6 +102,7 @@ Once a connection is allowed globally, these settings control access to specific [web] allow connections from = localhost allow dashboard from = localhost + allow mcp from = localhost allow management from = localhost ``` @@ -106,6 +111,7 @@ Once a connection is allowed globally, these settings control access to specific [web] allow connections from = localhost 10.* 192.168.* allow dashboard from = localhost 10.* 192.168.* + allow mcp from = localhost 10.* 192.168.* allow badges from = * allow streaming from = * allow management from = localhost @@ -125,6 +131,7 @@ This process can be expensive on a machine that is serving many connections. Eac ```text allow connections by dns = heuristic allow dashboard by dns = heuristic + allow mcp by dns = heuristic allow badges by dns = heuristic allow streaming by dns = heuristic allow netdata.conf by dns = no @@ -224,11 +231,12 @@ The option `[web].default port` is used when entries in `[web].bind to` do not s As shown in the example above, these permissions are optional, with the default permitting all request types on the specified port. -The request types are strings identical to the `allow X from` directives of the access lists, i.e. `dashboard`, `streaming`, `registry`, `netdata.conf`, `badges` and `management`. The access lists themselves and the general setting `allow connections from` in the next section are applied regardless of the ports that are configured to provide these services. +The request types are strings identical to the `allow X from` directives of the access lists, i.e. `dashboard`, `mcp`, `streaming`, `registry`, `netdata.conf`, `badges` and `management`. The access lists themselves and the general setting `allow connections from` in the next section are applied regardless of the ports that are configured to provide these services. The API requests are serviced as follows: - `dashboard` gives access to the UI, the read API and badges API calls. +- `mcp` gives access to MCP endpoints (`/mcp`, `/sse`) and the MCP WebSocket protocol. - `badges` gives access only to the badge API calls. - `management` gives access only to the management API calls. @@ -390,4 +398,3 @@ ws://localhost:19999/echo?max_frame_size=32768 This is particularly useful for resource-constrained devices or network environments with specific limitations. - diff --git a/docs/Netdata Agent/Database.mdx b/docs/Netdata Agent/Database.mdx index 24f781b043..8e8c3201c6 100644 --- a/docs/Netdata Agent/Database.mdx +++ b/docs/Netdata Agent/Database.mdx @@ -46,7 +46,14 @@ These limits are fully configurable. See [Changing how long Netdata stores metri ### Monitoring Retention Utilization -Netdata provides a visual representation of storage utilization for both the time and space limits across all Tiers under "Netdata" -> "dbengine retention" on the dashboard. This chart shows exactly how your storage space (disk space limits) and time (time limits) are used for metric retention. +Netdata provides a visual representation of storage utilization for both the time and space limits across all Tiers. In the dashboard, these are the **dbengine space and time retention** charts, found under the **Netdata** section → **dbengine retention** family — there is one chart per database tier. Each chart shows exactly how your storage space (disk space limits) and time (time limits) are used for metric retention. + +Each tier has its own independent **space** and **time** lines on the chart: + +- **Space (disk utilization %)**: the percentage of the tier's allocated disk space that is currently occupied, calculated as `disk_used / disk_max × 100`. When a size limit is configured for the tier, `disk_max` is that limit. When no size limit is configured (set to 0), `disk_max` is the total available disk space at the tier's data directory (free space plus already-used space). For example, a space value of 89% means 89% of the tier's allocated or available disk space is occupied by datafiles. +- **Time (retention time utilization %)**: the percentage of the configured retention time period that has been filled with data, calculated as `current_retention_duration / configured_time_limit × 100`. When no time limit is configured (set to 0), this dimension shows 0% and no time-based retention is enforced. For example, a time value of 61% means 61% of the configured time retention period has elapsed since the oldest sample. This value is capped at 100%. + +Different tiers naturally show different percentages because they have different write volumes, compression ratios, and configured limits. When either the space or time dimension reaches 100%, the oldest datafiles are rotated out as described in the [Retention Size Enforcement](#retention-size-enforcement) section below. ### Retention Size Enforcement diff --git a/docs/Netdata Cloud/Authentication & Authorization/Role-based access model.mdx b/docs/Netdata Cloud/Authentication & Authorization/Role-based access model.mdx index ea7fe706fd..19cb253c6a 100644 --- a/docs/Netdata Cloud/Authentication & Authorization/Role-based access model.mdx +++ b/docs/Netdata Cloud/Authentication & Authorization/Role-based access model.mdx @@ -37,6 +37,10 @@ You can control what functionalities users can access in Netdata Cloud through t | **View-only access** - monitor specific systems without making changes | **Observer** | | **Billing management** - handle invoices and payments without system access | **Billing** | +## Role Change Propagation + +Role changes take effect immediately. When an Admin or Manager changes a user's role, the updated permissions are applied right away by the Netdata Cloud backend. + ## Quick Reference
diff --git a/docs/Network Flows/Enrichment Methods/AWS IP Ranges.mdx b/docs/Network Flows/Enrichment Methods/AWS IP Ranges.mdx index 6e8e89dd8f..143c5c7124 100644 --- a/docs/Network Flows/Enrichment Methods/AWS IP Ranges.mdx +++ b/docs/Network Flows/Enrichment Methods/AWS IP Ranges.mdx @@ -69,9 +69,7 @@ than the file actually changes; daily is enough for most flow-attribution use cases. The plugin floors the configured `interval` at 60s. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration supports multiple instances configured side-by-side. diff --git a/docs/Network Flows/Enrichment Methods/Azure IP Ranges.mdx b/docs/Network Flows/Enrichment Methods/Azure IP Ranges.mdx index 821e1d642a..085342ee53 100644 --- a/docs/Network Flows/Enrichment Methods/Azure IP Ranges.mdx +++ b/docs/Network Flows/Enrichment Methods/Azure IP Ranges.mdx @@ -56,9 +56,7 @@ trie. Same mechanism as AWS / GCP IP Ranges -- different URL and JSON shape, plus one important operational caveat documented below. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration supports multiple instances configured side-by-side. diff --git a/docs/Network Flows/Enrichment Methods/BMP BGP Monitoring Protocol.mdx b/docs/Network Flows/Enrichment Methods/BMP BGP Monitoring Protocol.mdx index c5fa14d2b3..0d5b1a8ea0 100644 --- a/docs/Network Flows/Enrichment Methods/BMP BGP Monitoring Protocol.mdx +++ b/docs/Network Flows/Enrichment Methods/BMP BGP Monitoring Protocol.mdx @@ -73,9 +73,7 @@ withdrawal (`MP_UNREACH` or `withdraw_routes`), PeerDown, or session disconnect followed by the `keep` interval expiring (default 5 minutes). -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/CAIDA Routeviews Prefix-to-AS.mdx b/docs/Network Flows/Enrichment Methods/CAIDA Routeviews Prefix-to-AS.mdx index e41baabf0e..609a2ec7fd 100644 --- a/docs/Network Flows/Enrichment Methods/CAIDA Routeviews Prefix-to-AS.mdx +++ b/docs/Network Flows/Enrichment Methods/CAIDA Routeviews Prefix-to-AS.mdx @@ -50,9 +50,7 @@ standard auto-detected cache directory. The plugin reloads the generated MMDB automatically when the file changes. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/Classifiers.mdx b/docs/Network Flows/Enrichment Methods/Classifiers.mdx index 7499eb5bc7..0411399753 100644 --- a/docs/Network Flows/Enrichment Methods/Classifiers.mdx +++ b/docs/Network Flows/Enrichment Methods/Classifiers.mdx @@ -98,9 +98,7 @@ cache TTL is `enrichment.classifier_cache_duration` (default 5 minutes). It is a last-access TTL so entries live as long as they're queried. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/Custom MMDB Database.mdx b/docs/Network Flows/Enrichment Methods/Custom MMDB Database.mdx index bdb0322190..1c46ccb18c 100644 --- a/docs/Network Flows/Enrichment Methods/Custom MMDB Database.mdx +++ b/docs/Network Flows/Enrichment Methods/Custom MMDB Database.mdx @@ -57,9 +57,7 @@ agent host, and point `enrichment.geoip.asn_database` and / or file change automatically (mechanism documented on the IP Intelligence page). -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/DB-IP IP Intelligence.mdx b/docs/Network Flows/Enrichment Methods/DB-IP IP Intelligence.mdx index 295b913c63..43424c3269 100644 --- a/docs/Network Flows/Enrichment Methods/DB-IP IP Intelligence.mdx +++ b/docs/Network Flows/Enrichment Methods/DB-IP IP Intelligence.mdx @@ -67,9 +67,7 @@ under `${NETDATA_STOCK_DATA_DIR}/topology-ip-intel/` (typically treated as optional, so a missing or unreadable file does not abort plugin startup. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/Decapsulation.mdx b/docs/Network Flows/Enrichment Methods/Decapsulation.mdx index 5293c48c1d..694511adec 100644 --- a/docs/Network Flows/Enrichment Methods/Decapsulation.mdx +++ b/docs/Network Flows/Enrichment Methods/Decapsulation.mdx @@ -80,9 +80,7 @@ stream where only a subset of exporters ship the frame bytes. Enabling decap is half the work; the exporter must also be configured to ship the inner frame. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/GCP IP Ranges.mdx b/docs/Network Flows/Enrichment Methods/GCP IP Ranges.mdx index 7d26f090a1..293c02eaba 100644 --- a/docs/Network Flows/Enrichment Methods/GCP IP Ranges.mdx +++ b/docs/Network Flows/Enrichment Methods/GCP IP Ranges.mdx @@ -66,9 +66,7 @@ per cycle is the whole dataset. Each contains a `syncToken` and a The plugin fetches the full document on each refresh cycle. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration supports multiple instances configured side-by-side. diff --git a/docs/Network Flows/Enrichment Methods/Generic JSON-over-HTTP IPAM.mdx b/docs/Network Flows/Enrichment Methods/Generic JSON-over-HTTP IPAM.mdx index 0c2452e453..4938075c77 100644 --- a/docs/Network Flows/Enrichment Methods/Generic JSON-over-HTTP IPAM.mdx +++ b/docs/Network Flows/Enrichment Methods/Generic JSON-over-HTTP IPAM.mdx @@ -55,9 +55,7 @@ The same flow applies to every JSON-over-HTTP source; the integration-specific part is the URL and the `transform` expression. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration supports multiple instances configured side-by-side. diff --git a/docs/Network Flows/Enrichment Methods/IP2Location LITE IP-Country.mdx b/docs/Network Flows/Enrichment Methods/IP2Location LITE IP-Country.mdx index de6078cff4..6853acb97a 100644 --- a/docs/Network Flows/Enrichment Methods/IP2Location LITE IP-Country.mdx +++ b/docs/Network Flows/Enrichment Methods/IP2Location LITE IP-Country.mdx @@ -47,9 +47,7 @@ auto-detected cache directory. The plugin reloads the generated MMDB automatically when the file changes. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/IPDeny Country Zones.mdx b/docs/Network Flows/Enrichment Methods/IPDeny Country Zones.mdx index ce7f74e9a8..8084c02414 100644 --- a/docs/Network Flows/Enrichment Methods/IPDeny Country Zones.mdx +++ b/docs/Network Flows/Enrichment Methods/IPDeny Country Zones.mdx @@ -49,9 +49,7 @@ standard auto-detected cache directory. The plugin reloads the generated MMDB automatically when the file changes. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/IPIP Country Database.mdx b/docs/Network Flows/Enrichment Methods/IPIP Country Database.mdx index c776ab210a..a8806a393d 100644 --- a/docs/Network Flows/Enrichment Methods/IPIP Country Database.mdx +++ b/docs/Network Flows/Enrichment Methods/IPIP Country Database.mdx @@ -48,9 +48,7 @@ auto-detected cache directory. The plugin reloads the generated MMDB automatically when the file changes. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/IPtoASN.mdx b/docs/Network Flows/Enrichment Methods/IPtoASN.mdx index 8db76c12cc..82a66f85c6 100644 --- a/docs/Network Flows/Enrichment Methods/IPtoASN.mdx +++ b/docs/Network Flows/Enrichment Methods/IPtoASN.mdx @@ -64,9 +64,7 @@ IPtoASN-to-MMDB converter that produces a standard will also work with the Custom MMDB integration. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/MaxMind GeoIP GeoLite2.mdx b/docs/Network Flows/Enrichment Methods/MaxMind GeoIP GeoLite2.mdx index b8d4e0f913..42995f1c7f 100644 --- a/docs/Network Flows/Enrichment Methods/MaxMind GeoIP GeoLite2.mdx +++ b/docs/Network Flows/Enrichment Methods/MaxMind GeoIP GeoLite2.mdx @@ -73,9 +73,7 @@ successful `geoipupdate` run causes the plugin to swap readers within ~30s, no restart needed. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/NetBox.mdx b/docs/Network Flows/Enrichment Methods/NetBox.mdx index b59c727789..194742174b 100644 --- a/docs/Network Flows/Enrichment Methods/NetBox.mdx +++ b/docs/Network Flows/Enrichment Methods/NetBox.mdx @@ -70,9 +70,7 @@ allows) or an explicit `?limit=N` greater than your prefix count, or expose a server-side aggregator that returns the full list at one URL. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration supports multiple instances configured side-by-side. diff --git a/docs/Network Flows/Enrichment Methods/Static Metadata.mdx b/docs/Network Flows/Enrichment Methods/Static Metadata.mdx index 9da85d4946..454edb061e 100644 --- a/docs/Network Flows/Enrichment Methods/Static Metadata.mdx +++ b/docs/Network Flows/Enrichment Methods/Static Metadata.mdx @@ -85,9 +85,7 @@ from. There is no network access, no file watching, and no hot reload -- changes take effect on the next plugin startup. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Enrichment Methods/bio-rd RIPE RIS.mdx b/docs/Network Flows/Enrichment Methods/bio-rd RIPE RIS.mdx index 9f5793d2b1..287694ed64 100644 --- a/docs/Network Flows/Enrichment Methods/bio-rd RIPE RIS.mdx +++ b/docs/Network Flows/Enrichment Methods/bio-rd RIPE RIS.mdx @@ -91,9 +91,7 @@ rollup tiers do not carry them. Queries that need AS path or community data must run against a window that the raw retention still covers. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Flow Protocols/IPFIX.mdx b/docs/Network Flows/Flow Protocols/IPFIX.mdx index bd55209bb0..aed062d853 100644 --- a/docs/Network Flows/Flow Protocols/IPFIX.mdx +++ b/docs/Network Flows/Flow Protocols/IPFIX.mdx @@ -41,9 +41,7 @@ version number 10 and decoded using cached templates. Decoded records are enrich appended to disk-backed journal tiers. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Flow Protocols/NetFlow.mdx b/docs/Network Flows/Flow Protocols/NetFlow.mdx index 3bae84aec5..687a8898b8 100644 --- a/docs/Network Flows/Flow Protocols/NetFlow.mdx +++ b/docs/Network Flows/Flow Protocols/NetFlow.mdx @@ -41,9 +41,7 @@ dynamic templates cached from the exporter. Decoded records are enriched in-memo and appended to disk-backed journal tiers (raw, 1-minute, 5-minute, 1-hour rollups). -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Flow Protocols/sFlow.mdx b/docs/Network Flows/Flow Protocols/sFlow.mdx index d5d51e16d3..292b9de6d8 100644 --- a/docs/Network Flows/Flow Protocols/sFlow.mdx +++ b/docs/Network Flows/Flow Protocols/sFlow.mdx @@ -42,9 +42,7 @@ their distinct header format and decoded per the sFlow v5 specification. Decoded are enriched and appended to disk-backed journal tiers. -This integration is only supported on the following platforms: - -- Linux +This integration is supported on all platforms. This integration runs as a single instance per Netdata Agent. diff --git a/docs/Network Flows/Installation.mdx b/docs/Network Flows/Installation.mdx index 3306524a2e..6233a3c18c 100644 --- a/docs/Network Flows/Installation.mdx +++ b/docs/Network Flows/Installation.mdx @@ -23,7 +23,7 @@ The static install (the kickstart `--static-only` path) bundles the plugin autom - A working Netdata Agent on the host that will receive flow data. - That host must be reachable on UDP from your routers and switches (default port `2055`). -- Linux. The plugin is Linux-only. +- A Netdata installation that includes `netdata-plugin-netflow`. Native Linux packages install it as a separate package; static installs bundle it automatically; source builds need a Rust toolchain. ## Install on Debian / Ubuntu / Mint diff --git a/docs/SNMP Traps/Configuration.mdx b/docs/SNMP Traps/Configuration.mdx index 81a0ff366b..a984cb4697 100644 --- a/docs/SNMP Traps/Configuration.mdx +++ b/docs/SNMP Traps/Configuration.mdx @@ -115,7 +115,7 @@ Job names must be 64 characters or shorter, start with a letter or digit, and ma | Enrichment | `reverse_dns.enabled` | `false` | Adds best-effort PTR annotation as `TRAP_REVERSE_DNS`. Never used as authoritative identity. | | Storm controls | `rate_limit` | disabled | Optional per-source token-bucket rate limiting. | | Storm controls | `dedup` | disabled | Optional suppression of repeated identical traps inside a window. | -| Outputs | `journal.enabled` | `true` | Writes decoded traps to local journal-compatible files and exposes listener jobs through the `snmp:traps` Function. Linux only. | +| Outputs | `journal.enabled` | `true` | Writes decoded traps to local journal-compatible files and exposes listener jobs through the `snmp:traps` Function. | | Outputs | `otlp` | disabled | Optional OTLP/gRPC Logs export. | | Storage | `retention` | `max_size: 10GB` | Per-job direct journal retention and rotation. Ignored when `journal.enabled` is `false`. | | Meaning | `overrides` | `[]` | Per-OID category, severity, and label overrides on top of profile defaults. | @@ -323,7 +323,7 @@ The listener can write to the direct journal, export to OTLP/gRPC, or do both. | Backend | Enabled by default | Local querying | Notes | |---|---:|---:|---| -| Direct journal | yes | yes | Stores journal-compatible files under the Netdata log directory and exposes the job through the `snmp:traps` Function. Linux only. | +| Direct journal | yes | yes | Stores journal-compatible files under the Netdata log directory and exposes the job through the `snmp:traps` Function. | | OTLP/gRPC Logs | no | no | Exports traps as OTLP LogRecords to an external collector. | When both backends are enabled, traps go to both outputs and the local journal is authoritative: an OTLP export failure does not affect what was already written to the journal. When journal is disabled and OTLP is enabled, no local journal files are created and the job does not appear as a local SNMP trap log source. @@ -332,7 +332,7 @@ Trap rows can contain sensitive operational payloads, not only credentials. Revi ### Direct journal -Direct journal storage is enabled by default and requires Linux: +Direct journal storage is enabled by default: ```yaml journal: diff --git a/docs/SNMP Traps/Forwarding to SIEM.mdx b/docs/SNMP Traps/Forwarding to SIEM.mdx index 93525249a9..e3e4da496c 100644 --- a/docs/SNMP Traps/Forwarding to SIEM.mdx +++ b/docs/SNMP Traps/Forwarding to SIEM.mdx @@ -43,7 +43,7 @@ OTLP-only jobs create no local trap journal files and do not appear as job sourc ## Direct journal backend -Direct journal output is enabled by default for listener jobs and requires Linux. On non-Linux systems, jobs with `journal.enabled: true` fail validation; use OTLP-only mode instead. +Direct journal output is enabled by default for listener jobs. It writes local trap log files that can be read with `journalctl --directory` on systems where `journalctl` is available. Use OTLP-only mode when the external OTLP receiver is the system of record and local trap files are not needed. ```yaml journal: diff --git a/docs/SNMP Traps/Installation.mdx b/docs/SNMP Traps/Installation.mdx index 1ab050acdf..69c2d2c849 100644 --- a/docs/SNMP Traps/Installation.mdx +++ b/docs/SNMP Traps/Installation.mdx @@ -15,16 +15,16 @@ slug: "/snmp-traps/installation" Netdata receives SNMP traps with the **snmp_traps** collector in `go.d.plugin`. Trap receiving is explicit: Netdata does not create a trap listener job or configure devices to send traps by itself. You must create an explicit listener job before Netdata can receive traps. -The default direct-journal backend requires Linux. OTLP-only jobs are not blocked by the Linux direct-journal requirement, but they do not create local journal files or local SNMP trap log sources. +The default direct-journal backend writes local trap log files on every supported platform. OTLP-only jobs do not create local journal files or local SNMP trap log sources. The default `listen.endpoints` template uses UDP `0.0.0.0` on port `162`. The stock `go.d/snmp_traps.conf` file ships as a commented template; Netdata does not bind any UDP port until a job is uncommented, created, or applied with Dynamic Configuration. ## Prerequisites - A Netdata Agent host with the `go.d.plugin` component installed. -- A Linux host when you want the default direct-journal backend or local SNMP trap log sources. -- At least one output backend enabled per listener job: `journal.enabled: true` on Linux (the default), `otlp.enabled: true`, or both. -- For direct-journal jobs on Linux, the files `/etc/machine-id` and `/proc/sys/kernel/random/boot_id` must exist, be readable, and contain non-empty values. Minimal containers, chroots, and embedded systems should check these before relying on local journal storage. +- A host with writable Netdata log and state directories when you want the default direct-journal backend or local SNMP trap log sources. +- At least one output backend enabled per listener job: `journal.enabled: true` (the default), `otlp.enabled: true`, or both. +- For direct-journal jobs, Netdata must be able to resolve a stable local Agent identity and boot identity. Minimal containers, chroots, and embedded systems should validate local journal storage before relying on it. - UDP reachability from each trap sender to the Netdata host. - Network devices configured to send SNMP Trap or INFORM notifications to the Netdata host IP and listener port. - Firewall, security group, ACL, NAT, and host firewall rules that allow the selected UDP port. diff --git a/docs/SNMP Traps/SNMP Trap Profile Format.mdx b/docs/SNMP Traps/SNMP Trap Profile Format.mdx index 00a448206f..9c374b9d3d 100644 --- a/docs/SNMP Traps/SNMP Trap Profile Format.mdx +++ b/docs/SNMP Traps/SNMP Trap Profile Format.mdx @@ -281,14 +281,14 @@ Identity behavior: - `identity.device: listener` is only for listener-owned rules that should merge all source devices. - `source_id_privacy: hash` hides raw source values behind a stable local hash - derived from the selected source value, job name, and local Agent identity. + derived from the selected source value, job name, and SDK local Agent identity. Use `raw` only when source labels are acceptable in your environment. Treat hashed `source_id` values as local listener identifiers, not portable join keys across Agents, listeners, or reinstalls. - The local salt is read from `/etc/machine-id`, then - `/var/lib/dbus/machine-id`, then hostname, with a fixed last-resort fallback - only when no stable local identity is available. The emitted `source_id` is - truncated to 16 hex characters. + The local salt comes from the systemd journal SDK host identity helper. On + platforms without a native machine ID, the helper uses its configured Netdata + state directory for synthesized stable local identity. The emitted `source_id` + is truncated to 16 hex characters. - `source_kind` is a closed label set: `vnode`, `listener`, `trusted_trap_address`, `udp_peer`, `entry_source`, `hostname_or_ip`, `trap_varbind`, `topology_ifindex`, `source`, or `other`. diff --git a/docs/SNMP Traps/Validation and Data Quality.mdx b/docs/SNMP Traps/Validation and Data Quality.mdx index 1645ea3393..773938a70e 100644 --- a/docs/SNMP Traps/Validation and Data Quality.mdx +++ b/docs/SNMP Traps/Validation and Data Quality.mdx @@ -36,7 +36,7 @@ Work through these checks in order during first deployment. Use [Quick Start](/d | Varbind quality | `TRAP_VAR_*`, `TRAP_JSON`, `snmp.trap.errors` `template_unresolved`, `binary_encoded` | Important event payload is queryable through indexed fields, with structured payload and audit details available in `TRAP_JSON`; binary-encoded journal fields are counted and need review. | | Deduplication | `TRAP_REPORT_TYPE=deduplication_summary`, `TRAP_SUPPRESSED_COUNT`, `TRAP_SUPPRESSED_FINGERPRINTS`, `snmp.trap.dedup_suppressed` | Repeated traps are summarized only when deduplication is intentionally enabled and the fingerprint matches operational expectations. | | Rate limiting | `snmp.trap.errors` `rate_limited`, job `rate_limit.mode` | Over-limit traffic is counted by `rate_limited`. In `drop` mode the packet is discarded; in `sample` mode it is counted and still enters the pipeline. | -| Journal health | `snmp.trap.pipeline` `committed`, `write_failed`, `snmp.trap.errors` `journal_write_failed`, direct journal path | Healthy direct-journal jobs commit rows and do not report write failures. Direct journal output is Linux-only. | +| Journal health | `snmp.trap.pipeline` `committed`, `write_failed`, `snmp.trap.errors` `journal_write_failed`, direct journal path | Healthy direct-journal jobs commit rows and do not report write failures. Local `journalctl` validation requires `journalctl` on the host where you query the files. | | OTLP health | `snmp.trap.errors` `otlp_export_failed`, downstream receiver records, OTLP resource attributes | OTLP export succeeds, records have `service.name=netdata-snmptrap` and the expected `service.instance.id`, and downstream records contain the expected trap attributes. | | Retention | Job `retention` settings and direct journal files | Local retention keeps enough trap history for investigation without unexpectedly evicting needed rows. | | Downstream SIEM fields | Ingested field names or OTLP attributes | SIEM rules use the fields that actually arrive, especially report type, source, OID/name, category, severity, and payload fields. | diff --git a/docs/Security and Privacy Design/Access Control and Feature Availability.mdx b/docs/Security and Privacy Design/Access Control and Feature Availability.mdx index cc90647f62..4ba4a0688f 100644 --- a/docs/Security and Privacy Design/Access Control and Feature Availability.mdx +++ b/docs/Security and Privacy Design/Access Control and Feature Availability.mdx @@ -106,6 +106,8 @@ When accessing Netdata via Agent/Parent MCP: - **Without Cloud connection**: MCP can access public functions and metrics, but sensitive functions follow the same restrictions as the dashboard - **With Cloud connection**: MCP inherits the user's Cloud permissions, enabling access to sensitive functions for authenticated users +- **With `[web].bearer token protection = yes`**: local MCP requires the local MCP API key on all transports (HTTP, SSE, WebSocket); anonymous MCP requests are rejected +- **Network ACL**: local MCP exposure is controlled by `[web].allow mcp from` (in addition to the global `[web].allow connections from`) For MCP setup and configuration, see the [MCP documentation](/docs/netdata-ai/mcp).