What it watches · 3 of 14
Network and service maps
Maps that draw themselves from what the agents see: sites, links and WireGuard tunnels on one; services and what each needs on the other. Corrections instead of configuration, and readable at thousands of hosts.
Cairn OBS draws two maps with nothing written by hand. A host that joins, a compose project that starts, a cluster that's added: each shows up in the right place within a few reports, with what it talks to.
Where it comes from
Each report carries a sample of the host's sockets, taken by the root helper: which process or container listens on which port, and which connections it has. The helper works out each socket's owner (a container or a systemd unit), and the agent shrinks the sample before sending it:
- Listeners: owner, protocol, address and port.
- Outgoing connections: owner, the address and port at the far end, and how many.
- Incoming from private addresses: owner, local port, the remote address, and how many.
- Incoming from public addresses: owner, local port, and a count.
No Internet client's address ever leaves the host. People's addresses from the Internet aren't stored anywhere.
It's read-only and small: no packet capture, no eBPF, no payloads, no command lines. Each agent also sends its interfaces, addresses and default gateway, and its WireGuard interfaces and peers.
map: false in a host's agent.yaml turns the
sample off there.
The network map
| What | From |
|---|---|
| Sites | Hosts that share a private network (RFC 1918, ULA or CGNAT) are on one; a site is the hosts joined by private networks. Container bridges don't count |
| WireGuard links | Each peer's key matched to another host's interface key: a fact, not a guess. Up while the last handshake is under three minutes old. A peer that isn't one of your hosts is counted as an outside peer |
| Other links | Connections between hosts, drawn with their ports |
| The way in | Listeners on public addresses with connections from the Internet; with Cloudflare set up, the Cloudflare box and its pools |
| Clusters | A box of its nodes, each linked to its host agent where it has one |
| Remote hosts | A host with no private network in common with a site, but a WireGuard link to it, is drawn off-site with that link |
It opens on an overview, one box per site and cluster, and you go in: a site's hosts (past 60, grouped by role, name pattern or subnet), then one host with everything it's linked to.
The service map
A service is a named group of parts, found like this, first match wins:
- A compose project; its containers are the parts.
- In Kubernetes, controllers sharing an
app.kubernetes.io/part-oflabel, elsenameorinstance; else each controller is its own, grouped under its namespace. A KubeVirt VM is a part, like a controller. - A systemd unit that listens on a port. The same unit on several hosts is one service with a part on each.
- A container outside compose, grouped with others from the same image.
What a service needs comes from the connections: a part connected to a port another service listens on needs that service. In Kubernetes the API says it outright (an Ingress points at a Service, a Service picks its pods), and those edges count as declared.
Tiers (edge, apps, data) are worked out, not written: what takes traffic from the Internet is the edge, what only gets connected to is data. Past 150 services the overview groups them, and focusing on one shows what it needs and what needs it, three steps each way. Every view can be linked to.
When a learned edge is believed
| Stage | When | Drawn |
|---|---|---|
| Seen | At once | Thin and dashed |
| Steady | Seen in at least three separate hours within seven days | Solid |
| Fading | Not seen for 14 days | Faint, then dropped after 30 days |
Only declared and steady edges are used to group alerts by cause (How alerts work), and an incident grouped by a learned edge says so: "Grouped because webmail has talked to postgresql :5432 since Nov 2." Not a dependency, on the incident or the map, rejects that edge for good.
Corrections
Admins can correct what was found, on the map:
- Rename a service or site ("Office LAN" rather than "10.20.0.0/24").
- Set a service's tier.
- Merge two services, or move a part out into another or a new one.
- Hide a service or a host.
- Confirm a learned edge, or reject one.
- Add an outside service (a payment provider, another company's mail relay) by its addresses, and what needs it.
Corrections key on stable names (the compose project, the unit, the
controller, the WireGuard key), so they survive restarts, redeploys and
pods being replaced, and later discovery never undoes them. They're kept
with the other settings, and export and import like them. They need a
database.
topology.yaml is the same corrections in a file, with names and roles for hosts and services you declare yourself.