[PATCH 3/3] XFS metadump utility

[PATCH 3/3] XFS metadump utility

[Barry Naujok]

[-- Attachment #1: Type: text/plain, Size: 41 bytes --]

xfs_metadump and xfs_mdrestore man pages.

[-- Attachment #2: xfs_md_man.patch --]
[-- Type: application/octet-stream, Size: 7325 bytes --]


===========================================================================
xfsprogs/man/man8/xfs_db.8
===========================================================================

--- a/xfsprogs/man/man8/xfs_db.8	2007-05-28 15:09:38.000000000 +1000
+++ b/xfsprogs/man/man8/xfs_db.8	2007-05-28 12:46:00.823121319 +1000
@@ -367,6 +367,10 @@ If no \f2label\f1 is given, the current 
 Start logging output to \f2filename\f1, stop logging,
 or print the current logging status.
 .TP
+\f3metadump\f1 [ \f3-egow\f1 ] \f2filename\f1
+Dumps metadata to a file. See
+.BR xfs_metadump "(8) for more information."
+.TP
 \f3ncheck\f1 [ \f3\-s\f1 ] [ \f3\-i\f1 \f2ino\f1 ] ...
 Print name-inode pairs.
 A \f3blockget \-n\f1 command must be run first to gather the information.
@@ -1239,6 +1243,7 @@ xfs_admin(8),
 xfs_check(8),
 xfs_copy(8),
 xfs_logprint(8),
+xfs_metadump(8),
 xfs_ncheck(8),
 xfs_repair(8),
 mount(8),

===========================================================================
xfsprogs/man/man8/xfs_mdrestore.8
===========================================================================

--- a/xfsprogs/man/man8/xfs_mdrestore.8	2006-06-17 00:58:24.000000000 +1000
+++ b/xfsprogs/man/man8/xfs_mdrestore.8	2007-05-28 13:00:01.919418531 +1000
@@ -0,0 +1,48 @@
+.TH xfs_mdrestore 8
+.SH NAME
+xfs_mdrestore \- restores an XFS metadump image to a filesystem image
+.SH SYNOPSIS
+.B xfs_mdrestore
+.RB [ \-g ]
+.I source
+.I target
+.SH DESCRIPTION
+.B xfs_mdrestore
+is a debugging tool that restores a metadata image generated by
+.BR xfs_metadump (8)
+to a filesystem. The
+.I source
+argument specifies the location of the metadump image and the
+.I target
+argument specifies the destination for the filsystem image.
+If the
+.I source
+is \-, then the metadata image is read from stdin. This allows the output of
+be another program such as a compression application to be redirected to
+.BR xfs_mdrestore .
+The
+.I target
+can be either a file or a device.
+.PP
+.B xfs_mdrestore
+should not be used to restore metadata onto an existing filesystem unless
+you are completely certain the
+.I target
+can be destroyed.
+.PP
+.SH OPTIONS
+.TP
+.B \-g
+Shows restore progress on stdout.
+.SH DIAGNOSTICS
+.B xfs_mdrestore
+returns an exit code of 0 if all the metadata is succesfully restored or
+1 if an error occurs.
+.SH SEE ALSO
+.BR xfs_metadump (8),
+.BR xfs_repair (8),
+.BR xfs_check (8),
+.BR xfs (5)
+.SH BUGS
+Email bug reports to
+.BR xfs@oss.sgi.com .
\ No newline at end of file

===========================================================================
xfsprogs/man/man8/xfs_metadump.8
===========================================================================

--- a/xfsprogs/man/man8/xfs_metadump.8	2006-06-17 00:58:24.000000000 +1000
+++ b/xfsprogs/man/man8/xfs_metadump.8	2007-05-28 15:07:58.350147551 +1000
@@ -0,0 +1,127 @@
+.TH xfs_metadump 8
+.SH NAME
+xfs_metadump \- copy XFS filesystem metadata to a file
+.SH SYNOPSIS
+.B xfs_metadump
+.RB [ \-efgow ]
+.RB [ \-l
+.IR logdev ]
+.I source
+.I target
+.SH DESCRIPTION
+.B xfs_metadump
+is a debugging tool that copies the metadata from an XFS filesystem to a file.
+The
+.I source
+argument must be the pathname of the device or file
+containing the XFS filesystem and the
+.I target
+argument specifies the destination file name.
+If
+.I target
+is \-, then the output is sent to stdout. This allows the output to be
+redirected to another program such as a compression application.
+.PP
+.B xfs_metadump
+should only be used to copy unmounted filesystems, read-only mounted
+filesystems, or frozen filesystems (see
+.BR xfs_freeze (8)).
+Otherwise, the generated dump could be inconsistent or corrupt.
+.PP
+.B xfs_metadump
+does not alter the source filesystem in any way. The
+.I target
+image is a contiguous (non-sparse) file containing all the
+filesystem's metadata and indexes to where the blocks were copied from.
+.PP
+By default,
+.B xfs_metadump
+obfuscates most directory names and extended attribute names to allow the dumps
+to be sent without revealing confidential information. Extended attribute
+values are zeroed and no data is copied. The only exceptions are directory
+or attribute names that are 4 or less characters in length. Also directory
+names that span extents (this can only occur with the
+.BR mkfs.xfs (8)
+options where
+.B \-n
+.I size
+>
+.B \-b
+.IR size )
+are not obfuscated.
+.PP
+.B xfs_metadump
+should not be used for any purposes other than for debugging and reporting
+filesystem problems. The most common usage scenario for this tool is when
+.BR xfs_repair (8)
+fails to repair a filesystem and a metadump image can be sent for
+analysis.
+.PP
+The file generated by
+.B xfs_metadump
+can be restored to filesystem image (minus the data) using the
+.BR xfs_mdrestore (8)
+tool.
+.PP
+.SH OPTIONS
+.TP
+.B \-e
+Stops the dump on a read error. Nomally, it will ignore read errors and copy
+as much metadump data as is accessible.
+.TP
+.B \-f
+Specifies that the filesystem image to be processed is stored in a regular file
+(see the
+.B mkfs.xfs -d
+file option). This can also happen if an image copy of a filesystem has
+been made into an ordinary file with
+.BR xfs_copy (8).
+.TP
+.B \-g
+Shows dump progress. This is sent to stdout if the
+.I target
+is a file or to stderr if the
+.I target
+is stdout.
+.TP
+.BI \-l " logdev"
+For filesystems which use an external log, this specifies the device where the
+external log resides. The external log is not copied, only internal logs are
+copied.
+.TP
+.B \-o
+Disables obfuscation of file names and extended attributes.
+.TP
+.B \-w
+Prints warnings of inconsistant metadata encountered to stderr. Bad metadata
+is still copied.
+.SH DIAGNOSTICS
+.B xfs_metadump
+returns an exit code of 0 if all readable metadata is succesfully copied or
+1 if a write error occurs or a read error occurs and the
+.B \-e
+option used.
+.SH NOTES
+As
+.B xfs_metadump
+copies metadata only, it does not matter if the
+.I source
+filesystem has a realtime section or not. If the filesystem has an external
+log, it is not copied. Internal logs are copied and any outstanding log
+transactions are not obfuscated if they contain names.
+.PP
+.B xfs_metadump
+is a shell wrapper around the
+.BR xfs_db (8)
+.B metadump
+command.
+.SH SEE ALSO
+.BR xfs_repair (8),
+.BR xfs_mdrestore (8),
+.BR xfs_freeze (8),
+.BR xfs_db (8),
+.BR xfs_copy (8),
+.BR xfs (5)
+.SH BUGS
+Email bug reports to
+.BR xfs@oss.sgi.com .
\ No newline at end of file

===========================================================================
xfsprogs/man/man8/xfs_repair.8
===========================================================================

--- a/xfsprogs/man/man8/xfs_repair.8	2007-05-28 15:09:38.000000000 +1000
+++ b/xfsprogs/man/man8/xfs_repair.8	2007-05-28 12:47:44.889800552 +1000
@@ -434,9 +434,17 @@ maps, particularly lost blocks or subtly
 The no-modify mode can generate repeated warnings about
 the same problems because it cannot fix the problems as they
 are encountered.
+.PP
+If a filesystem fails to be repaired, a metadump image can be generated
+with
+.BR xfs_metadump (8)
+and be sent to an XFS maintainer to be analysed and
+.B xfs_repair
+fixed and/or improved.
 .SH SEE ALSO
 dd(1),
 mkfs.xfs(8),
 umount(8),
 xfs_check(8),
+xfs_metadump(8),
 xfs(5).

Re: [PATCH 3/3] XFS metadump utility

[Christoph Hellwig]

On Mon, May 28, 2007 at 03:22:58PM +1000, Barry Naujok wrote:
> xfs_metadump and xfs_mdrestore man pages.

Looks fine.