Everything an operator needs, start to finish.

From the .deb package

The postinst step creates the etminan-agent (group tss) and etminan-verifier system users, /var/lib/etminan-{agent,verifier}, and /etc/etminan-{agent,verifier}/ — but enables nothing. Pick the role(s) this host plays:

etminan-agent-ima-policy.service is a one-shot unit that writes the IMA measurement policy once, early at boot, before the agent daemon starts — zero manual reboot/policy steps needed. It's idempotent: if a policy is already active this boot, that's treated as success, not an error. etminan-verifier.timer runs etminan-verifier run hourly (OnBootSec=10min, OnUnitActiveSec=1h) — one pass over every enrolled host, firing the alarm path on anything wrong. etminan-verifierd.service is the long-running RBAC daemon that every operator action goes through: it authenticates each operator by Unix UID over a local socket, holds the single signing key, and signs authorised actions on their behalf (see Configuring the verifier to bootstrap the first admin, and the op identity reference).

From the prebuilt tarball

For a distro without .deb support, unpack the signed release tarball by hand (import the Etminan Team key from the Downloads section first). Copy the etminan-agent/etminan-verifier binaries onto PATH and the unit files under deploy/ into place, then create the service users and directories the .deb's postinst would have created for you. The .deb remains the recommended path on Debian/Ubuntu — it wires all of that up automatically.

Shell completion (bash/zsh/fish)

Tab-completes subcommand and flag names for both binaries (op's and op exclude's / op identity's nested actions included) — not flag values (host ids, file paths, etc.), which are operator-specific and not enumerable. Hand-written, not generated: neither binary uses clap (or any CLI-parsing crate) — both hand-roll std::env::args() + match — so there's no clap::Command for clap_complete to derive completions from. These scripts are a hand-maintained twin of the usage string in verifier/src/main.rs/agent/src/main.rs and the man pages — nothing automatically keeps them in sync if a flag changes, the same discipline this project already applies to this page and its Markdown twin.

Installed from the .deb package: nothing to do for zsh or fish — both load /usr/share/zsh/vendor-completions/ and /usr/share/fish/vendor_completions.d/ automatically. Bash needs the bash-completion package (a Suggests:, not a hard dependency — most Debian/Ubuntu systems already have it) to dynamically source /usr/share/bash-completion/completions/:

Open a new shell (or source /usr/share/bash-completion/completions/etminan-verifier in the current one) and etminan-verifier <Tab> / etminan-agent <Tab> should list subcommands.

Running from the tarball, not the .deb: the same files ship at deploy/completions/{bash,zsh,fish}/ — source or copy them by hand:

Installed from the .deb package: nothing to do. postinst already created the etminan-verifier-plugin user, and etminan-verifier.service already carries the AmbientCapabilities=CAP_SETUID CAP_SETGID grant that lets sandboxing actually happen. Confirm it's active:

The second command should include CAP_SETUID and CAP_SETGID in its output. If either command comes back empty, see "Upgrading from an older install" or "Running from the tarball" below.

Protect the daemon signing key and the baseline database — this is the one thing sandboxing doesn't do for you automatically, because it's your files, not this project's:

Neither should be readable by etminan-verifier-plugin — in practice this almost always already holds with no changes needed (the daemon signing key is 0600 and owned by the etminan-verifier daemon user, not group-readable by anyone; baseline.db is created 0600, owned by etminan-verifier, and etminan-verifier-plugin isn't in that user's group by design — see debian/postinst's own comment on why it's deliberately a separate group). If you've manually loosened either file's permissions (e.g. chmod 644 while debugging something), tighten it back up — sandboxing only closes this gap if the file permissions actually keep the plugin user out.

Upgrading from an older install: apt upgrade/dpkg -i re-runs postinst, which creates the user and reloads systemd (systemctl daemon-reload) automatically — nothing else needed, since etminan-verifier.service is Type=oneshot (no persistent process to restart); the very next scheduled run (or manual op check) already picks up the new capability grant.

Running from the tarball, not the .deb (see "From the prebuilt tarball" above): postinst's steps aren't run for you, so do them by hand once:

and copy deploy/etminan-verifier.service (which already carries the AmbientCapabilities=/CapabilityBoundingSet=/NoNewPrivileges= lines) into place rather than hand-rolling your own unit file.

Opting out: set ETMINAN_PLUGIN_USER= (explicitly empty) in verifier.env — plugins then run as etminan-verifier's own user, matching every install before this feature existed. There's rarely a reason to do this on a real deployment; it exists mainly for local development, where the dedicated user usually isn't provisioned anyway.

Running etminan-verifier interactively (sudo -u etminan-verifier etminan-verifier op check ..., during initial setup/testing, or any manual invocation outside the systemd unit) never holds CAP_SETUID/CAP_SETGID — only the unit's AmbientCapabilities= grants that. Sandboxing degrades automatically in that case: a warning is printed (could not drop plugin '<name>' to ETMINAN_PLUGIN_USER ...) and the plugin still runs, just as etminan-verifier's own user, exactly like before this feature existed. This is expected for interactive use, not a misconfiguration to chase down — only the scheduled run via etminan-verifier.timer needs the capability to actually be sandboxed.

Takes a first quote, validates it self-consistently (refuses to enroll on a malformed/inconsistent quote rather than seed a bad baseline), and prints the AK fingerprint. Before pinning anything, enroll also runs an EK credential-activation challenge (TPM2_MakeCredential → ActivateCredential) and refuses to enroll unless the host's TPM recovers the sealed secret — proving the AK resides in a real TPM, not a software key of the right shape. Confirm the printed fingerprint out-of-band — e.g. read it off the host's console — before trusting it; the residency proof establishes it's a genuine TPM, this human step confirms it's the right host's TPM. --reason is required: the enrollment decision itself is signed and recorded in the audit log. No key file — the daemon authenticates your Unix UID and signs the record on your behalf.

Optional: require genuine manufacturer hardware with --ek-roots <dir>. Credential activation proves the AK and EK live in the same TPM, but not that that TPM is real silicon rather than a software/emulated one under a compromised hypervisor. When you pass a directory of trusted TPM-manufacturer CA certificates, enroll additionally requires the host to present an EK certificate (read from TPM NV) whose key matches the activated EK and which chains, by signature, to a self-signed manufacturer root in that directory — closing that gap for discrete TPMs:

Put the manufacturer's root AND intermediate CA certificates (PEM or DER, one per file or bundled) in that directory — download them from your TPM vendor. With the flag, a host whose TPM ships no EK certificate (typical for vTPMs and swtpm) is refused, so it's a deliberate hardware-only mode; the verified certificate's fingerprint is recorded in the host's state and folded into the signed enrollment record. Without the flag, enrollment relies on residency alone (the default). Scope, stated plainly: RSA manufacturer CAs only (an ECDSA issuer is rejected with a clear error), and there is no CRL/OCSP revocation checking yet.

Every measurement from that first quote is recorded as pending, never auto-trusted — review and approve it to seed the baseline:

What to expect right after enrollment: every entry in that first op review shows (new file, no prior baseline) — there is no baseline yet, so nothing can look like a modification. That's expected, not a warning sign; it's establishing the starting point, not detecting tampering. This is the one moment a single bulk op approve web-01 covering everything is normal — from the next hourly run onward, approvals should be small and specific to what actually changed.

When and how a channel is executed

At the end of a op check/run cycle, if there's at least one finding, the verifier runs every plugin named in ETMINAN_NOTIFY_CHANNELS. Each finding is first filtered against that channel's own ETMINAN_NOTIFY_<CHANNEL>_SEVERITIES (unset means every severity reaches that channel), then the surviving findings are piped as one JSON array on the plugin's stdin — never argv, since finding text is free-form and shouldn't be shell-escaped into a command line:

[
  {"host_id": "web-01", "text": "quote signature failed to verify", "severity": "critical",
   "kind": "signature-invalid", "formatted": "[signature-invalid] web-01: quote signature failed to verify"},
  {"host_id": "web-02", "text": "3 pending item(s) aged past the 24h review SLA", "severity": "warning",
   "kind": "sla-exceeded", "formatted": "[sla-exceeded] web-02: 3 pending item(s) aged past the 24h review SLA"}
]

A channel's exit code is the only signal read back: 0 means it fired successfully, non-zero means "didn't fire this cycle" — logged, never retried, never allowed to block the rest of the cycle or the other configured channels. kind is a stable, machine-matchable category (e.g. signature-invalid, sla-exceeded); formatted is this channel's own pre-rendered display text, reshapeable per channel via ETMINAN_NOTIFY_<CHANNEL>_FORMAT with no plugin script edit. Full field-by-field reference and every kind value: Notification channels.

What each shipped reference plugin actually does with that input

Setting up a channel

Adding a channel that isn't shipped (Microsoft Teams, SMS, an internal on-call system) is the same plugin recipe as any other category — write a script that reads the findings JSON from stdin and exits non-zero on failure: see the Plugin API and the full notification-channels worked example.

etminan-verifier.timer calls run hourly. It confirms the presented AK still matches enrollment, the signature is valid, and the replayed IMA log's digest matches the signed PCR10 — any failure is a critical finding, fed straight to the alarm path and recorded in the audit log. Unchanged measurements are silent; new or changed ones go to pending_review. Any pending item older than the review SLA (24h by default) is escalated to a warning-severity finding — pending review is never a silent, indefinite state.

When package-ownership correlation finds a match, baseline review shows a third line beyond ownership: whether this exact version arrived via a real, timely, authenticated transaction — e.g. "✓ installed via an authenticated apt transaction at 2026-07-21 10:00:00." or, on an rpm host, "✓ signed with trusted key a1b2c3d4e5f6a7b8." A mismatch is a loud "⚠ ... — treat with suspicion." rather than a soft note. Note dpkg's line never claims a signature check — only whether the install went through APT's own authentication — the wording says so explicitly rather than implying rpm-level confidence it doesn't have.

Every command that changes trust-relevant state — op enroll, op approve/op reject/exclude create/revoke, op assign-profile, op rotate-tls — is signed by the etminan-verifierd daemon on the authenticated operator's behalf (the operator holds no key) and appended to a self-contained, hash-chained audit log: deleting, editing, or reordering any past entry breaks the chain for everything recorded after it. No external tool is involved. Verify the whole store on demand with op verify-signatures.

The verifier is the single place an alarm can fire — so if it stops working, silence looks exactly like “all healthy”. A broken or compromised verifier can't be trusted to report its own failure, so an independent monitor, running on a separate system this box does not control, should watch everything the verifier's function depends on. It is deliberately product-agnostic — any external uptime / dead-man's-switch monitor works; what matters is which signals it watches:

• The attestation cycle completes — etminan-verifier.timer fires and etminan-verifier run finishes successfully within its interval. The primary heartbeat: if it stops, attestation silently stops.
• The verifier service is healthy — etminan-verifier.service is active, not failed, masked, or crash-looping.
• Notification delivery works (email & channels) — a finding is worthless if it can't leave the host. Exercise the mail relay and every configured channel on a schedule (etminan-verifier notify-test) so a dead SMTP relay or webhook is caught before a real alert needs it.
• The database and audit log are intact — baseline.db and its audit log are readable and the disk holding them has free space; a full or unwritable disk stalls both attestation and the signed log.
• The firewall still enforces default-deny — the zero-inbound posture hasn't drifted open; no port has quietly started listening on this host.
• Every enrolled host is reachable — the verifier can open its pinned mutual-TLS connection to each agent it pulls quotes from; a host it can no longer reach is a silent attestation gap, not a clean result.
• Host liveness and clock — the host is up and its time is synced; certificate validity and audit-log timestamps depend on it.

Emit the heartbeat on a successful cycle and let an off-box service alert when a ping is overdue or a check fails:

Give each check a grace period slightly longer than the cycle interval (e.g. alert if no heartbeat within 75 minutes for the hourly timer) so one slow cycle doesn't page anyone, but two consecutive misses reliably does. The verifier-hardening guide covers the full rationale.

state.json — per-host enrollment state

One JSON object per enrolled host, keyed by host id, at $ETMINAN_VERIFIER_STATE (default /var/lib/etminan-verifier/state.json). Written atomically (temp file + fsync + rename) on every update.

baseline.db — SQLite schema

At $ETMINAN_BASELINE_DB (default /var/lib/etminan-verifier/baseline.db), WAL mode — back up the -wal/-shm sidecars alongside it.

Signed action payloads

Every signed action's payload is deterministic, canonical JSON — object keys sorted lexicographically at every nesting level, no whitespace between tokens, string fields escaped exactly as JSON requires (a literal newline inside a field becomes the two characters \n, never a raw newline byte). Built this way specifically so the exact bytes signed can be reconstructed and re-verified outside this tool (e.g. with a Python or openssl Ed25519 check), not just trusted because the tool says so — and so that a field containing attacker-influenceable content (a path sourced from the IMA log on a possibly-compromised host, which can legally contain a newline) can never be ambiguous about where one field ends and the next begins. Prior to 2026-07-22 these payloads were hand-rolled \0/\n-joined text; already-signed rows keep verifying against their own stored bytes regardless of which format produced them, so this was a forward-only change, not a migration.

Signatures are Ed25519 over the exact payload bytes above, hex-encoded (128 hex chars). Every one of these is signed by the etminan-verifierd daemon on the authenticated operator's behalf — the operator holds no key. The daemon's own signing key (/var/lib/etminan-verifier/daemon-signing.key) is a raw 32-byte seed, hex-encoded (64 hex chars) at file mode 0600 — no PEM, no DER, nothing but hex text.

audit_log — the hash chain, and how to recompute it independently

Each row's entry_hash is SHA256(canonical_json({seq, recorded_at, actor, action, resource, severity, detail_canonical: detail, prev_hash})), hex-encoded. "Canonical JSON" means object keys sorted lexicographically at every nesting level and no whitespace between tokens — deterministic regardless of what produced the row. The very first row's prev_hash is 68 zero characters (the genesis sentinel, not a real hash of anything). op verify-signatures already walks this chain for you; the formula above is what you'd reimplement to check it with an independent script instead of trusting this binary's own verification.

Alarm severities

Only two values exist anywhere in this project — there is no "info" or "error" tier for findings, by design:

Both values are valid in every severity-filter env var — ETMINAN_NOTIFY_EMAIL_SEVERITIES and every ETMINAN_NOTIFY_<CHANNEL>_SEVERITIES — as a comma-separated list.