From 803b757519b96f2af964eb824841fb5f5fff54b9 Mon Sep 17 00:00:00 2001 From: Ole Herman Schumacher Elgesem Date: Thu, 5 Mar 2026 19:12:27 +0100 Subject: [PATCH] Added more detailed documentation for cf-check Ticket: ENT-13796 Signed-off-by: Ole Herman Schumacher Elgesem --- .../reference/components/cf-check.markdown | 127 +++++++++++++++++- 1 file changed, 123 insertions(+), 4 deletions(-) diff --git a/content/reference/components/cf-check.markdown b/content/reference/components/cf-check.markdown index 6cf3d362a..2deb09055 100644 --- a/content/reference/components/cf-check.markdown +++ b/content/reference/components/cf-check.markdown @@ -2,13 +2,132 @@ layout: default title: cf-check sorting: 80 -keywords: [cf-hub] aliases: - "/reference-components-cf-check.html" --- -Utility for diagnosis and repair of local CFEngine databases. +The `cf-check` binary can be used to inspect, dump, diagnose, and repair LMDB databases used by CFEngine. +The diagnosis and repair parts of `cf-check` are built into CFEngine, meaning corrupt databases are automatically fixed and users normally don't need to run these commands manually. -## Command reference +## Help output (`--help`) -{{< CFEngine_include_snippet(cf-check.help, [\s]*--[a-z], ^$) >}} +The `--help` command line option gives you an overview of what the tool can do: + +```command +cf-check --help +``` + +```output +{{< CFEngine_include_markdown(cf-check.help, .*) >}} +``` + +## Inspecting databases + +The `dump` command can be used to look at the contents of each database in a JSON5 format. + +```command +cf-check dump /var/cfengine/state/cf_lastseen.lmdb +``` + +```json {output} +{ + "a172.31.7.155": "SHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0", + "kSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": "172.31.7.155", + "qiSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": { + "Q": { "dq": 190.0, "expect": 173.8105, "q": 245.0, "var": 14173.7558 }, + "acknowledged": false, + "lastseen": 1772732121 + }, + "qoSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": { + "Q": { "dq": 190.0, "expect": 173.8105, "q": 245.0, "var": 14173.7558 }, + "acknowledged": false, + "lastseen": 1772732121 + }, + "version": "2" +} +``` + +We use JSON5 because it has some nice additions to normal JSON, like allowing trailing commas and escape sequences which make binary (non-ascii) data more readable. + +**Tip:** You can use `json5` and `jq` if you want to convert to JSON and format the output; + +```command +cf-check dump /var/cfengine/state/cf_lastseen.lmdb | json5 | jq +``` + +```json {output} +{ + "a172.31.7.155": "SHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0", + "kSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": "172.31.7.155", + "qiSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": { + "Q": { "dq": 190, "expect": 173.7718, "q": 245, "var": 14127.5535 }, + "acknowledged": false, + "lastseen": 1772732421 + }, + "qoSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": { + "Q": { "dq": 190, "expect": 173.7718, "q": 245, "var": 14127.5535 }, + "acknowledged": false, + "lastseen": 1772732421 + }, + "version": "2" +} +``` + +## Diagnosing potentially corrupt database files + +The `diagnose` command can be used to check the state of databases. +By default it will look at all the LMDB databases (in `/var/cfengine/state/`). +Technically it will attempt to open the database, and run some per-database validation checks (based on the filename). +This work is done in a forked subprocess, so if it crashes or fails in any way, the parent `cf-check` process can handle it and print a summary. + +```command +cf-check diagnose +``` + +```output +info: No filenames specified, defaulting to .lmdb files in /var/cfengine/state +info: Status of '/var/cfengine/state/history.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/cf_state.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/nova_cookies.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/nova_track.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/nova_measures.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/cf_changes.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/packages_installed_apt_get.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/cf_lock.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/performance.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/cf_lastseen.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/cf_observations.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/nova_agent_execution.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/packages_updates_apt_get.lmdb': OK [0% usage] +info: Status of '/var/cfengine/state/nova_static.lmdb': OK [0% usage] +info: All 14 databases healthy +``` + +You can also specify a specific filename: + +```command +cf-check diagnose /var/cfengine/state/cf_lastseen.lmdb +``` + +```output +info: Status of '/var/cfengine/state/cf_lastseen.lmdb': OK [0% usage] +info: All 1 databases healthy +``` + +## Repairing corrupt databases + +The `repair` command builds on the functionality of the `diagnose` command, but attempts to fix the situation when there are corrupt databases found. + +```command +cf-check repair /var/cfengine/state/cf_state.lmdb +``` + +```output + info: Status of '/var/cfengine/state/cf_state.lmdb': LMDB_INVALID_DATABASE [0% usage] + error: Problems detected in 1/1 databases +notice: 1 corrupt database to fix + info: Backing up to '/var/cfengine/backups/1772733351-WZgDKk/' + info: Copying: '/var/cfengine/state/cf_state.lmdb' -> '/var/cfengine/backups/1772733351-WZgDKk/cf_state.lmdb' + error: Failed to repair file '/var/cfengine/state/cf_state.lmdb', removing +notice: Database repair successful +```