Monitoring FreeIPA with ipa-healthcheck

How to monitor FreeIPA with ipa-healthcheck on every server

An identity service that many hosts depend on rarely fails loudly. When replication drifts, a certificate approaches expiry or a DNS record goes stale, logins may keep working for hours or days while the problem grows. ipa-healthcheck is the tool FreeIPA provides to run a set of checks against a server and report what it finds. This section of the page covers why it should run on every server rather than only the first one, how to schedule it, how to handle its output, and how to route results into alerting. Teams usually need this before go-live so they have a known-good baseline, after every upgrade because checks can change between releases, and then as an ongoing signal between maintenance windows.

Start by confirming the installed version. Check names, severity levels, output fields and the available options can differ between releases, so the examples you build from must come from the ipa-healthcheck on your own servers, not from memory or from this page. Run the tool by hand on each replica and CA server first, then record the baseline. Compare servers against each other as well as against their own history: a check that passes on one replica and fails on another is often the most useful finding. Keep the list of checks you intend to alert on separate from the full list, so that a change in the tool's output does not silently remove coverage.

Scheduling and output handling are where most monitoring setups go wrong. Run the check on a fixed schedule with a systemd timer, and configure it to report failures only so that routine passes do not bury real problems. Confirm the options for output location and log directory in your version, then make sure the log directory is included in your log collection and retention rules. Decide who owns each failure class in advance, because a healthy-looking log that nobody reads is the same as no monitoring. Test the alert path deliberately by causing a known failure in a lab deployment, and confirm that the alert reaches the right on-call group, includes the hostname, and clears when the problem is fixed.

Output, schedule and alerting choices compared

This table compares the main decisions for running ipa-healthcheck: where it runs, how its output is handled, how it is scheduled and where its results go. Read each row for when the option fits and what it leaves unseen, then combine choices so that every server is covered and no failure is silent.

Decision	Option and when it fits	What it leaves unseen
Where checks run	First server only fits a small topology where one host is the only place anyone looks. It reduces noise but reports nothing about the other replicas.	Replicas with local problems, such as a stopped service, expired local files or a clock drift, stay invisible until a client fails.
Where checks run	Every server fits most deployments, because each host reports on its own state and on the replication view it sees. It needs a plan for collecting results from each host.	Results only help if someone reads them from all hosts. Confirm how the output is gathered so that a silent host is also noticed.
Output handling	Full output fits initial validation, change windows and audit evidence, where you want every check listed. It is noisy for daily use.	Teams tend to stop reading full reports, so a real failure can sit among many expected lines.
Output handling	Failures-only output fits daily monitoring, where a non-empty result should trigger an alert. Confirm the exact option and its exit behavior in your installed version.	Checks that never ran, failed to start or were skipped may look like a clean pass. Pair this with a check that the run itself completed.
Scheduling	A systemd timer fits RHEL-family servers already managed by systemd, because it logs to the journal, records each run and can be paired with a service unit. Confirm unit names in your packages.	Timers on a host that is down or unmanaged do not run, so the monitoring system must also notice missing results.
Scheduling	Cron or configuration management fits estates that already standardize on it, or hosts where systemd units are restricted. It is easy to audit in the same tooling.	Cron output is often mailed to a local account nobody reads, and configuration drift can silently remove the job.
Alert path	Forwarding results to an existing log platform fits teams that already run alert rules on logs and want one place for FreeIPA events. Define a rule for failed runs as well as failed checks.	Parsing rules break after format changes between versions, so test them after each FreeIPA upgrade.
Alert path	A file-based check read by a monitoring agent fits teams that already collect host metrics and want a simple last-run and result-count signal on each server.	Local files alone do not survive a dead host or a full disk, so keep a remote check that a fresh result arrived.

What the checks cover and how to confirm them

A health check on an identity server looks for four broad kinds of condition: directory and replication state, Kerberos and certificate health, DNS and time synchronization, and service status. Directory and replication checks ask whether the 389 Directory Server instance is answering and whether its replication agreements are working. Kerberos and certificate checks look at the KDC and the Dogtag certificate authority, including whether certificates are close to expiry. DNS and time checks confirm that the records and clock offsets that Kerberos depends on are in order. Service status checks confirm that the components FreeIPA runs on the host are up. The categories are stable, but the individual checks, their names and their severity levels are not. They change with the installed package version, and some checks only run on servers that hold a particular role, such as CA or DNS.

Do not write alert rules from this description or from any published list. On each server, run the tool with its list option after installation and record the check names, the severity each one reports and the roles that apply to that host. Keep that output with your configuration so that a later package update can be compared against it. Ask your team to confirm which checks run on a replica that has no CA or DNS role, because an alert that never fires on a host is a gap you will not see until an incident. Where the tool needs a specific invocation to reach a particular check, document that invocation next to the list.

A check run on one server only tells you about that server. A replica can show a clean local result while a replication agreement to another replica has stopped, or while the CA renewal server has moved and the other servers still point at the old one. Those topology problems appear as failures on other hosts, or as no output at all if the other hosts are not checked. For that reason, confirm that the health check runs on every server in the topology, and that the results are gathered in one place where a missing report is itself visible. Treat a silent host as a failure until someone has confirmed otherwise.

Setting up the health check timer on each server

This sequence turns ipa-healthcheck from a one-off command into a scheduled check on every FreeIPA server. When it is finished, each server has a confirmed package, a saved baseline, a working timer that writes results to a log directory, and an alert path that a named on-call person has tested. Run the steps on each server in turn, including replicas that hold no CA or DNS role.

Confirm the package and version on each server
Run rpm -q freeipa-healthcheck on every FreeIPA server, including replicas and any server with a CA or DNS role, and record the output beside the server name. Confirm the package name against your distribution's repository first, since packaging can differ between releases. Compare versions across the topology so every server runs the same release family. Done when each server reports an installed version and the list matches your server inventory.
Run the check once and save a baseline
As root, run ipa-healthcheck on each server and save the complete output to a file named with the hostname and date, and attach it to your change record. A healthy server should report no failures at this stage. Any finding is either a real problem to resolve before alerting starts or a known exception to document with its reason. Keep the baseline so later runs can be compared against it. Done when every server has a saved baseline and every finding is resolved or recorded.
Identify the installed timer and service units
Run systemctl list-unit-files | grep -i healthcheck and systemctl list-timers --all | grep -i healthcheck to find the timer and service units the package installed. Use the unit names shown on each server, because the names can vary by release and should not be copied from another system. Inspect the service with systemctl cat on the name you found and note its ExecStart line, the user it runs as and any output settings. Done when you can name the timer and the service and know which command the timer runs.
Enable the timer and confirm its schedule
If the package does not enable the timer, enable and start it with systemctl enable --now on the timer unit you identified. Then run systemctl list-timers and confirm that the next trigger time is populated for that unit. Avoid adding a second timer beside the packaged one, because duplicate timers produce duplicate records. Done when the timer is active, shows a next trigger time, and its schedule matches the one in your change record.
Confirm the log directory is writable and rotated
Find the directory where results are written by checking the service configuration and the package file list from rpm -ql freeipa-healthcheck. Run ls -ld on that path to confirm the service user can write to it, then trigger a manual run and confirm it creates or appends to a file there. Run logrotate -d against the rotation configuration the package provides, or your own rule if none exists, so the directory cannot fill the disk. Done when a manual run writes to the directory and the rotation dry run reports no errors.
Create a deliberate failure to test detection
Illustrative example: on a non-production replica, stop a service that the health check tests, then run the check manually. Confirm that a failure record appears in the log directory and names the expected check. Restore the service, run the check again, and confirm that the recovery is recorded. Do not run this test on the only certificate renewal server in production. Done when the failure record matches the induced condition and the recovery is also logged.
Confirm the alert reaches the on-call channel
Repeat the induced condition and follow the path from the log file through the collector or agent that reads the directory, the alert rule and the notification route. Confirm that the alert arrives at the on-call channel in the expected form and that the recovery notice also arrives. Ask the monitoring team to confirm the rule threshold and the owner of the notification route in writing. Done when a named on-call person has received both notices and the test is recorded with the date and server name.

Running checks on primary, replica and DNS-role servers

The first server in the topology handles certificate renewal and CRL publication by default, so a failure here affects certificates across the deployment, not only this host. Read its results before you decide the rest of the topology is healthy.

Certificate tracking and renewal: Confirm that the CA and service certificates the check reports are tracked and set to renew. Treat any tracking failure as urgent.
CRL publication: Confirm that the certificate revocation list is being published and is current, since clients that check revocation depend on it.
Replication agreements: Check that this server's agreements to its peers report as healthy, because a broken agreement here can leave renewal state out of step with other replicas.
After a restore: The backup documentation warns that restoring an outdated backup into an active replica topology can break replication. Run the check before and after the restore and compare the results with the other replicas.
After an upgrade: Rerun the full check on this server first, since it holds CA state that other servers depend on.

Before you sign off, confirm that this server's CA and replication results are clean, and save the output as a baseline for later runs.

Feeding results into monitoring and alerting

The point of running ipa-healthcheck on every server is to turn its output into a signal someone acts on, and that means alerting on failures and missing runs, not on the full report. Parse the output for failed checks only, and ignore informational results so they never reach an on-call queue. Tag each event with the server name, its FreeIPA role (for example, whether it holds the CA renewal role, runs DNS, or is a plain replica) and the check identifier, so an alert tells the responder which server to open and which subsystem is affected. Repeated runs will report the same unresolved failure every time the timer fires, so deduplicate on server plus check identifier and raise a new event only when a failure first appears or clears. Role tags matter here because a failed check on the server that renews certificates carries more urgency than the same check on a replica without that role.

A silent timer is a failure mode in its own right. If the systemd timer is disabled, the unit fails to start, the log directory fills or the host drops off the network, the absence of output looks identical to a clean run. Alert when the most recent run for a server is older than the schedule allows, measured from the log file or from the service's last-run state, and treat a missing host in your inventory as a gap to investigate. Keep this staleness alert separate from failure alerts so each has its own owner and threshold. Choose the threshold from the timer schedule you actually configured, not from a default you assumed.

The destination is your choice: a metrics system, a central log platform or a ticket queue each suit different teams. Before building anything, confirm which of these your environment already runs, who staffs the alert path and how alerts reach them outside business hours. Ask your monitoring team whether they can ingest a text log or need a small exporter, and agree the alert severity for failures on the CA renewal server before the first run. Test the full path once by deliberately causing a benign failure on a non-production replica, then confirm the alert arrives, clears, and the staleness alert fires when you stop the timer.

Security and operational considerations for check output

Health check output describes your identity infrastructure in detail, so it deserves the same care as the server it inspects. The cards below cover who can read results, what privileges the timer needs, what alerts may carry, how far to trust results from a suspect host, and how monitoring changes should be controlled.

Protect check logs as sensitive data

Check output can name hosts, the realm, DNS zones and service principals, which gives an attacker a map of your FreeIPA topology. Confirm that the log directory and the files in it are readable only by the accounts that need them, and that log forwarding sends them only to systems with the same access controls. Review file modes after each package update, since defaults may change.

Scope the timer's privileges

The health check must read configuration and service state that ordinary users cannot, so the systemd unit runs with elevated rights. Inspect the unit file and any drop-ins to confirm which user, capabilities and filesystem paths it uses, and remove anything it does not need. Confirm that the unit cannot write to identity data directories, since a read-only check should not be able to change them.

Keep secrets out of alerts

Alert messages often travel to chat tools, ticket queues and paging services with broad membership. Treat the failure text as potentially sensitive, and send only a summary such as the host, the check name and the severity, with a pointer to the full log on the server. Verify that no alert template includes credential material, Kerberos keytab paths or configuration excerpts.

Distrust results from compromised hosts

A server that an attacker controls can alter the checks, suppress failures or report a clean run. Do not treat a passing result from a suspect host as proof of health. Compare results with an independent view, such as the state of other replicas or external probes, and treat a missing or unexpectedly quiet report as an alert in its own right.

Put monitoring under change control

Changes to which checks run, their thresholds, alert routing and the timer schedule can hide real faults just as a configuration change can. Route these changes through the same review, approval and rollback process you use for the identity service itself, and record who changed what. Confirm that your change tickets cover the monitoring host and the forwarding pipeline as well as the FreeIPA servers.

What does it take to monitor FreeIPA with ipa-healthcheck?

How much effort does it take to set up ipa-healthcheck on each server?

The per-server work is small, but it multiplies with the number of FreeIPA servers, so the total depends on how many you run. Each server needs the health check run on a schedule, its output routed to a log location, and a way for failures to reach someone. Setup on one server is a short task; the effort grows with the number of servers, the consistency of configuration across them, and the number of replicas that must be checked the same way. Ask any partner to state the server count, the alert path for each environment, and whether a test replica is available for validation before rollout.

Can our own team set up FreeIPA health checks without a partner?

Yes, if your team already runs FreeIPA and your monitoring platform. The tool runs on the FreeIPA hosts, and the work is mostly about scheduling, log handling and alert rules that match your environment. A partner adds value when several teams share ownership of the servers, when the existing monitoring stack is fragmented, or when you need a documented build that auditors and new staff can follow. Your team should confirm the check set, the failure handling, and who receives each alert before deciding between internal and external work.

What recurs after ipa-healthcheck is set up?

Setup is one-time work, but operations are recurring. Someone must review failures, tune alert thresholds, and decide what to do when a check reports a problem. Each FreeIPA upgrade can change what is checked or how results look, so the configuration needs a review after each upgrade. Replica additions, removals and renames also change the list of hosts to monitor. Ask whether the work includes periodic reviews of alert noise and whether it is covered by a retainer or left to your team.

How long does a FreeIPA monitoring project take?

No duration can be stated here without a written scope. The main drivers are the number of FreeIPA servers, how many alert destinations you use, whether your monitoring platform already ingests host logs, and how many change windows you can use for rollout. A single-site deployment with one alert path moves faster than a multi-site topology with separate on-call teams. Ask for a timeline that lists each server, each alert route and each validation step, and check whether it includes testing a forced failure.

What do we need to provide before monitoring work starts?

Plan to provide the following before work starts:

Administrative access to each FreeIPA server, with the change approval process your organization uses.
Scheduled change windows for configuration changes on replicas, and a rule for which server is changed first.
Details of your existing monitoring platform, including its version, how it receives logs or events, and who owns it.
A list of alert destinations, such as on-call rotations, ticket queues and chat channels, with escalation rules.
A test environment or non-production replica if you have one.

The quote should reflect what is missing from this list.

How should ipa-healthcheck results be handled during an incident?

Treat a health check failure as a signal to confirm the state of replication, certificates, DNS and the directory before changing anything. Check the failing item in the log directory, compare it with the other FreeIPA servers, and decide whether the issue affects authentication for users or hosts. Do not run repair steps on a replica until the first server, the certificate authority role and replication status are understood. Your runbook should name who owns the response, which alerts page someone, and which failures can wait for the next business day.

What drives the cost of FreeIPA monitoring up or down?

Cost follows the written scope, so the key inputs are the number of FreeIPA servers, the number of alert destinations, and the maturity of your existing monitoring. A stable stack that already collects host logs needs less integration work than a platform built around manual checks. Multiple sites, separate on-call teams and strict approval steps add coordination time. Recurring support, such as reviewing alerts after each upgrade, is priced separately from the initial build. Ask each bidder to itemize setup, integration, testing, documentation, and any retainer for ongoing review.

Limits to confirm in your environment

A health check reports the state of one FreeIPA server at one moment, against the checks shipped in your installed version. The cards below cover what to confirm before you rely on ipa-healthcheck output in monitoring, and where a clean result stops being evidence for an auditor.

Exact check list and severities

The set of checks, their names and their severity levels come from the package version installed on each server, not from this page. Run the tool with its listing option on a test server and record the output for each FreeIPA version you operate. Confirm which results count as failures in your alerting, and whether any check you depend on has been renamed or removed after an upgrade.

Output format for your monitoring platform

Failures-only output is useful only if your collector can parse what the tool writes. Confirm whether your platform expects JSON, plain text or a systemd journal entry, and test the parser against a real failure on a non-production server. Decide who owns the parser when the output format changes between releases.

Behavior on unusual server roles

Servers that run the CA renewal role, DNS, or an AD trust controller may produce checks that do not apply to a plain replica. Ask your deployment team which checks are skipped on each role, and whether a check that fails by design is suppressed or silently ignored. Test this on every role your topology uses, including any server that has been restored from backup.

Upgrade path for the check package

The check package is versioned with FreeIPA, but your servers may receive updates on different schedules. Confirm that the package version matches the FreeIPA server version after each upgrade, and that your timer and log directory still work after a package update. Plan the check against a staging copy of your topology before it goes into the production upgrade window.

Fit with audit and compliance requirements

A passing run shows that the checks you have enabled succeeded on that day. It does not show that controls were designed, operated or evidenced over a period, and it is not an audit result. Ask your compliance lead which control objectives the health checks support, and which evidence the auditor will need from elsewhere. DeployOpen prepares systems and evidence for assessments but does not issue audit reports; independent auditors and certification bodies do.

How DeployOpen works on this

DeployOpen is a Chainscore Labs company that plans, implements, hardens, documents and supports self-hosted open-source platforms in infrastructure you control. For FreeIPA health monitoring, we turn ipa-healthcheck into a repeatable check on every server, with failures routed to the alerting system your operations team already runs.

How we scope

We confirm which FreeIPA servers, replicas and client hosts the written scope covers for ipa-healthcheck runs.
We record the monitoring system, alert channels and on-call owners that will receive failure output from each server.
We agree in writing whether the scope includes the systemd timer, log directory layout and alert rules, or only the design.

How we build

We install and configure the ipa-healthcheck timer on each server and set the log directory with the permissions your team requires.
We set up failures-only output so monitoring receives actionable results instead of a full report on every run.
We test the pipeline by inducing a controlled, documented failure on a non-production server and confirming the alert arrives.

How we hand over

We document each check that runs, what a failure means, and the first response steps your team should take.
We provide the timer configuration, log locations and alert mapping in a runbook kept in your own repository.
We walk your operators through reading results and adjusting the schedule so the setup stays under your control.

How we support

Ongoing monitoring support, upgrades and reviews after FreeIPA version changes are available as a retainer.
We confirm with your team which ipa-healthcheck results need to be re-checked after a FreeIPA upgrade or topology change.
Engagements are fixed-scope, so changes to the monitored estate are agreed in writing before the work starts.