Registry Configuration Reference

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.

The Registry operates with minimal data transfer, with all communication occurring directly between your web browser and the Registry.

Configure a Custom Registry

Any Netdata Agent can function as a Registry.

1. To set up your own Registry node, modify netdata.conf using edit-config:

   [registry]
       enabled = yes
       registry to announce = http://your.registry:19999

2. Restart the Agent for the changes to take effect.

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

   [registry]
      enabled = no
      registry to announce = http://your.registry:19999

4. To improve node identification in your dashboard, you can assign custom names to each Agent (optional):

   [registry]
      registry hostname = Group1 - Master DB

Configure Registry Access Control

You can restrict Registry access to specific IP addresses or hostnames using simple pattern matching:

[registry]
    allow from = *

Info

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

Access Control Considerations

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

DNS Resolution Settings

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

[registry]
    allow by dns = heuristic

Available options:

Option	Description
yes	Enables hostname pattern matching using DNS
no	Restricts patterns to match IP addresses only
heuristic	Automatically determines whether to use DNS based on pattern syntax (presence of : or letters)

Registry database location

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

File	Purpose	Behavior
registry-log.db	Records all real-time Registry operations	Captures every modification to the Registry as it occurs
registry.db	Stores the consolidated Registry data	Updates after every [registry].registry save db every new entries entries in the transaction log, at which point the main database is refreshed and the transaction log is cleared

Configure Cookie Security Settings

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.

To modify cookie settings, edit netdata.conf using edit-config:

[registry]
    enable cookies SameSite and Secure = no

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

Troubleshooting the Registry

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. The Registry relies on third-party cookies to function properly. The Registry sets these cookies while you're viewing dashboards from other Netdata Agents.

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

• Set a test cookie.
• Redirect the browser back to verify the cookie.

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

ERROR 409: Cannot ACCESS netdata registry: https://registry.my-netdata.io responded with: {"status":"redirect","registry":"https://registry.my-netdata.io"}

To view these error messages, open your browser's developer console (typically F12).