]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | |
2 | cephfs-journal-tool | |
3 | =================== | |
4 | ||
5 | Purpose | |
6 | ------- | |
7 | ||
8 | If a CephFS journal has become damaged, expert intervention may be required | |
9 | to restore the filesystem to a working state. | |
10 | ||
11 | The ``cephfs-journal-tool`` utility provides functionality to aid experts in | |
12 | examining, modifying, and extracting data from journals. | |
13 | ||
14 | .. warning:: | |
15 | ||
16 | This tool is **dangerous** because it directly modifies internal | |
17 | data structures of the filesystem. Make backups, be careful, and | |
18 | seek expert advice. If you are unsure, do not run this tool. | |
19 | ||
20 | Syntax | |
21 | ------ | |
22 | ||
23 | :: | |
24 | ||
25 | cephfs-journal-tool journal <inspect|import|export|reset> | |
26 | cephfs-journal-tool header <get|set> | |
11fdf7f2 | 27 | cephfs-journal-tool event <get|splice|apply> [filter] <list|json|summary|binary> |
7c673cae FG |
28 | |
29 | ||
30 | The tool operates in three modes: ``journal``, ``header`` and ``event``, | |
31 | meaning the whole journal, the header, and the events within the journal | |
32 | respectively. | |
33 | ||
34 | Journal mode | |
35 | ------------ | |
36 | ||
37 | This should be your starting point to assess the state of a journal. | |
38 | ||
39 | * ``inspect`` reports on the health of the journal. This will identify any | |
40 | missing objects or corruption in the stored journal. Note that this does | |
41 | not identify inconsistencies in the events themselves, just that events are | |
42 | present and can be decoded. | |
43 | ||
44 | * ``import`` and ``export`` read and write binary dumps of the journal | |
45 | in a sparse file format. Pass the filename as the last argument. The | |
46 | export operation may not work reliably for journals which are damaged (missing | |
47 | objects). | |
48 | ||
49 | * ``reset`` truncates a journal, discarding any information within it. | |
50 | ||
51 | ||
52 | Example: journal inspect | |
53 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
54 | ||
55 | :: | |
56 | ||
57 | # cephfs-journal-tool journal inspect | |
58 | Overall journal integrity: DAMAGED | |
59 | Objects missing: | |
60 | 0x1 | |
61 | Corrupt regions: | |
62 | 0x400000-ffffffffffffffff | |
63 | ||
64 | Example: Journal import/export | |
65 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
66 | ||
67 | :: | |
68 | ||
69 | # cephfs-journal-tool journal export myjournal.bin | |
70 | journal is 4194304~80643 | |
71 | read 80643 bytes at offset 4194304 | |
72 | wrote 80643 bytes at offset 4194304 to myjournal.bin | |
73 | NOTE: this is a _sparse_ file; you can | |
74 | $ tar cSzf myjournal.bin.tgz myjournal.bin | |
75 | to efficiently compress it while preserving sparseness. | |
76 | ||
77 | # cephfs-journal-tool journal import myjournal.bin | |
78 | undump myjournal.bin | |
79 | start 4194304 len 80643 | |
80 | writing header 200.00000000 | |
81 | writing 4194304~80643 | |
82 | done. | |
83 | ||
84 | .. note:: | |
85 | ||
86 | It is wise to use the ``journal export <backup file>`` command to make a journal backup | |
87 | before any further manipulation. | |
88 | ||
89 | Header mode | |
90 | ----------- | |
91 | ||
92 | * ``get`` outputs the current content of the journal header | |
93 | ||
94 | * ``set`` modifies an attribute of the header. Allowed attributes are | |
95 | ``trimmed_pos``, ``expire_pos`` and ``write_pos``. | |
96 | ||
97 | Example: header get/set | |
98 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
99 | ||
100 | :: | |
101 | ||
102 | # cephfs-journal-tool header get | |
103 | { "magic": "ceph fs volume v011", | |
104 | "write_pos": 4274947, | |
105 | "expire_pos": 4194304, | |
106 | "trimmed_pos": 4194303, | |
107 | "layout": { "stripe_unit": 4194304, | |
108 | "stripe_count": 4194304, | |
109 | "object_size": 4194304, | |
110 | "cas_hash": 4194304, | |
111 | "object_stripe_unit": 4194304, | |
112 | "pg_pool": 4194304}} | |
113 | ||
114 | # cephfs-journal-tool header set trimmed_pos 4194303 | |
115 | Updating trimmed_pos 0x400000 -> 0x3fffff | |
116 | Successfully updated header. | |
117 | ||
118 | ||
119 | Event mode | |
120 | ---------- | |
121 | ||
122 | Event mode allows detailed examination and manipulation of the contents of the journal. Event | |
123 | mode can operate on all events in the journal, or filters may be applied. | |
124 | ||
125 | The arguments following ``cephfs-journal-tool event`` consist of an action, optional filter | |
126 | parameters, and an output mode: | |
127 | ||
128 | :: | |
129 | ||
130 | cephfs-journal-tool event <action> [filter] <output> | |
131 | ||
132 | Actions: | |
133 | ||
134 | * ``get`` read the events from the log | |
135 | * ``splice`` erase events or regions in the journal | |
136 | * ``apply`` extract filesystem metadata from events and attempt to apply it to the metadata store. | |
137 | ||
138 | Filtering: | |
139 | ||
140 | * ``--range <int begin>..[int end]`` only include events within the range begin (inclusive) to end (exclusive) | |
141 | * ``--path <path substring>`` only include events referring to metadata containing the specified string | |
11fdf7f2 | 142 | * ``--inode <int>`` only include events referring to metadata containing the specified inode |
7c673cae FG |
143 | * ``--type <type string>`` only include events of this type |
144 | * ``--frag <ino>[.frag id]`` only include events referring to this directory fragment | |
145 | * ``--dname <string>`` only include events referring to this named dentry within a directory | |
146 | fragment (may only be used in conjunction with ``--frag`` | |
147 | * ``--client <int>`` only include events from this client session ID | |
148 | ||
149 | Filters may be combined on an AND basis (i.e. only the intersection of events from each filter). | |
150 | ||
151 | Output modes: | |
152 | ||
153 | * ``binary``: write each event as a binary file, within a folder whose name is controlled by ``--path`` | |
154 | * ``json``: write all events to a single file, as a JSON serialized list of objects | |
155 | * ``summary``: write a human readable summary of the events read to standard out | |
156 | * ``list``: write a human readable terse listing of the type of each event, and | |
157 | which file paths the event affects. | |
158 | ||
159 | ||
160 | Example: event mode | |
161 | ~~~~~~~~~~~~~~~~~~~ | |
162 | ||
163 | :: | |
164 | ||
165 | # cephfs-journal-tool event get json --path output.json | |
166 | Wrote output to JSON file 'output.json' | |
167 | ||
168 | # cephfs-journal-tool event get summary | |
169 | Events by type: | |
170 | NOOP: 2 | |
171 | OPEN: 2 | |
172 | SESSION: 2 | |
173 | SUBTREEMAP: 1 | |
174 | UPDATE: 43 | |
175 | ||
176 | # cephfs-journal-tool event get list | |
177 | 0x400000 SUBTREEMAP: () | |
178 | 0x400308 SESSION: () | |
179 | 0x4003de UPDATE: (setattr) | |
180 | / | |
181 | 0x40068b UPDATE: (mkdir) | |
182 | diralpha | |
183 | 0x400d1b UPDATE: (mkdir) | |
184 | diralpha/filealpha1 | |
185 | 0x401666 UPDATE: (unlink_local) | |
186 | stray0/10000000001 | |
187 | diralpha/filealpha1 | |
188 | 0x40228d UPDATE: (unlink_local) | |
189 | diralpha | |
190 | stray0/10000000000 | |
191 | 0x402bf9 UPDATE: (scatter_writebehind) | |
192 | stray0 | |
193 | 0x403150 UPDATE: (mkdir) | |
194 | dirbravo | |
195 | 0x4037e0 UPDATE: (openc) | |
196 | dirbravo/.filebravo1.swp | |
197 | 0x404032 UPDATE: (openc) | |
198 | dirbravo/.filebravo1.swpx | |
199 | ||
11fdf7f2 | 200 | # cephfs-journal-tool event get --path filebravo1 list |
7c673cae FG |
201 | 0x40785a UPDATE: (openc) |
202 | dirbravo/filebravo1 | |
203 | 0x4103ee UPDATE: (cap update) | |
204 | dirbravo/filebravo1 | |
205 | ||
206 | # cephfs-journal-tool event splice --range 0x40f754..0x410bf1 summary | |
207 | Events by type: | |
208 | OPEN: 1 | |
209 | UPDATE: 2 | |
210 | ||
211 | # cephfs-journal-tool event apply --range 0x410bf1.. summary | |
212 | Events by type: | |
213 | NOOP: 1 | |
214 | SESSION: 1 | |
215 | UPDATE: 9 | |
216 | ||
217 | # cephfs-journal-tool event get --inode=1099511627776 list | |
218 | 0x40068b UPDATE: (mkdir) | |
219 | diralpha | |
220 | 0x400d1b UPDATE: (mkdir) | |
221 | diralpha/filealpha1 | |
222 | 0x401666 UPDATE: (unlink_local) | |
223 | stray0/10000000001 | |
224 | diralpha/filealpha1 | |
225 | 0x40228d UPDATE: (unlink_local) | |
226 | diralpha | |
227 | stray0/10000000000 | |
228 | ||
229 | # cephfs-journal-tool event get --frag=1099511627776 --dname=filealpha1 list | |
230 | 0x400d1b UPDATE: (mkdir) | |
231 | diralpha/filealpha1 | |
232 | 0x401666 UPDATE: (unlink_local) | |
233 | stray0/10000000001 | |
234 | diralpha/filealpha1 | |
235 | ||
236 | # cephfs-journal-tool event get binary --path bin_events | |
237 | Wrote output to binary files in directory 'bin_events' | |
238 |