--- /dev/null
+
+cephfs-journal-tool
+===================
+
+Purpose
+-------
+
+If a CephFS journal has become damaged, expert intervention may be required
+to restore the filesystem to a working state.
+
+The ``cephfs-journal-tool`` utility provides functionality to aid experts in
+examining, modifying, and extracting data from journals.
+
+.. warning::
+
+ This tool is **dangerous** because it directly modifies internal
+ data structures of the filesystem. Make backups, be careful, and
+ seek expert advice. If you are unsure, do not run this tool.
+
+Syntax
+------
+
+::
+
+ cephfs-journal-tool journal <inspect|import|export|reset>
+ cephfs-journal-tool header <get|set>
+ cephfs-journal-tool event <get|splice|apply> [filter] <list|json|summary>
+
+
+The tool operates in three modes: ``journal``, ``header`` and ``event``,
+meaning the whole journal, the header, and the events within the journal
+respectively.
+
+Journal mode
+------------
+
+This should be your starting point to assess the state of a journal.
+
+* ``inspect`` reports on the health of the journal. This will identify any
+ missing objects or corruption in the stored journal. Note that this does
+ not identify inconsistencies in the events themselves, just that events are
+ present and can be decoded.
+
+* ``import`` and ``export`` read and write binary dumps of the journal
+ in a sparse file format. Pass the filename as the last argument. The
+ export operation may not work reliably for journals which are damaged (missing
+ objects).
+
+* ``reset`` truncates a journal, discarding any information within it.
+
+
+Example: journal inspect
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ # cephfs-journal-tool journal inspect
+ Overall journal integrity: DAMAGED
+ Objects missing:
+ 0x1
+ Corrupt regions:
+ 0x400000-ffffffffffffffff
+
+Example: Journal import/export
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ # cephfs-journal-tool journal export myjournal.bin
+ journal is 4194304~80643
+ read 80643 bytes at offset 4194304
+ wrote 80643 bytes at offset 4194304 to myjournal.bin
+ NOTE: this is a _sparse_ file; you can
+ $ tar cSzf myjournal.bin.tgz myjournal.bin
+ to efficiently compress it while preserving sparseness.
+
+ # cephfs-journal-tool journal import myjournal.bin
+ undump myjournal.bin
+ start 4194304 len 80643
+ writing header 200.00000000
+ writing 4194304~80643
+ done.
+
+.. note::
+
+ It is wise to use the ``journal export <backup file>`` command to make a journal backup
+ before any further manipulation.
+
+Header mode
+-----------
+
+* ``get`` outputs the current content of the journal header
+
+* ``set`` modifies an attribute of the header. Allowed attributes are
+ ``trimmed_pos``, ``expire_pos`` and ``write_pos``.
+
+Example: header get/set
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ # cephfs-journal-tool header get
+ { "magic": "ceph fs volume v011",
+ "write_pos": 4274947,
+ "expire_pos": 4194304,
+ "trimmed_pos": 4194303,
+ "layout": { "stripe_unit": 4194304,
+ "stripe_count": 4194304,
+ "object_size": 4194304,
+ "cas_hash": 4194304,
+ "object_stripe_unit": 4194304,
+ "pg_pool": 4194304}}
+
+ # cephfs-journal-tool header set trimmed_pos 4194303
+ Updating trimmed_pos 0x400000 -> 0x3fffff
+ Successfully updated header.
+
+
+Event mode
+----------
+
+Event mode allows detailed examination and manipulation of the contents of the journal. Event
+mode can operate on all events in the journal, or filters may be applied.
+
+The arguments following ``cephfs-journal-tool event`` consist of an action, optional filter
+parameters, and an output mode:
+
+::
+
+ cephfs-journal-tool event <action> [filter] <output>
+
+Actions:
+
+* ``get`` read the events from the log
+* ``splice`` erase events or regions in the journal
+* ``apply`` extract filesystem metadata from events and attempt to apply it to the metadata store.
+
+Filtering:
+
+* ``--range <int begin>..[int end]`` only include events within the range begin (inclusive) to end (exclusive)
+* ``--path <path substring>`` only include events referring to metadata containing the specified string
+* ``--inode <int>`` only include events referring to metadata containing the specified string
+* ``--type <type string>`` only include events of this type
+* ``--frag <ino>[.frag id]`` only include events referring to this directory fragment
+* ``--dname <string>`` only include events referring to this named dentry within a directory
+ fragment (may only be used in conjunction with ``--frag``
+* ``--client <int>`` only include events from this client session ID
+
+Filters may be combined on an AND basis (i.e. only the intersection of events from each filter).
+
+Output modes:
+
+* ``binary``: write each event as a binary file, within a folder whose name is controlled by ``--path``
+* ``json``: write all events to a single file, as a JSON serialized list of objects
+* ``summary``: write a human readable summary of the events read to standard out
+* ``list``: write a human readable terse listing of the type of each event, and
+ which file paths the event affects.
+
+
+Example: event mode
+~~~~~~~~~~~~~~~~~~~
+
+::
+
+ # cephfs-journal-tool event get json --path output.json
+ Wrote output to JSON file 'output.json'
+
+ # cephfs-journal-tool event get summary
+ Events by type:
+ NOOP: 2
+ OPEN: 2
+ SESSION: 2
+ SUBTREEMAP: 1
+ UPDATE: 43
+
+ # cephfs-journal-tool event get list
+ 0x400000 SUBTREEMAP: ()
+ 0x400308 SESSION: ()
+ 0x4003de UPDATE: (setattr)
+ /
+ 0x40068b UPDATE: (mkdir)
+ diralpha
+ 0x400d1b UPDATE: (mkdir)
+ diralpha/filealpha1
+ 0x401666 UPDATE: (unlink_local)
+ stray0/10000000001
+ diralpha/filealpha1
+ 0x40228d UPDATE: (unlink_local)
+ diralpha
+ stray0/10000000000
+ 0x402bf9 UPDATE: (scatter_writebehind)
+ stray0
+ 0x403150 UPDATE: (mkdir)
+ dirbravo
+ 0x4037e0 UPDATE: (openc)
+ dirbravo/.filebravo1.swp
+ 0x404032 UPDATE: (openc)
+ dirbravo/.filebravo1.swpx
+
+ # cephfs-journal-tool event get --path /filebravo1 list
+ 0x40785a UPDATE: (openc)
+ dirbravo/filebravo1
+ 0x4103ee UPDATE: (cap update)
+ dirbravo/filebravo1
+
+ # cephfs-journal-tool event splice --range 0x40f754..0x410bf1 summary
+ Events by type:
+ OPEN: 1
+ UPDATE: 2
+
+ # cephfs-journal-tool event apply --range 0x410bf1.. summary
+ Events by type:
+ NOOP: 1
+ SESSION: 1
+ UPDATE: 9
+
+ # cephfs-journal-tool event get --inode=1099511627776 list
+ 0x40068b UPDATE: (mkdir)
+ diralpha
+ 0x400d1b UPDATE: (mkdir)
+ diralpha/filealpha1
+ 0x401666 UPDATE: (unlink_local)
+ stray0/10000000001
+ diralpha/filealpha1
+ 0x40228d UPDATE: (unlink_local)
+ diralpha
+ stray0/10000000000
+
+ # cephfs-journal-tool event get --frag=1099511627776 --dname=filealpha1 list
+ 0x400d1b UPDATE: (mkdir)
+ diralpha/filealpha1
+ 0x401666 UPDATE: (unlink_local)
+ stray0/10000000001
+ diralpha/filealpha1
+
+ # cephfs-journal-tool event get binary --path bin_events
+ Wrote output to binary files in directory 'bin_events'
+
Code Review / stor4nfv.git / blobdiff