Skip to content

Commit 803b757

Browse files
olehermanseolehermanse
committed
Added more detailed documentation for cf-check
Ticket: ENT-13796 Signed-off-by: Ole Herman Schumacher Elgesem <ole.elgesem@northern.tech>
1 parent b0bbe0f commit 803b757

1 file changed

Lines changed: 123 additions & 4 deletions

File tree

‎content/reference/components/cf-check.markdown‎

Lines changed: 123 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,132 @@
22
layout: default
33
title: cf-check
44
sorting: 80
5-
keywords: [cf-hub]
65
aliases:
76
- "/reference-components-cf-check.html"
87
---
98

10-
Utility for diagnosis and repair of local CFEngine databases.
9+
The `cf-check` binary can be used to inspect, dump, diagnose, and repair LMDB databases used by CFEngine.
10+
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.
1111

12-
## Command reference
12+
## Help output (`--help`)
1313

14-
{{< CFEngine_include_snippet(cf-check.help, [\s]*--[a-z], ^$) >}}
14+
The `--help` command line option gives you an overview of what the tool can do:
15+
16+
```command
17+
cf-check --help
18+
```
19+
20+
```output
21+
{{< CFEngine_include_markdown(cf-check.help, .*) >}}
22+
```
23+
24+
## Inspecting databases
25+
26+
The `dump` command can be used to look at the contents of each database in a JSON5 format.
27+
28+
```command
29+
cf-check dump /var/cfengine/state/cf_lastseen.lmdb
30+
```
31+
32+
```json {output}
33+
{
34+
"a172.31.7.155": "SHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0",
35+
"kSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": "172.31.7.155",
36+
"qiSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": {
37+
"Q": { "dq": 190.0, "expect": 173.8105, "q": 245.0, "var": 14173.7558 },
38+
"acknowledged": false,
39+
"lastseen": 1772732121
40+
},
41+
"qoSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": {
42+
"Q": { "dq": 190.0, "expect": 173.8105, "q": 245.0, "var": 14173.7558 },
43+
"acknowledged": false,
44+
"lastseen": 1772732121
45+
},
46+
"version": "2"
47+
}
48+
```
49+
50+
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.
51+
52+
**Tip:** You can use `json5` and `jq` if you want to convert to JSON and format the output;
53+
54+
```command
55+
cf-check dump /var/cfengine/state/cf_lastseen.lmdb | json5 | jq
56+
```
57+
58+
```json {output}
59+
{
60+
"a172.31.7.155": "SHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0",
61+
"kSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": "172.31.7.155",
62+
"qiSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": {
63+
"Q": { "dq": 190, "expect": 173.7718, "q": 245, "var": 14127.5535 },
64+
"acknowledged": false,
65+
"lastseen": 1772732421
66+
},
67+
"qoSHA=9153587b09d8426fd6b3e2dc6c47c29891e2a20430148725ce6e7d95d48637c0": {
68+
"Q": { "dq": 190, "expect": 173.7718, "q": 245, "var": 14127.5535 },
69+
"acknowledged": false,
70+
"lastseen": 1772732421
71+
},
72+
"version": "2"
73+
}
74+
```
75+
76+
## Diagnosing potentially corrupt database files
77+
78+
The `diagnose` command can be used to check the state of databases.
79+
By default it will look at all the LMDB databases (in `/var/cfengine/state/`).
80+
Technically it will attempt to open the database, and run some per-database validation checks (based on the filename).
81+
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.
82+
83+
```command
84+
cf-check diagnose
85+
```
86+
87+
```output
88+
info: No filenames specified, defaulting to .lmdb files in /var/cfengine/state
89+
info: Status of '/var/cfengine/state/history.lmdb': OK [0% usage]
90+
info: Status of '/var/cfengine/state/cf_state.lmdb': OK [0% usage]
91+
info: Status of '/var/cfengine/state/nova_cookies.lmdb': OK [0% usage]
92+
info: Status of '/var/cfengine/state/nova_track.lmdb': OK [0% usage]
93+
info: Status of '/var/cfengine/state/nova_measures.lmdb': OK [0% usage]
94+
info: Status of '/var/cfengine/state/cf_changes.lmdb': OK [0% usage]
95+
info: Status of '/var/cfengine/state/packages_installed_apt_get.lmdb': OK [0% usage]
96+
info: Status of '/var/cfengine/state/cf_lock.lmdb': OK [0% usage]
97+
info: Status of '/var/cfengine/state/performance.lmdb': OK [0% usage]
98+
info: Status of '/var/cfengine/state/cf_lastseen.lmdb': OK [0% usage]
99+
info: Status of '/var/cfengine/state/cf_observations.lmdb': OK [0% usage]
100+
info: Status of '/var/cfengine/state/nova_agent_execution.lmdb': OK [0% usage]
101+
info: Status of '/var/cfengine/state/packages_updates_apt_get.lmdb': OK [0% usage]
102+
info: Status of '/var/cfengine/state/nova_static.lmdb': OK [0% usage]
103+
info: All 14 databases healthy
104+
```
105+
106+
You can also specify a specific filename:
107+
108+
```command
109+
cf-check diagnose /var/cfengine/state/cf_lastseen.lmdb
110+
```
111+
112+
```output
113+
info: Status of '/var/cfengine/state/cf_lastseen.lmdb': OK [0% usage]
114+
info: All 1 databases healthy
115+
```
116+
117+
## Repairing corrupt databases
118+
119+
The `repair` command builds on the functionality of the `diagnose` command, but attempts to fix the situation when there are corrupt databases found.
120+
121+
```command
122+
cf-check repair /var/cfengine/state/cf_state.lmdb
123+
```
124+
125+
```output
126+
info: Status of '/var/cfengine/state/cf_state.lmdb': LMDB_INVALID_DATABASE [0% usage]
127+
error: Problems detected in 1/1 databases
128+
notice: 1 corrupt database to fix
129+
info: Backing up to '/var/cfengine/backups/1772733351-WZgDKk/'
130+
info: Copying: '/var/cfengine/state/cf_state.lmdb' -> '/var/cfengine/backups/1772733351-WZgDKk/cf_state.lmdb'
131+
error: Failed to repair file '/var/cfengine/state/cf_state.lmdb', removing
132+
notice: Database repair successful
133+
```

0 commit comments

Comments
 (0)