[PATCH] man: describe the metadata scrubbing ioctl

From: "Darrick J. Wong" <darrick.wong@oracle.com>
To: linux-xfs@vger.kernel.org, Brian Foster <bfoster@redhat.com>,
	Dave Chinner <david@fromorbit.com>
Subject: [PATCH] man: describe the metadata scrubbing ioctl
Date: Thu, 21 Sep 2017 20:27:31 -0700	[thread overview]
Message-ID: <20170922032731.GC5728@magnolia> (raw)
In-Reply-To: <150595305131.18473.16572195821331601191.stgit@magnolia>

Document the XFS-specific metadata scrub/repair ioctl's behavior,
arguments, and side effects.  Dump this in xfsprogs for lack of a
better destination.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/Makefile                        |    2 
 man/man2/ioctl_xfs_scrub_metadata.2 |  298 +++++++++++++++++++++++++++++++++++
 2 files changed, 299 insertions(+), 1 deletion(-)
 create mode 100644 man/man2/ioctl_xfs_scrub_metadata.2

diff --git a/man/Makefile b/man/Makefile
index 863284c..cae891f 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -5,7 +5,7 @@
 TOPDIR = ..
 include $(TOPDIR)/include/builddefs
 
-SUBDIRS = man3 man5 man8
+SUBDIRS = man2 man3 man5 man8
 
 default : $(SUBDIRS)
 
diff --git a/man/man2/ioctl_xfs_scrub_metadata.2 b/man/man2/ioctl_xfs_scrub_metadata.2
new file mode 100644
index 0000000..fa1c56d
--- /dev/null
+++ b/man/man2/ioctl_xfs_scrub_metadata.2
@@ -0,0 +1,298 @@
+.\" Copyright (c) 2017, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-SCRUB-METADATA 2 2017-09-21 "Linux" "Linux Programmer's Manual"
+.SH NAME
+ioctl_xfs_scrub_metadata \- check XFS filesystem metadata
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " dest_fd ", XFS_IOC_SCRUB_METADATA, struct xfs_scrub_metadata *" arg );
+.SH DESCRIPTION
+This XFS ioctl asks the kernel driver to examine a piece of metadata for
+errors or suboptimal metadata.
+Examination includes running the metadata verifiers, checking records
+for obviously incorrect or impossible values, and cross-referencing each
+record with any other available metadata in the filesystem.
+This ioctl can also try to repair or optimize metadata, though this may
+tie up the filesystem for a long period of time.
+The type and location of the metadata is conveyed in a structure of the
+following form:
+.PP
+.in +4n
+.EX
+struct xfs_scrub_metadata {
+	__u32 sm_type;
+	__u32 sm_flags;
+	__u64 sm_ino;
+	__u32 sm_gen;
+	__u32 sm_agno;
+	__u64 sm_reserved[5];
+};
+.EE
+.in
+.PP
+The field
+.I sm_reserved
+must be zero.
+.PP
+The field
+.I sm_type
+indicates the type of metadata to check:
+.RS 0.4i
+.TP
+.B XFS_SCRUB_TYPE_PROBE
+Probe the kernel to see if it is willing to try to check or repair this
+filesystem.
+If any
+.B sm_flags
+output flags are set in
+.BR sm_gen ", "
+they will be copied to
+.B sm_flags
+before the call returns.
+
+.PD 0
+.PP
+.nf
+.B XFS_SCRUB_TYPE_SB
+.B XFS_SCRUB_TYPE_AGF
+.B XFS_SCRUB_TYPE_AGFL
+.fi
+.TP
+.B XFS_SCRUB_TYPE_AGI
+Examine a given allocation group's superblock, free space header, free
+block list, or inode header, respectively.
+Headers are checked for obviously incorrect values and cross-referenced
+against the allocation group's metadata btrees, if possible.
+The allocation group number must be given in
+.BR sm_agno "."
+
+.PP
+.nf
+.B XFS_SCRUB_TYPE_BNOBT
+.B XFS_SCRUB_TYPE_CNTBT
+.B XFS_SCRUB_TYPE_INOBT
+.B XFS_SCRUB_TYPE_FINOBT
+.B XFS_SCRUB_TYPE_RMAPBT
+.fi
+.TP
+.B XFS_SCRUB_TYPE_REFCNTBT
+Examine a given allocation group's free space btrees, inode btress, reverse
+mapping btrees, or reference count btrees, respectively.
+against the allocation group's metadata btrees, if possible.
+Space extent records are checked for obviously incorrect values and
+cross-referenced with the other space extent metadata to ensure that
+there are no conflicts.
+The allocation group number must be given in
+.BR sm_agno "."
+
+.TP
+.B XFS_SCRUB_TYPE_INODE
+Examine a given inode's inode record for obviously incorrect values and
+discrepancies with the rest of filesystem metadata.
+Parent pointers are checked for impossible inode values and are then
+followed up to the parent directory to ensure that the linkage makes
+sense.
+The inode to examine can be specified either through
+.B sm_ino
+and
+.BR sm_gen "; "
+if not specified, then the file described by
+.B dest_fd
+will be examined.
+
+.PP
+.nf
+.B XFS_SCRUB_TYPE_BMBTD
+.B XFS_SCRUB_TYPE_BMBTA
+.fi
+.TP
+.B XFS_SCRUB_TYPE_BMBTC
+Examine a given inode's data block map, extended attribute block map,
+copy on write block map, or parent inode pointer.
+Inode records are examined for obviously incorrect values and
+discrepancies with the three block map types.
+The block maps are checked for obviously wrong values and
+cross-referenced with the allocation group space extent metadata for
+discrepancies.
+The inode to examine can be specified in the same manner as
+.BR XFS_SCRUB_TYPE_INODE "."
+
+.TP
+.B XFS_SCRUB_TYPE_XATTR
+Examine the extended attribute records and indices of a given inode for
+incorrect pointers and other signs of damage.
+The inode to examine can be specified in the same manner as
+.BR XFS_SCRUB_TYPE_INODE "."
+
+.TP
+.B XFS_SCRUB_TYPE_DIR
+Examine the entries in a given directory for invalid data or dangling pointers.
+The directory to examine can be specified in the same manner as
+.BR XFS_SCRUB_TYPE_INODE "."
+
+.TP
+.B XFS_SCRUB_TYPE_SYMLINK
+Examine the target of a symbolic link for obvious pathname problems.
+The link to examine can be specified in the same manner as
+.BR XFS_SCRUB_TYPE_INODE "."
+
+.PP
+.nf
+.B XFS_SCRUB_TYPE_RTBITMAP
+.fi
+.TP
+.B XFS_SCRUB_TYPE_RTSUM
+Examine the realtime block bitmap and realtime summary inodes for
+corruption.
+
+.PP
+.nf
+.B XFS_SCRUB_TYPE_UQUOTA
+.B XFS_SCRUB_TYPE_GQUOTA
+.fi
+.TP
+.B XFS_SCRUB_TYPE_PQUOTA
+Examine all user, group, or project quota records for corruption.
+.RE
+
+.PD 1
+.PP
+The field
+.I sm_flags
+control the behavior of the scrub operation and provide more information
+about the outcome of the operation.
+If none of the
+.B XFS_SCRUB_OFLAG_*
+flags are set upon return, the metadata is clean.
+.RS 0.4i
+.TP
+.B XFS_SCRUB_IFLAG_REPAIR
+If the caller sets this flag, the checker will examine the metadata and
+try to fix any problems or suboptimal metadata that it finds.
+If no errors occur during the repair operation, the check is performed a
+second time to determine if the repair succeeded.
+If errors do occur, the call returns an error status immediately.
+.TP
+.B XFS_SCRUB_OFLAG_CORRUPT
+The metadata was corrupt when the call returned.
+If
+.B XFS_SCRUB_IFLAG_REPAIR
+was specified, then an attempted repair failed to fix the problem.
+Unmount the filesystem and run
+.B xfs_repair
+to fix the filesystem.
+.TP
+.B XFS_SCRUB_OFLAG_PREEN
+The metadata is ok, but some aspect of the metadata could be optimized
+to increase performance.
+.TP
+.B XFS_SCRUB_OFLAG_XFAIL
+Filesystem errors were encountered when accessing other metadata to
+cross-reference the records attached to this metadata object.
+.TP
+.B XFS_SCRUB_OFLAG_XCORRUPT
+Discrepancies were found when cross-referencing the records attached to
+this metadata object against all other available metadata in the system.
+.TP
+.B XFS_SCRUB_OFLAG_INCOMPLETE
+The checker was unable to complete its check of all records.
+.TP
+.B XFS_SCRUB_OFLAG_WARNING
+The checker encountered a metadata object with potentially problematic
+records.
+However, the records were not obviously corrupt.
+.RE
+.PP
+For metadata checkers that operate on inodes or inode metadata, the fields
+.IR sm_ino " and " sm_gen
+are the inode number and generation number of the inode to check.
+If the inode number is zero, the inode represented by
+.I dest_fd
+is used instead.
+.PP
+For metadata checkers that operate on allocation group metadata, the field
+.I sm_agno
+indicates the allocation group in which to find the metadata.
+.PP
+For metadata checkers that operate on filesystem-wide metadata, no
+further arguments are required.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EBUSY
+The filesystem object is busy; the repair will have to be tried again.
+.TP
+.B EFSCORRUPTED
+Severe filesystem corruption was detected and could not be repaired.
+Unmount the filesystem and run
+.B xfs_repair
+to fix the filesystem.
+.TP
+.B EINVAL
+One or more of the arguments specified is invalid.
+.TP
+.B ENOENT
+The specified metadata object does not exist.
+For example, this error code is returned for a
+.B XFS_SCRUB_TYPE_REFCNTBT
+request on a filesystem that does not support reflink.
+.TP
+.B ENOMEM
+There was not sufficient memory to perform the scrub or repair operation.
+Some operations (most notably reference count checking) require a lot of
+memory.
+.TP
+.B ENOSPC
+There is not enough free disk space to attempt a repair.
+.TP
+.B ENOTRECOVERABLE
+Filesystem was mounted in
+.B norecovery
+mode and therefore has an unclean log.
+.TP
+.B ENOTTY
+Online scrubbing or repair were not enabled.
+.TP
+.B EOPNOTSUPP
+Repairs of the requested metadata object are not supported.
+.TP
+.B EROFS
+Filesystem is read-only and a repair was requested.
+.TP
+.B ESHUTDOWN;
+Filesystem is shut down due to previous errors.
+.SH CONFORMING TO
+This API is specific to XFS on Linux.
+.SH NOTES
+These operations may tie up the filesystem for a long time.
+A calling process can be stop the operation by being sent a fatal
+signal, but non-fatal signals are blocked.
+.SH SEE ALSO
+.BR ioctl (2)
