Document the metadump file format.
Signed-off-by: Darrick J. Wong <darrick.wong@xxxxxxxxxx>
---
design/XFS_Filesystem_Structure/docinfo.xml | 14 +++++
design/XFS_Filesystem_Structure/magic.asciidoc | 1
design/XFS_Filesystem_Structure/metadump.asciidoc | 62 ++++++++++++++++++++
.../xfs_filesystem_structure.asciidoc | 9 +++
4 files changed, 86 insertions(+)
create mode 100644 design/XFS_Filesystem_Structure/metadump.asciidoc
diff --git a/design/XFS_Filesystem_Structure/docinfo.xml b/design/XFS_Filesystem_Structure/docinfo.xml
index 5cdcf6c..e13d705 100644
--- a/design/XFS_Filesystem_Structure/docinfo.xml
+++ b/design/XFS_Filesystem_Structure/docinfo.xml
@@ -155,4 +155,18 @@
</simplelist>
</revdescription>
</revision>
+ <revision>
+ <revnumber>3.14159</revnumber>
+ <date>June 2017</date>
+ <author>
+ <firstname>Darrick</firstname>
+ <surname>Wong</surname>
+ <email>darrick.wong@xxxxxxxxxx</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Add the metadump file format.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
</revhistory>
diff --git a/design/XFS_Filesystem_Structure/magic.asciidoc b/design/XFS_Filesystem_Structure/magic.asciidoc
index 77bed6d..7e62783 100644
--- a/design/XFS_Filesystem_Structure/magic.asciidoc
+++ b/design/XFS_Filesystem_Structure/magic.asciidoc
@@ -47,6 +47,7 @@ relevant chapters. Magic numbers tend to have consistent locations:
| +XFS_RMAP_CRC_MAGIC+ | 0x524d4233 | RMB3 | xref:Reverse_Mapping_Btree[Reverse Mapping B+tree], v5 only
| +XFS_RTRMAP_CRC_MAGIC+ | 0x4d415052 | MAPR | xref:Real_time_Reverse_Mapping_Btree[Real-Time Reverse Mapping B+tree], v5 only
| +XFS_REFC_CRC_MAGIC+ | 0x52334643 | R3FC | xref:Reference_Count_Btree[Reference Count B+tree], v5 only
+| +XFS_MD_MAGIC+ | 0x5846534d | XFSM | xref:Metadata_Dumps[Metadata Dumps]
|=====
The magic numbers for log items are at offset zero in each log item, but items
diff --git a/design/XFS_Filesystem_Structure/metadump.asciidoc b/design/XFS_Filesystem_Structure/metadump.asciidoc
new file mode 100644
index 0000000..2bddb77
--- /dev/null
+++ b/design/XFS_Filesystem_Structure/metadump.asciidoc
@@ -0,0 +1,62 @@
+[[Metadata_Dumps]]
+= Metadata Dumps
+
+The +xfs_metadump+ and +xfs_mdrestore+ tools are used to create a sparse
+snapshot of a live file system and to restore that snapshot onto a block
+device for debugging purposes. Only the metadata are captured in the
+snapshot, and the metadata blocks may be obscured for privacy reasons.
+
+A metadump file starts with a +xfs_metablock+ that records the addresses of
+the blocks that follow. Following that are the metadata blocks captured
+from the filesystem. The first block following the first superblock
+must be the superblock from AG 0. If the metadump has more blocks than
+can be pointed to by the +xfs_metablock.mb_daddr+ area, the sequence
+of +xfs_metablock+ followed by metadata blocks is repeated.
+
+.Metadata Dump Format
+
+[source, c]
+----
+struct xfs_metablock {
+ __be32 mb_magic;
+ __be16 mb_count;
+ uint8_t mb_blocklog;
+ uint8_t mb_reserved;
+ __be64 mb_daddr[];
+};
+----
+
+*mb_magic*::
+The magic number, ``XFSM'' (0x5846534d).
+
+*mb_count*::
+Number of blocks indexed by this record. This value must not exceed +(1
+<< mb_blocklog) - sizeof(struct xfs_metablock)+.
+
+*mb_blocklog*::
+The log size of a metadump block. This size of a metadump block 512
+bytes, so this value should be 9.
+
+*mb_reserved*::
+Reserved. Should be zero.
+
+*mb_daddr*::
+An array of disk addresses. Each of the +mb_count+ blocks (of size +(1
+<< mb_blocklog+) following the +xfs_metablock+ should be written back to
+the address pointed to by the corresponding +mb_daddr+ entry.
+
+== Dump Obfuscation
+
+Unless explicitly disabled, the +xfs_metadump+ tool obfuscates empty block
+space and naming information to avoid leaking sensitive information into
+the metadump file. +xfs_metadump+ does not copy user data blocks.
+
+The obfuscation policy is as follows:
+
+* File and extended attribute names are both considered "names".
+* Names longer than 8 characters are totally rewritten with a name that matches the hash of the old name.
+* Names between 5 and 8 characters are partially rewritten to match the hash of the old name.
+* Names shorter than 5 characters are not obscured at all.
+* Names that cross a block boundary are not obscured at all.
+* Extended attribute values are zeroed.
+* Empty parts of metadata blocks are zeroed.
diff --git a/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc b/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc
index 7916fbe..5540fa0 100644
--- a/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc
+++ b/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc
@@ -96,3 +96,12 @@ include::extended_attributes.asciidoc[]
include::symbolic_links.asciidoc[]
:leveloffset: 0
+
+Auxiliary Data Structures
+=========================
+
+:leveloffset: 1
+
+include::metadump.asciidoc[]
+
+:leveloffset: 0
--
To unsubscribe from this list: send the line "unsubscribe linux-xfs" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
