Configuration Checks
Since 4.5
A Checkmk site collects leftovers over the years: rules nobody needs any more, two checks doing the same job, migrations that were started and never finished. The Configuration Checks look at the setup of a site and list these problems, each with the rules involved and what to do about it. Another check lists the unhandled problems of the monitoring, grouped to work them off. The list can be exported as a PDF report.
Go to: Modules → Checkmk → Data Quality → Configuration Checks.
Note
The checks only read from Checkmk. They never change, delete or activate anything. Cleaning up is up to you, with the report in hand. The one exception you start yourself: the service discovery on the hosts of the topic Service discovery pending, see below.
Permissions
The page belongs to the Data Quality area: users with the Checkmk right or
the role Checkmk: Data Quality Check (this area only) can open it.
Account-restricted users only see their own accounts.
Run checks
- Pick the Checkmk account.
- Tick the checks to run. All of them are ticked by default.
- Run checks shows one card per check.
Each card is split by topic, one topic per kind of problem:
- At the top, the numbers of what the check looked at (rules, endpoints, ...) and a summary with the number of findings per topic and in total. A click on a topic jumps to its section.
- Then one section per topic: its title with the number of findings, what the topic means, what to do about it, and a table with the columns that fit this topic (a failing service has host, state and output, a duplicate has URL, scope and the checks involved). Topics without findings show "No findings".
Every topic folds: a click on its title opens or closes it. Topics without findings start closed, a click on a topic in the summary opens it.
Every rule involved is given with its id, to find it in Checkmk.
Export as PDF
Export PDF runs the selected checks again and downloads the result as a PDF
file, named after the account and the date, e.g.
checkmk-config-checks-cmk01-2026-10-21.pdf. The report is in the design of
your Syncer installation (logo on a band in the color of the navigation bar),
A4 landscape, with the same summary and sections per topic as on the page.
The PDF export needs the Python package fpdf2, which is part of the extras:
pip install 'cmdbsyncer[extras]' # or just: pip install fpdf2
The Docker image installs the extras already. Without the package the page and the checks work as usual; only the Export PDF button is disabled and says which package is missing.
Export one topic
Every topic with findings has its own CSV and PDF button. They run that
check again and download only this topic, named after account, check, topic and
date, e.g. checkmk-config-checks-cmk01-unhandled-discovery-2026-11-12.csv.
- The CSV opens straight in Excel:
;between the columns, UTF-8 with a BOM, one row per finding with the columns of the topic. A cell with several rules or services holds one per line. It does not needfpdf2. - The PDF is the report of the whole page cut to this topic, in the same design.
HTTP web service checks (check_httpv2)
Checkmk replaced the old active check check_http by check_httpv2 (rule
Check HTTP web service). The old check needed one rule for the web page and a
second rule for the certificate. The new one checks both in a single endpoint,
but cmk-migrate-http turns every old rule into a new rule of its own. After the
migration a site therefore often has two checks per URL where one is enough.
The check reads the rules of active_checks:httpv2 and active_checks:http
and the state of the HTTP check services. Disabled rules are skipped.
Failing checks
Every HTTP check service, new check_httpv2 as well as old check_http, that
is WARN, CRIT or UNKNOWN in the monitoring right now is listed first, the
worst state on top: host, service, state and the output of the check. The rule
behind the service is named when the service name of an enabled rule matches
(for an old rule HTTP or HTTPS plus its name). Service names built from
macros such as $HOSTNAME$ cannot be traced back to a rule; the report says so.
Nothing is acknowledged or changed in Checkmk.
When two endpoints check the same thing
Each endpoint of each rule is compared with its effective settings: the standard settings of the rule, overwritten by the individual settings of the endpoint (the same way Checkmk combines them). Two endpoints check the same target when
- their rules are in the same folder,
- their rules have the same conditions,
- their URLs are equal (scheme and host name in any case, with or without the
default port 80 or 443 and a trailing
/), - and they connect to the same server (the setting Connect to specific host).
Endpoints in different folders or with different conditions are never compared, even if their hosts overlap.
Topics
The report has these sections, in this order:
| Topic | Meaning | What to do |
|---|---|---|
| HTTP checks not OK | HTTP check services that are WARN, CRIT or UNKNOWN right now (see above). Columns: host, service, state, output, rule. | Fix the web service, or the rule if it checks something that is not there any more. |
| Duplicate checks | Two or more endpoints with identical settings check the same target. Only the service name may differ. | Keep one, remove the others. |
| Website and certificate checked separately | One endpoint only checks the certificate, another one checks the web page of the same target. | Set Certificate validity of the web page check to Check certificate with the levels of the certificate check, then remove the certificate check. If the web page check already checks the certificate, just remove the certificate check. The table says which applies. |
| Several checks on the same URL | More than one endpoint with different settings on the same target, e.g. two different expected texts. Often intended, so this is information only. | Check whether all of them are needed. |
| Migration not finalized | Old rules that cmk-migrate-http already migrated, but the migration was not finalized: old and new rule both run. |
Finalize the migration with cmk-migrate-http finalize or disable the old rules. |
| Old check_http rules not migrated | Old rules without a migrated counterpart, e.g. ones the migration skipped. | Migrate them. |
An endpoint counts as a certificate check when it checks the certificate with expiry levels (Certificate validity set to Check certificate with fixed levels) and sets none of Response time, Response (status codes), Content or a Document option other than ignoring the body. Every other endpoint counts as a web page check.
When the certificate check uses other connection settings than the web page check, the report names the settings that differ (never their values), so you can carry them over when merging.
Unhandled problems
This check reads the monitoring of the site and lists every problem nobody has taken care of yet, grouped so you can work them off one kind at a time.
A problem counts as unhandled as in the Checkmk views: it is not acknowledged, and neither it nor its host is in a scheduled downtime. Services on a host that is DOWN or UNREACHABLE are left out, there the host is the problem. The numbers on top say how many problems were skipped for which reason.
The services are grouped by check type: the check plugin (df,
cpu_loads, ...) or the active check (httpv2 (active check)). The type with
the worst state comes first, CRIT before UNKNOWN before WARN, then the type with
the most services. The same problem on many hosts usually has one cause.
| Topic | Meaning | What to do |
|---|---|---|
| Hosts DOWN or UNREACHABLE | Hosts that are not UP. Columns: host, state, output. | Bring the host back, set a downtime for planned work, or remove the host from the monitoring. |
| Agent or data source fails | The Check_MK service is not OK: the agent, SNMP or a special agent delivered no data, so the other services of the host are not updated. |
Fix the connection to the agent or the data source. |
| Service discovery pending | The Check_MK Discovery service reports unmonitored or vanished services or changed host labels. |
Run a service discovery and accept the changes, or disable the services that should not be monitored. |
| Service problems by check type | All other services that are WARN, CRIT or UNKNOWN, one row per check type with the worst state, the number of services and hosts, and every service with its output. | Work through the check types from the top: fix the cause, adjust the levels, or acknowledge the problem. |
Service discovery from the topic
Users with the Checkmk right can start a service discovery right from the
topic Service discovery pending. Every host of the topic has a checkbox, all
ticked; untick the hosts to leave out. Then choose what the discovery may
change:
| Option | Default | Effect |
|---|---|---|
| Add new services | on | Monitors the services the discovery finds that are not monitored yet. |
| Remove vanished services | off | Removes the monitored services the host no longer reports. |
| Update host labels | on | Takes over new and changed host labels. |
| Activate changes when done | off | Activates the changes once the discovery of all hosts went through. |
Start discovery asks once and starts a bulk discovery in Checkmk, with a full scan of the hosts. The page stays as it is and says when Checkmk started the job. Checkmk runs only one bulk discovery at a time; while another one runs, the page says Checkmk refused the start.
The Syncer waits for the job in the background and writes the result to
Settings → Log with source Checkmk: who started it, the hosts, the
options, the job output with the number of services and labels added and
removed, and whether the changes were activated. A host whose discovery failed
(an unreachable agent, for example) marks the run as failed; then nothing is
activated. The Check_MK Discovery service shows the new state on its next run,
until then the host stays in the topic.
The role Checkmk: Data Quality Check (this area only) sees the topic but not
the discovery: unlike the checks, it changes the site.
Adding a check
The checks are modules in application/plugins/checkmk/config_checks/. A new
check is a class derived from ConfigCheck with a name, title,
description, its topics and an analyze(cmk) method that returns the
problems found (Finding) and a few numbers about what it looked at.
Each Topic declares its title, what it means, what to do and the columns of
its table (Column with a key and a type: text, code, state or a list of
rules). A Finding names its topic and carries one value per column. The page
and the PDF report build the summary and the sections from that, so a new check
or a new topic needs no template change. Registered with @register_check and
imported in the package's __init__.py, the check shows up on the page.