Skip to content

Commit e443090

Browse files
github-actions[bot]netdatabot
github-actions[bot]
and
netdatabot
authored
Ingest New Documentation (#2828)
Co-authored-by: netdatabot <43409846+netdatabot@users.noreply.github.com>
1 parent 16f3438 commit e443090

14 files changed

Lines changed: 268 additions & 19 deletions

‎docs/Alerts & Notifications/Alert Configuration Reference.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -812,11 +812,14 @@ chart labels: mount_point=/mnt/disk1 device=sda
812812

813813
This requires BOTH conditions to be true (AND logic).
814814

815-
**Important Notes:**
815+
:::important
816816

817817
- Space-separated list with [simple patterns](/docs/developer-and-contributor-corner/libnetdata/simple-patterns) support
818818
- If a specified label doesn't exist on the chart, the chart won't match
819819
- Multiple labels use AND logic
820+
- Alerts based on `chart labels` require the underlying chart to exist. For example, a `disk.space` chart is only created when a mount point is present and collected. For example, if a CIFS mount fails to mount after a system reboot, no `disk.space` chart will exist for that mount point, and the alert will not activate
821+
822+
:::
820823

821824
#### Alert Line `summary`
822825

‎docs/Netdata Agent/Configuration/Dynamic Configuration Manager.mdx‎

Lines changed: 30 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,6 @@ slug: "/netdata-agent/configuration/dynamic-configuration-manager"
1010

1111
# Dynamic Configuration Manager
1212

13-
## Table of Contents
14-
15-
- [Overview](#overview)
16-
- [Quick Access Methods](#quick-access-methods)
17-
- [Getting Started](#getting-started)
18-
- [Collectors](#collectors)
19-
- [Multi-Node Deployment](#multi-node-deployment)
20-
2113
## Overview
2214

2315
:::important
@@ -283,6 +275,36 @@ This feature is particularly valuable for managing large infrastructures where m
283275

284276
:::
285277

278+
## Troubleshooting
279+
280+
### HTTP 412 Error When Editing Alert Configurations
281+
282+
If you receive an **HTTP 412 error** with a message like "Request failed with status 412" when editing alert configurations, this indicates an **authentication issue**, not a schema validation error.
283+
284+
:::important
285+
286+
In Netdata, HTTP 412 is used to indicate that an authorization bearer token was required but was not present in the request. This differs from the generic HTTP 412 "Precondition Failed" response.
287+
288+
:::
289+
290+
**Common causes:**
291+
292+
1. **Bearer token protection enabled** - Your agent requires Cloud authentication for API access
293+
2. **Cloud connection lost** - Agent disconnected from Netdata Cloud
294+
3. **Session expired** - Bearer token has expired (tokens expire after 24 hours)
295+
4. **Missing browser authentication state** - Your browser is no longer sending a valid Cloud bearer token with the request
296+
297+
**Resolution steps:**
298+
299+
1. **Verify claim and Cloud connection**: Check `http://IP:19999/api/v3/info` and inspect the `cloud` section. Use `cloud.status` to verify whether the Agent is connected to Netdata Cloud, and if it is not `online`, inspect `cloud.reason` for the failure details.
300+
2. **Re-authenticate**: Log out and log back into Netdata Cloud to refresh your bearer token.
301+
3. **Verify bearer token protection setting**: If enabled in `netdata.conf`, ensure you're accessing the agent through a Cloud-authenticated session.
302+
4. **Check permissions only if you get HTTP 403**: If the request changes from HTTP 412 to HTTP 403 after re-authenticating, ensure you have Admin or Manager role in the space containing the agent.
303+
304+
For more information, see [Secure Your Netdata Agent with Bearer Token Protection](/docs/netdata-agent/configuration/securing-agents/bearer-token-protection).
305+
306+
---
307+
286308
Experience the efficiency and power of the Dynamic Configuration Manager in Netdata today. Whether you're managing a handful of nodes or a vast infrastructure, this feature will make your monitoring and alerting tasks smoother and more intuitive.
287309

288310
Developing with dynamic configuration? [Click here](https://learn.netdata.cloud/docs/developer-and-contributor-corner/dynamic-configuration/).

‎docs/Netdata Agent/Configuration/Securing Agents/Bearer Token Protection.mdx‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
custom_edit_url: "https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md"
3+
sidebar_label: "Bearer Token Protection"
4+
learn_status: "Published"
5+
learn_rel_path: "Netdata Agent/Configuration/Securing Agents"
6+
sidebar_position: "20"
7+
learn_link: "https://learn.netdata.cloud/docs/netdata-agent/configuration/securing-agents/bearer-token-protection"
8+
slug: "/netdata-agent/configuration/securing-agents/bearer-token-protection"
9+
---
10+
11+
# Secure Your Netdata Agent with Bearer Token Protection
12+
13+
Netdata provides native bearer token protection that integrates with Netdata Cloud Single Sign-On (SSO). With a single configuration setting, you can secure direct access to your Netdata Agents and Parents while inheriting the same permissions and roles your users have in Netdata Cloud.
14+
15+
## Who Can Use This
16+
17+
Bearer token protection is available to all Netdata Cloud users:
18+
19+
- **Community plan** (free)
20+
- **Business plan** (paid)
21+
22+
Your agent must be [claimed to Netdata Cloud](/docs/netdata-cloud/connect-agent) to use this feature.
23+
24+
## How It Works
25+
26+
When bearer token protection is enabled:
27+
28+
1. Users visit your agent's dashboard directly (e.g., `http://your-server:19999`)
29+
2. The agent redirects them to Netdata Cloud for authentication
30+
3. After successful Cloud SSO login, users receive a time-limited bearer token
31+
4. The token grants access based on their Netdata Cloud role (Admin, Manager, Troubleshooter, etc.)
32+
5. Tokens expire after 24 hours and are automatically renewed through Cloud
33+
34+
This means:
35+
36+
- **Single Sign-On**: Users authenticate once via Netdata Cloud
37+
- **Role-Based Access**: Cloud roles and permissions apply to direct agent access
38+
- **Centralized Control**: Manage access through Netdata Cloud, not per-agent configurations
39+
- **No Password Files**: No htpasswd files or reverse proxy auth configuration needed
40+
41+
## Enable Bearer Token Protection
42+
43+
Edit your `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration#edit-configuration-files) script:
44+
45+
```bash
46+
cd /etc/netdata
47+
sudo ./edit-config netdata.conf
48+
```
49+
50+
Add or modify the `[web]` section:
51+
52+
```ini
53+
[web]
54+
bearer token protection = yes
55+
```
56+
57+
Restart Netdata to apply:
58+
59+
```bash
60+
sudo systemctl restart netdata
61+
```
62+
63+
## What Gets Protected
64+
65+
When enabled, bearer token protection secures **all data APIs**, including:
66+
67+
- Metrics and charts (`/api/v3/data`, `/api/v3/allmetrics`)
68+
- Alerts (`/api/v3/alerts`, `/api/v3/alert_transitions`)
69+
- Contexts and nodes (`/api/v3/contexts`, `/api/v3/nodes`)
70+
- Functions (`/api/v3/function`, `/api/v3/functions`)
71+
- Dynamic configuration (`/api/v3/config`)
72+
73+
## What Remains Public
74+
75+
**Static web files** (HTML, CSS, JavaScript) in Netdata's web directory are **not protected**. This means:
76+
77+
- Users can still download and view the dashboard UI
78+
- The dashboard will load but **won't display any data**
79+
- All API calls from the dashboard will fail until the user authenticates
80+
81+
This is by design - it allows the dashboard to redirect users to Netdata Cloud for authentication.
82+
83+
A small set of APIs also remain publicly accessible for operational reasons:
84+
85+
| API | What it exposes |
86+
|-----|-----------------|
87+
| `/api/v3/info` | Agent version, OS, build info, capabilities |
88+
| `/api/v3/me` | Current user authentication status |
89+
| `/api/v3/claim` | Agent claiming endpoint (protected by separate security key) |
90+
| `/api/v3/stream_info` | Streaming connection statistics |
91+
| `/api/v2/claim` | Agent claiming endpoint (v2, protected by security key) |
92+
| `/api/v1/registry?action=hello` | Node list, machine GUIDs, cloud connection status |
93+
| `/api/v1/manage/health` | Alert silencing (protected by separate X-Auth-Token) |
94+
95+
These APIs are required for the authentication flow and dashboard initialization. The registry `hello` action returns node identifiers and cloud connection status, which the dashboard needs to initiate the authentication redirect.
96+
97+
**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.
98+
99+
## Requirements
100+
101+
- Agent must be claimed to Netdata Cloud
102+
- ACLK connection must be active (agent connected to Cloud)
103+
- Users must have a Netdata Cloud account with access to the space containing the agent
104+
105+
## Comparison with Other Methods
106+
107+
| Method | Setup Complexity | SSO | Centralized Management | Works Offline |
108+
|--------|-----------------|-----|----------------------|---------------|
109+
| **Bearer Token Protection** | Single setting | Yes | Yes | No |
110+
| Reverse Proxy + Basic Auth | High (proxy + htpasswd) | No | No | Yes |
111+
| IP-Based Restrictions | Medium | No | No | Yes |
112+
| Disable Dashboard | Single setting | N/A | N/A | N/A |
113+
114+
Choose bearer token protection when you want the simplest setup with Cloud SSO integration. Choose reverse proxy if you need custom authentication, don't use Netdata Cloud, or require offline access.
115+
116+
## Combining with Other Security Measures
117+
118+
Bearer token protection can be combined with:
119+
120+
- **TLS/SSL encryption**: Configure [TLS in Netdata](/docs/netdata-agent/configuration/securing-agents/web-server-reference#examples) for encrypted connections
121+
- **IP restrictions**: Add `allow connections from` to limit which IPs can even attempt to connect
122+
- **Firewall rules**: Block port 19999 from untrusted networks
123+
124+
Example combining bearer token with IP restrictions:
125+
126+
```ini
127+
[web]
128+
bearer token protection = yes
129+
allow connections from = 10.* 192.168.* localhost
130+
```
131+
132+
## Troubleshooting
133+
134+
**Users can't authenticate:**
135+
136+
- Verify the Agent is claimed and connected to Cloud: Check `http://your-server:19999/api/v3/info` and inspect the `cloud` section. Use `cloud.status` to verify whether the agent is connected to Netdata Cloud, and if it is not `online`, inspect `cloud.reason` for the failure details
137+
- If needed, run `sudo netdatacli aclk-state` to diagnose the ACLK connection
138+
- Ensure users have access to the same Cloud Space as the Agent
139+
140+
**Token expired errors:**
141+
142+
- Tokens automatically renew when users have an active Cloud session
143+
- If tokens expire, users simply re-authenticate through Cloud
144+
145+
**Want to disable temporarily:**
146+
147+
```ini
148+
[web]
149+
bearer token protection = no
150+
```
151+
152+
Or via API (requires Admin/Manager role via Cloud):
153+
154+
```
155+
POST /api/v3/bearer_protection
156+
```

‎docs/Netdata Agent/Configuration/Securing Agents/Running the Agent behind a reverse proxy/Apache.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,7 @@ Repeat the operation for as many servers as you need.
171171

172172
:::tip Simpler Alternative
173173

174-
If you use Netdata Cloud, [Bearer Token Protection](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htpasswd files or Apache auth configuration needed.
174+
If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/securing-agents/bearer-token-protection) provides authentication with a single setting - no htpasswd files or Apache auth configuration needed.
175175

176176
:::
177177

‎docs/Netdata Agent/Configuration/Securing Agents/Running the Agent behind a reverse proxy/Caddy.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ netdata.domain.tld {
3434

3535
:::tip Simpler Alternative
3636

37-
If you use Netdata Cloud, [Bearer Token Protection](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no Caddy auth configuration needed.
37+
If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/securing-agents/bearer-token-protection) provides authentication with a single setting - no Caddy auth configuration needed.
3838

3939
:::
4040

‎docs/Netdata Agent/Configuration/Securing Agents/Running the Agent behind a reverse proxy/H2O.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ necessary to specify inside the H2O configuration that the final destination is
114114

115115
:::tip Simpler Alternative
116116

117-
If you use Netdata Cloud, [Bearer Token Protection](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htpasswd files or H2O auth configuration needed.
117+
If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/securing-agents/bearer-token-protection) provides authentication with a single setting - no htpasswd files or H2O auth configuration needed.
118118

119119
:::
120120

‎docs/Netdata Agent/Configuration/Securing Agents/Running the Agent behind a reverse proxy/HAProxy.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ backend netdata_backend
172172

173173
:::tip Simpler Alternative
174174

175-
If you use Netdata Cloud, [Bearer Token Protection](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no HAProxy userlist configuration needed.
175+
If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/securing-agents/bearer-token-protection) provides authentication with a single setting - no HAProxy userlist configuration needed.
176176

177177
:::
178178

‎docs/Netdata Agent/Configuration/Securing Agents/Running the Agent behind a reverse proxy/Lighttpd v1.4.x.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Though if it's public facing, you might then want to put some authentication on
4343

4444
:::tip Simpler Alternative
4545

46-
If you use Netdata Cloud, [Bearer Token Protection](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htdigest files or lighttpd auth configuration needed.
46+
If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/securing-agents/bearer-token-protection) provides authentication with a single setting - no htdigest files or lighttpd auth configuration needed.
4747

4848
:::
4949

‎docs/Netdata Agent/Configuration/Securing Agents/Running the Agent behind a reverse proxy/Nginx.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ If Nginx is not configured as described here, you will probably receive the erro
191191

192192
:::tip Simpler Alternative
193193

194-
If you use Netdata Cloud, [Bearer Token Protection](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htpasswd files or nginx auth configuration needed.
194+
If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/securing-agents/bearer-token-protection) provides authentication with a single setting - no htpasswd files or nginx auth configuration needed.
195195

196196
:::
197197

‎docs/Netdata Agent/Configuration/Securing Agents/Running the Agent behind a reverse proxy/Running the Agent behind a reverse proxy.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ custom_edit_url: "https://github.com/netdata/netdata/edit/master/docs/netdata-ag
33
sidebar_label: "Running the Agent behind a reverse proxy"
44
learn_status: "Published"
55
learn_rel_path: "Netdata Agent/Configuration/Securing Agents/Running the Agent behind a reverse proxy"
6-
sidebar_position: "20"
6+
sidebar_position: "30"
77
learn_link: "https://learn.netdata.cloud/docs/netdata-agent/configuration/securing-agents/running-the-agent-behind-a-reverse-proxy"
88
slug: "/netdata-agent/configuration/securing-agents/running-the-agent-behind-a-reverse-proxy"
99
---
@@ -12,7 +12,7 @@ slug: "/netdata-agent/configuration/securing-agents/running-the-agent-behind-a-r
1212

1313
:::tip Simpler Alternative for Netdata Cloud Users
1414

15-
If you use Netdata Cloud (free or paid), consider [Bearer Token Protection](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) instead. With a single setting (`bearer token protection = yes`), you get:
15+
If you use Netdata Cloud (free or paid), consider [Bearer Token Protection](/docs/netdata-agent/configuration/securing-agents/bearer-token-protection) instead. With a single setting (`bearer token protection = yes`), you get:
1616

1717
- **Cloud SSO authentication** - Users sign in through Netdata Cloud
1818
- **Role-based access** - Cloud roles apply to direct agent access

0 commit comments

Comments
 (0)