Skip to content

Commit 16de0c0

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 16de0c0

1 file changed

Lines changed: 125 additions & 4 deletions

File tree

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

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

0 commit comments

Comments
 (0)