| 1 | # Node Identities |
| 2 | |
| 3 | :::tip |
| 4 | |
| 5 | **What You'll Learn** |
| 6 | |
| 7 | How Netdata identifies nodes across Agents, Parents, and Cloud - and why each identity type matters for your infrastructure. |
| 8 | |
| 9 | ::: |
| 10 | |
| 11 | ## Node Lifecycle and Ephemerality |
| 12 | |
| 13 | Every node has a **lifecycle** determined by its **ephemerality** setting. By default, all nodes are **permanent** - they are expected to maintain connectivity, and disconnections trigger alerts. |
| 14 | |
| 15 | Ephemeral nodes are designed for dynamic infrastructure: |
| 16 | - No alerts when they disconnect |
| 17 | - Automatic cleanup after configurable timeout |
| 18 | - Perfect for auto-scaling and short-lived workloads |
| 19 | |
| 20 | To change a node's ephemerality, edit `netdata.conf`: |
| 21 | |
| 22 | ```ini |
| 23 | [global] |
| 24 | is ephemeral node = yes # Ephemeral - no alerts, auto-cleanup |
| 25 | is ephemeral node = no # Permanent (default) - alerts on disconnect |
| 26 | ``` |
| 27 | |
| 28 | See [Node Ephemerality](/docs/nodes-ephemerality.md) for detailed configuration options. |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | Netdata uses several identity mechanisms to uniquely identify nodes, authenticate connections, and track metrics across your infrastructure. Understanding these identities is essential when: |
| 33 | |
| 34 | - Creating VM templates or golden images |
| 35 | - Troubleshooting connection issues |
| 36 | - Moving nodes between Spaces |
| 37 | - Setting up Parent-Child streaming |
| 38 | - Configuring virtual nodes for remote monitoring |
| 39 | |
| 40 | ## Agent Self Identity |
| 41 | |
| 42 | Every Netdata Agent has a **Machine GUID** - a UUID that uniquely identifies this specific node. |
| 43 | |
| 44 | | Property | Value | |
| 45 | |----------|-------| |
| 46 | | **File** | `/var/lib/netdata/registry/netdata.public.unique.id` | |
| 47 | | **Format** | UUID (e.g., `a1b2c3d4-e5f6-7890-abcd-ef1234567890`) | |
| 48 | | **Generated** | On first start, if missing | |
| 49 | | **Persistence** | Permanent - never changes once created | |
| 50 | |
| 51 | ### Generation Behavior |
| 52 | |
| 53 | On startup, Netdata determines the Machine GUID: |
| 54 | |
| 55 | 1. Read from primary file (`netdata.public.unique.id`) |
| 56 | 2. If missing/invalid, read from status file backup |
| 57 | 3. If still missing, generate new random UUID |
| 58 | 4. Save to primary file with timestamp |
| 59 | |
| 60 | ### Status File Backups |
| 61 | |
| 62 | The Machine GUID is also stored in status files for crash recovery: |
| 63 | |
| 64 | | Location | Purpose | |
| 65 | |----------|---------| |
| 66 | | `/var/lib/netdata/status-netdata.json` | Primary backup | |
| 67 | | `/var/cache/netdata/status-netdata.json` | Fallback 1 | |
| 68 | | `/tmp/status-netdata.json` | Fallback 2 | |
| 69 | | `/run/status-netdata.json` | Fallback 3 | |
| 70 | | `/var/run/status-netdata.json` | Fallback 4 | |
| 71 | |
| 72 | :::note |
| 73 | |
| 74 | **Redundant Storage** |
| 75 | |
| 76 | The Machine GUID is stored redundantly across multiple locations. If the primary file is missing or corrupted, Netdata automatically recovers the GUID from backup locations. This ensures identity persistence across crashes and unexpected shutdowns. |
| 77 | |
| 78 | ::: |
| 79 | |
| 80 | :::warning |
| 81 | |
| 82 | **GUID Must Be Unique** |
| 83 | |
| 84 | If two Agents have the same Machine GUID: |
| 85 | - They cannot connect to the same Parent simultaneously |
| 86 | - Cloud kicks the older connection offline when the second connects |
| 87 | - This causes unstable "flapping" connections |
| 88 | |
| 89 | See [VM Templates](/docs/learn/vm-templates.md) for how to avoid this when cloning VMs. |
| 90 | |
| 91 | ::: |
| 92 | |
| 93 | ## Parent: Children Identities |
| 94 | |
| 95 | When a Netdata Agent operates as a **Parent** (receiving metrics from Children), it stores metadata about all nodes it has seen. |
| 96 | |
| 97 | | Property | Value | |
| 98 | |--------------|--------------------------------------| |
| 99 | | **Database** | `/var/cache/netdata/netdata-meta.db` | |
| 100 | | **Table** | `node_instance` | |
| 101 | | **Contains** | GUIDs of all Children ever connected | |
| 102 | |
| 103 | ### Relationship Between Metadata and Metrics |
| 104 | |
| 105 | Each metric in Netdata has a UUID. The metadata database (`netdata-meta.db`) links these UUIDs to nodes, charts, and dimensions. The dbengine stores metric samples indexed by these UUIDs. |
| 106 | |
| 107 | | Component | Purpose | |
| 108 | |-----------|---------| |
| 109 | | **Metadata** (`netdata-meta.db`) | Links metric UUIDs to node GUIDs, charts, dimensions | |
| 110 | | **Dbengine** (`dbengine*` directories) | Stores actual metric samples indexed by UUID | |
| 111 | |
| 112 | The metadata acts as an index - without it, metric samples in dbengine cannot be associated with their source nodes or chart definitions. |
| 113 | |
| 114 | ### Key Point: Metadata DB Does Not Determine Agent Identity |
| 115 | |
| 116 | The metadata database stores information about **all nodes** (including the Agent itself), but this data exists only to link nodes with their metrics. The Agent's identity is **not** determined by the database - it comes exclusively from: |
| 117 | - The GUID file |
| 118 | - Status file backups |
| 119 | |
| 120 | ### Multiple Node Identities in Database |
| 121 | |
| 122 | When a database contains metadata for multiple nodes (from Children or [Virtual Nodes](#virtual-nodes-vnodes)), Netdata: |
| 123 | |
| 124 | 1. **Reports all nodes** - All known nodes are reported to Netdata Cloud |
| 125 | 2. **Retention persistence** - Node entries persist in Cloud until database retention expires (can be years with tiering) |
| 126 | |
| 127 | This is normal for Parent nodes receiving data from Children, and for Agents using Virtual Nodes. See [VM Templates](/docs/learn/vm-templates.md) for implications when cloning VMs. |
| 128 | |
| 129 | ## Virtual Nodes (vnodes) |
| 130 | |
| 131 | **Virtual Nodes** allow Go collectors to report metrics as if they came from separate logical nodes. This is useful for monitoring remote systems, containers, or logical entities that don't run their own Netdata Agent (SNMP devices, cloud provider db instances, etc.). |
| 132 | |
| 133 | | Property | Value | |
| 134 | |----------|-------| |
| 135 | | **Directory** | `/etc/netdata/vnodes/` | |
| 136 | | **Format** | YAML files (`.yaml`, `.yml`, `.conf`) | |
| 137 | | **Identity** | User-defined GUID in config file | |
| 138 | |
| 139 | ### Configuration |
| 140 | |
| 141 | Each virtual node is defined in a YAML file: |
| 142 | |
| 143 | ```yaml |
| 144 | - name: my-remote-server |
| 145 | hostname: remote-server.example.com |
| 146 | guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| 147 | labels: |
| 148 | environment: production |
| 149 | datacenter: us-east |
| 150 | ``` |
| 151 | |
| 152 | | Field | Required | Description | |
| 153 | |-------|----------|-------------| |
| 154 | | `hostname` | Yes | Display name shown in dashboards and Cloud | |
| 155 | | `guid` | Yes | UUID that uniquely identifies this virtual node | |
| 156 | | `name` | No | Internal reference name | |
| 157 | | `labels` | No | Key-value pairs for filtering and organization | |
| 158 | |
| 159 | :::warning |
| 160 | |
| 161 | **GUID Uniqueness** |
| 162 | |
| 163 | Each virtual node GUID must be unique across your entire infrastructure. Using the same GUID as another node (real or virtual) causes identity conflicts - the same problems as [duplicate Machine GUIDs](#agent-self-identity). |
| 164 | |
| 165 | ::: |
| 166 | |
| 167 | ### How Virtual Nodes Work |
| 168 | |
| 169 | 1. Go collector reads vnode configuration |
| 170 | 2. Metrics are tagged with the vnode's GUID instead of the Agent's Machine GUID |
| 171 | 3. Cloud sees the vnode as a separate node in your Space |
| 172 | 4. Parent nodes store vnode metadata alongside Children metadata |
| 173 | |
| 174 | Virtual nodes appear in Netdata Cloud as independent nodes, with their own dashboards and alert states. |
| 175 | |
| 176 | ## Cloud: Node Identity |
| 177 | |
| 178 | When an Agent connects to Netdata Cloud, it receives a **Node ID** that links the Machine GUID to your Space. |
| 179 | |
| 180 | | Property | Value | |
| 181 | |----------|-------| |
| 182 | | **Assigned by** | Netdata Cloud | |
| 183 | | **Stored in** | `/var/cache/netdata/netdata-meta.db` (`node_instance` table) | |
| 184 | | **Purpose** | Links Machine GUID to your Cloud Space | |
| 185 | |
| 186 | Machine GUIDs and Cloud Node IDs map 1-to-1. |
| 187 | |
| 188 | ### Node Instances |
| 189 | |
| 190 | A single Machine GUID can have multiple **Node Instances** in Cloud when the same node connects through different Parents. Each Parent-node connection creates a separate node instance. Although, Node Instances are critical in metrics routing decisions and alerts deduplication, they are usually not visible to users. |
| 191 | |
| 192 | ## Agent-Cloud Link (ACLK) Identity |
| 193 | |
| 194 | The **Agent-Cloud Link (ACLK)** uses separate credentials for authentication: |
| 195 | |
| 196 | | File | Purpose | |
| 197 | |------|---------| |
| 198 | | `/var/lib/netdata/cloud.d/cloud.conf` | Cloud configuration, contains `claimed_id` | |
| 199 | | `/var/lib/netdata/cloud.d/private.pem` | RSA private key | |
| 200 | | `/var/lib/netdata/cloud.d/public.pem` | RSA public key | |
| 201 | |
| 202 | ### Claimed ID |
| 203 | |
| 204 | The **Claimed ID** is a random UUID generated during the claiming process. It's separate from the Machine GUID, as it uniquely identifies the link between the Agent and Cloud. |
| 205 | |
| 206 | | Property | Description | |
| 207 | |----------|-------------| |
| 208 | | **Purpose** | Authenticates the ACLK connection to Netdata Cloud | |
| 209 | | **Generated** | During the claiming process | |
| 210 | | **Independence** | Separate from Machine GUID - they can change independently | |
| 211 | | **Regeneration** | A new Claimed ID is generated each time the agent is re-claimed | |
| 212 | |
| 213 | :::note |
| 214 | |
| 215 | **Custom Paths** |
| 216 | |
| 217 | If you customized `[directories]` in `netdata.conf`: |
| 218 | - `lib` setting affects `/var/lib/netdata/` paths |
| 219 | - `cache` setting affects `/var/cache/netdata/` paths |
| 220 | |
| 221 | ::: |
| 222 | |
| 223 | ## FAQ |
| 224 | |
| 225 | <details> |
| 226 | <summary>How do I find my node's Machine GUID?</summary> |
| 227 | |
| 228 | Read the file `/var/lib/netdata/registry/netdata.public.unique.id`. |
| 229 | |
| 230 | </details> |
| 231 | |
| 232 | <details> |
| 233 | <summary>Can I change my node's Machine GUID?</summary> |
| 234 | |
| 235 | Yes, but it will appear as a new node in Netdata Cloud and Netdata Parents. Delete the GUID file and status backups, then restart Netdata. See [VM Templates](/docs/learn/vm-templates.md) for the complete procedure. |
| 236 | |
| 237 | </details> |
| 238 | |
| 239 | <details> |
| 240 | <summary>Why does my node keep going offline/online in Cloud?</summary> |
| 241 | |
| 242 | Two agents likely have the same Machine GUID. This causes "flapping" as Cloud kicks the older connection when the second connects. Each agent needs a unique GUID. |
| 243 | |
| 244 | </details> |
| 245 | |
| 246 | <details> |
| 247 | <summary>What's the difference between Machine GUID, Node ID, and Claimed ID?</summary> |
| 248 | |
| 249 | - **Machine GUID**: Agent-generated, identifies the node itself, never changes |
| 250 | - **Node ID**: Cloud-assigned, links the Machine GUID to your Space |
| 251 | - **Claimed ID**: Agent-generated during claiming, identifies the ACLK connection |
| 252 | |
| 253 | </details> |
| 254 | |
| 255 | <details> |
| 256 | <summary>Do containers need unique GUIDs?</summary> |
| 257 | |
| 258 | Containers with ephemeral storage get unique GUIDs automatically on each start. Containers with persistent volumes at `/var/lib/netdata/` retain their GUID across restarts. |
| 259 | |
| 260 | </details> |
| 261 | |
| 262 | <details> |
| 263 | <summary>Can the same node exist in multiple Spaces?</summary> |
| 264 | |
| 265 | No. A node can only exist in one Space. To move a node to a different Space, unclaim it first, then claim to the new Space. |
| 266 | |
| 267 | </details> |
| 268 | |
| 269 | <details> |
| 270 | <summary>Does ephemerality affect my node's identity?</summary> |
| 271 | |
| 272 | No. **Identity** and **ephemerality** are separate concepts: |
| 273 | |
| 274 | - **Identity** (Machine GUID, Node ID) uniquely identifies the node |
| 275 | - **Ephemerality** determines lifecycle behavior (alerts, cleanup) |
| 276 | |
| 277 | A node can be permanent or ephemeral and still have a unique identity. Changing ephemerality does not change or reset identity. |
| 278 | |
| 279 | </details> |
| 280 | |
| 281 | <details> |
| 282 | <summary>Can I change a node's ephemerality after cloning?</summary> |
| 283 | |
| 284 | Yes. Edit `/etc/netdata/netdata.conf` and restart Netdata: |
| 285 | |
| 286 | ```ini |
| 287 | [global] |
| 288 | is ephemeral node = yes # Enable ephemeral behavior |
| 289 | is ephemeral node = no # Revert to permanent (default) |
| 290 | ``` |
| 291 | |
| 292 | Changes apply immediately. Ephemerality is stored as a host label and propagates to Parents and Netdata Cloud. |
| 293 | |
| 294 | </details> |
| 295 | |
| 296 | <details> |
| 297 | <summary>How do I rename a node?</summary> |
| 298 | |
| 299 | A node's display name is determined by the `hostname` setting in `netdata.conf` under the `[global]` section. To rename a node, edit `netdata.conf` and set: |
| 300 | |
| 301 | ```ini |
| 302 | [global] |
| 303 | hostname = my-new-node-name |
| 304 | ``` |
| 305 | |
| 306 | Use the [`edit-config` script](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to safely edit configuration files, then [restart Netdata](/docs/netdata-agent/start-stop-restart.md). |
| 307 | |
| 308 | :::note |
| 309 | |
| 310 | Changing the hostname does **not** change the Machine GUID, Node ID, or Claimed ID. The node remains the same entity in Netdata Cloud and on Parent nodes. Historical metrics are preserved because they are keyed by Machine GUID, not hostname. |
| 311 | |
| 312 | ::: |
| 313 | |
| 314 | :::warning |
| 315 | |
| 316 | **Do not use `NETDATA_HOSTNAME` as an environment variable to set the hostname.** |
| 317 | |
| 318 | `NETDATA_HOSTNAME` is an output variable set by the Netdata daemon at runtime for use by plugins and scripts — it is not an input configuration. To override a node's name within Netdata, use the `hostname` setting in `netdata.conf`. If `hostname` is not set, Netdata falls back to the system/container hostname. |
| 319 | |
| 320 | ::: |
| 321 | |
| 322 | The updated hostname propagates to Parent nodes and Netdata Cloud on the next connection. |
| 323 | |
| 324 | For virtual nodes, see [Does renaming a virtual node change its identity?](#does-renaming-a-virtual-node-change-its-identity). |
| 325 | |
| 326 | </details> |
| 327 | |
| 328 | <a id="does-renaming-a-virtual-node-change-its-identity"></a> |
| 329 | <details> |
| 330 | <summary>Does renaming a virtual node change its identity?</summary> |
| 331 | |
| 332 | A virtual node's identity is determined by its **`guid`** field — not its `hostname` or `name`. The fields behave as follows: |
| 333 | |
| 334 | - **`guid`** — This is the vnode's identity. Changing it creates an entirely new node in Netdata Cloud. The old vnode's historical data remains under the old GUID but is no longer associated with the new one. |
| 335 | - **`hostname`** — This is used as the internal lookup key in the Agent and as the display name in dashboards. Changing `hostname` while keeping the same `guid` renames the display without creating a new node identity. |
| 336 | - **`name`** — The Agent ignores this field. When set to a value different from `hostname`, the Agent logs a warning and overrides it with `hostname`. |
| 337 | |
| 338 | **To preserve data continuity when renaming a vnode**, change only the `hostname` field in the YAML config file under `/etc/netdata/vnodes/` and keep the `guid` unchanged. If a true identity change is needed, accept that historical data belongs to the old identity. |
| 339 | |
| 340 | </details> |