@cryptotaxi247 / netdata / commits / f3f84db87

Agent docs alignement (#20676)

Co-authored-by: ilyam8 <ilya@netdata.cloud>

Kanela committed Jul 15, 2025 at 11:08 UTC f3f84db87bf5a0652d19be40732675178dddeb2d

10 files changed +739 -543

docs/netdata-agent/README.md

+75 -61

@@ -1,89 +1,103 @@

1 # Netdata Agent

3 -The Netdata Agent is the main building block in the Netdata ecosystem. It is installed on all monitored systems to monitor system components, containers and applications.

3 +The Netdata Agent is the main building block in the Netdata ecosystem. You install it on all monitored systems to monitor system components, containers, and applications.

5 -The Netdata Agent is an **observability pipeline in a box** that can either operate standalone, or blend into a bigger pipeline made by more Netdata Agents (Children and Parents).

5 +The Netdata Agent is an **observability pipeline in a box** that you can either operate standalone, or blend into a bigger pipeline made by more Netdata Agents (Children and Parents).

7 ## Distributed Observability Pipeline

9 -The Netdata observability pipeline looks like in the following graph.

9 +Your Netdata observability pipeline looks like in the following graph.

11 -The pipeline is extended by creating Metrics Observability Centralization Points that are linked all together (`from a remote Netdata`, `to a remote Netdata`), so that all Netdata installed become a vast integrated observability pipeline.

11 +You can extend the pipeline by creating Metrics Observability Centralization Points that are linked all together (`from a remote Netdata`, `to a remote Netdata`), so that all Netdata you install become a vast integrated observability pipeline.

12 +

13 +<details>

14 +<summary>Click to see visual representation of the observability pipeline</summary>

16 ```mermaid

14 -stateDiagram-v2

15 - classDef userFeature fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow

16 - classDef usedByNC fill:#090,color:white,font-weight:bold,stroke-width:2px,stroke:yellow

17 - Local --> Discover

18 - Local: Local Netdata

19 - [*] --> Detect: from a remote Netdata

20 - Others: 3rd party time-series DBs

21 - Detect: Detect Anomalies

22 - Dashboard:::userFeature

23 - Dashboard: Netdata Dashboards

24 - AIAssistant:::userFeature

25 - AIAssistant: AI Assistant

26 - 3rdDashboard:::userFeature

27 - 3rdDashboard: 3rd party Dashboards

28 - Notifications:::userFeature

29 - Notifications: Alert Notifications

30 - Alerts: Alert Transitions

31 - Discover --> Collect

32 - Collect --> Detect

33 - Store: Store

34 - Store: Time-Series Database

35 - Detect --> Store

36 - Store --> Learn

17 +flowchart TD

18 + Start(["Remote Netdata Input"]) --> Discover

19 + LocalAgent["Local Netdata Agent"] --> Discover

20 + Discover["Discover Auto-detect metric sources Auto-discover on Kubernetes"] --> Collect

21 + Collect["Collect Query data sources 800+ integrations OpenMetrics, StatsD"] --> Detect

22 + Detect["Detect Anomalies Machine learning models Real-time outlier detection"] --> Store

23 + Store["Store Time-series database Anomaly status tracking"] --> Learn

24 Store --> Check

25 Store --> Query

26 Store --> Score

27 Store --> Stream

28 Store --> Export

42 - Query --> Visualize

29 + Learn["Learn Train ML models Behavior patterns"] --> Detect

30 + Check["Check Health engine Alert triggering"] --> Alerts

31 + Query["Query Time-series data queries"] --> Visualize

32 + Score["Score Metric comparison Correlation analysis"] --> Visualize

33 Query --> MCP

44 - Score --> Visualize

34 Score --> MCP

46 - Check --> Alerts

47 - Learn --> Detect: trained ML models

48 - Alerts --> Notifications

49 - Stream --> [*]: to a remote Netdata

50 - Export --> Others

51 - Others --> 3rdDashboard

35 + Alerts["Alert Transitions"] --> Notifications

36 + Stream --> End(["Remote Netdata Output"])

37 + Export --> ThirdParty

38 Visualize --> Dashboard

39 MCP --> AIAssistant

54 - Score:::usedByNC

55 - Query:::usedByNC

56 - Alerts:::usedByNC

40 + ThirdParty["Third-party DBs External systems"] --> ExternalDash

41 + Dashboard["Netdata Dashboards Real-time visualization"]

42 + AIAssistant["AI Assistant Intelligent analysis"]

43 + ExternalDash["Third-party Dashboards Grafana, etc."]

44 + Notifications["Alert Notifications Multi-channel delivery"]

45 + classDef input fill: #e8f4fd, stroke: #4a90e2, stroke-width: 3px, color: #2c3e50, rx: 15, ry: 15, font-size: 14px

46 + classDef process fill: #e8f5e8, stroke: #27ae60, stroke-width: 3px, color: #2c3e50, rx: 15, ry: 15, font-size: 14px

47 + classDef storage fill: #f3e8ff, stroke: #9b59b6, stroke-width: 3px, color: #2c3e50, rx: 15, ry: 15, font-size: 14px

48 + classDef output fill: #ffe8e8, stroke: #e74c3c, stroke-width: 3px, color: #2c3e50, rx: 15, ry: 15, font-size: 14px

49 + classDef userFeature fill: #fff2e8, stroke: #f39c12, stroke-width: 3px, color: #2c3e50, rx: 15, ry: 15, font-size: 14px

50 + classDef cloudFeature fill: #f0f8ff, stroke: #87ceeb, stroke-width: 3px, color: #2c3e50, rx: 15, ry: 15, font-size: 14px

51 + class Start input

52 + class LocalAgent input

53 + class End input

54 + class Discover process

55 + class Collect process

56 + class Detect process

57 + class Learn process

58 + class Check process

59 + class Store storage

60 + class Stream output

61 + class Export output

62 + class Alerts output

63 + class Dashboard userFeature

64 + class AIAssistant userFeature

65 + class ExternalDash userFeature

66 + class Notifications userFeature

67 + class Query cloudFeature

68 + class Score cloudFeature

69 + class MCP cloudFeature

70 + class Visualize cloudFeature

71 ```

59 -1. **Discover**: auto-detect metric sources on localhost, auto-discover metric sources on Kubernetes.

60 -2. **Collect**: query data sources to collect metric samples, using the optimal protocol for each data source. 800+ integrations supported, including dozens of native application protocols, OpenMetrics and StatsD.

61 -3. **Detect Anomalies**: use the trained machine learning models for each metric to detect in real-time if each sample collected is an outlier (an anomaly), or not.

62 -4. **Store**: keep collected samples and their anomaly status, in the time-series database (database mode `dbengine`) or a ring buffer (database modes `ram` and `alloc`).

63 -5. **Learn**: train multiple machine learning models for each metric collected, learning behaviors and patterns for detecting anomalies.

64 -6. **Check**: a health engine, triggering alerts and sending notifications. Netdata comes with hundreds of alert configurations that are automatically attached to metrics when they get collected, detecting errors, common configuration errors and performance issues.

65 -7. **Query**: a query engine for querying time-series data.

66 -8. **Score**: a scoring engine for comparing and correlating metrics.

67 -9. **Stream**: a mechanism to connect Netdata Agents and build Metrics Centralization Points (Netdata Parents).

73 +</details>

74 +

75 +1. **Discover**: You can auto-detect metric sources on localhost and auto-discover metric sources on Kubernetes.

76 +2. **Collect**: Query data sources to collect metric samples, using the optimal protocol for each data source. You get 800+ integrations supported, including dozens of native application protocols, OpenMetrics and StatsD.

77 +3. **Detect Anomalies**: Use the trained machine learning models for each metric to detect in real-time if each sample collected is an outlier (an anomaly), or not.

78 +4. **Store**: Keep collected samples and their anomaly status, in the time-series database (database mode `dbengine`) or a ring buffer (database modes `ram` and `alloc`).

79 +5. **Learn**: Train multiple machine learning models for each metric collected, learning behaviors and patterns for detecting anomalies.

80 +6. **Check**: A health engine, triggering alerts and sending notifications. Netdata comes with hundreds of alert configurations that are automatically attached to metrics when they get collected, detecting errors, common configuration errors and performance issues.

81 +7. **Query**: A query engine for querying time-series data.

82 +8. **Score**: A scoring engine for comparing and correlating metrics.

83 +9. **Stream**: A mechanism to connect Netdata Agents and build Metrics Centralization Points (Netdata Parents).

84 10. **Visualize**: Netdata's fully automated dashboards for all metrics.

69 -11. **Export**: export metric samples to third party time-series databases, enabling the use of third party tools for visualization, like Grafana.

70 -

71 -## Comparison to other observability solutions

72 -

73 -1. **One moving part**: Another monitoring solution requires maintaining metrics exporters, time-series databases, and visualization engines. Netdata has everything integrated into one package, even when [Metrics Centralization Points](/docs/observability-centralization-points/metrics-centralization-points/README.md) are required, making deployment and maintenance a lot simpler.

74 -

75 -2. **Automation**: Netdata is designed to automate most of the process of setting up and running an observability solution. It is designed to instantly provide comprehensive dashboards and fully automated alerts, with zero configuration.

76 -

77 -3. **High Fidelity Monitoring**: Netdata was born from our need to kill the console for observability. So, it provides metrics and logs in the same granularity and fidelity console tools do, but also comes with tools that go beyond metrics and logs, to provide a holistic view of the monitored infrastructure (e.g., check [Top Monitoring](/docs/top-monitoring-netdata-functions.md)).

85 +11. **Export**: Export metric samples to third party time-series databases, enabling you to use third party tools for visualization, like Grafana.

79 -4. **Minimal impact on monitored systems and applications**: Netdata has been designed to have a minimal impact on the monitored systems and their applications. There are [independent studies](https://www.ivanomalavolta.com/files/papers/ICSOC_2023.pdf) reporting that Netdata excels in CPU usage, RAM utilization, Execution Time and the impact Netdata has on monitored applications and containers.

87 +## Comparison to Other Observability Solutions

81 -5. **Energy efficiency**: [University of Amsterdam did a research to find the energy efficiency of monitoring tools](https://twitter.com/IMalavolta/status/1734208439096676680). They tested Netdata, Prometheus, ELK, among other tools. The study concluded that **Netdata is the most energy efficient monitoring tool**.

89 +| Aspect | Traditional Solutions | Netdata |

90 +|---------------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|

91 +| **Architecture** | Multiple components (metrics exporters, time-series databases, visualization engines) requiring separate maintenance | One integrated package with everything included, even for Metrics Centralization Points |

92 +| **Setup & Configuration** | Manual configuration and setup required | Fully automated with comprehensive dashboards and alerts available instantly with zero configuration |

93 +| **Monitoring Fidelity** | Variable granularity depending on configuration | Console-level granularity and fidelity, plus holistic monitoring tools like [Top Monitoring](/docs/top-monitoring-netdata-functions.md) |

94 +| **System Impact** | Higher CPU usage, RAM utilization, and execution time impact on monitored systems | Minimal impact on monitored systems and applications, verified by [independent studies](https://www.ivanomalavolta.com/files/papers/ICSOC_2023.pdf) |

95 +| **Energy Efficiency** | Higher energy consumption | [Most energy efficient monitoring tool](https://twitter.com/IMalavolta/status/1734208439096676680) according to University of Amsterdam research |

97 ## Dashboard Versions

85 -The Netdata Agents (Standalone, Children and Parents) **share the dashboard** of Netdata Cloud. However, when the user is logged in and the Agent is connected to the Cloud, the following are enabled (which are otherwise disabled):

99 +Your Netdata Agents (Standalone, Children and Parents) **share the dashboard** of Netdata Cloud. However, when you are logged in and your Agent is connected to the Cloud, the following are enabled (which are otherwise disabled):

100

87 -1. **Access to Sensitive Data**: Some data, like systemd-journal logs and several [Top Monitoring](/docs/top-monitoring-netdata-functions.md) features expose sensitive data, like IPs, ports, process command lines and more. To access all these when the dashboard is served directly from an Agent, Netdata Cloud is required to verify that the user accessing the dashboard has the required permissions.

101 +1. **Access to Sensitive Data**: Some data, like systemd-journal logs and several [Top Monitoring](/docs/top-monitoring-netdata-functions.md) features expose sensitive data, like IPs, ports, process command lines and more. To access all these when the dashboard is served directly from an Agent, Netdata Cloud is required to verify that you have the required permissions to access the dashboard.

102

89 -2. **Dynamic Configuration**: Netdata Agents are configured via configuration files, manually or through some provisioning system. The latest Netdata includes a feature to allow users to change some configurations (collectors, alerts) via the dashboard. This feature is only available to users of paid Netdata Cloud plan.

103 +2. **Dynamic Configuration**: You can configure Netdata Agents via configuration files, manually or through some provisioning system. The latest Netdata includes a feature to allow you to change some configurations (collectors, alerts) via the dashboard. This feature is only available to you if you have a paid Netdata Cloud plan.

docs/netdata-agent/configuration/README.md

+52 -24

@@ -1,49 +1,77 @@

1 # Netdata Agent Configuration

3 -> **Info**

4 ->

5 -> Netdata Cloud lets you configure Agents on the fly. Check the [Dynamic Configuration Manager](/docs/netdata-agent/configuration/dynamic-configuration.md) documentation for details.

3 +:::info

7 -The main Netdata Agent configuration is `netdata.conf`.

5 +You can configure Netdata Agents on the fly using Netdata Cloud. Check the [Dynamic Configuration Manager](/docs/netdata-agent/configuration/dynamic-configuration.md) documentation for details.

9 -## The Netdata config directory

7 +:::

11 -On most Linux systems, the **Netdata config

12 -directory** will be `/etc/netdata/`. The config directory contains several configuration files with the `.conf` extension, a

13 -few directories, and a shell script named `edit-config`.

9 +You configure your Netdata Agent using the main configuration file `netdata.conf`. This guide shows you how to locate, edit, and manage this configuration file.

15 -> Some operating systems will use `/opt/netdata/etc/netdata/` as the config directory. If you're not sure where yours

16 -> is, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with the IP address or hostname of

17 -> your node, and find the `# config directory =` setting. The value listed is the config directory for your system.

11 +## Locate Your Config Directory

19 -All of Netdata's documentation assumes that your config directory is at `/etc/netdata`, and that you're running any scripts from inside that directory.

13 +First, you need to find where your configuration files are stored. On most Linux systems, you'll find your **Netdata config directory** at `/etc/netdata/`. This directory contains:

21 -## Edit a configuration file using `edit-config`

15 +- Several configuration files with the `.conf` extension

16 +- A few directories for specific configurations

17 +- A shell script named `edit-config` for safely editing files

23 -We recommend the use of the `edit-config` script for configuration changes.

19 +:::tip

25 -It exists inside your config directory (read above) and helps manage and safely edit configuration files.

21 +Some operating systems use `/opt/netdata/etc/netdata/` as the config directory.

22 +If you're **not sure where yours is located**, navigate to `http://NODE:19999/netdata.conf` in your browser (replace `NODE` with your node's IP address or hostname) and find the `# config directory =` setting. The value listed shows your system's config directory.

27 -To edit `netdata.conf`, run this on your terminal:

24 +:::

29 -```bash

30 -cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata

31 -sudo ./edit-config netdata.conf

32 -```

26 +:::note

27 +

28 +All of Netdata's documentation **assumes your config directory is at** `/etc/netdata`, and that you run any scripts from inside that directory.

29 +

30 +:::

31 +

32 +## Edit Configuration Files

33 +

34 +<details>

35 +<summary>Method 1: Using `edit-config` (Recommended)</summary>

36 +

37 +You should use the `edit-config` script for making configuration changes. This script lives inside your config directory and helps you manage and safely edit configuration files.

34 -Your editor will open.

39 +To edit `netdata.conf`:

36 -## downloading `netdata.conf`

41 +1. Navigate to your config directory and run the edit script:

38 -The running version of `netdata.conf` can be downloaded from a running Netdata Agent, at this URL:

43 + ```bash

44 + cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata

45 + sudo ./edit-config netdata.conf

46 + ```

47 +

48 +2. Your default editor will open with the configuration file

49 +3. Make your changes and save the file

50 +

51 +</details>

52 +

53 +<details>

54 +<summary>Method 2: Download Current Configuration</summary>

55 +

56 +If you want to work with the exact configuration currently running on your Agent, you can download it directly.

57 +

58 +You can download the running version of `netdata.conf` from your running Netdata Agent at this URL:

60 ```url

61 http://agent-ip:19999/netdata.conf

62 ```

44 -You can save and use this version, using these commands:

64 +To download and replace your current configuration file:

66 ```bash

67 cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata

68 curl -ksSLo /tmp/netdata.conf.new http://localhost:19999/netdata.conf && sudo mv -i /tmp/netdata.conf.new netdata.conf

69 ```

70 +

71 +This method is useful when you want to:

72 +

73 +- Backup your current running configuration

74 +- Start with the default settings that are currently active

75 +- Replicate configuration across multiple agents

76 +

77 +</details>

docs/netdata-agent/configuration/optimize-the-netdata-agents-performance.md

+91 -40

@@ -1,71 +1,122 @@

1 # Agent Performance Optimization Guide

3 -While Netdata Agents prioritize simplicity and out-of-the-box functionality, their default configuration focuses on comprehensive monitoring rather than performance optimization.

3 +While Netdata Agents work seamlessly out-of-the-box with comprehensive monitoring, you can tune their configuration for better performance when needed.

5 -By default, Agents provide:

5 +## Why optimize your Agent

7 -- **Automatic Application Discovery**: Continuously detects and monitors applications running on your node without manual configuration.

8 -- **Real-time Metric Collection**: Collects metrics with one-second granularity.

9 -- **Health Monitoring**: Actively tracks the health status of your applications and system components with built-in alerting.

10 -- **Machine Learning**: Trains models for each metric to detect anomalies and unusual patterns in your system's behavior ([Anomaly Detection](/src/ml/README.md)).

7 +By default, your Netdata Agent provides:

12 -> **Note**

13 ->

14 -> For details about Agent resource requirements, see [Resource Utilization](/docs/netdata-agent/sizing-netdata-agents/README.md).

9 +- **Automatic Application Discovery**: Continuously detects and monitors applications on your node

10 +- **Real-time Metric Collection**: Collects metrics every second

11 +- **Health Monitoring**: Actively tracks health status with built-in alerting

12 +- **Machine Learning**: Trains anomaly detection models for each metric ([Anomaly Detection](/src/ml/README.md))

16 -This document describes various strategies to optimize Netdata's performance for your specific monitoring needs.

14 +These features deliver comprehensive monitoring but consume system resources. You might need to optimize when running Agents on resource-constrained systems or when scaling your monitoring infrastructure.

18 -## Summary of performance optimizations

16 +:::note

20 -The following table summarizes the effect of each optimization on the CPU, RAM and Disk IO utilization in production.

18 +See [Resource Utilization](/docs/netdata-agent/sizing-netdata-agents/README.md) for detailed Agent resource requirements.

22 -| Optimization | CPU | RAM | Disk IO |

23 -|---------------------------------------------------------------------------|--------------------|--------------------|--------------------|

20 +:::

31 -## Implement Centralization Points

22 +## How to optimize performance

33 -In production environments, use Parent nodes as centralization points to collect and aggregate data from Child nodes across your infrastructure. This architecture follows our recommended [Centralization Points](/docs/observability-centralization-points/README.md) pattern.

24 +Here's how each optimization strategy reduces resource usage:

35 -## Disable Plugins or Collectors

27 +|-----------------------------------------------------------------------|-------------|-------------|-----------------|

28 +| [Set up Parent-Child architecture](#set-up-parent-child-architecture) | ✓ | ✓ | ✓ |

29 +| [Disable unneeded collectors](#disable-unneeded-collectors) | ✓ | ✓ | ✓ |

30 +| [Reduce collection frequency](#reduce-collection-frequency) | ✓ | | ✓ |

31 +| [Adjust metric retention](#adjust-metric-retention) | | ✓ | ✓ |

32 +| [Switch to RAM mode](#switch-to-ram-mode) | | ✓ | ✓ |

33 +| [Turn off ML on Children](#turn-off-ml-on-children) | ✓ | | |

37 -You can improve Agent performance by selectively disabling [Plugins or Collectors](/src/collectors/README.md) that you don't need for your monitoring requirements.

35 +## Set up Parent-Child architecture

39 -> **Note**

40 ->

41 -> Inactive Plugins and Collectors automatically shut down and don't consume system resources. Performance benefits come only from disabling those that are actively collecting metrics.

37 +Transform your monitoring by using Parent nodes as centralization points. Parents collect and aggregate data from multiple Child nodes, significantly reducing the load on individual systems.

43 -For detailed instructions on managing Plugins and Collectors, see [configuration guide](/src/collectors/REFERENCE.md).

39 +In this setup:

45 -## Adjust Data Collection Frequency

41 +- **Children** stream their metrics to Parents instead of storing everything locally

42 +- **Parents** handle data aggregation, storage, and dashboard queries

43 +- **You** access all metrics through the Parent nodes

47 -One of the most effective ways to reduce the Agent's resource consumption is to modify its data collection frequency.

45 +:::tip

46 +This architecture works especially well in production environments where you monitor many systems. Learn more in our [Centralization Points documentation](/docs/observability-centralization-points/README.md).

47 +:::

49 -If you don't require per-second precision, or if your Agent is consuming excessive CPU during periods of low dashboard activity, you can [reduce the collection frequency](/src/collectors/REFERENCE.md).

50 -This adjustment can significantly improve CPU utilization while maintaining meaningful monitoring capabilities.

49 +## Disable unneeded collectors

52 -## Optimize Metric Retention Settings

51 +Reduce resource usage by turning off [Plugins or Collectors](/src/collectors/README.md) you don't need.

54 -You can reduce memory and disk usage by adjusting [how long the Agent stores metrics](/src/database/CONFIGURATION.md).

53 +:::warning Important

54 +Only active collectors consume resources. Inactive plugins and collectors shut down automatically, so you only save resources by disabling those currently running and collecting metrics.

55 +:::

56 -## Select Appropriate Database Mode

57 +Follow our [configuration guide](/src/collectors/REFERENCE.md) to identify and disable specific collectors.

58 -For IoT devices and Child nodes in [Centralization Point setups](/docs/observability-centralization-points/README.md), you can optimize performance by [switching to RAM mode](/src/database/CONFIGURATION.md). This can significantly reduce resource usage while maintaining essential monitoring capabilities.

59 +## Reduce collection frequency

60 -## Disable Machine Learning on Children

61 +Save CPU and disk IO by collecting metrics less frequently. If you don't need per-second precision, or if your Agent consumes too much CPU during periods of low dashboard activity, increase the collection interval.

62 -For optimal resource allocation, we recommend running Machine Learning only on Parent nodes, or on systems with sufficient CPU and memory capacity.

63 +This change:

64 -To reduce resource usage on Child nodes or less powerful systems, you can disable ML by modifying `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config):

65 +- Significantly reduces CPU usage

66 +- Decreases disk write operations

67 +- Maintains meaningful monitoring capabilities

68 +

69 +Learn how to adjust collection frequency in our [configuration guide](/src/collectors/REFERENCE.md).

70 +

71 +## Adjust metric retention

72 +

73 +Control memory and disk usage by changing how long your Agent stores historical data. Shorter retention periods mean:

74 +

75 +- Less RAM needed for in-memory metrics

76 +- Reduced disk space requirements

77 +- Faster Agent startup times

78 +

79 +Configure retention settings using our [database configuration guide](/src/database/CONFIGURATION.md).

80 +

81 +## Switch to RAM mode

82 +

83 +For IoT devices and Child nodes in [Parent-Child setups](/docs/observability-centralization-points/README.md), switch to RAM mode to eliminate disk operations entirely. This mode:

84 +

85 +- Stores all metrics in memory only

86 +- Eliminates disk IO for metric storage

87 +- Significantly reduces overall resource usage

88 +

89 +:::tip

90 +

91 +Since Child nodes stream metrics to Parents, they don't need persistent local storage. RAM mode is ideal for this use case.

92 +

93 +:::

94 +

95 +Set up RAM mode following our [database configuration guide](/src/database/CONFIGURATION.md).

96 +

97 +## Turn off ML on Children

98 +

99 +Optimize resource allocation by running Machine Learning only where it matters most. We recommend:

100 +

101 +- **Enable ML on Parents**: They have the complete data picture and typically more resources

102 +- **Disable ML on Children**: They focus on collecting and streaming metrics

103 +

104 +To disable ML, edit your configuration using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files):

105

106 ```text

107 [ml]

108 enabled = no

109 ```

110

71 -This configuration is particularly beneficial for Child nodes since their primary role is to collect and stream metrics to Parent nodes, where ML analysis can be performed centrally.

111 +:::tip

112 +

113 +This configuration particularly benefits Child nodes, allowing them to focus on their primary role of collecting and streaming metrics to Parent nodes where ML analysis happens centrally.

114 +

115 +:::

116 +

117 +## Next steps

118 +

119 +1. **Identify your needs**: Determine whether you need optimization for resource constraints or architectural efficiency

120 +2. **Start with architecture**: If monitoring multiple systems, implement Parent-Child setup first

121 +3. **Fine-tune individual Agents**: Apply specific optimizations based on each system's role and resources

122 +4. **Monitor the impact**: Use Netdata dashboards to confirm your optimizations haven't compromised monitoring visibility

docs/netdata-agent/configuration/organize-systems-metrics-and-alerts.md

+145 -154

@@ -1,205 +1,193 @@

1 # Organize systems, metrics, and alerts

3 -When you use Netdata to monitor and troubleshoot an entire infrastructure, you need sophisticated ways of keeping everything organized.

4 -Netdata allows organizing your observability infrastructure with Spaces, Rooms, virtual nodes, host labels, and metric labels.

3 +When you monitor dozens or hundreds of systems, you need powerful ways to keep everything organized. Netdata helps you structure your infrastructure with Spaces, Rooms, virtual nodes, host labels, and metric labels.

6 -## Spaces and Rooms

5 +## Choose your organization strategy

8 -[Spaces](/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md#spaces) are used for organization-level or infrastructure-level

9 -grouping of nodes and people. A node can only appear in a single space, while people can have access to multiple spaces.

7 +Netdata provides multiple organization methods that work together:

11 -The [Rooms](/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md#rooms) in a space bring together nodes and people in

12 -collaboration areas. Rooms can also be used for fine-tuned

13 -[role-based access control](/docs/netdata-cloud/authentication-and-authorization/role-based-access-model.md).

9 +- **Spaces and Rooms**: Group your infrastructure and team members

10 +- **Virtual nodes**: Monitor multi-component systems as separate entities

11 +- **Host labels**: Tag systems by purpose, location, or any custom criteria

12 +- **Metric labels**: Filter and group metrics within charts

15 -## Virtual nodes

14 +### Organize your infrastructure and team

17 -Netdata’s virtual nodes functionality allows you to define nodes in configuration files and have them be treated as regular nodes

18 -in all the UI, dashboards, tabs, filters, etc. For example, you can create a virtual node each for all your Windows machines

19 -and monitor them as discrete entities. Virtual nodes can help you simplify your infrastructure monitoring and focus on the

20 -individual node that matters.

16 +<details>

17 +<summary>Spaces are your primary collaboration environment where you:</summary>

22 -To define your Windows server as a Virtual Node, you need to:

19 +- Organize team members and manage access levels

20 +- Connect nodes for monitoring

21 +- Create a unified monitoring environment

24 -* Define virtual nodes in `/etc/netdata/vnodes/vnodes.conf`

23 +</details>

26 - ```yaml

27 - - hostname: win_server1

28 - guid: <value>

29 - ```

25 +<details>

26 +<summary>Rooms function as organizational units within Spaces, providing:</summary>

31 - Remember to use a valid guid (On Linux you can use `uuidgen` command to generate one, on Windows use the `[guid]::NewGuid()` command in PowerShell)

28 +- Infrastructure-wide dashboards

29 +- Real-time metrics visualization

30 +- Focused monitoring views

31 +- Flexible node grouping

33 -* Add the vnode config to the data collection job. e.g., in `go.d/windows.conf`:

33 +</details>

35 - ```yaml

36 - jobs:

37 - - name: win_server1

38 - vnode: win_server1

39 - url: http://203.0.113.10:9182/metrics

40 - ```

35 +

42 -## Host labels

37 +:::info

44 -Host labels can be extremely useful when:

39 +Each node belongs to exactly one Space but can be assigned to multiple Rooms within that Space.

46 -* You need alerts that adapt to the system's purpose

47 -* You need properly labeled metrics archiving so you can sort, correlate, and mash-up your data to your heart's content.

48 -* You need to keep tabs on ephemeral Docker containers in a Kubernetes cluster.

41 +:::

50 -Let's take a peek into how to create host labels and apply them across a few of Netdata's features to give you more

51 -organization power over your infrastructure.

43 +### Set up your organization

53 -### Default labels

45 +1. **Create a Space** using the plus (+) icon in the left-most sidebar

46 +2. **Invite team members** and set their access levels

47 +3. **Create Rooms** to organize nodes by:

48 + - Service type (Nginx, MySQL, Pulsar)

49 + - Purpose (webserver, database, application)

50 + - Location or infrastructure type (cloud provider, bare metal, containers)

55 -When Netdata starts, it captures relevant information about the system and converts them into automatically generated

56 -host labels. You can use these to logically organize your systems via health entities, exporting metrics,

57 -parent-child status, and more.

52 +:::tip

59 -They capture the following:

54 +Most organizations need only one Space. Create multiple Rooms within that Space to organize your infrastructure effectively.

61 -* Kernel version

62 -* Operating system name and version

63 -* CPU architecture, system cores, CPU frequency, RAM, and disk space

64 -* Whether Netdata is running inside a container, and if so, the OS and hardware details about the container's host

65 -* Whether Netdata is running inside K8s node

66 -* What virtualization layer the system runs on top of, if any

67 -* Whether the system is a streaming parent or child

56 +:::

69 -If you want to organize your systems without manually creating host labels, try the automatic labels in some

70 -features below. You can see them under `http://HOST-IP:19999/api/v1/info`, beginning with an underscore `_`.

58 +Learn more in our [Spaces and Rooms documentation](/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md).

72 -```json

73 -{

74 - ...

75 - "host_labels": {

76 - "_is_k8s_node": "false",

77 - "_is_parent": "false",

78 - ...

79 -```

60 +## Virtual nodes

81 -### Custom labels

62 +### Monitor complex systems as separate entities

83 -Host labels are defined in `netdata.conf`. To create host labels, open that file using `edit-config`.

64 +Virtual nodes let you split multi-component systems into distinct, monitorable units. For example, you can monitor each Windows server in your infrastructure as its own node, even when collecting metrics through a single Netdata Agent.

85 -```bash

86 -cd /etc/netdata # Replace this path with your Netdata config directory, if different

87 -sudo ./edit-config netdata.conf

88 -```

66 +To create a virtual node for your Windows server:

90 -Create a new `[host labels]` section defining a new host label and its value for the system in question. Make sure not to violate any of the host label naming rules:

68 +1. Define the virtual node in `/etc/netdata/vnodes/vnodes.conf`:

92 -* Names can’t start with `_`, but it can be present in other parts of the name.

93 -* Names only accept alphabet letters, numbers, dots, and dashes.

70 + ```yaml

71 + - hostname: win_server1

72 + guid: <value>

73 + ```

95 -The policy for values is more flexible, but you can’t use exclamation marks (`!`), whitespaces (` `), single quotes (`'`), double quotes (`"`), or asterisks (`*`), because they’re used to compare label values in health alerts and templates.

75 + :::tip

76 + Generate a valid GUID using `uuidgen` on Linux or `[guid]::NewGuid()` in Windows PowerShell.

77 + :::

97 -```text

98 -[host labels]

99 - type = webserver

100 - location = us-seattle

101 - installed = 20200218

102 -```

79 +2. Add the vnode configuration to your data collection job in `go.d/windows.conf`:

104 -Once you've written a few host labels, you need to enable them. Instead of restarting the entire Netdata service, you

105 -can reload labels using the helpful `netdatacli` tool:

81 + ```yaml

82 + jobs:

83 + - name: win_server1

84 + vnode: win_server1

85 + url: http://203.0.113.10:9182/metrics

86 + ```

107 -```bash

108 -netdatacli reload-labels

109 -```

88 +## Host labels

89 +

90 +### Tag your systems for smarter monitoring

91 +

92 +Host labels help you:

111 -Your host labels will now be enabled. You can double-check these by using `curl http://HOST-IP:19999/api/v1/info` to read the status of your Agent. For example, from a VPS system running Debian 10:

94 +- Create alerts that adapt to each system's purpose

95 +- Archive metrics with proper categorization for analysis

96 +- Track ephemeral containers in Kubernetes clusters

97 +

98 +### Use automatic labels

99 +

100 +Netdata automatically generates host labels when it starts, capturing:

101 +

102 +| Label Category | Information Captured |

103 +|----------------|-----------------------------------------------------|

104 +| System Info | Kernel version, OS name and version |

105 +| Hardware | CPU architecture, cores, frequency, RAM, disk space |

106 +| Environment | Container details, Kubernetes node status |

107 +| Infrastructure | Virtualization layer, Parent-child streaming status |

108 +

109 +View your automatic labels at `http://HOST-IP:19999/api/v1/info`:

110

111 ```json

112 {

115 - ...

113 "host_labels": {

114 "_is_k8s_node": "false",

118 - "_is_parent": "false",

119 - "_virt_detection": "systemd-detect-virt",

120 - "_container_detection": "none",

121 - "_container": "unknown",

122 - "_virtualization": "kvm",

123 - "_architecture": "x86_64",

124 - "_kernel_version": "4.19.0-6-amd64",

125 - "_os_version": "10 (buster)",

126 - "_os_name": "Debian GNU/Linux",

127 - "type": "webserver",

128 - "location": "seattle",

129 - "installed": "20200218"

130 - },

131 - ...

115 + "_is_parent": "false"

116 + }

117 }

118 ```

119

135 -### Host labels in streaming

120 +### Create custom labels

121

137 -You may have noticed the `_is_parent` and `_is_child` automatic labels from above. Host labels are also now

138 -streamed from a child to its parent node, which concentrates an entire infrastructure's OS, hardware, container,

139 -and virtualization information in one place: the parent.

122 +Add your own labels to categorize systems by any criteria you need.

123

141 -Now, if you'd like to remind yourself of how much RAM a certain child node has, you can access

142 -`http://localhost:19999/host/CHILD_HOSTNAME/api/v1/info` and reference the automatically generated host labels from the

143 -child system. It's a vastly simplified way of accessing critical information about your infrastructure.

124 +1. Edit your Netdata configuration:

125

145 -> ⚠️ Because automatic labels for child nodes are accessible via API calls, and contain sensitive information like kernel and operating system versions, you should secure streaming connections with SSL. See the [streaming documentation](/src/streaming/README.md#securing-streaming-with-tlsssl) for details. You may also want to use [access lists](/src/web/server/README.md#access-lists) or [expose the API only to LAN/localhost connections](/docs/netdata-agent/securing-netdata-agents.md#restrict-dashboard-access-to-private-lan).

126 + ```bash

127 + cd /etc/netdata # Replace with your Netdata config directory

128 + sudo ./edit-config netdata.conf

129 + ```

130

147 -You can also use `_is_parent`, `_is_child`, and any other host labels in both health entities and metrics

148 -exporting. Speaking of which...

131 +2. Add a `[host labels]` section:

132

150 -### Host labels in alerts

133 + ```text

134 + [host labels]

135 + type = webserver

136 + location = us-seattle

137 + installed = 20200218

138 + ```

139

152 -You can use host labels to logically organize your systems by their type, purpose, or location, and then apply specific

153 -alerts to them.

140 + :::info Label naming rules

141 + - Names cannot start with `_`

142 + - Use only letters, numbers, dots, and dashes

143 + - Values cannot contain: `!` ` ` `'` `"` `*`

144 + :::

145

155 -For example, let's use configuration example from earlier:

146 +3. Enable your labels without restarting Netdata:

147

157 -```text

158 -[host labels]

159 - type = webserver

160 - location = us-seattle

161 - installed = 20200218

162 -```

148 + ```bash

149 + netdatacli reload-labels

150 + ```

151

164 -You could now create a new health entity (checking if disk space runs out soon) that applies only to any host

165 -labeled `webserver`:

152 +4. Verify your labels at `http://HOST-IP:19999/api/v1/info`

153

167 -```yaml

168 - template: disk_fill_rate

169 - on: disk.space

170 - lookup: max -1s at -30m unaligned of avail

171 - calc: ($this - $avail) / (30 * 60)

172 - every: 15s

173 - host labels: type = webserver

174 -```

154 +### Stream labels from Child to Parent

155

176 -Or, by using one of the automatic labels, for only webserver systems running a specific OS:

156 +In Parent-Child setups, host labels automatically stream from children to the parent node. Access any child's labels through the parent at:

157 +`http://localhost:19999/host/CHILD_HOSTNAME/api/v1/info`

158

178 -```yaml

179 - host labels: _os_name = Debian*

180 -```

159 +:::warning

160

182 -In a streaming configuration where a parent node is triggering alerts for its child nodes, you could create health

183 -entities that apply only to child nodes:

161 +Child node labels contain sensitive system information. Secure your streaming connections with SSL and consider using [access lists](/src/web/server/README.md#access-lists) or [restricting API access](/docs/netdata-agent/securing-netdata-agents.md#alternative-methods).

162

185 -```yaml

186 - host labels: _is_child = true

187 -```

163 +:::

164

189 -Or when ephemeral Docker nodes are involved:

165 +### Apply labels to alerts

166

191 -```yaml

192 - host labels: _container = docker

167 +Create targeted alerts based on host labels. For example, monitor disk space only on webservers:

168 +

169 +```text

170 + template: disk_fill_rate

171 + on: disk.space

172 + lookup: max -1s at -30m unaligned of avail

173 + calc: ($this - $avail) / (30 * 60)

174 + every: 15s

175 +host labels: type = webserver

176 ```

177

195 -Of course, there are many more possibilities for intuitively organizing your systems with host labels. See the [health

196 -documentation](/src/health/REFERENCE.md#alert-line-host-labels) for more details, and then get creative!

178 +Target systems by multiple criteria:

179 +

180 +| Target | Host Label | Use Case |

181 +|-------------------|-----------------------|--------------------------------|

182 +| Specific OS | `_os_name = Debian*` | Apply alerts to Debian systems |

183 +| Child nodes only | `_is_child = true` | Monitor streaming children |

184 +| Docker containers | `_container = docker` | Container-specific alerts |

185 +

186 +See the [health documentation](/src/health/REFERENCE.md#alert-line-host-labels) for more possibilities.

187

198 -### Host labels in metrics exporting

188 +### Export labels with metrics

189

200 -If you have enabled any metrics exporting via our experimental [exporters](/src/exporting/README.md), any new host

201 -labels you created manually are sent to the destination database alongside metrics. You can change this behavior by

202 -editing `exporting.conf`, and you can even send automatically generated labels on with exported metrics.

190 +When using [metrics exporters](/src/exporting/README.md), include host labels with your exported data:

191

192 ```text

193 [exporting:global]

@@ -208,7 +196,7 @@ send configured labels = yes

196 send automatic labels = no

197 ```

198

211 -You can also change this behavior per exporting connection:

199 +Configure per-connection settings:

200

201 ```text

202 [opentsdb:my_instance3]

@@ -221,21 +209,13 @@ send configured labels = no

209 send automatic labels = yes

210 ```

211

224 -By applying labels to exported metrics, you can more easily parse historical metrics with the labels applied. To learn

225 -more about exporting, read the [documentation](/src/exporting/README.md).

226 -

212 ## Metric labels

213

229 -The Netdata aggregate charts allow you to filter and group metrics based on label name-value pairs.

230 -

231 -All go.d plugin collectors support the specification of labels at the "collection job" level. Some collectors come without of the box

232 -labels (e.g., generic Prometheus collector, Kubernetes, Docker and more). But you can also add your own custom labels by configuring

233 -the data collection jobs.

214 +### Filter and group metrics within charts

215

235 -For example, suppose we have a single Netdata Agent, collecting data from two remote Apache web servers, located in different data centers.

236 -The web servers are load balanced and provide access to the service "Payments".

216 +Netdata's aggregate charts let you filter and group metrics using label name-value pairs. All go.d plugin collectors support labels at the collection job level.

217

238 -You can define the following in `go.d.conf`, to be able to group the web requests by service or location:

218 +Configure metric labels when collected from multiple sources. For example, label two Apache servers by service and location:

219

220 ```yaml

221 jobs:

@@ -251,4 +231,15 @@ jobs:

231 location: "New York"

232 ```

233

254 -Of course, you may define as many custom label/value pairs as you like, in as many data collection jobs you need.

234 +:::tip

235 +

236 +Define as many label pairs as you need across all your data collection jobs to create meaningful groupings in your dashboards.

237 +

238 +:::

239 +

240 +## Next steps

241 +

242 +1. **Start with Spaces and Rooms** to organize your infrastructure and team

243 +2. **Add host labels** to categorize your systems

244 +3. **Configure metric labels** for detailed filtering within charts

245 +4. **Set up virtual nodes** if you monitor complex, multi-component systems

\ No newline at end of file

docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/README.md

+30 -17

@@ -1,33 +1,46 @@

1 -# Running the Netdata Agent behind a reverse proxy

1 +# Running Netdata Behind a Reverse Proxy

3 -If you need to access a Netdata Agent's user interface or API in a production environment, we recommend you put Netdata behind

4 -another web server and secure access to the dashboard via SSL, user authentication, and firewall rules.

3 +You can improve security and capabilities by running your Netdata Agent behind another web server in production environments. This approach lets you secure access to the dashboard with SSL, user authentication, and firewall rules while providing more robustness and capabilities than the Agent's [internal web server](/src/web/README.md).

6 -A dedicated web server also provides more robustness and capabilities than the Agent's [internal web server](/src/web/README.md).

5 +## Supported Reverse Proxy Solutions

8 -We have documented running behind

9 -[nginx](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-nginx.md),

10 -[Apache](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-apache.md),

11 -[HAProxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md),

12 -[Lighttpd](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-lighttpd.md),

13 -[Caddy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-caddy.md),

14 -and [H2O](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-h2o.md).

15 -If you prefer a different web server, we suggest you follow the documentation for nginx and tell us how you did it by adding your own "Running behind webserverX" document.

7 +We have documented configuration guides for these web servers:

17 -When you run Netdata behind a reverse proxy, we recommend you firewall protect all your Netdata servers, so that only the web server IP will be allowed to directly access Netdata. To do this, run this on each of your servers (or use your firewall manager):

9 +- [nginx](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-nginx.md)

10 +- [Apache](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-apache.md)

11 +- [HAProxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md)

12 +- [Lighttpd](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-lighttpd.md)

13 +- [Caddy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-caddy.md)

14 +- [H2O](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-h2o.md)

19 -```sh

16 +:::tip

17 +

18 +If you prefer a different web server, we suggest you follow the nginx documentation and tell us how you did it by adding your own "Running behind webserverX" document.

19 +

20 +:::

21 +

22 +## Secure Direct Access to Netdata

23 +

24 +After setting up your reverse proxy, you should firewall protect all your Netdata servers so that only the web server IP can directly access Netdata.

25 +

26 +### Method 1: Using Firewall Rules

27 +

28 +You can use iptables to block direct access. Run this on each of your servers (or use your firewall manager):

29 +

30 +```bash

31 PROXY_IP="1.2.3.4"

32 iptables -t filter -I INPUT -p tcp --dport 19999 \! -s ${PROXY_IP} -m conntrack --ctstate NEW -j DROP

33 ```

24 -The above will prevent anyone except your web server from accessing a Netdata dashboard running on the host.

35 +This prevents anyone except your web server from accessing a Netdata dashboard running on the host.

36 +

37 +### Method 2: Using Netdata Configuration

26 -You can also use `netdata.conf`:

39 +You can also configure access control in `netdata.conf`:

41 ```text

42 [web]

43 allow connections from = localhost 1.2.3.4

44 ```

33 -Of course, you can add more IPs.

46 +You can add more IPs as needed to this setting.

docs/netdata-agent/securing-netdata-agents.md

+67 -46

@@ -1,28 +1,20 @@

1 # Securing Netdata Agents

3 -By default, the Agent exposes its **local dashboard** on port `19999`. If the node has a public IP address, the dashboard and metrics are accessible to anyone at `http://NODE:19999`.

3 +By default, your Netdata Agent exposes its local dashboard on port `19999`. If your node has a public IP address, the dashboard and metrics are accessible to anyone at `http://NODE:19999`.

5 -Protect your Agents by implementing any of these security measures:

5 +You can protect your Agents by implementing any of these security measures:

7 -**Recommended**:

7 +## Security Approaches

9 -- [Disable the local dashboard](#disable-the-local-dashboard): Best for users who monitor their systems through Netdata Cloud dashboards.

10 -- [Use Netdata Parents as Web Application Firewalls](#use-netdata-parents-as-web-application-firewalls): Deploy Parent nodes as border gateways to isolate production systems from direct internet exposure, even when using Netdata Cloud.

9 +### Recommended Methods

12 -**Alternative Approaches**:

11 +**Disable the Local Dashboard**

14 -- [Restrict dashboard access to private LAN](#restrict-dashboard-access-to-private-lan): Suitable for accessing the local dashboard via a LAN connection.

15 -- [Configure granular access control](#configure-granular-access-control): Limit local dashboard access to specific IP addresses, such as trusted static IPs or management LAN connections.

16 -- [Deploy a reverse proxy](#deploy-a-reverse-proxy): Secure your dashboard with password protection and TLS encryption.

13 +*Best for:* Users who monitor their systems through Netdata Cloud dashboards

18 -## Disable the local dashboard

15 +You can secure your nodes by disabling local dashboard access while maintaining Cloud monitoring capabilities. This eliminates public exposure of metrics and system information while maintaining secure metrics viewing through Netdata Cloud via [ACLK](/src/aclk/README.md).

20 -Secure your nodes by disabling local dashboard access while maintaining Cloud monitoring capabilities:

21 -

22 -- Eliminates public exposure of metrics and system information.

23 -- Maintains secure metrics viewing through Netdata Cloud via [ACLK](/src/aclk/README.md).

24 -

25 -Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) script:

17 +Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script:

19 ```text

20 [web]

@@ -31,26 +23,45 @@ Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netda

24 Restart your Agent to apply changes. After restart, the local dashboard (http://NODE:19999) will no longer be accessible, but all metrics remain available through Netdata Cloud.

34 -> **Note**

35 ->

36 -> For Docker deployments, set `NETDATA_HEALTHCHECK_TARGET=cli` in your environment variables.

26 +:::tip

27 +

28 +For Docker deployments, set `NETDATA_HEALTHCHECK_TARGET=cli` in your environment variables.

29 +

30 +:::

31 +

32 +**Use Netdata Parents as Web Application Firewalls**

38 -## Use Netdata Parents as Web Application Firewalls

34 +*Best for:* Production systems requiring layered security and centralized access control

40 -Enhance security by deploying Parent nodes as border gateways, eliminating the need for direct internet access from production Agents. Parent nodes:

36 +You can enhance security by deploying Parent nodes as border gateways, eliminating the need for direct internet access from production Agents.

42 -- Act as application firewalls.

43 -- Receive metrics from Child Agents securely.

44 -- Serve dashboard requests using local data.

45 -- Maintain Netdata Cloud connectivity through encrypted connection.

38 +Parent nodes provide security by:

39 +

40 +- Acting as application firewalls

41 +- Receiving metrics from Child Agents securely

42 +- Serving dashboard requests using local data

43 +- Maintaining Netdata Cloud connectivity through encrypted connection

44 +

45 +:::info

46 +

47 +This approach isolates production systems from direct internet exposure, even when using Netdata Cloud.

49 For more information, see [Observability Centralization Points](/docs/observability-centralization-points/README.md).

49 -## Restrict dashboard access to private LAN

51 +:::

52 +

53 +### Alternative Methods

54 +

55 +<details>

56 +<summary>Restrict Dashboard Access to Private Networks</summary>

51 -Enhance security by binding the Agent to your organization's private management network interface. This limits dashboard access to your administrative LAN only.

58 +**Best for:** Organizations with private management networks

53 -Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) script:

60 +You can enhance security by binding the Agent to your organization's private management network interface. This limits dashboard access to your administrative LAN only.

61 +

62 +**Configuration:**

63 +

64 +Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script:

66 ```text

67 [web]

@@ -59,25 +70,24 @@ Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netda

71 The Agent supports binding to multiple IPs and ports. When using hostnames, all resolved IPs will be used (for example, `localhost` typically resolves to both `127.0.0.1` and `::1`).

62 -<details><summary>More info for cloud-based installations</summary>

73 +**Cloud Environment Setup:**

75 For cloud environments without private LAN capabilities or multi-cloud deployments, you can create a virtual management network using mesh VPN tools like `tincd` or `gvpe`. These tools enable secure, private communication between servers while allowing administration stations to access management functions across your cloud infrastructure.

66 -For `gvpe` specifically, we maintain a [deployment tool](https://github.com/netdata/netdata-demo-site/tree/master/gvpe) that includes:

77 +For `gvpe` specifically, we maintain a [deployment tool](https://github.com/netdata/netdata-demo-site/tree/master/gvpe) that includes pre-compiled binaries for Linux and FreeBSD, macOS compilation script, and configuration templates. We use this tool to manage our Netdata demo sites across multiple hosting providers.

68 -- Pre-compiled binaries for Linux and FreeBSD.

69 -- macOS compilation script.

70 -- Configuration templates.

79 +</details>

72 -We use this tool to manage our Netdata demo sites across multiple hosting providers.

81 +<details>

82 +<summary>Configure Granular Access Control</summary>

74 -</details>

84 +**Best for:** Specific IP address or hostname-based access requirements

76 -## Configure granular access control

86 +You can restrict access to your local dashboard while maintaining Netdata Cloud connectivity by using [access lists](/src/web/server/README.md#access-lists).

78 -Restrict access to your local dashboard while maintaining Netdata Cloud connectivity by using [access lists](/src/web/server/README.md#access-lists).

88 +**Basic Access Control:**

80 -Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) script.

90 +Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script.

92 Use the `allow connections from` setting to permit specific IP addresses or hostnames:

@@ -95,6 +105,8 @@ Use the `allow connections from` setting to permit specific IP addresses or host

105

106 The default setting `localhost *` allows both localhost and all external connections. You can customize this using Netdata's [simple patterns](/src/libnetdata/simple_pattern/README.md).

107

108 +**Advanced Feature-Specific Controls:**

109 +

110 While `allow connections from` globally controls access to all Netdata services, you can set specific permissions for individual features:

111

112 ```text

@@ -107,18 +119,25 @@ While `allow connections from` globally controls access to all Netdata services,

119 allow management from = localhost

120 ```

121

110 -For additional security:

122 +**Additional Security Options:**

123

112 -- Review detailed access list options in the [Web Server documentation](/src/web/server/README.md#access-lists).

113 -- Consider [enabling SSL](/src/web/server/README.md#enable-httpstls-support) to encrypt local dashboard traffic (Netdata Cloud connections are always TLS-encrypted).

124 +- Review detailed access list options in the [Web Server documentation](/src/web/server/README.md#access-lists)

125 +- Consider [enabling SSL](/src/web/server/README.md#examples) to encrypt local dashboard traffic (Netdata Cloud connections are always TLS-encrypted)

126

115 -## Deploy a reverse proxy

127 +</details>

128 +

129 +<details>

130 +<summary>Deploy a Reverse Proxy</summary>

131 +

132 +**Best for:** Multi-agent environments requiring unified authentication and SSL termination

133

117 -Secure multiple Agents using a single authenticating web server as a reverse proxy. This provides:

134 +You can secure multiple Agents using a single authenticating web server as a reverse proxy. This provides:

135

119 -- Unified access through URLs like `http://{HOST}/netdata/{NETDATA_HOSTNAME}/`.

120 -- Single sign-on across all Agents.

121 -- Optional TLS encryption.

136 +- Unified access through URLs like `http://{HOST}/netdata/{NETDATA_HOSTNAME}/`

137 +- Single sign-on across all Agents

138 +- Optional TLS encryption

139 +

140 +**Supported Web Servers:**

141

142 We provide detailed configuration guides for popular web servers:

143

@@ -128,3 +147,5 @@ We provide detailed configuration guides for popular web servers:

147 - [Lighttpd](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-lighttpd.md)

148 - [Caddy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-caddy.md)

149 - [H2O](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-h2o.md)

150 +

151 +</details>

\ No newline at end of file

src/daemon/config/README.md

+86 -50

@@ -1,39 +1,52 @@

1 # Daemon Configuration Reference

3 -The Netdata daemon's main configuration file is located at `/INSTALL_PREFIX/netdata/netdata.conf`. While Netdata works effectively with default settings, this file allows you to fine-tune its behavior.

3 +You can fine-tune your Netdata daemon's behavior using the main configuration file located at `/INSTALL_PREFIX/netdata/netdata.conf`. While Netdata works effectively with default settings, this file allows you to fine-tune its behavior.

4 +

5 +:::note

7 You can view your current configuration, including default values, at `http://IP:19999/netdata.conf`. Access to this URL is [restricted to local IPs by default](/src/web/server/README.md#access-lists).

7 -The configuration file uses an INI-style format with `[SECTION]` headers:

9 +:::

10 +

11 +:::info

12 +

13 +The configuration file uses an INI-style format with `[SECTION]` headers and a simple `name = value` format. Netdata tolerates unknown options, marking them with comments when you view the running configuration through `/netdata.conf`.

14 +

15 +:::

16 +

17 +## Configuration Sections Overview

9 -| Section | Controls |

10 -|-------------------------------------------------------------------|----------------------------------------------------------|

11 -| [[global]](#global-section-options) | [Daemon](/src/daemon/README.md) |

12 -| [[db]](#db-section-options) | [Database](/src/database/README.md) |

13 -| [[directories]](#directories-section-options) | Directories used by Netdata |

14 -| [[logs]](#logs-section-options) | Logging |

15 -| [[environment variables]](#environment-variables-section-options) | Environment variables |

16 -| [[sqlite]](#sqlite-section-options) | SQLite |

17 -| `[ml]` | [Machine Learning](/src/ml/README.md) |

18 -| [[health]](#health-section-options) | [Health monitoring](/src/health/README.md) |

19 -| `[web]` | [Web Server](/src/web/server/README.md) |

20 -| `[registry]` | [Registry](/src/registry/README.md) |

21 -| `[telemetry]` | Internal monitoring |

22 -| `[statsd]` | [StatsD plugin](/src/collectors/statsd.plugin/README.md) |

23 -| [`[plugins]`](#plugins-section-options) | Data collection Plugins (Collectors) |

24 -| [[plugin:NAME]](#per-plugin-configuration) | Individual [Plugins](#per-plugin-configuration) |

19 +Your configuration file contains these main sections:

26 -> **Note**

27 ->

28 -> The configuration uses a simple `name = value` format. Netdata tolerates unknown options, marking them with comments when viewing the running configuration through `/netdata.conf`.

21 +| Section | Controls |

22 +|-------------------------------------------------------------|----------------------------------------------------------|

23 +| [`[global]`](#configuration-section-details) | [Daemon](/src/daemon/README.md) |

24 +| [`[db]`](#configuration-section-details) | [Database](/src/database/README.md) |

25 +| [`[directories]`](#configuration-section-details) | Directories used by Netdata |

26 +| [`[logs]`](#configuration-section-details) | Logging |

27 +| [`[environment variables]`](#configuration-section-details) | Environment variables |

28 +| [`[sqlite]`](#configuration-section-details) | SQLite |

29 +| `[ml]` | [Machine Learning](/src/ml/README.md) |

30 +| [`[health]`](#configuration-section-details) | [Health monitoring](/src/health/README.md) |

31 +| `[web]` | [Web Server](/src/web/server/README.md) |

32 +| `[registry]` | [Registry](/src/registry/README.md) |

33 +| `[telemetry]` | Internal monitoring |

34 +| `[statsd]` | [StatsD plugin](/src/collectors/statsd.plugin/README.md) |

35 +| `[plugins]` | Data collection Plugins (Collectors) |

36 +| [`[plugin:NAME]`](#per-plugin-configuration) | Individual [Plugins](#per-plugin-configuration) |

30 -## Applying changes

38 +## Apply Configuration Changes

32 -After `netdata.conf` has been modified, Netdata needs to be [restarted](/docs/netdata-agent/start-stop-restart.md) for changes to apply.

40 +:::note

34 -## Configuration Sections

42 +After you modify `netdata.conf`, you need to [restart Netdata](/docs/netdata-agent/start-stop-restart.md) for your changes to take effect.

36 -### `global` section options

44 +:::

45 +

46 +## Configuration Section Details

47 +

48 +<details>

49 +<summary>Global Section Options</summary>

51 | setting | default | info |

52 |:----------------------------------:|:--------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

@@ -49,11 +62,11 @@ After `netdata.conf` has been modified, Netdata needs to be [restarted](/docs/ne

62 | pthread stack size | auto-detected | |

63 | crash reports | `all` or `off` | `all` when anonymous telemetry is enabled, or the agent is claimed or connected to Netdata Cloud (directly or via a Netdata Parent). When it is `all` Netdata reports restarts and crashes. It can also be `crashes` to report only crashes. When it is `off` nothing is reported. Each kind of event is deduplicated and reported at most once per day. [Read more at this blog post](https://www.netdata.cloud/blog/2025-03-06-monitoring-netdata-restarts/). |

52 -#### Profiles

65 +### Profiles

67 The profiles are detected in this order:

56 -1. `iot` is used when the system has 1 CPU core and/or less than 1GiB of RAM. It has the highest priority among all the profiles, so that if this is detected, it will be used instead of any of the others.

69 +1. `iot` is used when the system has 1 CPU core and/or less than 1GiB of RAM. It has the highest priority among all the profiles, so that if this is detected, it will be used instead of the others.

70 2. `parent` is detected when `stream.conf` has configuration for receiving data from child nodes and the system is not `iot`.

71 3. `child` is detected when `stream.conf` has configuration for sending data to a parent node, does not have configuration for receiving data from other nodes, and the system is not `iot`.

72 4. `standalone` is the fallback profile when none of the above are detected.

@@ -71,7 +84,10 @@ The following are the parameters affected by the profile:

85 A few of these settings can be individually configured in `netdata.conf`, like the libc allocation arenas and machine learning. The rest are automatically set based on the profile.

74 -### `db` section options

87 +</details>

88 +

89 +<details>

90 +<summary>Database Section Options</summary>

92 | setting | default | info |

93 |:---------------------------------------------:|:------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

@@ -90,11 +106,14 @@ A few of these settings can be individually configured in `netdata.conf`, like t

106 | cleanup orphan hosts after | `1h` | How long to wait until automatically removing from the DB a remote Netdata host (child) that is no longer sending data. |

107 | enable zero metrics | `no` | Set to `yes` to show charts when all their metrics are zero. |

108

93 -> ### Info

94 ->

95 -> The multiplication of all the **enabled** tiers `dbengine tier N update every iterations` values must be less than `65535`.

109 +:::info Storage Tiers

110 +The multiplication of all the **enabled** tiers `dbengine tier N update every iterations` values must be less than `65535`.

111 +:::

112

97 -### `directories` section options

113 +</details>

114 +

115 +<details>

116 +<summary>Directories Section Options</summary>

117

118 | setting | default | info |

119 |:-------------------:|:------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

@@ -111,7 +130,10 @@ A few of these settings can be individually configured in `netdata.conf`, like t

130 | stock Health config | `/usr/lib/netdata/conf.d/health.d` | Contains the stock Alert configuration files for each collector |

131 | registry | `/opt/netdata/var/lib/netdata/registry` | Contains the [registry](/src/registry/README.md) database and GUID that uniquely identifies each Netdata Agent |

132

114 -### `logs` section options

133 +</details>

134 +

135 +<details>

136 +<summary>Logs Section Options</summary>

137

138 There are additional configuration options for the logs. For more info, see [Netdata Logging](/src/libnetdata/log/README.md).

139

@@ -129,7 +151,10 @@ There are additional configuration options for the logs. For more info, see [Net

151 | logs to trigger flood protection | `1000` | Number of errors written to the log in `errors flood protection period` sec before flood protection is activated. |

152 | level | `info` | Controls which log messages are logged, with error being the most important. Supported values: `info` and `error`. |

153

132 -### `environment variables` section options

154 +</details>

155 +

156 +<details>

157 +<summary>Environment Variables Section Options</summary>

158

159 | setting | default | info |

160 |:----------:|:-----------------:|:-----------------------------------------------------------|

@@ -137,7 +162,10 @@ There are additional configuration options for the logs. For more info, see [Net

162 | PATH | `auto-detected` | Specifies the directories to be searched to find a command |

163 | PYTHONPATH | | Used to set a custom python path |

164

140 -### `sqlite` section options

165 +</details>

166 +

167 +<details>

168 +<summary>SQLite Section Options</summary>

169

170 | setting | default | info |

171 |:------------------:|:-------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

@@ -148,12 +176,14 @@ There are additional configuration options for the logs. For more info, see [Net

176 | journal size limit | `16777216` | Used to set a new [limit in bytes for the database](https://www.sqlite.org/pragma.html#pragma_journal_size_limit) |

177 | cache size | `-2000` | Used to [suggest the maximum number of database disk pages](https://www.sqlite.org/pragma.html#pragma_cache_size) that SQLite will hold in memory at once per open database file |

178

151 -### `health` section options

179 +</details>

180 +

181 +<details>

182 +<summary>Health Section Options</summary>

183

184 This section controls the general behavior of the Health monitoring capabilities of Netdata.

185

155 -Specific Alerts are configured in per-collector config files under the `health.d` directory. For more info, see [health

156 -monitoring](/src/health/README.md).

186 +Specific Alerts are configured in per-collector config files under the `health.d` directory. For more info, see [health monitoring](/src/health/README.md).

187

188 [Alert notifications](/src/health/notifications/README.md) are configured in `health_alarm_notify.conf`.

189

@@ -167,11 +197,10 @@ monitoring](/src/health/README.md).

197 | Health log retention | `5d` | Specifies the history of Alert events (in seconds) kept in the Agent's sqlite database. |

198 | enabled alarms | * | Defines which Alerts to load from both user and stock directories. This is a [simple pattern](/src/libnetdata/simple_pattern/README.md) list of Alert or template names. Can be used to disable specific Alerts. For example, `enabled alarms = !oom_kill *` will load all Alerts except `oom_kill`. |

199

170 -### `web` section options

200 +</details>

201

172 -Refer to the [web server documentation](/src/web/server/README.md)

173 -

174 -### `plugins` section options

202 +<details>

203 +<summary>Plugins Section Options</summary>

204

205 In this section you will see be a boolean (`yes`/`no`) option for each plugin (e.g., tc, cgroups, apps, proc etc.). Note that the configuration options in this section for the orchestrator plugins `python.d` and `charts.d` control **all the modules** written for that orchestrator. For instance, setting `python.d = no` means that all Python modules under `collectors/python.d.plugin` will be disabled.

206

@@ -183,22 +212,29 @@ Additionally, there will be the following options:

212 | check for new plugins every | 60 | The time in seconds to check for new plugins in the plugins directory. This allows having other applications dynamically creating plugins for Netdata. |

213 | checks | `no` | This is a debugging plugin for the internal latency |

214

186 -### `registry` section options

187 -

188 -To understand what this section is and how it should be configured, refer to the [registry documentation](/src/registry/README.md).

215 +</details>

216

190 -## Per-plugin configuration

217 +## Per-Plugin Configuration

218

219 The configuration options for plugins appear in sections following the pattern `[plugin:NAME]`.

220

194 -### Internal plugins

221 +### Internal Plugins

222

223 Most internal plugins will provide additional options. Check [Internal Plugins](/src/collectors/README.md) for more information.

224

198 -Note that by default, Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they are constantly zero, they are ignored. Metrics that will start having values, after Netdata is started, will be detected and charts will be automatically added to the dashboard when refreshed. Use `yes` instead of `auto` in plugin configuration sections to enable these charts permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics

199 -for all internal Netdata plugins.

225 +:::note

226 +

227 +By default, Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they are constantly zero, they are ignored. Metrics that will start having values, after Netdata is started, will be detected and charts will be automatically added to the dashboard when refreshed.

228 +

229 +:::

230 +

231 +:::tip

232 +

233 +Use `yes` instead of `auto` in plugin configuration sections to enable these charts permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all internal Netdata plugins.

234 +

235 +:::

236

201 -### External plugins

237 +### External Plugins

238

239 External plugins will have only two options at `netdata.conf`:

240

src/database/CONFIGURATION.md

+26 -19

@@ -1,10 +1,10 @@

1 # Database Configuration Reference

3 -This document provides details on configuring the Agent's Database. For a deeper understanding of the Database components, see the [Database overview](/src/database/README.md).

3 +You can configure the Agent's Database through the database settings. For a deeper understanding of the Database components, see the [Database overview](/src/database/README.md).

5 ## Modes

7 -Use [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) to open `netdata.conf` and set your preferred mode:

7 +Use [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to open `netdata.conf` and set your preferred mode:

9 ```text

10 [db]

@@ -16,9 +16,11 @@ Use [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configura

17 ### Retention Settings

19 -> **Important**

20 ->

21 -> In a Parent-Child setup, these settings manage the entire storage space used by the Parent for storing metrics collected both by itself and its Children.

19 +:::note

20 +

21 +In a Parent-Child setup, these settings manage the entire storage space used by the Parent for storing metrics collected both by itself and its Children.

22 +

23 +:::

25 You can fine-tune retention for each tier by setting a time limit or size limit. Setting a limit to 0 disables it. This enables the following retention strategies:

@@ -28,7 +30,7 @@ You can fine-tune retention for each tier by setting a time limit or size limit.

30 | Time Limit = 0, Size Limit > 0 | **Space based:** data is stored with a disk space limit, regardless of time |

31 | Time Limit > 0, Size Limit > 0 | **Combined time and space limits:** data is deleted once it reaches either the time limit or the disk space limit, whichever comes first |

31 -You can change these limits using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) to open `netdata.conf`:

33 +You can change these limits using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to open `netdata.conf`:

35 ```text

36 [db]

@@ -48,12 +50,12 @@ You can change these limits using [`edit-config`](/docs/netdata-agent/configurat

50 dbengine tier 2 retention time = 2y

51 ```

51 -### Legacy configuration

53 +### Legacy Configuration

53 -<details><summary>v1.99.0 and prior</summary>

55 +<details>

56 +<summary>v1.99.0 and prior</summary>

55 -Netdata prior to v2 supports the following configuration options in `netdata.conf`.

56 -They have the same defaults as the latest v2, but the unit of each value is given in the option name, not at the value.

58 +Netdata prior to v2 supports the following configuration options in `netdata.conf`. They have the same defaults as the latest v2, but the unit of each value is given in the option name, not at the value.

60 ```text

61 storage tiers = 3

@@ -70,17 +72,18 @@ dbengine tier 2 retention days = 730

73 </details>

73 -<details><summary>v1.45.6 and prior</summary>

75 +<details>

76 +<summary>v1.45.6 and prior</summary>

78 Netdata versions prior to v1.46.0 relied on disk space-based retention.

77 -**Default Retention Limits**:

80 +**Default Retention Limits:**

79 -| Tier | Resolution | Size Limit |

80 -|:----:|:-------------------:|:----------:|

81 -| 0 | high (per second) | 256 MB |

82 -| 1 | middle (per minute) | 128 MB |

83 -| 2 | low (per hour) | 64 GiB |

82 +| Tier | Resolution | Size Limit |

83 +|------|---------------------|------------|

84 +| 0 | high (per second) | 256 MB |

85 +| 1 | middle (per minute) | 128 MB |

86 +| 2 | low (per hour) | 64 GiB |

88 You can change these limits in `netdata.conf`:

@@ -98,11 +101,15 @@ You can change these limits in `netdata.conf`:

101

102 </details>

103

101 -## Cache sizes

104 +## Cache Sizes

105

103 -There are two cache sizes that can be configured in `netdata.conf` to better optimize the Database:

106 +There are two cache sizes that you can configure in `netdata.conf` to better optimize the Database:

107

108 1. `[db].dbengine page cache size`: controls the size of the cache that keeps metric data on memory.

109 2. `[db].dbengine extent cache size`: controls the size of the cache that keeps in memory compressed data blocks.

110

111 +:::info

112 +

113 Both of them are dynamically adjusted to use some of the total memory computed above. The configuration in `netdata.conf` allows providing additional memory to them, increasing their caching efficiency.

114 +

115 +:::

src/registry/CONFIGURATION.md

+39 -21

@@ -1,14 +1,20 @@

1 # Registry Configuration Reference

3 -Netdata uses a **central Registry**. Together with certain browser features, it allows Netdata to provide unified cross-server dashboards. Read more about it in the [overview page](/src/registry/README.md).

3 +You can configure Netdata's **central Registry** to provide unified cross-server dashboards. Together with certain browser features, it allows Netdata to provide these dashboards. The Registry operates with [minimal data transfer](/src/registry/README.md#communication-with-the-registry), with all communication occurring directly between your web browser and the Registry.

5 -The Registry operates with [minimal data transfer](/src/registry/README.md#communication-with-the-registry), with all communication occurring directly between your web browser and the Registry.

5 +:::info

6 +

7 +Read more about it in the [Registry overview](/src/registry/README.md).

8 +

9 +:::

11 ## Configure a Custom Registry

13 Any Netdata Agent can function as a Registry.

11 -1. To set up your own Registry node, modify `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config):

15 +**Set up your Registry node:**

16 +

17 +1. Modify `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files):

19 ```text

20 [registry]

@@ -17,7 +23,8 @@ Any Netdata Agent can function as a Registry.

23 ```

25 2. [Restart the Agent](/docs/netdata-agent/start-stop-restart.md) for the changes to take effect.

20 -3. Next, configure all other Agents to use your custom Registry instead of the default one. For each Agent, modify `netdata.conf`:

26 +

27 +3. Configure all other Agents to use your custom Registry instead of the default one. For each Agent, modify `netdata.conf`:

29 ```text

30 [registry]

@@ -41,33 +48,33 @@ You can restrict Registry access to specific IP addresses or hostnames using [si

48 allow from = *

49 ```

44 -> **Info**

45 ->

46 -> For example, `allow from = !10.1.2.3 10.*` allows all IPs in the `10.*` range except `10.1.2.3`.

51 +:::tip

48 -**Access Control Considerations**

53 +For example, `allow from = !10.1.2.3 10.*` allows all IPs in the `10.*` range except `10.1.2.3`.

54 +

55 +:::

56 +

57 +### Access Control Considerations

59 - Registry access rules work in conjunction with the main API access control (`[web].allow connections from`). IPs must be allowed by both settings to access the Registry.

60 - Patterns can match against IP addresses or host FQDNs. For hostname matching, the system performs both reverse and forward DNS lookups to prevent DNS spoofing.

53 -**DNS Resolution Settings**

62 +### DNS Resolution Settings

55 -DNS resolution for pattern matching can impact performance on systems handling many connections. Control this behavior using:

64 +DNS resolution for pattern matching can impact performance on systems handling many connections. You can control this behavior using:

66 ```text

67 [registry]

68 allow by dns = heuristic

69 ```

62 -Available options:

63 -

64 -| Option | Description |

65 -|:-----------:|--------------------------------------------------------------------------------------------------|

66 -| `yes` | Enables hostname pattern matching using DNS |

67 -| `no` | Restricts patterns to match IP addresses only |

71 +| Option | Description |

72 +|-------------|--------------------------------------------------------------------------------------------------|

73 +| `yes` | Enables hostname pattern matching using DNS |

74 +| `no` | Restricts patterns to match IP addresses only |

75 | `heuristic` | Automatically determines whether to use DNS based on pattern syntax (presence of `:` or letters) |

70 -## Registry database location

77 +## Registry Database Location

79 The Registry maintains its data in two text-based database files located at `/var/lib/netdata/registry/`.

@@ -80,24 +87,35 @@ The Registry maintains its data in two text-based database files located at `/va

88 By default, the Netdata Agent's web server sets `SameSite=none` and `Secure` attributes for its cookies. If these security settings interfere with accessing your Agent dashboard or Netdata Cloud, you can disable them.

83 -To modify cookie settings, edit `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config):

90 +To modify cookie settings, edit `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files):

92 ```text

93 [registry]

94 enable cookies SameSite and Secure = no

95 ```

97 +:::warning

98 +

99 Disabling these security attributes may affect browser compatibility and security. Only disable them if you're experiencing specific access issues.

100

92 -## Troubleshooting the Registry

101 +:::

102 +

103 +## Troubleshoot Registry Issues

104 +

105 +### Verify Registry Configuration

106

107 The Registry URL must point to a valid Netdata dashboard where the Registry is enabled (`[registry].enabled = yes`). You can verify your Registry configuration by accessing its URL directly in your web browser—it should display the dashboard of the Netdata Agent running the Registry.

108 +

109 +### Cookie Requirements

110 +

111 The Registry relies on third-party cookies to function properly. The Registry sets these cookies while you're viewing dashboards from other Netdata Agents.

112

113 When a new browser first connects, the Registry performs a cookie compatibility check through the following process:

114

99 -- Set a test cookie.

100 -- Redirect the browser back to verify the cookie.

115 +- Set a test cookie

116 +- Redirect the browser back to verify the cookie

117 +

118 +### Debug Connection Problems

119

120 If cookies are disabled or blocked, this process fails after several redirects with an error similar to:

121

src/web/server/README.md

+128 -111

@@ -1,93 +1,115 @@

1 -# Web Server

1 +# Web Server Configuration Reference

3 -The Netdata Web Server is `static-threaded`, with a fixed, configurable number of threads.

3 +You can configure Netdata's built-in web server to control how it serves dashboards, handles connections, and manages security. The web server is `static-threaded`, with a fixed, configurable number of threads.

4 +

5 +## Understanding the Web Server Architecture

7 All the threads are concurrently listening for web requests on the same sockets, and the kernel distributes the incoming requests to them. Each thread uses non-blocking I/O so it can serve any number of web requests in parallel.

9 It respects the `keep-alive` HTTP header to serve multiple HTTP requests via the same connection.

9 -## Configuration

10 -

11 -Edit `netdata.conf` using the [`edit-config` script](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config)

12 -

13 -Scroll down to the `[web]` section to find the following settings.

14 -

15 -## Settings

16 -

17 -| Setting | Default | Description |

18 -|:-----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

19 -| `ssl key` | `/etc/netdata/ssl/key.pem` | Declare the location of an SSL key to enable HTTPS. |

20 -| `ssl certificate` | `/etc/netdata/ssl/cert.pem` | Declare the location of an SSL certificate to enable HTTPS. |

21 -| `tls version` | `1.3` | Choose which TLS version to use. While all versions are allowed (`1` or `1.0`, `1.1`, `1.2` and `1.3`), we recommend `1.3` for the most secure encryption. If left blank, Netdata uses the highest available protocol version on your system. |

22 -| `tls ciphers` | `none` | Choose which TLS cipher to use. Options include `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, and `TLS_AES_128_GCM_SHA256`. If left blank, Netdata uses the default cipher list for that protocol provided by your TLS implementation. |

23 -| `ses max window` | `15` | See [single exponential smoothing](/src/web/api/queries/ses/README.md). |

24 -| `des max window` | `15` | See [double exponential smoothing](/src/web/api/queries/des/README.md). |

25 -| `mode` | `static-threaded` | Turns on (`static-threaded`) or off (`none`) the static-threaded Web Server. See the [example](#disable-the-web-server) to turn off the Web Server and disable the dashboard. |

26 -| `listen backlog` | `4096` | The port backlog. Check `man 2 listen`. |

27 -| `default port` | `19999` | The listen port for the static Web Server. |

28 -| `web files owner` | `netdata` | The user that owns the web static files. Netdata will refuse to serve a file that is not owned by this user, even if it has read access to that file. If the user given is not found, Netdata will only serve files owned by user given in `run as user`. |

29 -| `web files group` | `netdata` | If this is set, Netdata will check if the file is owned by this group and refuse to serve the file if it's not. |

30 -| `disconnect idle clients after` | `1m` | The time in seconds to disconnect web clients after being totally idle. |

31 -| `timeout for first request` | `1m` | How long to wait for a client to send a request before closing the socket. Prevents slow request attacks. |

32 -| `accept a streaming request every` | `off` | Can be used to set a limit on how often a Parent will accept streaming requests from Children in a [streaming and replication setup](/src/streaming/README.md). |

33 -| `respect do not track policy` | `no` | If set to `yes`, Netdata will respect the user's browser preferences for [Do Not Track](https://www.eff.org/issues/do-not-track) (DNT) and storing cookies. If DNT is _enabled_ in the browser, and this option is set to `yes`, nodes will not connect to any [registry](/src/registry/README.md). For certain browsers, users must disable DNT and change this option to `yes` for full functionality. |

34 -| `x-frame-options response header` | `` | Avoid [clickjacking attacks](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options), by ensuring that the content is not embedded into other sites. |

35 -| `allow connections from` | `localhost *` | Declare which IP addresses or full-qualified domain names (FQDNs) are allowed to connect to the Web Server, including the [dashboard](/docs/dashboards-and-charts/README.md) or [HTTP API](/src/web/api/README.md). This is a global setting with higher priority to any of the ones below. |

36 -| `allow connections by dns` | `heuristic` | See the [access list section](#access-lists) for details on using `allow` settings. |

37 -| `allow dashboard from` | `localhost *` | |

38 -| `allow dashboard by dns` | `heuristic` | |

39 -| `allow badges from` | `*` | |

40 -| `allow badges by dns` | `heuristic` | |

41 -| `allow streaming from` | `*` | |

42 -| `allow streaming by dns` | `heuristic` | |

43 -| `allow netdata.conf` | `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.* UNKNOWN` | |

44 -| `allow netdata.conf by dns` | `no` | |

45 -| `allow management from` | `localhost` | |

46 -| `allow management by dns` | `heuristic` | |

47 -| `enable gzip compression` | `yes` | When set to `yes`, Netdata web responses will be GZIP compressed, if the web client accepts such responses. |

48 -| `gzip compression strategy` | `default` | Valid settings are `default`, `filtered`, `huffman only`, `rle` and `fixed`. |

49 -| `gzip compression level` | `3` | Valid settings are 1 (fastest) to 9 (best ratio). |

50 -| `web server threads` | `` | How many processor threads the web server is allowed. The default is system-specific, the minimum of `6` or the number of CPU cores. |

51 -| `web server max sockets` | `` | Available sockets. The default is system-specific, automatically adjusted to 50% of the max number of open files Netdata is allowed to use (via `/etc/security/limits.conf` or systemd), to allow enough file descriptors to be available for data collection. |

52 -| `custom dashboard_info.js` | `` | Specifies the location of a custom `dashboard.js` file. See [customizing the standard dashboard](/docs/developer-and-contributor-corner/customize.md#customize-the-standard-dashboard) for details. |

53 -

54 -## Access lists

55 -

56 -Netdata supports access lists in `netdata.conf`:

11 +## Configure Basic Settings

12 +

13 +You can modify web server behavior by editing the `[web]` section in `netdata.conf` using the [`edit-config` script](/docs/netdata-agent/configuration/README.md#edit-configuration-files).

14 +

15 +### Configuration Options

16 +

17 +| Setting | Default | Description |

18 +|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

19 +| `ssl key` | `/etc/netdata/ssl/key.pem` | Declare the location of an SSL key to enable HTTPS |

20 +| `ssl certificate` | `/etc/netdata/ssl/cert.pem` | Declare the location of an SSL certificate to enable HTTPS |

21 +| `tls version` | `1.3` | Choose which TLS version to use. While all versions are allowed (`1` or `1.0`, `1.1`, `1.2` and `1.3`), we recommend `1.3` for the most secure encryption. If left blank, Netdata uses the highest available protocol version on your system |

22 +| `tls ciphers` | `none` | Choose which TLS cipher to use. Options include `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, and `TLS_AES_128_GCM_SHA256`. If left blank, Netdata uses the default cipher list for that protocol provided by your TLS implementation |

23 +| `ses max window` | `15` | See [single exponential smoothing](/src/web/api/queries/ses/README.md) |

24 +| `des max window` | `15` | See [double exponential smoothing](/src/web/api/queries/des/README.md) |

25 +| `mode` | `static-threaded` | Turns on (`static-threaded`) or off (`none`) the static-threaded Web Server. See the [example](#examples) to turn off the Web Server and disable the dashboard |

26 +| `listen backlog` | `4096` | The port backlog. Check `man 2 listen` |

27 +| `default port` | `19999` | The listen port for the static Web Server |

28 +| `web files owner` | `netdata` | The user that owns the web static files. Netdata will refuse to serve a file that is not owned by this user, even if it has read access to that file. If the user given is not found, Netdata will only serve files owned by user given in `run as user` |

29 +| `web files group` | `netdata` | If this is set, Netdata will check if the file is owned by this group and refuse to serve the file if it's not |

30 +| `disconnect idle clients after` | `1m` | The time in seconds to disconnect web clients after being totally idle |

31 +| `timeout for first request` | `1m` | How long to wait for a client to send a request before closing the socket. Prevents slow request attacks |

32 +| `accept a streaming request every` | `off` | Can be used to set a limit on how often a Parent will accept streaming requests from Children in a [streaming and replication setup](/src/streaming/README.md) |

33 +| `respect do not track policy` | `no` | If set to `yes`, Netdata will respect the user's browser preferences for [Do Not Track](https://www.eff.org/issues/do-not-track) (DNT) and storing cookies. If DNT is _enabled_ in the browser, and this option is set to `yes`, nodes will not connect to any [registry](/src/registry/README.md). For certain browsers, users must disable DNT and change this option to `yes` for full functionality |

34 +| `x-frame-options response header` | empty | Avoid [clickjacking attacks](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options), by ensuring that the content is not embedded into other sites |

35 +| `allow connections from` | `localhost *` | Declare which IP addresses or full-qualified domain names (FQDNs) are allowed to connect to the Web Server, including the [dashboard](/docs/dashboards-and-charts/README.md) or [HTTP API](/src/web/api/README.md). This is a global setting with higher priority to any of the ones below |

36 +| `allow connections by dns` | `heuristic` | See the [access list section](#access-lists) for details on using `allow` settings |

37 +| `allow dashboard from` | `localhost *` | Controls dashboard and API access |

38 +| `allow dashboard by dns` | `heuristic` | DNS resolution setting for dashboard access |

39 +| `allow badges from` | `*` | Controls badge API access |

40 +| `allow badges by dns` | `heuristic` | DNS resolution setting for badge access |

41 +| `allow streaming from` | `*` | Controls metric streaming from child agents |

42 +| `allow streaming by dns` | `heuristic` | DNS resolution setting for streaming access |

43 +| `allow netdata.conf` | `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.* UNKNOWN` | Controls access to configuration endpoint |

44 +| `allow netdata.conf by dns` | `no` | DNS resolution setting for netdata.conf access |

45 +| `allow management from` | `localhost` | Controls management API access |

46 +| `allow management by dns` | `heuristic` | DNS resolution setting for management access |

47 +| `enable gzip compression` | `yes` | When set to `yes`, Netdata web responses will be GZIP compressed, if the web client accepts such responses |

48 +| `gzip compression strategy` | `default` | Valid settings are `default`, `filtered`, `huffman only`, `rle` and `fixed` |

49 +| `gzip compression level` | `3` | Valid settings are 1 (fastest) to 9 (best ratio) |

50 +| `web server threads` | auto-detected | How many processor threads the web server is allowed. The default is system-specific, the minimum of `6` or the number of CPU cores |

51 +| `web server max sockets` | auto-detected | Available sockets. The default is system-specific, automatically adjusted to 50% of the max number of open files Netdata is allowed to use (via `/etc/security/limits.conf` or systemd), to allow enough file descriptors to be available for data collection |

52 +| `custom dashboard_info.js` | empty | Specifies the location of a custom `dashboard.js` file. See [customizing the standard dashboard](/docs/developer-and-contributor-corner/customize.md#customize-the-standard-dashboard) for details |

53 +

54 +## Access Lists

55 +

56 +You can control who accesses different Netdata features using access lists in `netdata.conf`. `*` does string matches on the IPs or FQDNs of the clients.

57 +

58 +### Global Access Control (Applied First)

59 +

60 +:::caution Priority Setting

61 +`allow connections from` matches anyone that connects on the Netdata port(s). So, if someone is not allowed, it will be connected and disconnected immediately, without reading even a single byte from its connection. This is a global setting with higher priority to any of the ones below.

62 +:::

64 ```text

65 [web]

66 allow connections from = localhost *

61 - allow dashboard from = localhost *

62 - allow badges from = *

63 - allow streaming from = *

64 - 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.*

65 - allow management from = localhost

67 ```

68 -`*` does string matches on the IPs or FQDNs of the clients.

69 +### Feature-Specific Access Control

70 +

71 +Once a connection is allowed globally, these settings control access to specific features:

70 -- `allow connections from` matches anyone that connects on the Netdata port(s).

71 - So, if someone is not allowed, it will be connected and disconnected immediately, without reading even

72 - a single byte from its connection. This is a global setting with higher priority to any of the ones below.

73 +- **`allow dashboard from`** - receives the request and examines if it is a static dashboard file or an API call the dashboards do.

74 -- `allow dashboard from` receives the request and examines if it is a static dashboard file or an API call the

75 - dashboards do.

75 +- **`allow badges from`** - checks if the API request is for a badge. Badges aren't matched by `allow dashboard from`.

77 -- `allow badges from` checks if the API request is for a badge. Badges aren’t matched by `allow dashboard from`.

77 +- **`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`.

79 -- `allow streaming from` checks if the child willing to stream metrics to this Netdata is allowed.

80 - This can be controlled per API KEY and MACHINE GUID in `stream.conf`.

81 - The setting in `netdata.conf` is checked before the ones in `stream.conf`.

79 +- **`allow netdata.conf from`** - checks the IP to allow `http://netdata.host:19999/netdata.conf`. The IPs listed are all the private IPv4 addresses, including link-local IPv6 addresses. Keep in mind that connections to Netdata API ports are filtered by `allow connections from`. So, IPs allowed by `allow netdata.conf from` should also be allowed by `allow connections from`.

83 -- `allow netdata.conf from` checks the IP to allow `http://netdata.host:19999/netdata.conf`.

84 - The IPs listed are all the private IPv4 addresses, including link-local IPv6 addresses. Keep in mind that connections to Netdata API ports are filtered by `allow connections from`. So, IPs allowed by `allow netdata.conf from` should also be allowed by `allow connections from`.

81 +- **`allow management from`** - checks the IPs to allow API management calls. Management via the API is currently supported for [health](/src/web/api/health/README.md#health-management-api)

86 -- `allow management from` checks the IPs to allow API management calls. Management via the API is currently supported for [health](/src/web/api/health/README.md#health-management-api)

83 +### Common Configuration Examples

84 +

85 +```text

86 +# Allow only local access

87 +[web]

88 + allow connections from = localhost

89 + allow dashboard from = localhost

90 + allow management from = localhost

91 +```

92 +

93 +```text

94 +# Allow private network access

95 +[web]

96 + allow connections from = localhost 10.* 192.168.*

97 + allow dashboard from = localhost 10.* 192.168.*

98 + allow badges from = *

99 + allow streaming from = *

100 + allow management from = localhost

101 +```

102 +

103 +<details>

104 +<summary>Advanced: DNS Resolution Settings</summary>

105

106 To check the FQDN of the connection without opening the Netdata Agent to DNS-spoofing, a reverse-dns record must be setup for the connecting host. At connection time, the reverse-dns of the peer IP address is resolved, and a forward DNS resolution is made to validate the IP address against the name-pattern.

107

90 -Please note that this process can be expensive on a machine that is serving many connections. Each access list has an associated configuration option to turn off DNS-based patterns completely to avoid incurring this cost at run-time:

108 +:::note

109 +

110 +This process can be expensive on a machine that is serving many connections. Each access list has an associated configuration option to turn off DNS-based patterns completely to avoid incurring this cost at run-time:

111 +

112 +:::

113

114 ```text

115 allow connections by dns = heuristic

@@ -100,7 +122,9 @@ Please note that this process can be expensive on a machine that is serving many

122

123 The three possible values for each of these options are `yes`, `no` and `heuristic`. The `heuristic` option disables the check when the pattern only contains IPv4/IPv6 addresses or `localhost`, and enables it when wildcards are present that may match DNS FQDNs.

124

103 -## DDoS protection

125 +</details>

126 +

127 +## DDoS Protection

128

129 If you publish your Netdata web server to the internet, you may want to apply some protection against DDoS:

130

@@ -112,11 +136,10 @@ If you publish your Netdata web server to the internet, you may want to apply so

136

137 ## Examples

138

115 -### Disable the Web Server

116 -

117 -<details><summary>details</summary>

139 +<details>

140 +<summary>Disable the Web Server</summary>

141

119 -Edit `netdata.conf` using the [`edit-config` script](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config)

142 +Edit `netdata.conf` using the [`edit-config` script](/docs/netdata-agent/configuration/README.md#edit-configuration-files)

143

144 ```text

145 [web]

@@ -125,9 +148,8 @@ Edit `netdata.conf` using the [`edit-config` script](/docs/netdata-agent/configu

148

149 </details>

150

128 -### Change the number of threads

129 -

130 -<details><summary>details</summary>

151 +<details>

152 +<summary>Change the Number of Threads</summary>

153

154 Control the number of threads and sockets with the following settings:

155

@@ -139,9 +161,8 @@ Control the number of threads and sockets with the following settings:

161

162 </details>

163

142 -### Binding Netdata to multiple ports

143 -

144 -<details><summary>details</summary>

164 +<details>

165 +<summary>Binding Netdata to Multiple Ports</summary>

166

167 Netdata can bind to multiple IPs and ports, offering access to different services on each. Up to 100 sockets can be used (increase it at compile time with `CFLAGS="-DMAX_LISTEN_FDS=200" ./netdata-installer.sh ...`).

168

@@ -159,7 +180,7 @@ Using the above, Netdata will bind to:

180 - IPv4 10.1.1.1 at port 19998. The management API and `netdata.conf` will be accessible on this port.

181 - All the IPs `hostname` resolves to (both IPv4 and IPv6 depending on the resolved IPs) at port 19997. Only badges will be accessible on this port.

182 - All IPv6 IPs at port 19996. Only metric streaming requests from other Netdata Agents will be accepted on this port. Only encrypted streams will be allowed (i.e., Children also need to be [configured for TLS](/src/streaming/README.md)).

162 -- All the IPs `localhost` resolves to (both IPv4 and IPv6 depending on the resolved IPs) at port 19996. This port will only accept registry API requests.

183 +- All the IPs `localhost` resolves to (both IPv4 and IPv6 depending on the resolved IPs) at port 19995. This port will only accept registry API requests.

184 - All IPv4 and IPv6 IPs at port `http` as set in `/etc/services`. Only the UI (dashboard) and the read API will be accessible on this port.

185 - Unix domain socket `/run/netdata/netdata.sock`. All requests are serviceable on this socket. Note that in some OSs like Fedora, every service sees a different `/tmp`, so don't create a Unix socket under `/tmp`. `/run` or `/var/run` is suggested.

186

@@ -167,8 +188,7 @@ The option `[web].default port` is used when entries in `[web].bind to` do not s

188

189 As shown in the example above, these permissions are optional, with the default permitting all request types on the specified port.

190

170 -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`.

171 -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.

191 +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.

192

193 The API requests are serviced as follows:

194

@@ -178,19 +198,16 @@ The API requests are serviced as follows:

198

199 </details>

200

181 -### Enable HTTPS/TLS support

201 +<details>

202 +<summary>Enable HTTPS/TLS Support</summary>

203

183 -<details><summary>details</summary>

184 -

185 -Since v1.16.0, Netdata supports encrypted HTTP connections to the web server, plus encryption of streaming data to a

186 -parent from its child nodes, via the TLS protocol.

204 +Since v1.16.0, Netdata supports encrypted HTTP connections to the web server, plus encryption of streaming data to a parent from its child nodes, via the TLS protocol.

205

206 Inbound unix socket connections are unaffected, regardless of the TLS settings.

207

190 -> While Netdata uses Transport Layer Security (TLS) 1.2 to encrypt communications rather than the obsolete SSL protocol,

191 -> it's still common practice to refer to encrypted web connections as `SSL`. Many vendors, like Nginx and even Netdata

192 -> itself, use `SSL` in configuration files, whereas documentation will always refer to encrypted communications as `TLS`

193 -> or `TLS/SSL`.

208 +:::tip SSL vs TLS Terminology

209 +While Netdata uses Transport Layer Security (TLS) 1.2 to encrypt communications rather than the obsolete SSL protocol, it's still common practice to refer to encrypted web connections as `SSL`. Many vendors, like Nginx and even Netdata itself, use `SSL` in configuration files, whereas documentation will always refer to encrypted communications as `TLS` or `TLS/SSL`.

210 +:::

211

212 To enable TLS, provide the path to your certificate and private key in the `[web]` section of `netdata.conf`:

213

@@ -200,7 +217,7 @@ To enable TLS, provide the path to your certificate and private key in the `[web

217 ssl certificate = /etc/netdata/ssl/cert.pem

218 ```

219

203 -Both files must be readable by the `netdata` user. If any of these files are missing or can’t be read, Netdata will fall back to using HTTP. For a parent-child connection, only the parent needs these settings.

220 +Both files must be readable by the `netdata` user. If any of these files are missing or can't be read, Netdata will fall back to using HTTP. For a parent-child connection, only the parent needs these settings.

221

222 For test purposes, generate self-signed certificates with the following command:

223

@@ -208,19 +225,19 @@ For test purposes, generate self-signed certificates with the following command:

225 openssl req -newkey rsa:2048 -nodes -sha512 -x509 -days 365 -keyout key.pem -out cert.pem

226 ```

227

211 -> If you use 4096 bits for your key and the certificate, Netdata will need more CPU to process the communication.

212 -> `rsa4096` can be up to four times slower than `rsa2048`, so we recommend using 2048 bits. Verify the difference

213 -> by running:

214 ->

215 -> ```sh

216 -> openssl speed rsa2048 rsa4096

217 -> ```

228 +:::tip Certificate Performance

229 +If you use 4096 bits for your key and the certificate, Netdata will need more CPU to process the communication. `rsa4096` can be up to four times slower than `rsa2048`, so we recommend using 2048 bits. Verify the difference by running:

230

219 -</details>

231 +```bash

232 +openssl speed rsa2048 rsa4096

233 +```

234

221 -### Select TLS version

235 +:::

236

223 -<details><summary>details</summary>

237 +</details>

238 +

239 +<details>

240 +<summary>Select TLS Version</summary>

241

242 Beginning with version `v1.21.0`, specify the TLS version and the ciphers that you want to use:

243

@@ -230,9 +247,9 @@ Beginning with version `v1.21.0`, specify the TLS version and the ciphers that y

247 tls ciphers = TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

248 ```

249

233 -If you don’t specify these options, Netdata will use the highest available protocol version on your system and the default cipher list for that protocol provided by your TLS implementation.

250 +If you don't specify these options, Netdata will use the highest available protocol version on your system and the default cipher list for that protocol provided by your TLS implementation.

251

235 -#### TLS/SSL enforcement

252 +### TLS/SSL Enforcement

253

254 When the certificates are defined and unless any other options are provided, a Netdata server will:

255

@@ -254,7 +271,7 @@ Example:

272 ```

273

257 -For information how to configure the child to use TLS, check [securing the communication](/src/streaming/README.md#securing-streaming-with-tlsssl) in the streaming documentation. There you will find additional details on the expected behavior for client and server nodes, when their respective TLS options are enabled.

274 +For information how to configure the child to use TLS, check [securing the communication](/src/streaming/README.md#secure-communications) in the streaming documentation. There you will find additional details on the expected behavior for client and server nodes, when their respective TLS options are enabled.

275

276 When we define the use of SSL in a Netdata Agent for different ports, Netdata will apply the behavior specified on each port. For example, using the configuration line below:

277

@@ -270,7 +287,7 @@ Netdata will:

287 - Allow both HTTP and HTTPS requests to port 20000 for `netdata.conf`

288 - Force HTTP requests to port 20001 to be redirected to HTTPS (same port). Only allow requests for the dashboard, the read API and the Registry on port 20001.

289

273 -#### TLS/SSL errors

290 +### TLS/SSL Errors

291

292 When you start using Netdata with TLS, you may find errors in the Netdata log, which is stored at `/var/log/netdata/error.log` by default.

293

@@ -278,13 +295,12 @@ Most of the time, these errors are due to incompatibilities between your browser

295

296 </details>

297

281 -### WebSocket Support

282 -

283 -<details><summary>details</summary>

298 +<details>

299 +<summary>WebSocket Support</summary>

300

301 Netdata supports WebSocket connections for real-time data streaming and interactive features. For detailed information on WebSocket protocols, configuration options, and examples, see the [WebSocket documentation](/src/web/websocket/README.md).

302

287 -#### WebSocket Frame Size Configuration

303 +### WebSocket Frame Size Configuration

304

305 Netdata automatically fragments large WebSocket messages to ensure browser compatibility. The default maximum outgoing frame size is 4MB, which works well for most browsers.

306

@@ -297,3 +313,4 @@ ws://localhost:19999/echo?max_frame_size=32768

313 This is particularly useful for resource-constrained devices or network environments with specific limitations.

314

315 </details>

316 +