8 If a CephFS journal has become damaged, expert intervention may be required
9 to restore the filesystem to a working state.
11 The ``cephfs-journal-tool`` utility provides functionality to aid experts in
12 examining, modifying, and extracting data from journals.
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.
25 cephfs-journal-tool journal <inspect|import|export|reset>
26 cephfs-journal-tool header <get|set>
27 cephfs-journal-tool event <get|splice|apply> [filter] <list|json|summary>
30 The tool operates in three modes: ``journal``, ``header`` and ``event``,
31 meaning the whole journal, the header, and the events within the journal
37 This should be your starting point to assess the state of a journal.
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.
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
49 * ``reset`` truncates a journal, discarding any information within it.
52 Example: journal inspect
53 ~~~~~~~~~~~~~~~~~~~~~~~~
57 # cephfs-journal-tool journal inspect
58 Overall journal integrity: DAMAGED
62 0x400000-ffffffffffffffff
64 Example: Journal import/export
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
77 # cephfs-journal-tool journal import myjournal.bin
79 start 4194304 len 80643
80 writing header 200.00000000
86 It is wise to use the ``journal export <backup file>`` command to make a journal backup
87 before any further manipulation.
92 * ``get`` outputs the current content of the journal header
94 * ``set`` modifies an attribute of the header. Allowed attributes are
95 ``trimmed_pos``, ``expire_pos`` and ``write_pos``.
97 Example: header get/set
98 ~~~~~~~~~~~~~~~~~~~~~~~
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,
111 "object_stripe_unit": 4194304,
114 # cephfs-journal-tool header set trimmed_pos 4194303
115 Updating trimmed_pos 0x400000 -> 0x3fffff
116 Successfully updated header.
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.
125 The arguments following ``cephfs-journal-tool event`` consist of an action, optional filter
126 parameters, and an output mode:
130 cephfs-journal-tool event <action> [filter] <output>
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.
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
142 * ``--inode <int>`` only include events referring to metadata containing the specified string
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
149 Filters may be combined on an AND basis (i.e. only the intersection of events from each filter).
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.
165 # cephfs-journal-tool event get json --path output.json
166 Wrote output to JSON file 'output.json'
168 # cephfs-journal-tool event get summary
176 # cephfs-journal-tool event get list
177 0x400000 SUBTREEMAP: ()
179 0x4003de UPDATE: (setattr)
181 0x40068b UPDATE: (mkdir)
183 0x400d1b UPDATE: (mkdir)
185 0x401666 UPDATE: (unlink_local)
188 0x40228d UPDATE: (unlink_local)
191 0x402bf9 UPDATE: (scatter_writebehind)
193 0x403150 UPDATE: (mkdir)
195 0x4037e0 UPDATE: (openc)
196 dirbravo/.filebravo1.swp
197 0x404032 UPDATE: (openc)
198 dirbravo/.filebravo1.swpx
200 # cephfs-journal-tool event get --path /filebravo1 list
201 0x40785a UPDATE: (openc)
203 0x4103ee UPDATE: (cap update)
206 # cephfs-journal-tool event splice --range 0x40f754..0x410bf1 summary
211 # cephfs-journal-tool event apply --range 0x410bf1.. summary
217 # cephfs-journal-tool event get --inode=1099511627776 list
218 0x40068b UPDATE: (mkdir)
220 0x400d1b UPDATE: (mkdir)
222 0x401666 UPDATE: (unlink_local)
225 0x40228d UPDATE: (unlink_local)
229 # cephfs-journal-tool event get --frag=1099511627776 --dname=filealpha1 list
230 0x400d1b UPDATE: (mkdir)
232 0x401666 UPDATE: (unlink_local)
236 # cephfs-journal-tool event get binary --path bin_events
237 Wrote output to binary files in directory 'bin_events'