@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 126 lines 5.61 KB
Rendered Raw
1 # Registry Configuration Reference
2
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.
4
5 :::info
6
7 Read more about it in the [Registry overview](/src/registry/README.md).
8
9 :::
10
11 ## Configure a Custom Registry
12
13 Any Netdata Agent can function as a Registry.
14
15 **Set up your Registry node:**
16
17 1. Modify `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files):
18
19 ```text
20 [registry]
21 enabled = yes
22 registry to announce = http://your.registry:19999
23 ```
24
25 2. [Restart the Agent](/docs/netdata-agent/start-stop-restart.md) for the changes to take effect.
26
27 3. Configure all other Agents to use your custom Registry instead of the default one. For each Agent, modify `netdata.conf`:
28
29 ```text
30 [registry]
31 enabled = no
32 registry to announce = http://your.registry:19999
33 ```
34
35 4. To improve node identification in your dashboard, you can assign custom names to each Agent (optional):
36
37 ```text
38 [registry]
39 registry hostname = Group1 - Master DB
40 ```
41
42 ## Configure Registry Access Control
43
44 You can restrict Registry access to specific IP addresses or hostnames using [simple pattern](/src/libnetdata/simple_pattern/README.md) matching:
45
46 ```text
47 [registry]
48 allow from = *
49 ```
50
51 :::tip
52
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
58
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.
61
62 ### DNS Resolution Settings
63
64 DNS resolution for pattern matching can impact performance on systems handling many connections. You can control this behavior using:
65
66 ```text
67 [registry]
68 allow by dns = heuristic
69 ```
70
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) |
76
77 ## Registry Database Location
78
79 The Registry maintains its data in two text-based database files located at `/var/lib/netdata/registry/`.
80
81 | File | Purpose | Behavior |
82 |-------------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
83 | `registry-log.db` | Records all real-time Registry operations | Captures every modification to the Registry as it occurs |
84 | `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 |
85
86 ## Configure Cookie Security Settings
87
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.
89
90 To modify cookie settings, edit `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files):
91
92 ```text
93 [registry]
94 enable cookies SameSite and Secure = no
95 ```
96
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
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
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
122 ```text
123 ERROR 409: Cannot ACCESS netdata registry: https://registry.my-netdata.io responded with: {"status":"redirect","registry":"https://registry.my-netdata.io"}
124 ```
125
126 To view these error messages, open your browser's developer console (typically F12).