Configuration reference

Where the file is read from

The first config.yaml found, in this order:

1. /etc/infrality-agent/ — where the installer and the packages put it
2. /etc/infrality/
3. $HOME/.infrality/
4. the working directory

--config <path> replaces the search, and is also where settings chosen on the dashboard are written back. infrality-agent config writes a starting file into the first location when run as root, and into the working directory otherwise.

A missing file is fine: defaults plus environment variables are a legitimate way to run. A file that cannot be parsed stops the agent — it used to fall back silently to defaults and sweep the wrong network.

Who decides what

Three sources, from strongest to weakest:

1. The dashboard. Settings an admin chose for this agent come back in every registration and over the live connection, and win over everything below — except the API key and URL, which are how the agent reaches the API in the first place.
2. Environment variables. INFRALITY_ plus the key in capitals with . as _: INFRALITY_INGESTOR_API_KEY, INFRALITY_SCAN_CIDR, INFRALITY_DISCOVERY_SNMP.
3. config.yaml, then the built-in defaults.

A setting nobody has chosen on the dashboard stays the file’s. When the agent registers, the API fills its empty dashboard settings from what the agent reports, so the settings dialog shows real values; from the moment somebody saves one there, it is the dashboard’s.

The discovery block is local only: which protocols the agent may speak on a network is decided by whoever installed it there, not from the dashboard.

ingestor — reaching the API

Key	Default	Description
api_key	(empty)	The organization’s API key, nk_…. Always from the file or the environment, never from the dashboard.
base_url	https://api.infrality.io	The API. http:// is refused anywhere but loopback: the key travels in the first message.
project_id	(empty)	The board this agent draws on. Optional — it can be chosen on the dashboard, which then takes precedence.

agent

Key	Default	Description
name	My Local Agent	The name shown on the dashboard. Renaming it on the dashboard wins over this.
enabled	true	Written by the dashboard when the agent is paused. false starts no sweep. Kept in the file so a paused agent that restarts with no route to the API stays paused. Do not edit it by hand to resume — resume from the dashboard.

scan — what is swept, and when

Key	Default	Description
cidr	the network this machine is on	Base address of the range, e.g. 192.168.1.0. Read from the interface carrying the default route. Set it only to sweep another network — a range the machine has no route into finds nothing.
mask	that network’s prefix length	Prefix length, as a string: "24".
interface	(worked out from the range)	The interface to sweep from. Needed only for a segment this machine has no address on; ARP is then sent with an unspecified sender address. Also --interface on run.
timeout	90s	A ceiling on one sweep, not a duration: a fast network still finishes fast. A sweep that reaches it ends Partial, with everything found so far.
interval	0	How often to sweep on its own. 0 (also off, never, manual) means only when asked. Units: s, m, h, d, w, mo (30 days), y — 30m, 6h, 7d, 1mo. Ignored by daemon.

The packaged file says 15 seconds

The config.yaml that ships in the packages and archives sets timeout: 15s, and an explicit value wins over the 90-second default. On a busy /24 that can end every sweep Partial. Raise it to 90s in the file, or set the timeout in the agent’s settings on the dashboard.

workers

Key	Default	Description
count	50	Addresses probed in parallel. Identification is separately capped at 16 hosts at a time, so raising this mostly speeds up the ping sweep.

discovery — which protocols the agent may speak

Each switch turns one protocol off without affecting the others; the sweep is then exactly as informative minus that protocol. All on by default, except hop counting.

Key	Default	What it sends
arp	true	The layer-2 sweep: finds hosts that ignore ping, and every hardware address on the segment.
dns	true	Reverse lookups (PTR) to the configured resolver.
mdns	true	One multicast DNS browse per sweep (UDP 5353) — the .local names Macs, phones, printers and Avahi hosts announce.
netbios	true	A node-status query to each host (UDP 137) — Windows and Samba names, and a MAC.
llmnr	true	A name query to each host (UDP 5355) — Windows with NetBIOS off.
snmp	true	SNMP v2c get of sysName and sysDescr (UDP 161), with the community below.
ssdp	true	One UPnP search per sweep (UDP 1900) — televisions, NAS boxes, consoles, routers, cameras.
ports	true	A TCP connect to a short port list, closed at once. Also gates the TLS, HTTP and SSH reads.
snmp_community	public	Not a credential — what equipment ships with. Set your read-only community to get names from managed switches.
timeout	1200ms	Deadline of each probe.
port_list	[]	Replaces the default twenty ports. Empty uses the default — see network footprint.
oui_file	(empty)	An IEEE registry for manufacturer names. Empty looks in the usual places (ieee-data, arp-scan, nmap), then a small built-in table.
hops	false	Count the routers between here and each off-segment host by stepping the TTL. Costs one round trip per router; turn on for routed ranges.
max_hops	8	Where a hop count gives up.
internet	true	Once per sweep: a TCP handshake to port 443 of 1.1.1.1, 8.8.8.8 and 9.9.9.9, and cloudflare.com resolved.
public_ip	true	Once per sweep: one HTTPS request to https://1.1.1.1/cdn-cgi/trace for the network’s public address and country.

topology — the local copy

Key	Default	Description
name	My Network	The name written in the local file.
output	topology.json	A plain .json filename, written after every sweep for whoever stands at the machine. Paths are refused.

Under the systemd service the file is in /var/lib/infrality-agent/.

metrics

Key	Default	Description
enabled	true	Serve Prometheus metrics from run and daemon. See metrics.
listen	127.0.0.1:2112	Loopback by default. 0.0.0.0:2112 publishes it to the network.

A complete file

/etc/infrality-agent/config.yaml

agent:
  name: 'Head office'

ingestor:
  api_key: 'nk_…'
  base_url: 'https://api.infrality.io'
  project_id: '' # chosen on the dashboard

scan:
  # cidr and mask left out: the network this machine is on
  timeout: 90s
  interval: 0 # only when asked

workers:
  count: 50

discovery:
  snmp_community: 'public'
  public_ip: true

metrics:
  enabled: true
  listen: '127.0.0.1:2112'