Pular para o conteúdo

Collectors

A collector does work on the core’s behalf where the devices are. It collects device configurations for the Configuration Tracker, polls devices over SNMP, runs Web Probe passes, can be a DHCP Probe listening point, and runs the Scanner. Every installation has one built into the core; you add standalone collectors at sites the core cannot reach, or should not have to wait on.

Collectors are a platform primitive rather than part of any one feature, so they live under Settings → System → Collectors and carry their own permission section.

TermMeaning
Embedded collectorThe collector built into the core, named default and shown as Local (built-in). Runs on whichever node holds the leader role. Always present, always the default, cannot be deleted.
Standalone collectorA container at a site, installed with collector-join.sh or the appliance’s module installer. Dials out to the core; listens on no port the core would use.
Enrolment tokenA reveal-once secret that lets one standalone collector attach to the core the first time. Single-use, with a lifetime you choose.
IdentityAn Ed25519 key the collector generates for itself. The core pins its public key at enrolment and checks a signature on every request.
OutboxThe collector’s on-disk queue of results the core has not acknowledged yet. The only data a collector keeps.
Job contractThe version of each job (configuration collection, SNMP polling, Web Probe) that a collector speaks. For configuration collection it covers how a capture is scrubbed, hashed and fingerprinted, and what the collector must enforce. A job whose contract differs from the core’s is paused on that collector; its other jobs carry on.
One standalone collector works several jobs at its site and sends every result the same way: over the HTTPS connection it opens to the core. The only traffic that ever arrives at it comes from the site itself, when it is a DHCP listening point.
JobWho picks the collectorStandaloneEmbedded
Configuration collectionEach source and tracked-config address names its collector.YesYes
SNMP pollingThe SNMP profile names who polls: the core or a specific collector. There is no fallback from one to the other.YesThe core polls itself
Web ProbeEach Web Probe source runs on one collector, the built-in one or a site’s.YesYes
DHCP listening pointSwitched on per machine in the collector’s environment (COLLECTOR_DHCP_PROBE_ENABLED, off by default). See DHCP Probe.YesThe core’s nodes listen as nodes
ScannerZones are built in the core from the interfaces the collector reports. See Scanner.Every standalone collector is a scannerNo

A collector decides none of this itself. It reports what it can do and what its machine has, and the core hands it work. A standalone collector holds no database: once the core acknowledges a result, it is gone from the site.

Reach. A collector inside a segment reaches devices the core cannot route to: a branch behind NAT, a DMZ, an OT network. Scanning and hearing broadcast DHCP only work from inside the broadcast domain at all.

Taking the waiting off the core. Collecting a fleet is hundreds of small, slow sessions. Each one opens, sends commands and then waits: on a CLI to echo back, on a slow WAN link, on a device that takes thirty seconds to answer. A standalone collector does that waiting at the site and hands the core the finished result. The work is I/O-bound, so what the core is spared is mainly the fan-out of long-lived, mostly idle sessions and the retries around them.

Nothing left behind. Scrubbing happens at the site, so raw configuration bodies are never written down there, and device credentials are never stored there. See Security posture.

Settings → System → Collectors lists every collector. Access is governed by the Collectors permission section in the System category of RBAC, separate from the Configuration Tracker’s sections: running collectors is a different trust from curating a device inventory.

ActionPermission
See the list and a collector’s pagecollectors → view
Create a standalone collectorcollectors → create
Rename it, issue an enrolment token, re-enrol, revoke its identitycollectors → edit
Delete itcollectors → delete

The Collectors list under Settings → System, with the built-in default collector online The Collectors list. The page’s own description names the jobs a collector does. DHCP Probe says which sites listen for DHCP; Cluster node says which node a collector is connected to (standalone) or active on (embedded); Used by counts what references the collector.

ColumnWhat it shows
NameUnique. The built-in collector is default.
ModeLocal (built-in) or Standalone.
StatusOnline, Offline or Unknown. See Health.
DHCP ProbeListening with the bound address and port, Not listening with the reason (for example, the port is taken), or — for a collector that has never reported a DHCP listening point. — does not mean “off”: the core cannot tell an off probe from a collector that never mentioned one.
Cluster nodeA standalone collector is connected to the node that served its last poll. Under HA the nodes share no client-facing address and each collector talks to one node, so this tells you whose outage explains a quiet collector. The embedded collector is active on the current leader and moves with it at failover.
Last seenThe last poll of a standalone collector, the liveness signal.
Used byHow many objects reference the collector.

The General card holds the name and Site / Location, a free-text note of where the collector runs (not a URL: the core never calls a collector). The Identity card has Issue enrollment token (Re-enroll once it has an identity) and Revoke identity.

The Details rail shows mode, status, the connected node, last seen with the address it dialled in from, Version as core vX · collector vY with a compatibility badge, the identity state, fingerprint and issue time, whether nmap is installed (it enables the scanner’s Deep method), and the DHCP Probe state with its socket. The Interfaces card lists what the collector’s machine has, as the collector reported it when it started: each interface’s type (Physical, VLAN, Virtual), state, address, VLAN and MAC, and whether a scanner zone can Listen only or Listen and scan there.

A standalone collector's page after enrolment: Online, the connected node, the version pair marked Compatible, identity Active A standalone collector’s page once it has enrolled. The Details rail on the right is where a deployment shows it worked.

  1. You create the collector under Settings → System → Collectors → New Collector. It reads Unknown until it first reports.
  2. On its page, Issue enrollment token opens one drawer: the Core URL the collector should dial, the Token lifetime (minutes) (default 60, at most 7 days), and Build nmap on the collector host, which adds --with-nmap to the command. Issue token then shows, once, the join command with the address and token filled in.
  3. On the site host, collector-join.sh checks the address and the token against the core before it installs anything, then starts the container and waits until the collector has attached.
  4. On first start the collector generates its Ed25519 key, redeems the token, and the core pins the key as its identity. From then on every request is signed.

The full walkthrough, every flag and the environment switches are in Deploy a standalone collector.

A standalone collector adds as little attack surface as possible to the segment it sits in:

  • Dial-out only. The collector opens every connection. It long-polls the core for work and posts results back; the core never connects to it. Nothing needs opening inbound to the site or the core. The one listener it can have is the optional DHCP listening point, and that faces the site’s relays, not the core.
  • An identity it made itself. It enrols with a one-time token, then signs every request with a key it generated and never sends. Each request carries a timestamp accepted within a five-minute window; a verbatim repeat inside that window is rejected.
  • Credentials only for the job at hand. Device credentials arrive in the poll response for that work, are used in memory, and are never persisted, including just-in-time passwords, which rotate once the collector’s work drains.
  • The device is checked before the credential leaves. For SSH, SCP and SFTP the collector verifies the device’s host key at the site, with the source’s host-key policy and the key the core has pinned for that collector, address and port. A key the policy refuses ends the session after key exchange, before authentication, so whoever answers on a device’s address does not receive its credentials. The key it saw goes back with the result, and the core pins it or records it as a candidate, exactly as for the built-in collector.
  • Trust in the core is pinned. The collector accepts the certificate the core presents on first contact and only that one afterwards. A CA bundle is the stricter alternative.
  • A durable outbox, nothing else. Results wait on disk until the core acknowledges them and are delivered idempotently, so a restart or a link outage neither loses nor duplicates a capture. A stolen collector volume yields its own identity and already-scrubbed results, nothing that opens a device.
  • Its word counts only for its own wires. The core records a scanner sighting only from an interface the collector was asked to watch (an enabled zone listens or scans there, or a scan ran from it) and, where the interface has an address, only for an address inside its subnet. It also creates at most 1000 new endpoints per collector per hour; a device the inventory already knows is never held back. Refused sightings are dropped and counted in the core’s log. See Scanner.

Configuration captures follow the core’s limits. Every collection job carries the core’s capture limits (ncm.text_store_max_bytes, ncm.text_buffer_max_bytes, ncm.binary_max_bytes and the scrub bounds), and a standalone collector applies them at the site exactly as the built-in one does. A capture past the buffer or binary ceiling fails as too_large, naming the setting to raise; text past the store threshold is tracked by its hash alone. See Tracked configs.

One result is at most one upload. The bundled proxies in front of the core accept collector results and previews of up to 25 MiB. A collection result that would be larger is sent without its unmasked copy and, if still too large, by hash and size alone. A preview that large is reported as too_large. If a proxy of your own sits between the site and the core and refuses a result as too large, the collector sends a too_large failure naming the size instead, and does not retry a body that can never get through.

Reports wait for the core. Scanner sightings and DHCP reports wait up to 120 seconds for the core to accept them, and the collector keeps buffering meanwhile, so a slow core delays the next report rather than receiving the same one twice.

Status is derived when the page is read, from the last time a collector reported in. A standalone collector’s job poll is its heartbeat.

StatusStandaloneEmbedded
OnlineReported within the last 15 minutes.A writable primary is observed (always, on a single node).
OfflineNo report for 15 minutes: many missed polls, a deliberately coarse signal.No node is sweeping: a failover window or a quorum loss.
UnknownHas never reported: created, not yet enrolled or started.The cluster could not be reached at all.

A standalone collector that goes Offline raises one ncm_collector_offline alert, one per collector, carrying the number of tracked configs it serves. The check runs every 5 minutes. It never fires for the embedded collector, or for a collector that has never reported. Discovery sources name the same condition in their own terms: a Web Probe pass or an SNMP result reads Collector silent when the collector that should have done the work is not reporting in, which points at the collector rather than the device.

A standalone collector reports its release and, for each job it can run, the version of that job’s contract it speaks. The core compares each one with its own, job by job.

  • A job whose contract differs is paused, and only that job. Configuration collection, SNMP polling and Web Probe each have a contract version. A collector that speaks another version of one of them, older or newer, is offered none of that job’s work, while its other jobs carry on. Configuration collection’s contract covers how a capture is scrubbed, hashed and fingerprinted, and what each job tells the collector to enforce: the device’s SSH host key and the capture limits. A collector that would not enforce them gets no configuration work at all: an idle collector is safer than one that hands a credential to an unchecked host or writes history the core would hash differently.
  • Results under another contract are refused. Anything a collector posts for a job under a version the core does not speak is refused rather than stored.
  • The collector stays Online. Its polls are still answered, so it keeps its heartbeat and its SNMP and Web Probe work. The badge and the alert below are what tell you.
  • It recovers by itself on its first poll from an image that speaks the core’s versions. Nothing needs re-enrolling.
BadgeMeaning
CompatibleEvery job is offered.
Update recommendedEvery job is offered; the core runs a newer release. Upgrade when convenient.
Requires updateAt least one job is paused. Shown under Status in the list and on the Details rail. Its tooltip names each paused job and the collector release that runs it again, for example Configuration collection (NCM) requires collector 1.3.3 or newer. A collector newer than its core gets the same badge, and the tooltip says the core has to be updated to match.

For each collector with a paused job, the core raises one warning alert, Collector <name> requires an update (collector:update:<collector id>, source collectors), naming the release the collector runs and every paused job. It is evaluated every minute, also catches the moment the core is upgraded and every collector falls behind at once, and resolves when the collector catches up or is deleted.

The embedded collector has no badge: it is the core. A release that moves a contract says so in its release notes; plan the collector updates into the same maintenance window as the core. Moving a collector to its core’s version is one command, see Keep the collector in step.

Deleting a collector on the core and removing it from its host are independent, on purpose: a host being decommissioned often cannot reach the core any more.

  • On the core, the delete drawer lists what references the collector. Configuration Tracker sources and tracked-config addresses, Web Probe sources and SNMP profiles that name it must be moved or removed first. A device assigned to it is simply unassigned.
  • On the host, collector-join.sh --uninstall (or sudo taranac-module collector --uninstall on an appliance) removes the container, its state and its configuration. It refuses while the outbox holds results the core has not accepted, because they exist nowhere else; --force accepts the loss.

One flat site. Nothing to deploy. The built-in collector collects configurations, runs Web Probe sources, and the core polls SNMP itself.

A branch behind NAT. Deploy a standalone collector at the branch and point that branch’s sources, SNMP profile and Web Probe source at it. Nothing is opened inbound anywhere.

A branch with its own DHCP relay. Switch the DHCP listening point on for the branch’s collector and add its address as an extra helper on the branch router. The relayed copy never leaves the site; the core receives only what was parsed out of it.

Finding what is on a wire. Install the collector on a host with a leg (or a trunk) in the segments you care about, then build scanner zones on its interfaces in the core.

SituationCollector
The core reaches the devices directly and is not waiting on themEmbedded
Devices in a segment the core cannot route toStandalone in that segment
A site behind NAT, or with no inbound pathStandalone (it dials out)
You need to hear broadcast DHCP or scan a segmentStandalone with an interface in that segment
The core spends its time waiting on hundreds of slow device sessionsOne standalone per site
Raw configurations must never be written down at the siteStandalone (only scrubbed bodies leave it)
FieldNotes
NameUnique. The built-in one is default.
Modeembedded (Local (built-in): exactly one, always the default, undeletable) or standalone. Only standalone collectors can be created.
Site / LocationFree text, standalone only. Not a URL.
Statusonline · offline · unknown, derived when read. Standalone: 15-minute heartbeat staleness. Embedded: whether a writable primary exists.
Cluster nodeStandalone: the node that served its last poll. Embedded: the current leader. — when it cannot be resolved.
VersionRelease version pair and the compatibility badge, derived from the jobs the collector is not offered: compatible · update_recommended · update_required (shown as Requires update, with the paused jobs). None for embedded.
IdentityStandalone only: Ed25519 key pinned at enrolment; active or revoked.
Enrolment tokenReveal-once; lifetime 1 minute to 7 days (default 60 minutes); issuing a new one revokes any earlier one for that collector.
DHCP ProbeReported by the collector, never configured from the core: listening (address and port), not listening (reason), or nothing reported.
Interfaces, nmapReported by the collector when it starts.
Permissionscollectors: view · create · edit · delete (System category).
Offline alertncm_collector_offline, one per standalone collector, after 15 minutes, checked every 5.
Update alertcollector:update:<collector id>, warning, one per standalone collector with a paused job, checked every minute.