# The addons agent

Source: https://www.pingtower.com/docs/addons/

A single Go binary you install on external servers. It runs addons, small tasks that measure something about a target, on a schedule, and reports the measurements to the tower as ordinary events. Your rules do the rest.

<div class="docs-flow"><span class="st">addons agent</span><span class="ar">→</span><span class="st">check every 60s</span><span class="ar">→</span><span class="st">POST /v1/ingest</span><span class="ar">→</span><span class="st  ttfb_ms gte 500">rule</span><span class="ar">→</span><span class="st open">alert</span></div>


## What it does

- Runs the checks in its config on their own intervals, each with a timeout, up to eight at once.
- Reports on change by default, so a quiet target is not a noisy feed, with a periodic sample so you can see it is still running.
- Spools to disk through an outage, 64 MiB by default, and drains when the tower is reachable again.
- Sends a heartbeat about itself every five minutes, with counts of checks, sensors and failures, so the agent's own health is a rule away from paging someone.
- Never executes a string from the network. There is no route that makes it run a command, restart, or upload a file.

It works identically against the hosted service and a self-hosted box: the tower URL is one line of config.

## Status and levels

Every check ends in a status, and the status becomes the event's level: **up** is 200, **degraded** is 300, **down** is 400, or whatever `down_level` the check sets, typically 500 for one that should page. Each event carries the tags `addon:<name>`, `check:<id>` and `status:<status>`, and the measurements as `keys`, so a rule can threshold any number directly.

## The catalogue

| Addon | Measures | |
| --- | --- | --- |
| [`httpcheck`](/docs/addons/httpcheck/) | DNS, connect, TLS, first-byte and total time; body size; status and body assertions | |
| [`tcpcheck`](/docs/addons/tcpcheck/) | DNS and connect time to a port | |
| [`dnscheck`](/docs/addons/dnscheck/) | Resolve time and answers, against a chosen resolver | |
| [`tlscert`](/docs/addons/tlscert/) | Days until expiry, handshake time, chain length | |
| [`icmpping`](/docs/addons/icmpping/) | RTT min, avg, max; packet loss | |
| [`hostmetrics`](/docs/addons/hostmetrics/) | CPU, load, memory, swap and paging on the agent's own host | |
| [`sshcheck`](/docs/addons/sshcheck/) | Connect, handshake, auth and command time; exit code | <span class="pill priv">privileged</span> |
| [`portscan`](/docs/addons/portscan/) | Open, unexpected and missing ports against a baseline | <span class="pill priv">privileged</span> |
| [`traceroute`](/docs/addons/traceroute/) | Hop count, path change, per-hop RTT | <span class="pill priv">privileged</span> |
| [`logwatch`](/docs/addons/logwatch/) | Pattern matches in a local file, write age, rotation | <span class="pill priv">privileged</span> |
| [`securityupdates`](/docs/addons/securityupdates/) | Pending updates, security updates, reboot required | <span class="pill priv">privileged</span> |

Privileged addons need something beyond an outbound socket: a credential, an external binary, a heavier network footprint, or read access to a host file. They are off by default; a config naming one fails at startup unless it is listed in `agent.enable_addons`.

[Sensors](/docs/addons/sensors/) are the other half: continuous, kernel-level watchers of the box the agent runs on, new in 0.2.0.

## Down from more than one place

Run the same check from three agents and write a rule with `"fire_after": {"count": 2, "window_minutes": 5, "distinct_sources": true}`. One probe's bad network no longer pages you; two agreeing do.


## In this section

- [Install](https://www.pingtower.com/docs/addons/install/index.md): One command on a fresh Linux box, after you have verified what you are about to run.
- [Configure](https://www.pingtower.com/docs/addons/config/index.md): One YAML file. The agent refuses to start on anything it does not understand, which is the point.
- [httpcheck](https://www.pingtower.com/docs/addons/httpcheck/index.md): Fetch a URL and time every stage of it separately, because a slow resolver and a slow server wake up different people.
- [tcpcheck](https://www.pingtower.com/docs/addons/tcpcheck/index.md): Connect to a port and say how long it took, with DNS timed apart from the connect.
- [dnscheck](https://www.pingtower.com/docs/addons/dnscheck/index.md): Resolve a name, optionally against a specific resolver, and check what came back.
- [tlscert](https://www.pingtower.com/docs/addons/tlscert/index.md): Complete a TLS handshake and report how long the leaf certificate has left. Reported on every run, so the threshold lives in a rule, not the agent.
- [icmpping](https://www.pingtower.com/docs/addons/icmpping/index.md): Send a few pings and report round-trip and loss.
- [hostmetrics](https://www.pingtower.com/docs/addons/hostmetrics/index.md): CPU, load, memory, swap and paging on the box the agent runs on. Unprivileged, Linux only, reads a handful of files under /proc.
- [sshcheck](https://www.pingtower.com/docs/addons/sshcheck/index.md): Open an SSH session with a key, optionally run one command, and time every stage. Key-based auth only.
- [portscan](https://www.pingtower.com/docs/addons/portscan/index.md): Scan a host's ports and compare against a baseline. Needs nmap.
- [traceroute](https://www.pingtower.com/docs/addons/traceroute/index.md): Trace the path to a host and notice when it changes. Needs traceroute.
- [logwatch](https://www.pingtower.com/docs/addons/logwatch/index.md): Tail a local file for a pattern. Counts matches, notices rotation, and never sends a line off the box.
- [securityupdates](https://www.pingtower.com/docs/addons/securityupdates/index.md): Count pending package updates on a Debian host, and whether it wants a reboot. Reads only; never installs anything.
- [Sensors](https://www.pingtower.com/docs/addons/sensors/index.md): Checks run on a schedule. Sensors run continuously, subscribed to the kernel, and report the moment something happens on the box the agent runs on.