Alerts

Taranac watches itself and the boxes it runs on, and turns “something is wrong” into a small, stable list of alerts you can work through. An alert is a condition — disk filling up, RADIUS unreachable, an identity being brute-forced — not a stream of events. It opens (fires) when the condition appears and resolves when it clears, so a problem that lasts ten minutes is one row, not six hundred log lines.

This page covers where alerts come from, how severity is assigned, how operators acknowledge and clear them in the admin UI, and how notifications reach you — by email, by syslog to your SIEM, or both — so you hear about the things that matter without being buried.

The Alerts page: severity-sorted firing conditions with acknowledge and resolve actions. This is a standalone install; on a cluster a Node column and a node filter join the toolbar.

Alert — a single condition with a lifecycle. It carries a severity, a title and message, the originating source, an occurrence count, and timestamps for first-seen, last-seen and (once cleared) resolved.

Status — firing / resolved. This is the machine-driven axis. The system opens an alert when it detects the condition and resolves it automatically when the condition goes away. You normally do not set this by hand.

Acknowledged. This is the operator axis, completely separate from status. Acknowledging an alert means “I have seen this and I am on it.” It does not close the alert — the condition is still firing — but it silences repeat notifications so you stop getting reminded about something you are already handling.

Source. The subsystem that raised the alert. The producers that exist today are monitoring (host resources and daemon health), tacacs / radius / nac (AAA anomalies and NAC OCSP failures bridged from the protocol daemons), the three config builders (tacacs_config, radius_config, nac_config — validation failures, inheritance advisories, TACACS+ TLS revocation and the NAC daemon’s revocation-policy support), email (the email channel’s own delivery self-check), alerts (no notification channel configured at all), mfa (provider reachability, and TOTP enrollments left on old parameters), domain (the MS-CHAPv2 machine-account trust), ldap_sync (failed directory syncs), users (one username held by several accounts), nac_crl (certificate revocation lists), nac_pki (the NAC CA bundle), nac_ca_expiry (Internal CA chains), nac_enrollment (EST and SCEP enrollment blocks), backup, license, the Configuration Tracker’s three (ncm_collection, ncm_collector, ncm_drift), collectors (a collector that needs an update), and — only when running clustered — cluster_license (node count or edition against the licence) and cluster_sync (HA health). Every one of them is enumerated under Alert sources below.

Fingerprint. A stable internal identity for the condition (for example disk:/var or nac:brute_force:peap:jdoe). It is what keeps a recurring problem collapsed into one alert: while a condition keeps recurring, Taranac bumps the existing alert’s occurrence count rather than opening duplicates. Once an alert resolves, a fresh occurrence later opens a new one — so you get clean history, not endless churn.

Node. On an HA cluster every alert also records the node that observed and opened it, stamped once on open and kept stable across recurrences. For per-node conditions the fingerprint is additionally scoped to that node (an @<node> suffix), so a healthy peer can never resolve another node’s firing alert — each node keeps its own row. Everything a node observes about itself is scoped that way: host resources, daemon reachability and the daemon-not-authenticating checks, RADIUS and NAC configuration applies and radiusd restarts, config validation, the NAC daemon’s revocation-policy support, the NAC CA bundle, TACACS+ TLS revocation sync, NAC OCSP failures, MFA provider reachability, the domain machine-account trust, both backup alerts, CRL download failures, and the config-apply readiness gate. Conditions that are a function of replicated data, or that only the leader can observe, stay a single alert per cluster, stable across failover: the licence checks, the cluster_sync reconciles, the email self-check, the delivery check, the directory-sync and shared-username alerts, CRL expiry, Internal CA chain expiry, EST and SCEP enrollment blocks, a revoked CA in the TACACS+ TLS trust, the Configuration Tracker and collector-update alerts, and the key/banner inheritance advisories. On a standalone install there is one node and the scoping is inert — the fingerprint is left untouched.

Severity is assigned by the producer, not by the operator. The four levels follow a deliberate rubric:

Two boundary rules make this easy to reason about:

• warning vs error — “about to happen” versus “already happened.”
• error vs critical — is authentication itself impacted, or just a peripheral function?

If a condition gets worse while already firing (for example disk crosses from warning into critical), the alert escalates: its severity is raised, any acknowledgement is cleared, and it becomes eligible to notify again — so an escalation always gets your attention even if you had silenced the milder version.

Everything below is the complete catalogue: every condition the product can raise today, with its fingerprint, severity and scope. Unless a row says otherwise, an alert auto-resolves on the next healthy observation of the same condition — you never have to close it by hand.

The evaluator reads live host metrics every cycle and compares them against configurable percentage thresholds. All of these are per node — they are read from this machine’s psutil:

A threshold breach must persist for alerts.sustained_minutes (default 2) before the alert opens — this debounce stops a momentary CPU spike from paging you. Recovery clears the alert immediately, no debounce. Setting a level’s threshold to 0 disables it.

Disk alerts cover the mounts that can fill up. Read-only image mounts — a snap package (SquashFS), an installer or cloud-init seed (ISO 9660, UDF), an EROFS or CramFS image — are always exactly as full as their content, so they are not checked at all. A mount that disappears (unmounted, or its device removed) has its disk:<mount> alert resolved on the next cycle rather than left firing for a disk that is no longer there.

Daemon health is checked with no debounce — an AAA outage should surface at once. Two different questions are asked, and the second exists because the first is not enough:

All five are node-scoped: the node that lost its database is the one that is degraded, and a healthy peer must not clear its alert.

The service:*_backend trio states the condition the port check misses. Under load on the stand, TACACS+ refused 163 of 180 logins while the container stayed healthy, port 49 answered and cluster status printed Healthy — a daemon that has lost its database says a cheerful yes to “is your port open?” and refuses every authentication it receives. These alerts are reported by the daemon itself, not inferred.

The 30 seconds is a grace, not a debounce. A daemon that has just come up refuses while its workers load their caches — 7 to 20 seconds on a loaded node — so without the grace a routine docker compose up -d would land a critical alert and an email that resolved a minute later. A real outage lasts until the database comes back, so it clears the grace on its first evaluation and alerts at once, exactly as service:tacacs / service:radius do.

There is no service:nac port check — the NAC daemon’s liveness is covered by service:nac_backend alone.

The radius and nac containers run radiusd under a supervisor that applies every configuration by starting a new radiusd beside the running one (Applying a configuration). What it reports becomes two node-scoped families under the same source:

When you change AAA configuration, the config jobs re-render and validate it against the daemon’s own binary. They also re-run the device-key and banner inheritance analysis while they are there, and surface anything ambiguous as an advisory:

Validation is node-scoped because it runs this node’s binary against this node’s rendered files — a local render fault, or a lagging replica’s data, can fail on one node while a peer’s succeeds. The three advisories are a deterministic function of the replicated configuration, identical everywhere, so they stay cluster-wide.

The banner advisory has its own fingerprint deliberately: a banner ambiguity and a key ambiguity are different faults with different fixes, and sharing one fingerprint would let whichever synced last clear the other’s alert.

Email is one of the alert engine’s own notification channels, which makes a broken SMTP a blind spot — alert mail would silently never arrive. Taranac watches its own outgoing-mail audit trail (EMAIL_SENT / EMAIL_FAILED) and opens an error alert (email:delivery) after alerts.email_failure_threshold failures since the last success (default 3). It resolves on the next successful send, or once the failures age out of a 24-hour lookback window. Set the threshold to 0 to turn the self-check off.

The audit trail is replicated, so this reads identically on every node. It is therefore reconciled on the leader only and stays cluster-wide — node-scoping would report one broken mail server once per node.

The quieter blind spot is having no channel at all. With no email recipients and no syslog destination bound to alerts, every alert — a dead replica included — lands in a list nobody is told to look at. So the engine raises one warning, Alert delivery is not configured (alerts:delivery_unconfigured), whenever no notification channel has anywhere to send:

• email counts as configured when Email notifications is on, SMTP is enabled, and at least one recipient is set;
• syslog counts when at least one enabled destination carries a System / alerts binding (see Notification channel: syslog).

“Configured” is read from exactly the targets the next notification pass would use, so the alert resolves on the first cycle after either channel has one. It cannot be delivered by definition — it exists to be seen, on the Alerts page and the dashboard, and its message says where delivery is set up. A fresh install shows it until you configure one of the two. It says nothing about whether delivery works: a configured but failing mail server is the email:delivery alert above, and a syslog destination that does not accept the notices shows in its own delivery counters.

Turning the alert engine off (alerts.enabled = false) resolves this alert: a switched-off engine is a decision, not a missing setup. It is reconciled on the leader only and stays cluster-wide — the settings and bindings it reads are replicated.

The protocol daemons cannot call the alert service directly, so they write to a bridge table that the evaluator drains each cycle and promotes into stateful alerts. Each protocol’s condition is tracked independently:

NAC brute-force detection counts once per authentication attempt — an EAP attempt is many packets, and Taranac counts the logical outcome, not each round-trip. Defaults: enabled, threshold 10 failures, window 15 minutes (nac.bruteforce_*). The RADIUS and NAC unknown-device alert is throttled at the daemon: at most one bridge row per address per 10 minutes, so a chatty unknown switch cannot flood the queue.

These are event-type alerts: the daemons have no way to report “the condition stopped”, so they auto-resolve after alerts.event_ttl_minutes (default 60) with no fresh occurrence, rather than on an all-clear signal. The two OCSP alerts have their own period: they close after 60 minutes without another such refusal whatever alerts.event_ttl_minutes says, and send no resolution notice, also when closed by hand — the daemon reports no success, so silence does not prove the responder works again. See Certificate revocation → Alerts.

A degraded MFA provider silently breaks login for everyone enrolled in it, so a watchdog polls each enabled provider’s health every 90 seconds and reconciles an mfa:<provider> alert (error) from the result. A disabled provider never alerts, and each check has a 10-second ceiling so one slow provider cannot stall the others.

The alert is node-scoped, because reachability is: one node may reach the push service or the SMS gateway while its peer cannot, and a healthy peer must not clear the node that is broken. See Multi-factor authentication.

The same source carries one more, cluster-wide warning: TOTP enrollments predate the current settings (mfa:totp_params_drift:<algorithm>/<digits>/<interval>). Changing the TOTP algorithm, digit count or interval never breaks existing enrollments — each keeps the parameters it was issued with — and this alert lists the accounts still on older ones. It resolves once the last of them is re-enrolled. The current parameters are part of the fingerprint, so acknowledging it covers that divergence only; changing the settings again opens a fresh one. See TOTP code parameters belong to the enrollment.

Both are cluster-wide: the directory sync runs on the leader, and what they describe is replicated data.

With CRL checking on, an expired CRL makes the NAC service reject every client certificate of that CA, so the CRLs it checks against are watched:

The ca_chain kind is the CRL of a certificate in the issuing chain above an Internal CA signed by your corporate PKI (Upper-chain CRLs). Both its alerts are always warning: FreeRADIUS never uses that CRL, and TACACS+ over TLS, which does, rejects nobody over a stale one — it only misses the revocations published since. A CA with no CRL source is simply not checked, which is no alert. A source that is deleted, disabled or loses its URL has its alert resolved. See CRL checking.

One error alert, domain:membership, node-scoped — each node holds its own machine account. The condition is deliberately narrow: MS-CHAPv2 is switched on, and this node can no longer verify a domain password. It covers two causes, distinguished in the message and the details:

• the taranac-winbind sidecar is not reporting its status at all, so domain accounts cannot be authenticated here;
• the node holds a machine account but the domain controller no longer accepts it — a stale machine password (restored from a backup, or a second node joined under the same name) or a computer object deleted in AD.

A member with MS-CHAPv2 deliberately switched off never pages anyone, and “never joined” is not an alert — that is a state the MS-CHAPv2 tab shows plainly, and it is the state every installation starts in. The bad state must persist for 5 minutes before the alert opens, so a controller reboot does not page anyone; recovery is not delayed and clears it on the first healthy observation.

Both are node-scoped. The scheduled backup is a leader-only job, but what fails is node-local: this node ran out of space, lost a mount, or cannot read its own config/etcd-ca. A shared identity would let a failover launder the fault — a node with a full disk would have its alert cleared by a successful backup on the node that took leadership, while nothing about it had changed.

The stated cost of that: a node that raised the alert and then stopped being leader keeps a firing row nothing clears automatically, because it never runs the job again to report success. Close that row by hand, once. A cluster upgraded from an older release may also carry one old unscoped row — see Upgrading from an older release.

All cluster-wide, all reconciled on the leader:

A collector that has never heartbeated reads unknown, not offline, and never alerts; an embedded collector is the leader and never alerts either.

A collector on another release than its core keeps polling and stays online: the core withholds only the work whose contract no longer matches. That is the next alert, not this one.

Cluster-wide, evaluated on the leader every 60 seconds. It resolves when the collector reports matching versions (./collector-join.sh --update moves it to the version its core runs) or is deleted. See Version compatibility.

license:validation (error, cluster-wide) fires on any install — not just clustered ones — when a stored Pro licence cannot be honoured: a signature that does not verify, or one issued for a different installation. It only surfaces the problem; it disables nothing.

The rest exist only on an HA deployment. cluster_license carries one fingerprint; cluster_sync is a family sharing one source:

The freeze behind cluster:readiness is immediate; the alert waits out a further 60-second grace so a blip does not flap it. The health reconciles — the etcd ring, the connection ceiling and the PG_ALLOW_CIDR cross-check included — run every 60 seconds on the leader, the licence and phantom/grant reconciles hourly, and the slot reaper every 10 minutes. The etcd and PG_ALLOW_CIDR alerts need the fault on two consecutive checks, so one missed check during an election or a quick restart is never reported.

What each of these means and what to do about it is in HA alerts; see High availability for the cluster architecture behind all of them.

Notifications are sent on transitions and on repeats — never on every evaluation cycle. An alert is notified when:

• it fires (newly opened, or just escalated) and its severity is at or above alerts.notify_min_severity;
• it is still firing, unacknowledged, and its per-severity repeat interval has elapsed (a reminder);
• it resolves after having been notified (the “all clear”), if alerts.notify_on_resolve is on.

Acknowledging an alert stops the repeat reminders for it — that is the primary noise-control lever. Repeat cadence is set per severity, so critical conditions nag often and warnings rarely.

That policy is shared by every channel: the minimum severity, the repeat intervals and the all-clear switch under Settings → System → Alerts apply to email and syslog alike. There are two channels, and you can use either or both:

The notification pass runs at the end of each evaluation cycle, from stored state — so it also covers alerts opened by producers outside the evaluator (backups, MFA, the directory sync, the cluster reconciles, the Configuration Tracker). Delivery is tracked per alert and per target: a notice a target did not accept is offered to that target again on the next pass, and a target that works never resends because another one is down. A target added later receives the alerts that are firing at that moment as fresh notices, and a resolution only goes to targets that were told about the firing. A failed send is logged and never breaks evaluation. With no target at all, alerts:delivery_unconfigured says so.

On a standalone install the one node sends everything. Under HA each alert is sent once per target, by one node: a node sends the notifications of its own per-node alerts (only it can vouch for its disk, its daemons, its config), and the leader sends the cluster-wide ones — plus any per-node alert whose node is no longer an active member, which nobody else would send. Each target is handled under a cluster-wide lock, so a leadership change in the middle of a pass cannot send one notice twice.

Recipients are edited one address per line under Settings → System → Alerts and stored as a comma-separated list. The channel stays off entirely unless alerts.notify_email_enabled is on, SMTP is enabled, and at least one recipient is configured. A notice counts as delivered when at least one recipient accepted it; a broken mail server also surfaces as the email self-check alert.

Alert notification emails are rendered in English regardless of the interface language.

To send alerts to a SIEM or syslog server, add a binding with module System and log type alerts to a destination under Settings → Integrations → Syslog (see Audit & syslog). Every enabled destination with that binding is a target of its own and receives the firing, repeat and resolved notices under the shared policy above. A destination’s format, facility and ident apply, and the binding may override the facility or severity like any other.

Each notice is one line in the destination’s format — RFC 3164, RFC 5424 or CEF. The message ID (RFC 5424) or CEF signature ID is ALERT_FIRING, ALERT_REPEAT or ALERT_RESOLVED, and the header HOSTNAME is the name of the node that sent it:

<PRI>1 2026-10-11T08:15:02.114502Z taranac-node-1 taranac - ALERT_FIRING [taranac alertId="…" fingerprint="disk:/var" event="firing" severity="warning" source="monitoring" title="Disk usage high: /var" occurrenceCount="1" firstSeen="…" lastSeen="…" node="taranac-node-1" acknowledged="false"] ALERT_FIRING severity=warning source=monitoring fingerprint=disk:/var Disk usage high: /var: Filesystem /var is at 83% used.

Syslog severity follows the alert’s: critical → crit, error → err, warning → warning, info → info; every resolved notice is sent as notice. A binding’s severity override replaces that mapping. A multi-line alert message is folded onto one line, so a newline-framed receiver never splits a notice.

Unlike the AAA log forwarding, this path retries. A destination is sent its notices one after another, and the first one it does not accept ends that destination’s turn; the rest are offered again on the next pass, about a minute later. Each send waits at most 3 seconds, so a dead receiver cannot stall the rest of the pass. Over TCP or TLS “accepted” means the receiver took the message; over UDP it only means the datagram left the host, so a UDP notice that never arrived is not resent. A failing destination shows in its consecutive_failure_count and last_delivered_at, which the alert channel updates exactly as the AAA forwarder does — but a notice that is retried is not counted in dropped_record_count. Alert notices are never written to the audit log, so they never feed back into a system:audit stream.

Logging & Reports → Alerts lists conditions most-severe-first, then most recent, opening on the firing view. Summary tiles across the top count critical / error / warning / all-firing / resolved, and clicking one applies it as a filter. From there:

• Filter by status (firing / resolved), severity, source, acknowledgement, or a text search across title, message, source and fingerprint. On an HA cluster the list also shows a Node column and a node filter, so you can see and narrow to which node raised each alert. The Source dropdown offers the monitoring and config-validation sources; for the rest (tacacs / radius / nac, alerts, email, backup, mfa, domain, ldap_sync, users, nac_*, license, cluster_*, ncm_*) use the search box, which matches the source and fingerprint text.
• Acknowledge a single alert (or Acknowledge all firing ones) to silence its repeat notifications while you work it. The alert stays firing; the system records who acknowledged and when.
• Resolve an alert manually when you have decided it is handled. If the underlying condition is still bad, the next detection simply opens a fresh alert — so manual resolve is safe, not a way to hide a live problem.

Access is governed by RBAC under the alerts section: view to see the list and stats, acknowledge to acknowledge, and manage to manually resolve. The built-in operator role has all three; auditor is view-only. Alerts cannot be created through the UI or API — only the background producers listed above open them.

A disk is filling up. /var crosses 80%, persists past the debounce, and a warning opens (disk:/var). You get a firing email. It keeps climbing past 90%, the alert escalates to critical, your earlier acknowledgement is cleared, and you are notified again. You free space; on the next cycle the metric drops and the alert auto-resolves with an “all clear” mail.

RADIUS goes down. The health check fails and a critical alert fires immediately (no debounce), since authentication is impacted. You acknowledge to stop the repeats while you investigate, fix the daemon, and the alert resolves on the next reachable check.

A daemon is up but refusing everything. A node loses its database. The port still answers, so service:tacacs stays quiet — but the daemon reports that it is refusing, and after 30 seconds service:tacacs_backend opens as critical on that node only. Requests refused during the window are recorded and replayed into the AAA log once the database is reachable, so the gap is visible afterwards rather than lost. A routine container recreate never reaches that alert: the daemon’s cache warm-up is over inside the grace.

A password-spray against a user. Failed PEAP logins for jdoe cross the NAC threshold inside the window; a warning fires (nac:brute_force:peap:jdoe). The device is not banned — the alert tells you to investigate and, if warranted, block the endpoint manually. When the spray stops, the alert ages out and auto-resolves.

A switch you forgot to onboard. A NAS not in inventory hits the NAC path; a throttled unknown_device warning fires for that NAS IP. You add it under Network devices, and the alert clears once the requests stop.

A router logs in over TACACS+ before it is in the inventory. The connection is refused, the Authentication Log shows a Not in the inventory row, and Unknown TACACS+ device <address> fires once. You add the device; its next login is answered, and the alert ages out.

Bad config push. A TACACS+ profile change fails validation; an error opens (tacacs_config:validation). You correct the profile, the reload validates cleanly, and the alert resolves.

All alert settings live under alerts.* and are edited under Settings → System → Alerts. Resource thresholds are percentages where 0 disables that level; repeat intervals are in minutes where 0 disables repeats for that severity.

The same page also carries one key from outside the alerts.* namespace:

NAC brute-force detection is tuned separately under nac.*:

• Audit & syslog — syslog destinations and the System / alerts binding, and the event trail behind delivery self-checks and operator actions
• Authentication logs — the per-request log that brute-force counters draw from
• Network devices — onboard a NAS to clear unknown-device alerts, and the inheritance chain behind the key/banner advisories
• Endpoints & profiling — the block lifecycle that NAC enforcement actually uses
• High availability — the cluster:* and service:*_backend alerts in their operational context
• Backups & upgrades — the backup:scheduled and backup:incomplete alerts
• Multi-factor authentication — the provider health checks behind mfa:<provider>
• Users & groups — the shared usernames behind users:duplicate_usernames
• Settings reference — SMTP configuration for the email channel
• Taranac on GitHub