@cryptotaxi247 / netdata-1 / commits / 5e1822d09

Add VM templates and clones documentation (#21527)

* Add VM templates and clones documentation Added comprehensive guide for preparing VM templates and cloning VMs with Netdata. Files: - docs/learn/vm-templates.md: New guide covering: - Two types of identity (machine GUID vs claimed ID) - How node identity works - Preparing templates for cloning - Cloning behavior - Troubleshooting - FAQ for Proxmox, Vagrant, KVM, cloud images, Terraform, containers - docs/.map/map.csv: Added mapping for the new doc in Learn Related: Support case about VM template identity issues * docs: fix typos and curl syntax in VM templates guide - Fix 'Backup up' → 'Backed up' on line 16 - Fix 'fron' → 'from' on line 28 - Fix curl command syntax on line 118 (remove bash -c wrapper) * docs: fix curl command syntax in VM templates guide The flags were being passed to curl instead of the kickstart script. Use 'curl ... | bash -s -- <flags>' pattern to pass flags to the script. * updated * docs: add node identities documentation and reorganize VM templates - Add docs/learn/node-identities.md explaining all Netdata identity types: - Agent Self Identity (Machine GUID) - Parent: Children Identities (metadata database) - Virtual Nodes (vnodes) - Cloud: Node Identity - ACLK Identity (Claimed ID) - Update docs/learn/vm-templates.md: - Add auto-claiming configuration section - Convert troubleshooting to FAQ-style format - Add troubleshooting for clones not connecting to Parents - Fix broken links after restructuring - Move VM Templates from Netdata Cloud to Netdata Agent in sidebar - Add Node Identities to Netdata Agent sidebar after Agent CLI * docs: fix anchor links and complete cleanup commands in VM templates guide - Fix typo in node-identities.md FAQ ("identified" → "identifies") - Fix broken anchor links in vm-templates.md (#aclk-identity → #agent-cloud-link-aclk-identity) - Add missing status file locations (/tmp, /run, /var/run) to virt-sysprep example - Enhance "Fixing Already-Deployed Clones" section with all 5 status file locations and cloud.d cleanup - Add clearer comments and improved warning about re-claiming * Update node-identities.md fixed :::notes and placed faqs inside clickdowns * Update vm-templates.md fixed :::notes format, faqs under clickdowns --------- Co-authored-by: Kanela <kanela@netdata.cloud>

Costa Tsaousis committed Jan 11, 2026 at 05:34 UTC 5e1822d09cf0a59fd47ca0087ebfdaa116dddb09
3 files changed +528
docs/.map/map.csv
+2
@@ -66,6 +66,8 @@ https://github.com/netdata/netdata/edit/master/src/database/README.md,Database,P
66 https://github.com/netdata/netdata/edit/master/src/libnetdata/log/README.md,Logging,Published,Netdata Agent,,
67 https://github.com/netdata/netdata/edit/master/src/registry/README.md,Registry,Published,Netdata Agent,,"Netdata utilizes a central registry of machines/person GUIDs, URLs, and opt-in account information to provide unified cross-server dashboards."
68 https://github.com/netdata/netdata/edit/master/src/cli/README.md,Agent CLI,Published,Netdata Agent,,"The Netdata Agent includes a command-line experience for reloading health configuration, reopening log files, halting the daemon, and more."
69 +https://github.com/netdata/netdata/edit/master/docs/learn/node-identities.md,Node Identities,Published,Netdata Agent,"guid,machine guid,node id,claimed id,identity",Understanding how Netdata identifies nodes across Agents Parents and Cloud
70 +https://github.com/netdata/netdata/edit/master/docs/learn/vm-templates.md,VM Templates,Published,Netdata Agent,"vm,template,clone,kvm,proxmox,vagrant,terraform",Prepare VM templates so each clone gets a unique Netdata identity
71 https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/anonymous-telemetry-events.md,Anonymous telemetry events,Published,Netdata Agent,,
72 ,,,,,
73 ,,,,,
docs/learn/node-identities.md new
+246
@@ -0,0 +1,246 @@
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 +Netdata uses several identity mechanisms to uniquely identify nodes, authenticate connections, and track metrics across your infrastructure. Understanding these identities is essential when:
12 +
13 +- Creating VM templates or golden images
14 +- Troubleshooting connection issues
15 +- Moving nodes between Spaces
16 +- Setting up Parent-Child streaming
17 +- Configuring virtual nodes for remote monitoring
18 +
19 +## Agent Self Identity
20 +
21 +Every Netdata Agent has a **Machine GUID** - a UUID that uniquely identifies this specific node.
22 +
23 +| Property | Value |
24 +|----------|-------|
25 +| **File** | `/var/lib/netdata/registry/netdata.public.unique.id` |
26 +| **Format** | UUID (e.g., `a1b2c3d4-e5f6-7890-abcd-ef1234567890`) |
27 +| **Generated** | On first start, if missing |
28 +| **Persistence** | Permanent - never changes once created |
29 +
30 +### Generation Behavior
31 +
32 +On startup, Netdata determines the Machine GUID:
33 +
34 +1. Read from primary file (`netdata.public.unique.id`)
35 +2. If missing/invalid, read from status file backup
36 +3. If still missing, generate new random UUID
37 +4. Save to primary file with timestamp
38 +
39 +### Status File Backups
40 +
41 +The Machine GUID is also stored in status files for crash recovery:
42 +
43 +| Location | Purpose |
44 +|----------|---------|
45 +| `/var/lib/netdata/status-netdata.json` | Primary backup |
46 +| `/var/cache/netdata/status-netdata.json` | Fallback 1 |
47 +| `/tmp/status-netdata.json` | Fallback 2 |
48 +| `/run/status-netdata.json` | Fallback 3 |
49 +| `/var/run/status-netdata.json` | Fallback 4 |
50 +
51 +:::note
52 +
53 +**Redundant Storage**
54 +
55 +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.
56 +
57 +:::
58 +
59 +:::warning
60 +
61 +**GUID Must Be Unique**
62 +
63 +If two Agents have the same Machine GUID:
64 +- They cannot connect to the same Parent simultaneously
65 +- Cloud kicks the older connection offline when the second connects
66 +- This causes unstable "flapping" connections
67 +
68 +See [VM Templates](vm-templates.md) for how to avoid this when cloning VMs.
69 +
70 +:::
71 +
72 +## Parent: Children Identities
73 +
74 +When a Netdata Agent operates as a **Parent** (receiving metrics from Children), it stores metadata about all nodes it has seen.
75 +
76 +| Property | Value |
77 +|--------------|--------------------------------------|
78 +| **Database** | `/var/cache/netdata/netdata-meta.db` |
79 +| **Table** | `node_instance` |
80 +| **Contains** | GUIDs of all Children ever connected |
81 +
82 +### Relationship Between Metadata and Metrics
83 +
84 +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.
85 +
86 +| Component | Purpose |
87 +|-----------|---------|
88 +| **Metadata** (`netdata-meta.db`) | Links metric UUIDs to node GUIDs, charts, dimensions |
89 +| **Dbengine** (`dbengine*` directories) | Stores actual metric samples indexed by UUID |
90 +
91 +The metadata acts as an index - without it, metric samples in dbengine cannot be associated with their source nodes or chart definitions.
92 +
93 +### Key Point: Metadata DB Does Not Determine Agent Identity
94 +
95 +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:
96 +- The GUID file
97 +- Status file backups
98 +
99 +### Multiple Node Identities in Database
100 +
101 +When a database contains metadata for multiple nodes (from Children or [Virtual Nodes](#virtual-nodes-vnodes)), Netdata:
102 +
103 +1. **Reports all nodes** - All known nodes are reported to Netdata Cloud
104 +2. **Retention persistence** - Node entries persist in Cloud until database retention expires (can be years with tiering)
105 +
106 +This is normal for Parent nodes receiving data from Children, and for Agents using Virtual Nodes. See [VM Templates](vm-templates.md) for implications when cloning VMs.
107 +
108 +## Virtual Nodes (vnodes)
109 +
110 +**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.).
111 +
112 +| Property | Value |
113 +|----------|-------|
114 +| **Directory** | `/etc/netdata/vnodes/` |
115 +| **Format** | YAML files (`.yaml`, `.yml`, `.conf`) |
116 +| **Identity** | User-defined GUID in config file |
117 +
118 +### Configuration
119 +
120 +Each virtual node is defined in a YAML file:
121 +
122 +```yaml
123 +- name: my-remote-server
124 + hostname: remote-server.example.com
125 + guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
126 + labels:
127 + environment: production
128 + datacenter: us-east
129 +```
130 +
131 +| Field | Required | Description |
132 +|-------|----------|-------------|
133 +| `hostname` | Yes | Display name shown in dashboards and Cloud |
134 +| `guid` | Yes | UUID that uniquely identifies this virtual node |
135 +| `name` | No | Internal reference name |
136 +| `labels` | No | Key-value pairs for filtering and organization |
137 +
138 +:::warning
139 +
140 +**GUID Uniqueness**
141 +
142 +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).
143 +
144 +:::
145 +
146 +### How Virtual Nodes Work
147 +
148 +1. Go collector reads vnode configuration
149 +2. Metrics are tagged with the vnode's GUID instead of the Agent's Machine GUID
150 +3. Cloud sees the vnode as a separate node in your Space
151 +4. Parent nodes store vnode metadata alongside Children metadata
152 +
153 +Virtual nodes appear in Netdata Cloud as independent nodes, with their own dashboards and alert states.
154 +
155 +## Cloud: Node Identity
156 +
157 +When an Agent connects to Netdata Cloud, it receives a **Node ID** that links the Machine GUID to your Space.
158 +
159 +| Property | Value |
160 +|----------|-------|
161 +| **Assigned by** | Netdata Cloud |
162 +| **Stored in** | `/var/cache/netdata/netdata-meta.db` (`node_instance` table) |
163 +| **Purpose** | Links Machine GUID to your Cloud Space |
164 +
165 +Machine GUIDs and Cloud Node IDs map 1-to-1.
166 +
167 +### Node Instances
168 +
169 +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.
170 +
171 +## Agent-Cloud Link (ACLK) Identity
172 +
173 +The **Agent-Cloud Link (ACLK)** uses separate credentials for authentication:
174 +
175 +| File | Purpose |
176 +|------|---------|
177 +| `/var/lib/netdata/cloud.d/cloud.conf` | Cloud configuration, contains `claimed_id` |
178 +| `/var/lib/netdata/cloud.d/private.pem` | RSA private key |
179 +| `/var/lib/netdata/cloud.d/public.pem` | RSA public key |
180 +
181 +### Claimed ID
182 +
183 +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.
184 +
185 +| Property | Description |
186 +|----------|-------------|
187 +| **Purpose** | Authenticates the ACLK connection to Netdata Cloud |
188 +| **Generated** | During the claiming process |
189 +| **Independence** | Separate from Machine GUID - they can change independently |
190 +| **Regeneration** | A new Claimed ID is generated each time the agent is re-claimed |
191 +
192 +:::note
193 +
194 +**Custom Paths**
195 +
196 +If you customized `[directories]` in `netdata.conf`:
197 +- `lib` setting affects `/var/lib/netdata/` paths
198 +- `cache` setting affects `/var/cache/netdata/` paths
199 +
200 +:::
201 +
202 +## FAQ
203 +
204 +<details>
205 +<summary>How do I find my node's Machine GUID?</summary>
206 +
207 +Read the file `/var/lib/netdata/registry/netdata.public.unique.id`.
208 +
209 +</details>
210 +
211 +<details>
212 +<summary>Can I change my node's Machine GUID?</summary>
213 +
214 +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](vm-templates.md) for the complete procedure.
215 +
216 +</details>
217 +
218 +<details>
219 +<summary>Why does my node keep going offline/online in Cloud?</summary>
220 +
221 +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.
222 +
223 +</details>
224 +
225 +<details>
226 +<summary>What's the difference between Machine GUID, Node ID, and Claimed ID?</summary>
227 +
228 +- **Machine GUID**: Agent-generated, identifies the node itself, never changes
229 +- **Node ID**: Cloud-assigned, links the Machine GUID to your Space
230 +- **Claimed ID**: Agent-generated during claiming, identifies the ACLK connection
231 +
232 +</details>
233 +
234 +<details>
235 +<summary>Do containers need unique GUIDs?</summary>
236 +
237 +Containers with ephemeral storage get unique GUIDs automatically on each start. Containers with persistent volumes at `/var/lib/netdata/` retain their GUID across restarts.
238 +
239 +</details>
240 +
241 +<details>
242 +<summary>Can the same node exist in multiple Spaces?</summary>
243 +
244 +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.
245 +
246 +</details>
docs/learn/vm-templates.md new
+280
@@ -0,0 +1,280 @@
1 +# VM Templates and Clones
2 +
3 +:::danger
4 +
5 +**Destructive Operations - Data Loss Warning**
6 +
7 +The commands in this guide **permanently delete**:
8 +- All historical metrics
9 +- [Node identity](node-identities.md#agent-self-identity)
10 +- [Cloud connection](node-identities.md#agent-cloud-link-aclk-identity)
11 +- Alert history
12 +
13 +**This is irreversible. There is no undo.**
14 +
15 +Only run these commands on VMs you intend to convert to templates.
16 +Running these on a production system will destroy your monitoring data.
17 +
18 +:::
19 +
20 +:::tip
21 +
22 +**What You'll Learn**
23 +
24 +How to prepare a VM template so each clone gets a unique Netdata identity and automatically connects to Netdata Cloud.
25 +
26 +:::
27 +
28 +## Prerequisites
29 +
30 +- **Read first**: [Node Identities](node-identities.md) - understand what you're deleting
31 +- Netdata installed on a VM
32 +- Hypervisor that supports templates or golden images
33 +- (Optional) `/etc/netdata/claim.conf` configured for auto-claiming to Cloud
34 +
35 +## Overview
36 +
37 +To prepare a VM template:
38 +
39 +1. **Stop Netdata** - Prevent file regeneration
40 +2. **Delete identity and data files** - Force new identity on clone boot
41 +3. **Keep claim.conf** - Enable auto-claiming (optional)
42 +4. **Convert to template** - Without starting Netdata
43 +
44 +## Files to Delete
45 +
46 +:::danger
47 +
48 +**Verify you are on the correct VM before running these commands.**
49 +
50 +:::
51 +
52 +| Category | Files | What's Lost |
53 +|----------|-------|-------------|
54 +| **[Agent Identity](node-identities.md#agent-self-identity)** | [GUID file](node-identities.md#agent-self-identity), [status backups](node-identities.md#status-file-backups) | Node identity |
55 +| **[ACLK Auth](node-identities.md#agent-cloud-link-aclk-identity)** | [`cloud.d/`](node-identities.md#agent-cloud-link-aclk-identity) directory | Cloud connection, must re-claim |
56 +| **[Node Metadata](node-identities.md#parent-children-identities)** | `netdata-meta.db*`, `context-meta.db*` | Node metadata, metric mappings |
57 +| **Metrics** | `dbengine*` directories (all tiers) | All historical metrics |
58 +
59 +**Keep**: `/etc/netdata/claim.conf` - enables auto-claiming on clones
60 +
61 +## Step-by-Step
62 +
63 +### 1. Stop Netdata
64 +
65 +```bash
66 +sudo systemctl stop netdata
67 +```
68 +
69 +### 2. Delete All Identity and Data Files
70 +
71 +:::danger
72 +
73 +**Point of No Return**
74 +
75 +The following commands permanently delete Netdata data. Verify you are on the template VM.
76 +
77 +:::
78 +
79 +```bash
80 +# Machine GUID (Agent Self Identity)
81 +sudo rm -f /var/lib/netdata/registry/netdata.public.unique.id
82 +
83 +# Status file backups (GUID recovery locations)
84 +sudo rm -f /var/lib/netdata/status-netdata.json
85 +sudo rm -f /var/cache/netdata/status-netdata.json
86 +sudo rm -f /tmp/status-netdata.json
87 +sudo rm -f /run/status-netdata.json
88 +sudo rm -f /var/run/status-netdata.json
89 +
90 +# ACLK authentication (Claimed ID, RSA keys)
91 +sudo rm -rf /var/lib/netdata/cloud.d/
92 +
93 +# Databases and metrics (metadata, all dbengine tiers)
94 +sudo rm -f /var/cache/netdata/netdata-meta.db*
95 +sudo rm -f /var/cache/netdata/context-meta.db*
96 +sudo rm -rf /var/cache/netdata/dbengine*
97 +```
98 +
99 +### 3. Configure Auto-Claiming (Optional)
100 +
101 +To have clones automatically claim to Netdata Cloud on first boot, ensure `/etc/netdata/claim.conf` exists:
102 +
103 +```bash
104 +cat /etc/netdata/claim.conf
105 +```
106 +
107 +Should contain:
108 +```ini
109 +[global]
110 + url = https://app.netdata.cloud
111 + token = YOUR_SPACE_TOKEN
112 + rooms = ROOM_ID
113 +```
114 +
115 +### 4. Convert to Template
116 +
117 +**Do not start Netdata.** Convert the VM to a template using your hypervisor.
118 +
119 +## When Clones Boot
120 +
121 +1. Netdata starts, no [GUID](node-identities.md#agent-self-identity) found, generates new unique identity
122 +2. If `claim.conf` exists, auto-claims to Cloud
123 +3. Cloud assigns [Node ID](node-identities.md#cloud-node-identity), new node appears in your Space
124 +
125 +Each clone is a unique, independent node.
126 +
127 +## Hypervisor Notes
128 +
129 +The Netdata cleanup commands are the same for all hypervisors. The difference is **when** and **how** to run them.
130 +
131 +| Hypervisor | Template Support | When to Clean | Automation |
132 +|------------|------------------|---------------|------------|
133 +| **Proxmox** | Convert to Template | Before conversion | cloud-init scripts |
134 +| **VMware/vSphere** | VM Templates | Before conversion | Guest customization |
135 +| **libvirt/KVM** | virt-sysprep | During sysprep | `--delete` flags |
136 +| **AWS** | AMI | Before image creation | user-data scripts |
137 +| **Azure** | Managed Image | Before capture | cloud-init |
138 +| **GCP** | Machine Image | Before creation | startup scripts |
139 +| **Vagrant** | Box packaging | Before `vagrant package` | Vagrantfile provisioner |
140 +
141 +<details>
142 +<summary><strong>libvirt/KVM: virt-sysprep example</strong></summary>
143 +
144 +```bash
145 +virt-sysprep -a myvm.qcow2 \
146 + --delete /var/lib/netdata/registry/netdata.public.unique.id \
147 + --delete /var/lib/netdata/status-netdata.json \
148 + --delete /var/cache/netdata/status-netdata.json \
149 + --delete /tmp/status-netdata.json \
150 + --delete /run/status-netdata.json \
151 + --delete /var/run/status-netdata.json \
152 + --delete /var/lib/netdata/cloud.d \
153 + --delete '/var/cache/netdata/netdata-meta.db*' \
154 + --delete '/var/cache/netdata/context-meta.db*' \
155 + --delete '/var/cache/netdata/dbengine*'
156 +```
157 +
158 +</details>
159 +
160 +<details>
161 +<summary><strong>Cloud-init: Fresh install approach</strong></summary>
162 +
163 +Alternative: Install Netdata on first boot instead of templating:
164 +
165 +```yaml
166 +# cloud-init user-data
167 +runcmd:
168 + - curl -fsSL https://get.netdata.cloud/kickstart.sh -o /tmp/kickstart.sh
169 + - bash /tmp/kickstart.sh --claim-token TOKEN --claim-rooms ROOM_ID
170 +```
171 +
172 +Each instance installs fresh with unique identity.
173 +
174 +</details>
175 +
176 +## Troubleshooting
177 +
178 +### Clones share the same identity
179 +
180 +Cause: [GUID recovered from status backup](node-identities.md#status-file-backups). Netdata checks multiple backup locations before generating a new GUID.
181 +
182 +Solution: Delete **all** status file locations, not just the primary GUID file. See the cleanup commands in [Step 2](#2-delete-all-identity-and-data-files).
183 +
184 +### Clones don't connect to Parent
185 +
186 +Cause: Either clones share the same [Machine GUID](node-identities.md#agent-self-identity) (only one can connect at a time), or `stream.conf` wasn't configured in the template.
187 +
188 +Solution:
189 +- Verify each clone has a unique GUID: `cat /var/lib/netdata/registry/netdata.public.unique.id`
190 +- Verify `stream.conf` exists and has the correct Parent destination and API key
191 +- If GUIDs are duplicated, run the cleanup on each clone (loses metrics)
192 +
193 +### Stale "template" node appears in Cloud
194 +
195 +Cause: [Database files kept](node-identities.md#multiple-node-identities-in-database) from the template. The template's node identity persists in the metadata.
196 +
197 +Solution: Delete databases on all clones. This loses historical metrics but removes the stale node reference.
198 +
199 +### Clones using Parent profile unexpectedly
200 +
201 +Cause: Template had `stream.conf` with an enabled API key section (configured to receive streams, as Parent).
202 +
203 +Solution: Reset `stream.conf` on clones or delete the API key sections that enable receiving.
204 +
205 +### Unstable Cloud connections (flapping)
206 +
207 +Cause: Two agents have the same [Machine GUID](node-identities.md#agent-self-identity). Cloud kicks the older connection offline when the second connects.
208 +
209 +Solution: Each agent needs a unique GUID. Run the cleanup procedure on affected clones.
210 +
211 +### Clone doesn't auto-claim to Cloud
212 +
213 +Cause: Missing `claim.conf` or environment variables not set.
214 +
215 +Solution: Create `/etc/netdata/claim.conf` with your Space token.
216 +
217 +### Fixing Already-Deployed Clones
218 +
219 +If clones were deployed with identity files:
220 +
221 +```bash
222 +# On each affected clone
223 +sudo systemctl stop netdata
224 +
225 +# Machine GUID
226 +sudo rm -f /var/lib/netdata/registry/netdata.public.unique.id
227 +
228 +# Status file backups (all locations)
229 +sudo rm -f /var/lib/netdata/status-netdata.json
230 +sudo rm -f /var/cache/netdata/status-netdata.json
231 +sudo rm -f /tmp/status-netdata.json
232 +sudo rm -f /run/status-netdata.json
233 +sudo rm -f /var/run/status-netdata.json
234 +
235 +# ACLK authentication (if re-claiming to Cloud)
236 +sudo rm -rf /var/lib/netdata/cloud.d/
237 +
238 +# Databases and metrics
239 +sudo rm -f /var/cache/netdata/netdata-meta.db*
240 +sudo rm -f /var/cache/netdata/context-meta.db*
241 +sudo rm -rf /var/cache/netdata/dbengine*
242 +
243 +sudo systemctl start netdata
244 +```
245 +
246 +:::warning
247 +
248 +This deletes all historical metrics on the clone. If you skip deleting `cloud.d/`, you must re-claim to Cloud manually.
249 +
250 +:::
251 +
252 +## FAQ
253 +
254 +<details>
255 +<summary>What if I reboot a clone?</summary>
256 +
257 +Identity persists. Netdata only generates a new [GUID](node-identities.md#agent-self-identity) when the file AND all [backups](node-identities.md#status-file-backups) are missing.
258 +
259 +</details>
260 +
261 +<details>
262 +<summary>Can multiple clones use the same claim token?</summary>
263 +
264 +Yes. Each clone gets a unique [Machine GUID](node-identities.md#agent-self-identity) and [Claimed ID](node-identities.md#claimed-id). They authenticate with the same token but appear as separate nodes.
265 +
266 +</details>
267 +
268 +<details>
269 +<summary>Do containers need this?</summary>
270 +
271 +No. Containers start with empty volumes, so each gets a unique identity automatically.
272 +
273 +</details>
274 +
275 +<details>
276 +<summary>Is my claim token secure in the template?</summary>
277 +
278 +The token only allows claiming to your Space. It cannot read data or modify other nodes. Treat it like an API key - don't expose publicly, but it's safe in private templates.
279 +
280 +</details>