1xfs_metadump(8)             System Manager's Manual            xfs_metadump(8)
2
3
4

NAME

6       xfs_metadump - copy XFS filesystem metadata to a file
7

SYNOPSIS

9       xfs_metadump  [  -aefFgow  ]  [ -m max_extents ] ] [ -l logdev ] source
10       target
11       xfs_metadump -V
12

DESCRIPTION

14       xfs_metadump is a debugging tool that copies the metadata from  an  XFS
15       filesystem  to a file.  The source argument must be the pathname of the
16       device or file containing the XFS filesystem and  the  target  argument
17       specifies  the  destination file name.  If target is -, then the output
18       is sent to stdout. This allows the output to be redirected  to  another
19       program such as a compression application.
20
21       xfs_metadump  may  only be used to copy unmounted filesystems, or read-
22       only mounted filesystems.
23
24       xfs_metadump does not alter the source filesystem in any way. The  tar‐
25       get image is a contiguous (non-sparse) file containing all the filesys‐
26       tem's metadata and indexes to where the blocks were copied from.
27
28       By default, xfs_metadump obfuscates most file (regular file,  directory
29       and  symbolic  link)  names  and  extended attribute names to allow the
30       dumps to be sent without revealing confidential  information.  Extended
31       attribute  values are zeroed and no data is copied. The only exceptions
32       are file or attribute names that are 4 or less  characters  in  length.
33       Also  file  names  that  span  extents  (this  can  only occur with the
34       mkfs.xfs(8) options where -n size > -b size) are not obfuscated.  Names
35       between  5  and 8 characters in length inclusively are partially obfus‐
36       cated.
37
38       xfs_metadump cannot obfuscate metadata  in  the  filesystem  log.   Log
39       recovery of an obfuscated metadump image may expose clear-text metadata
40       and/or cause filesystem corruption in the restored image.  It is recom‐
41       mended  that  the  source filesystem first be mounted and unmounted, if
42       possible, to ensure that the log is clean.  A subsequent invocation  of
43       xfs_metadump  will  capture a clean log and obfuscate all metadata cor‐
44       rectly.
45
46       If a metadump must be produced from a filesystem with a dirty  log,  it
47       is  recommended that obfuscation be turned off with -o option, if meta‐
48       data such as filenames is not considered sensitive.  If obfuscation  is
49       required on a metadump with a dirty log, please inform the recipient of
50       the metadump image about this situation.
51
52       xfs_metadump should not be used for any purposes other than for  debug‐
53       ging  and reporting filesystem problems. The most common usage scenario
54       for this tool is when xfs_repair(8) fails to repair a filesystem and  a
55       metadump image can be sent for analysis.
56
57       The  file generated by xfs_metadump can be restored to filesystem image
58       (minus the data) using the xfs_mdrestore(8) tool.
59

OPTIONS

61       -a     Copies entire metadata blocks.  Normally, xfs_metadump will zero
62              any  stale  bytes  interspersed  with in-use metadata.  Use this
63              option to copy full metadata blocks, to provide  more  debugging
64              information  for  a  corrupted  filesystem.  Note that the extra
65              data will be unobfuscated.
66
67       -e     Stops the dump on a read error. Normally, it  will  ignore  read
68              errors and copy all the metadata that is accessible.
69
70       -f     Specifies that the filesystem image to be processed is stored in
71              a regular file (see the mkfs.xfs -d file option). This can  also
72              happen  if  an  image copy of a filesystem has been made into an
73              ordinary file with xfs_copy(8).
74
75       -F     Specifies that we want to continue even if the superblock  magic
76              is  not  correct.  If the source is truly not an XFS filesystem,
77              the resulting image will be useless, and xfs_metadump may crash.
78
79       -g     Shows dump progress. This is sent to stdout if the target  is  a
80              file or to stderr if the target is stdout.
81
82       -l logdev
83              For  filesystems  which  use an external log, this specifies the
84              device where the external log resides. The external log  is  not
85              copied, only internal logs are copied.
86
87       -m     Set  the  maximum size of an allowed metadata extent.  Extremely
88              large metadata extents are likely to be  corrupt,  and  will  be
89              skipped  if they exceed this value.  The default size is 2097151
90              blocks.
91
92       -o     Disables obfuscation of file names and extended attributes.
93
94       -w     Prints warnings of inconsistent metadata encountered to  stderr.
95              Bad metadata is still copied.
96
97       -V     Prints the version number and exits.
98

DIAGNOSTICS

100       xfs_metadump returns an exit code of 0 if all readable metadata is suc‐
101       cessfully copied or 1 if a write error occurs or a  read  error  occurs
102       and the -e option used.
103

NOTES

105       As  xfs_metadump copies metadata only, it does not matter if the source
106       filesystem has a realtime section or not.  If  the  filesystem  has  an
107       external  log,  it is not copied. Internal logs are copied and any out‐
108       standing log transactions are not obfuscated if they contain names.
109
110       xfs_metadump is a shell wrapper around the xfs_db(8) metadump command.
111

SEE ALSO

113       xfs_repair(8), xfs_mdrestore(8), xfs_freeze(8), xfs_db(8), xfs_copy(8),
114       xfs(5)
115

BUGS

117       Email bug reports to linux-xfs@vger.kernel.org.
118
119
120
121                                                               xfs_metadump(8)
Impressum