src/ceph/doc/cephfs/cephfs-journal-tool.rst

   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>
  27     cephfs-journal-tool event <get|splice|apply> [filter] <list|json|summary>
  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
 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
 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
 200     # cephfs-journal-tool event get --path /filebravo1 list
 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