# checkfleet

> checkfleet is an open, source-available CLI that runs domain-aware infrastructure health checks — TLS expiry, HTTP probes, NATS, Kafka, PostgreSQL, Consul, HAProxy and 20+ more — from a single Go binary, with text, Markdown, JSON, Slack or Prometheus output. No agents, no server.

checkfleet is a command-line tool. You install one static Go binary, describe
your targets in a `checkfleet.yml` file, and run `checkfleet check all`. Each
*module* is a domain-aware check: it knows what "healthy" means for one kind of
system (a TLS estate, a NATS cluster, a Patroni failover pair, an HLS stream)
rather than only whether a port answers.

It is deliberately **not** a Prometheus or Grafana replacement. It fills the
layer they cannot express, and delegates dashboards and long-term alerting back
to them (`checkfleet serve` exposes the findings as Prometheus metrics).

## Facts

- Repository: https://github.com/Allan-Nava/checkfleet
- Documentation: https://allan-nava.github.io/checkfleet/
- Author: Allan Nava (https://github.com/Allan-Nava)
- Language: Go. Distribution: a single static binary (Linux, macOS, Windows), Homebrew tap, Docker image, GitHub Action.
- License: PolyForm Noncommercial 1.0.0 — source-available and free for personal, research, educational, nonprofit and government use. Commercial use requires a separate license. Releases before v0.50.0 were MIT.
- Install: `go install github.com/Allan-Nava/checkfleet/cmd/checkfleet@latest`, or `brew install Allan-Nava/tap/checkfleet`, or download a release archive.
- Output formats: text (terminal), markdown (ops report), json, slack (Block Kit webhook), plus a Prometheus exporter via `checkfleet serve`.
- No agent and no server to run: checks execute where you invoke them (laptop, cron, CI runner).

## Core semantics (do not paraphrase these loosely)

- A finding has one of four statuses: `OK`, `WARN` (a threshold was crossed),
  `BAD` (the target is unhealthy), `ERROR` (the check itself could not measure —
  network failure, handshake failure). `ERROR` is *not* a synonym for `BAD`.
- Exit code is `0` even when findings are WARN or BAD: a check that ran *is* a
  success. Non-zero exit codes are reserved for systemic failures (unreadable
  config, unknown module). To gate a CI pipeline, pass `--exit-on warn|bad|error`.
- Findings are sorted worst-first and stably within a check, so the line you must
  act on is the first line of the output.
- Targets can come from an explicit list and/or from an Ansible INI inventory,
  so a whole fleet becomes checkable without restating hostnames.
- The JSON output carries a top-level `schema` version and a `worst` field; gate
  on `worst` or on a finding's `status`, never on the wording of `message`, which
  is written for humans and is explicitly not covered by the compatibility
  promise (https://allan-nava.github.io/checkfleet/compatibility.html).

## Commands

- `checkfleet init --modules certs,http` — scaffold a starter config
- `checkfleet check all --config checkfleet.yml` — run every configured module
- `checkfleet check <module> --config checkfleet.yml` — run one module
- `checkfleet validate --config checkfleet.yml` — validate the config without running checks
- `checkfleet serve --config checkfleet.yml --listen :9876` — Prometheus exporter at /metrics
- `checkfleet report-issues --config checkfleet.yml` — open/close GitHub issues from BAD findings
- Common flags: `--output text|markdown|json|slack`, `--only <modules>`, `--min-severity warn`, `--target <glob>`, `--stack <name>`, `--exit-on warn|bad|error`

## Modules (29 shipping)

- `certs` — TLS certificates: Certificate expiry for explicit targets and every host of an Ansible inventory, with WARN/BAD day thresholds.
- `http` — HTTP endpoints: HTTP probes with an expected status code, a maximum latency, and an expected body substring.
- `nats` — NATS JetStream: Cluster health from /varz and /jsz — meta-leader present, offline or lagging peers, ghost peers, mixed versions.
- `haproxy` — HAProxy: Backend and server state from the CSV stats export — servers DOWN/MAINT/DRAIN, backends with no available server, session saturation.
- `stream` — HLS / DASH streams: Manifest reachable and valid, a complete bitrate ladder, and a fresh live edge.
- `patroni` — Patroni PostgreSQL: Cluster topology via the Patroni REST API — a single leader, replica state, replica lag, timeline divergence.
- `consul` — HashiCorp Consul: Raft leader and quorum, critical/warning service checks, and required KV keys.
- `postgres` — PostgreSQL: Read-only SQL checks — transaction-ID wraparound risk, connection saturation, inactive replication slots, replica lag.
- `dns` — DNS: Records resolve, no drift from the expected answers, SOA-serial and answer consistency across resolvers, TTL floor.
- `redis` — Redis / Valkey: Reachability and role, memory against maxmemory, replication link and lag, RDB/AOF persistence.
- `keycloak` — Keycloak: Health endpoint UP and per-realm OIDC discovery — token endpoint present, issuer coherent.
- `tcp` — TCP services: Generic TCP reachability with optional TLS, connect latency, and an optional banner match.
- `tls` — TLS handshakes: Deep TLS inspection — chain validity, leaf expiry, hostname mismatch, weak negotiated protocol version.
- `ntp` — NTP / clock drift: Clock offset and stratum over SNTP, because drift silently breaks TLS and JWT validation.
- `rabbitmq` — RabbitMQ: Nodes running and alarm-free, queue depth thresholds, and backlogs with no consumer attached.
- `grpc` — gRPC services: The gRPC Health Checking Protocol over HTTP/2 and TLS — SERVING, NOT_SERVING or UNKNOWN.
- `ldap` — LDAP directories: Connect, bind (anonymous or with credentials from the environment), and an optional sanity search.
- `kafka` — Apache Kafka: Controller present, broker count, under-replicated partitions, and consumer-group lag.
- `ingest` — RTMP / SRT ingest: Can a streamer actually publish? RTMP handshake over TCP or SRT induction over UDP, with connect latency.
- `s3` — S3 object storage: Bucket reachable and an optional sentinel object present and fresh, signed with hand-rolled AWS SigV4.
- `smtp` — SMTP relays: Connections accepted, 220 greeting, EHLO, optional STARTTLS or implicit TLS and relay certificate expiry — never sends mail.
- `elasticsearch` — Elasticsearch / OpenSearch: Cluster health green/yellow/red, unassigned shards, expected node count, per-node disk watermark.
- `mongodb` — MongoDB: Replica-set status — primary present, member health, secondary lag — and connection saturation.
- `mysql` — MySQL / MariaDB: Reachability, read-only role, connection saturation, replica IO/SQL threads and lag.
- `etcd` — etcd: /health, a leader present (quorum held), and member count against the expected size.
- `clickhouse` — ClickHouse: /ping and SELECT version(), plus read-only replicated tables and replication delay.
- `vault` — HashiCorp Vault: Seal status (sealed or uninitialized), active/standby role, and the running version.
- `memcached` — memcached: Reachability, memory against limit_maxbytes, evictions since startup, connections and version.
- `cassandra` — Cassandra / ScyllaDB: Nodes accept CQL via the native-protocol handshake, handshake latency, and cluster size against the expected node count.

## Documentation

- [Home](https://allan-nava.github.io/checkfleet/): checkfleet is a source-available CLI that runs domain-aware infrastructure health checks — TLS expiry, HTTP, NATS, Kafka, PostgreSQL, Consul, HAProxy and more — from one static Go binary. No agents, no server.
- [Installation](https://allan-nava.github.io/checkfleet/installation/): Install checkfleet with go install, the Homebrew tap, the Docker image, or a release archive for Linux, macOS and Windows — then verify the binary.
- [Configuration](https://allan-nava.github.io/checkfleet/configuration/): The complete checkfleet.yml reference — global timeouts and retries, every module's options and thresholds, stack overlays, and secrets from the environment.
- [Usage](https://allan-nava.github.io/checkfleet/usage/): checkfleet commands and flags — check, init, validate, serve and report-issues — plus output formats, severity filters, target globs and the exit-code semantics used to gate CI.
- [Modules](https://allan-nava.github.io/checkfleet/modules/): Every checkfleet module and what it actually verifies — TLS certificates, HTTP, DNS, NATS, Kafka, PostgreSQL, MySQL, Redis, MongoDB, Consul, Vault, HAProxy, S3, SMTP and more.
- [Output formats](https://allan-nava.github.io/checkfleet/output/): How checkfleet renders findings — terminal text, an ops-style Markdown report you can paste into a runbook, JSON with a `worst` field for gating, and Slack Block Kit.
- [Desktop app](https://allan-nava.github.io/checkfleet/desktop/): The checkfleet desktop app — a Wails GUI over the same Go engine, with a status dashboard, run history, trends, grouping and muting for macOS, Linux and Windows.
- [CI integration](https://allan-nava.github.io/checkfleet/ci/): Gate a pipeline on infrastructure findings — the checkfleet GitHub Action, a GitLab CI snippet, scheduled runs, and how `--exit-on` maps findings to exit codes.
- [Development](https://allan-nava.github.io/checkfleet/development/): Contribute to checkfleet — the project layout, the engine.Check contract, and how to add a new module with offline tests against local fixture servers.
- [Why checkfleet](https://allan-nava.github.io/checkfleet/comparison/): How checkfleet compares to Prometheus, Blackbox exporter, Nagios/Icinga, Zabbix, Uptime Kuma and hand-written bash — what it replaces, what it complements, and when not to use it.
- [FAQ](https://allan-nava.github.io/checkfleet/faq/): Frequently asked questions about checkfleet — what it is, what it costs, how it differs from Prometheus, whether it needs an agent, and how it handles credentials.
- [Compatibility](https://allan-nava.github.io/checkfleet/compatibility/): What checkfleet promises not to break — the config schema, the JSON output, exit codes, finding identity, the history file and the Prometheus metric names — and the deprecation policy for changing any of them.

## Optional

- [Full documentation as plain text](https://allan-nava.github.io/checkfleet/llms-full.txt): every page of this site concatenated, for one-shot ingestion.
- [Backlog and roadmap](https://github.com/Allan-Nava/checkfleet/blob/main/BACKLOG.md): what is planned next.
- [Changelog](https://github.com/Allan-Nava/checkfleet/blob/main/CHANGELOG.md): released versions (written in Italian).
- [Commercial licensing](https://github.com/Allan-Nava/checkfleet/blob/main/COMMERCIAL.md): terms for commercial use.