| 1 | # Securing Netdata Agents |
| 2 | |
| 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`. |
| 4 | |
| 5 | You can protect your Agents by implementing any of these security measures: |
| 6 | |
| 7 | If you need to align Netdata with enterprise cybersecurity platforms such as Sophos, secure-access gateways, or corporate reverse proxies, see [Configure Netdata for cybersecurity platforms](/docs/netdata-agent/configure-netdata-for-cybersecurity-platforms.md). |
| 8 | |
| 9 | ## Security Approaches |
| 10 | |
| 11 | ### Recommended Methods |
| 12 | |
| 13 | **Enable Bearer Token Protection (Netdata Cloud SSO)** |
| 14 | |
| 15 | *Best for:* Users who want direct access to agents secured by Netdata Cloud authentication |
| 16 | |
| 17 | You can secure direct access to your Netdata Agents and Parents with a single configuration setting. Bearer token protection integrates with Netdata Cloud SSO, so users authenticate through Cloud and inherit their Cloud roles and permissions. |
| 18 | |
| 19 | Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script: |
| 20 | |
| 21 | ```text |
| 22 | [web] |
| 23 | bearer token protection = yes |
| 24 | ``` |
| 25 | |
| 26 | After restart, users accessing `http://NODE:19999` will be redirected to Netdata Cloud for authentication. Their Cloud role (Admin, Manager, Troubleshooter, etc.) determines what they can access. |
| 27 | |
| 28 | **Requirements:** |
| 29 | |
| 30 | - Agent must be [claimed to Netdata Cloud](/src/claim/README.md) |
| 31 | - Works with both Community (free) and Business plans |
| 32 | |
| 33 | For detailed configuration options, see [Secure Your Netdata Agent with Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md). |
| 34 | |
| 35 | --- |
| 36 | |
| 37 | **Disable the Local Dashboard** |
| 38 | |
| 39 | *Best for:* Users who monitor their systems through Netdata Cloud dashboards |
| 40 | |
| 41 | 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). |
| 42 | |
| 43 | Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script: |
| 44 | |
| 45 | ```text |
| 46 | [web] |
| 47 | mode = none |
| 48 | ``` |
| 49 | |
| 50 | Restart your Agent to apply changes. After restart, the Agent's web server (default port `19999`) will no longer accept inbound connections. |
| 51 | |
| 52 | :::warning |
| 53 | |
| 54 | This disables inbound connections, including streams from Child Agents. |
| 55 | **Do not use this setting on Parent Agents.** |
| 56 | |
| 57 | ::: |
| 58 | |
| 59 | :::tip |
| 60 | |
| 61 | For Docker deployments, set `NETDATA_HEALTHCHECK_TARGET=cli` in your environment variables. |
| 62 | |
| 63 | ::: |
| 64 | |
| 65 | **Use Netdata Parents as Web Application Firewalls** |
| 66 | |
| 67 | *Best for:* Production systems requiring layered security and centralized access control |
| 68 | |
| 69 | You can enhance security by deploying Parent nodes as border gateways, eliminating the need for direct internet access from production Agents. |
| 70 | |
| 71 | Parent nodes provide security by: |
| 72 | |
| 73 | - Acting as application firewalls |
| 74 | - Receiving metrics from Child Agents securely |
| 75 | - Serving dashboard requests using local data |
| 76 | - Maintaining Netdata Cloud connectivity through encrypted connection |
| 77 | |
| 78 | :::info |
| 79 | |
| 80 | This approach isolates production systems from direct internet exposure, even when using Netdata Cloud. |
| 81 | |
| 82 | For more information, see [Observability Centralization Points](/docs/deployment-guides/deployment-with-centralization-points.md). |
| 83 | |
| 84 | ::: |
| 85 | |
| 86 | ### Alternative Methods |
| 87 | |
| 88 | <details> |
| 89 | <summary><strong>Restrict Dashboard Access to Private Networks</strong></summary> |
| 90 | |
| 91 | **Best for:** Organizations with private management networks |
| 92 | |
| 93 | 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. |
| 94 | |
| 95 | **Configuration:** |
| 96 | |
| 97 | Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script: |
| 98 | |
| 99 | ```text |
| 100 | [web] |
| 101 | bind to = 10.1.1.1:19999 localhost:19999 |
| 102 | ``` |
| 103 | |
| 104 | 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`). |
| 105 | |
| 106 | **Cloud Environment Setup:** |
| 107 | |
| 108 | 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. |
| 109 | |
| 110 | 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. |
| 111 | |
| 112 | </details> |
| 113 | |
| 114 | <details> |
| 115 | <summary><strong>Configure Granular Access Control</strong></summary> |
| 116 | |
| 117 | **Best for:** Specific IP address or hostname-based access requirements |
| 118 | |
| 119 | You can restrict access to your local dashboard while maintaining Netdata Cloud connectivity by using [access lists](/src/web/server/README.md#access-lists). |
| 120 | |
| 121 | **Basic Access Control:** |
| 122 | |
| 123 | Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script. |
| 124 | |
| 125 | Use the `allow connections from` setting to permit specific IP addresses or hostnames: |
| 126 | |
| 127 | ```text |
| 128 | [web] |
| 129 | # Allow only localhost connections |
| 130 | allow connections from = localhost |
| 131 | |
| 132 | # Allow only from management LAN running on `10.X.X.X` |
| 133 | allow connections from = 10.* |
| 134 | |
| 135 | # Allow connections only from a specific FQDN/hostname |
| 136 | allow connections from = example* |
| 137 | ``` |
| 138 | |
| 139 | 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). |
| 140 | |
| 141 | **Advanced Feature-Specific Controls:** |
| 142 | |
| 143 | While `allow connections from` globally controls access to all Netdata services, you can set specific permissions for individual features: |
| 144 | |
| 145 | ```text |
| 146 | [web] |
| 147 | allow connections from = localhost * |
| 148 | allow dashboard from = localhost * |
| 149 | allow badges from = * |
| 150 | allow streaming from = * |
| 151 | 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.* |
| 152 | allow management from = localhost |
| 153 | ``` |
| 154 | |
| 155 | **Additional Security Options:** |
| 156 | |
| 157 | - Review detailed access list options in the [Web Server documentation](/src/web/server/README.md#access-lists) |
| 158 | - Consider [enabling SSL](/src/web/server/README.md#examples) to encrypt local dashboard traffic (Netdata Cloud connections are always TLS-encrypted) |
| 159 | |
| 160 | </details> |
| 161 | |
| 162 | <details> |
| 163 | <summary><strong>Deploy a Reverse Proxy</strong></summary> |
| 164 | |
| 165 | **Best for:** Multi-agent environments requiring unified authentication and SSL termination |
| 166 | |
| 167 | You can secure multiple Agents using a single authenticating web server as a reverse proxy. This provides: |
| 168 | |
| 169 | - Unified access through URLs like `http://{HOST}/netdata/{NETDATA_HOSTNAME}/` |
| 170 | - Single sign-on across all Agents |
| 171 | - Optional TLS encryption |
| 172 | |
| 173 | **Supported Web Servers:** |
| 174 | |
| 175 | We provide detailed configuration guides for popular web servers: |
| 176 | |
| 177 | - [nginx](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-nginx.md) |
| 178 | - [HAProxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md) |
| 179 | - [Apache](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-apache.md) |
| 180 | - [Lighttpd](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-lighttpd.md) |
| 181 | - [Caddy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-caddy.md) |
| 182 | - [H2O](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-h2o.md) |
| 183 | |
| 184 | </details> |