Tracked configs & transports

A tracked config is the unit the tracker watches: one device, its version history and its baseline. It doesn’t hold connection details itself — those live on a reusable source. The split is deliberate: a source describes how to reach a device, the recipe describes what to fetch, and the tracked config binds them to a specific box.

A source’s transport decides both the connection settings it carries and whether it needs a credential.

• CLI transports (ssh, telnet) run a CLI recipe — an ordered list of commands — and capture the output. The netmiko driver comes from the recipe, unless the source pins a device type of its own: that override is used verbatim and beats the recipe — the escape hatch for a box the recipe’s driver doesn’t fit, a plain Linux host, say. Both CLI transports also take an optional paging command, and telnet a prompt-regex override.
• File transports (scp, sftp) pull a config file straight off the device. The remote path lives on a file recipe, not on the source — the source is the connection, the recipe is what to fetch.
• API transports (http, https) run an HTTP recipe that carries its own request — method, path, headers and an optional body — so a custom recipe can fetch essentially any file or endpoint a device exposes.

SSH-family sources pin the device’s host key in Taranac’s own store (not OpenSSH known_hosts), keyed per (collector, address, port). A source picks a host-key policy:

When a pinned key changes, the connection is refused and the new key is stashed as a candidate — Taranac never silently re-pins. An operator re-trusts it explicitly (or resets the pin to re-learn from scratch); because the pin is keyed by (collector, address, port), that re-trust is shared by every source reaching the same host, not just the one you opened. Every pin, accept and reset is audited.

An http/https source carries the connection half of the request; the recipe carries the rest:

• Base path — a path-only prefix that must start with / (no scheme, host, query or fragment). The host and port come from the source’s network object.
• Method — GET (default) or POST.
• Headers — static request headers.
• Body template — an optional request body.
• TLS verify (https only) — off by default, because device management APIs are commonly self-signed. Turn it on where the device presents a trusted certificate.

Base path, headers and body may reference credential fields with {{cred.*}} placeholders so a token from the vault is injected at collection time rather than written into the source.

Sources live under Configuration Tracker → Settings → Sources; tracked configs under Configuration Tracker → Configs.

Add a source and set:

• Name — required, unique across all sources.
• Transport — one of the six above; it decides the rest of the form.
• Target — the network object (host or fqdn) to reach.
• Port — optional; blank uses the transport’s default.
• Credential — the vault entry to authenticate with (required for ssh/telnet/scp/sftp).
• Collector — the reachability domain that will do the collecting.
• Transport settings — host-key policy for the SSH family (with a paging command and a device-type override on ssh/telnet), or base path / method / headers / body / TLS-verify for HTTP(S).

The Sources list shows each source’s transport, resolved address:port, collector, whether a credential is attached, and a Used by count you can expand to see which tracked configs depend on it.

Sources across every transport — SSH, HTTP, SCP, SFTP and HTTPS — each with its target address, collector, credential and reference count.

From Configs, choose Track a config for a single device (or Onboard (bulk) to import a whole pool). Set:

• Name — required. Names need not be globally unique; the real identity is the address + collector + recipe.
• Source — the connection to use.
• Recipe — required: it is what says what to fetch. There is no default to fall back on. The recipe’s kind must also match the source’s transport — a file recipe belongs to an scp/sftp source and nowhere else (it carries the remote path), and an scp/sftp source is rejected with anything but a file recipe.
• Addresses — optional, under Advanced options. These are not the collection address — that comes from the source — they are the device address(es) used to attribute a change to an AAA login. Each is a concrete host (a subnet is rejected), scoped to a collector; leave the collector blank and it binds to the default one. Creating a config seeds one address automatically from the source’s target (a host object’s IP, or an fqdn resolved by DNS); remove it if you don’t want the correlation.

Source and recipe are picked from a drawer that searches the server, so a large catalogue is fully reachable rather than truncated.

On save you land on the config’s detail page, where you can Preview a collection, Collect now, watch the version history build, and later pin a baseline.

The Configs list shows each config’s source, recipe, collectors and change-notification recipients, whether a baseline is set, the last-changed version and the last-checked time — plus a derived status, computed at read time in precedence order, the first that applies winning: Disabled › Collector offline › Failing › Drifted › Never collected › OK. A failing config also carries why it failed: authentication, device unreachable, partial capture, or capture too large. The status table spells each one out.

Preview, on the config’s detail page, dry-runs the whole collection — the same plan, the same engine, the same scrub — and shows the would-be config beside a step-by-step trace of where a real collection would succeed or fail. It opens no run, writes no result and cuts no snapshot (its only trace is an activity-log entry), and it drives the engine exactly once, so a wrong credential costs one login rather than a lockout.

When that evidence has to travel — into a ticket, say — the same single collection can be run from the shell:

./taranac diagnose --protocol ncm --config "<name>"

It writes one report to ./diagnostics: what was resolved before any network was touched (transport, address, port, credential mode, recipe, and the CLI driver together with why it was chosen), whether the port answered, what the SSH handshake agreed on, and the login dialogue itself. It records nothing in Taranac — no run, no result, no snapshot, no version — and logs in exactly once, never the retry loop. Diagnostics covers the report’s anatomy and the --full-transcript warning.

A rack of identical switches. Create one source per switch (or bulk-onboard the pool), all pointing at the same SSH credential and the “Cisco IOS — running-config” recipe. Each becomes its own tracked config with its own history and baseline.

A firewall that only speaks its API. Use an https source with TLS-verify on (the firewall presents a real cert), an HTTP recipe whose request pulls the config export endpoint, and a token-type credential referenced from the header via {{cred.token}}.

A box that only hands you a file. Use an scp or sftp source plus a file recipe carrying the remote path (e.g. /config/running). Taranac pulls the blob and versions it like any other capture.

A remote site behind NAT. Point the source’s collector at a standalone collector deployed at that site; the source and recipe are otherwise identical to a local one.

Prefer ssh over telnet and https over http wherever the device supports it. For file transports, choose whichever of SCP/SFTP the device implements — the recipe side is identical.

Source fields:

Tracked-config fields:

• Recipes & scrub sets — what a source fetches, and cleaning it.
• Credentials & the vault — the credential a source authenticates with.
• Collectors — the reachability domain a source is bound to.
• Bulk onboarding — create many sources and configs at once.
• Snapshots, diff & drift — what a collection produces.
• Diagnostics — the per-config collection report, layer by layer.