# Linux host — Grafana Alloy agent

For Debian/Ubuntu hosts (amd64, arm64; armv7 via Grafana's APT repo). Installs
**Grafana Alloy** as a systemd service — the only agent. It collects metrics
(node_exporter is built in) and logs, and **pushes** both over HTTPS to the
monitoring server. Nothing listens on the host; it needs only outbound 443.

## Install

On the monitoring server, create the host's one-time enrollment code:

```bash
./host.sh add web01
```

Then on the host, run the command it prints:

```bash
curl -fsSL https://<INGEST_HOST>/install-linux.sh | sudo ENROLL=<code> bash
```

The installer:

1. trades the code for this host's push token (the name comes from the code);
2. installs Alloy from `https://<INGEST_HOST>/` (pinned, checked against
   `SHA256SUMS`);
3. writes `/etc/alloy/config.alloy` (this folder's `config.alloy`),
   `/etc/default/alloy` (`NODE_NAME`, `INGEST_URL`) and the token
   (`/etc/alloy/monitor-token`, `root:alloy 0640`);
4. removes this repo's old pull agent (`node_exporter` service on `:9100`) if
   present;
5. waits until the server confirms it has received data.

**Upgrade or repair:** run the same command **without** `ENROLL=` — the token
is kept. **Re-enroll / rotate the token:** `./host.sh add web01` again and use
the new code.

Without the served copy (e.g. offline, from this folder): set `INGEST_URL`
(and `ENROLL`) in `.env` next to `install.sh` — see `.env.example` — and run
`sudo ./install.sh`. It still downloads Alloy from the ingest site.

## What gets shipped

- **Metrics** every 30 s: everything node_exporter reports (CPU, memory, disks,
  filesystems, network, processes, systemd), labelled `job="node"`,
  `instance="<name>"`. Buffered on disk while the server is unreachable.
  Trimmed to what matters: per-unit systemd states only as `failed`, and
  network metrics only for real interfaces (`eth*`/`en*`, bonds, VLANs) and
  WireGuard (`wg*`) — not loopback or Docker's `docker0` / `br-*` / `veth*`
  (their traffic is already counted on the real interface). The exclusion
  list is in `config.alloy` (`netdev` / `netclass`).
- **Logs:** the systemd journal (labels `unit`, `level`) plus `/var/log/syslog`
  and `/var/log/auth.log`, labelled `host="<name>"`.

Covered by `prometheus/alerts/node.rules.yml` (including `HostNotReporting`)
and the **Hosts Overview** / **Host Details** dashboards.

## Firewall

None needed on the host: Alloy only makes outbound HTTPS connections.

## Uninstall

```bash
sudo systemctl disable --now alloy
sudo apt-get remove -y alloy
sudo rm -f /etc/alloy/monitor-token
```

Then on the server: `./host.sh remove <name>` (otherwise it alerts as not
reporting).