tail-watch

Know whether the things on your tailnet are reachable, and which layer broke when they are not.

Tailscale connects your devices, services and networks into one secure tailnet, and shows you which nodes are part of it. tail-watch builds on that foundation and watches the rest: whether you can reach the things that matter, such as a NAS behind a subnet router, an internal service, or a remote office LAN. It runs beside a node on your tailnet, probes the devices you choose, and tells you what failed: the route, the tunnel, the LAN behind a subnet router, or the service itself. When a subnet router goes down, you get one alert for the router, not one for every device behind it.

What you get

• Four checks. icmp, tcp, http (with an optional body match) and tsping, each on its own interval and timeout.
• A named failure layer. Every failed check is labeled unrouted, control, tunnel, lan or service, so the alert starts the diagnosis.
• Router-aware alerts. tail-watch learns which subnet router a LAN target depends on and suppresses the devices behind it while the router is down.
• One alert per outage. Alerts fire on state changes, with flap damping, to Slack, Microsoft Teams or a signed webhook. Routes pick which sinks hear a monitor, and a sink can keep its queue on disk across restarts.
• Prometheus metrics and a health check. /metrics and /healthz sit beside a status page at /.
• An opt-in monitor UI to add, edit and delete monitors on a running collector.
• One static binary and one YAML file. It is also a container image, and it can run as a sidecar in a Kubernetes ProxyGroup.

Quickstart

1. Download the archive for your platform from the releases page and extract it. Deploy has the checksum steps. No Go toolchain is needed.

2. Put your targets in a copy of examples/tail-watch.yaml, which is in the archive.

3. Check the file, then start the collector:

   tail-watch check-config --config tail-watch.yaml
   tail-watch --config tail-watch.yaml

The status page is at http://127.0.0.1:9109/ and metrics are at /metrics.

To run it as a container, under systemd, or with Docker Compose when you have no dedicated host, see Deploy tail-watch. To go from nothing to your first alert, follow the tutorial.

Requirements

• A host running tailscaled in kernel mode. Userspace networking cannot carry ICMP to LAN addresses, so tail-watch refuses it at startup.
• The host tagged tag:monitor, with grants for what you monitor. See Write the ACLs.
• A process that can open the LocalAPI socket, by default /var/run/tailscale/tailscaled.sock.

Setting collector.local_only drops the tailscaled requirement for the Kubernetes sidecar. See Watch a Kubernetes ProxyGroup.

How it works

The collector runs each check on its interval and keeps one state per target: UNKNOWN, UP, DOWN or SUPPRESSED. A target goes DOWN after consecutive failures, and the failure is classified by layer from the tailnet's own view of the path. A target that depends on a down router becomes SUPPRESSED instead of paging. Only transitions notify. For the reasoning, read Failure layers and Alert state.

Documentation

Every page is listed in the documentation index. Start here:

I want to	Read
Learn by doing	Set up your first monitor, Receive your first webhook
Install and secure it	Deploy, Write the ACLs, Troubleshoot
Monitor more	Remote subnets and LANs, Kubernetes ProxyGroup, Manage monitors in the UI
Get alerts	Slack, Microsoft Teams, Webhook, Routes, Heartbeat
Look something up	Configuration, Command line, Checks, Metrics, Event payload
Understand the design	Failure layers, Alert state, Incidents and queues, Monitor UI risks

Build from source and contribute

Go and the other tools are pinned in mise.toml:

mise install
mise run build   # writes bin/tail-watch
mise run check   # builds, tests, and lints

See Development and releases for the release process and CONTEXT.md for what the project will not do.

License

BSD 3-Clause. See LICENSE.