Collectors in the tracker

Every configuration the tracker collects is collected through a collector. Collectors are shared with discovery (SNMP, Web Probe, the DHCP Probe and the scanner run on them too), so they are managed under Settings → System → Collectors with their own permissions. What a collector is, how to install and enrol one, its health and its security posture are on the Collectors page and in Deploy a standalone collector. This page covers what the tracker does with them.

Term	Meaning here
Built-in collector	default, Local (built-in). Runs in the core. A source that names no collector uses it.
Standalone collector	A collector at a site. Collects that site’s devices locally and hands the core the scrubbed result.
Source’s collector	The collector a source is bound to. Every collection of that source goes through it.
Tracked-config address	A device address within a tracked config, together with its collector. The same address behind two collectors is two different devices.

The Collector field on a source decides where its collections run. Leave it at the default and the built-in collector does the work; pick a site’s standalone collector and the core only ever sees the result. Bulk onboarding takes a collector for the whole batch, which is the quick way to bring a new site in.

An address is unique per tracked config and collector: 10.0.0.1 behind the Berlin collector and 10.0.0.1 behind the Madrid collector are different devices, which is exactly what overlapping private ranges at two sites look like.

A collector cannot be deleted while a source or a tracked-config address still names it. The delete drawer lists them; move them to another collector first.

Where the sessions are. The built-in collector opens every device session from the core. A standalone collector opens them at its site, so the core does not hold hundreds of slow, mostly idle sessions. When the built-in collector’s scheduled sweep is still running as the next one falls due, the core raises Collection falling behind, the cue to move a site to a standalone collector or lengthen the interval. See Change alerts & safe deletion.

How work reaches it. The core queues the collection; the collector picks it up on its held long-poll, usually within a second. Collect now and Preview feel as immediate as on the core, unless a middlebox cuts the idle poll; then the collector falls back to its poll interval.

Credentials. The collector receives a device credential only in the answer that hands it the work, uses it in memory and keeps nothing. A just-in-time password handed to a collector rotates once that collector’s work drains.

The device’s host key. For SSH, SCP and SFTP, the collector checks the key the device presents against the source’s host-key policy and the key pinned for that collector, address and port, before it sends the credential. The key it saw comes back with the result, so pins, candidates and re-trusts work the same as on the built-in collector.

What is written down at the site. The collector scrubs and hashes a capture where it collects it, so what crosses the wire and waits in its outbox is a scrubbed body and its hash. Raw configuration bodies are never written down at the site. The core then re-scrubs the capture with the tracked config’s current rules before storing it, so the core’s copy and the version hash are authoritative.

The deliberate exception. A recipe can keep an unmasked copy of every capture. A standalone collector does collect it, but holds it in memory only and attaches it at the moment it uploads the result; it never reaches the outbox, whose contract is that no device secret touches disk. The memory buffer is bounded (64 captures or 64 MiB, oldest evicted first). A result that is queued instead (the collector restarted, or the core was unreachable long enough for uploads to fall behind) arrives without its unmasked copy. The configuration snapshot is never lost; only that second copy is.

The same steps run on the built-in and on a standalone collector:

1. Log in, and escalate if asked. When the source’s credential links an Enable secret (or carries a secret itself), the collector enters privileged mode before the paging command and the recipe’s commands. A session that already lands privileged sends nothing extra. A refused enable secret fails the collection as an authentication failure and is not retried, so a wrong secret cannot lock the collector out. See Credentials. Each recipe step must come back to the prompt the session started at; a step that changes the CLI context fails with the step number and command named (see Recipes).
2. Drop NUL characters. A text capture loses any U+0000 a device sent before anything else is done with it, so the body, its hash and the unmasked copy agree. When a standalone collector of an older release still hashes a body with NULs in it, the core recognises the difference as exactly those characters and stores the body without them instead of treating it as a hash disagreement.
3. Bound the input. Before the scrub rules run, the capture is limited to ncm.scrub_max_lines lines (default 200,000) and each line to ncm.scrub_max_line_length characters (default 32,768), which protects operator-written rules from a runaway regular expression. Anything cut off is still hashed into the version, so a change beyond the cut still creates a version, and the cut raises an alert. See Snapshots, diff & drift.
4. Scrub, hash and ship. The scrub set masks secrets, the result is hashed, and a body larger than ncm.text_store_max_bytes (default 8 MiB) is tracked by hash alone. The core’s capture limits travel with every job, so a standalone collector applies the same ones, and a capture past the buffer or binary ceiling fails as too_large. One result crosses the wire in at most 25 MiB; see Tracked configs.

Cause	What you see	Fix
The standalone collector is down or cut off	Its configs read Collector offline; one collector-offline alert names the collector and how many configs it serves	Bring it back; see Collectors → Health
It speaks an older configuration-collection contract than the core	Requires update under its status in the collectors list, and a Collector … requires an update alert. It stays Online, and its SNMP and Web Probe work continue	collector-join.sh --update; see Keep the collector in step
Its identity was revoked	The collector halts in re-enroll required	Issue a fresh token and run the join again

A contract mismatch stops every configuration that collector serves, not only the ones a change touched: the contract covers how captures are hashed and what the collector must enforce (the host key, the capture limits), and a collector that does either differently is worse than one that collects nothing. The core offers such a collector no configuration work, collections or previews, until its image matches again.

One flat site. Leave every source on the built-in collector.

A branch behind NAT. Deploy a standalone collector there, then set the branch sources’ Collector to it, or bulk-onboard the branch with it selected. Nothing is opened inbound.

A hardened segment. A standalone collector inside the segment reaches the devices locally and stores no device credentials; the only thing written down there is scrubbed.

Situation	Collector for the source
The core reaches the devices and is not waiting on them	Built-in
Devices in a segment the core cannot route to, or behind NAT	That site’s standalone collector
The core spends its time waiting on hundreds of slow sessions	One standalone per site
Raw configurations must never be written down at the site	Standalone

• Collectors: the collector itself, health, rights and compatibility.
• Deploy a standalone collector: install, enrol, update, remove.
• Tracked configs & transports: the source’s Collector field.
• Credentials & the vault: the credential hand-out and enable escalation.
• Recipes & scrub sets: masking, the unmasked copy and capture limits.
• Change alerts & safe deletion: collector-offline, falling-behind and truncation alerts.