From: Darrick J. Wong Date: Sun, 22 Feb 2026 22:41:17 +0000 (-0800) Subject: xfs_healer: add a manual page X-Git-Tag: v7.0.0~36 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=c5d8a2ad1d287c513c81e3ca0c6872e2db353ec8;p=xfsprogs-dev.git xfs_healer: add a manual page Add a new section 8 manpage for this service daemon so others can read about what this program is supposed to do. Signed-off-by: "Darrick J. Wong" Reviewed-by: Christoph Hellwig --- diff --git a/man/man8/Makefile b/man/man8/Makefile index 5be76ab7..05710f85 100644 --- a/man/man8/Makefile +++ b/man/man8/Makefile @@ -7,13 +7,41 @@ include $(TOPDIR)/include/builddefs MAN_SECTION = 8 -ifneq ("$(ENABLE_SCRUB)","yes") - MAN_PAGES = $(filter-out xfs_scrub%,$(shell echo *.$(MAN_SECTION))) -else - MAN_PAGES = $(shell echo *.$(MAN_SECTION)) - MAN_PAGES += xfs_scrub_all.8 +MAN_PAGES = \ + fsck.xfs.8 \ + mkfs.xfs.8 \ + xfs_admin.8 \ + xfs_bmap.8 \ + xfs_copy.8 \ + xfs_db.8 \ + xfs_estimate.8 \ + xfs_freeze.8 \ + xfs_fsr.8 \ + xfs_growfs.8 \ + xfs_info.8 \ + xfs_io.8 \ + xfs_logprint.8 \ + xfs_mdrestore.8 \ + xfs_metadump.8 \ + xfs_mkfile.8 \ + xfs_ncheck.8 \ + xfs_property.8 \ + xfs_protofile.8 \ + xfs_quota.8 \ + xfs_repair.8 \ + xfs_rtcp.8 \ + xfs_spaceman.8 + +ifeq ($(ENABLE_HEALER),yes) + MAN_PAGES += xfs_healer.8 +endif +ifeq ($(HAVE_HEALER_START_DEPS),yes) + MAN_PAGES += xfs_healer_start.8 endif -MAN_PAGES += mkfs.xfs.8 +ifeq ($(ENABLE_SCRUB),yes) + MAN_PAGES += xfs_scrub.8 xfs_scrub_all.8 +endif + MAN_DEST = $(PKG_MAN_DIR)/man$(MAN_SECTION) LSRCFILES = $(MAN_PAGES) DIRT = mkfs.xfs.8 xfs_scrub_all.8 diff --git a/man/man8/xfs_healer.8 b/man/man8/xfs_healer.8 new file mode 100644 index 00000000..ee6ac9bd --- /dev/null +++ b/man/man8/xfs_healer.8 @@ -0,0 +1,121 @@ +.TH xfs_healer 8 +.SH NAME +xfs_healer \- automatically heal damage to XFS filesystem metadata +.SH SYNOPSIS +.B xfs_healer +[ +.B OPTIONS +] +.I mount-point +.br +.B xfs_healer \-V +.SH DESCRIPTION +.B xfs_healer +is a daemon that tries to automatically repair damaged XFS filesystem metadata. +.PP +.B WARNING! +This program is +.BR EXPERIMENTAL "," +which means that its behavior and interface +could change at any time! +.PP +.B xfs_healer +asks the kernel to report all observations of corrupt metadata, media errors, +filesystem shutdowns, and file I/O errors. +The program can respond to runtime metadata corruption errors by initiating +targeted repairs of the suspect metadata or a full online fsck of the +filesystem. + +Normally this program runs as a systemd service. +The service is activated via the +.I xfs_healer_start +service if systemd is supported. + +The kernel may not support repairing or optimizing the filesystem. +If this is the case, the filesystem must be unmounted and +.BR xfs_repair (8) +run on the filesystem to fix the problems. +.SH OPTIONS +.TP +.BI \-\-everything +Ask the kernel to send us good metadata health events, not only events related +to metadata corruption, media errors, shutdowns, and I/O errors. +.TP +.B \-\-foreground +Start enough event handling threads to allow consumption of all online CPUs. +If not specified, start exactly one event handling thread. +.TP +.B \-\-no-autofsck +Do not use the +.I autofsck +filesystem property to decide whether or not to repair corrupt metadata. +If the +.B \-\-repair +option is given, then all corruptions will be repaired. +If the +.B \-\-repair +option is not given, then the program will never try to repair the filesystem. +.TP +.B \-\-quiet +Do not print every event to standard output. +.TP +.B \-\-repair +Always try to repair each piece of corrupt metadata when the kernel tells us +about it. +If an individual repair fails or the kernel tells us that health events were +lost, the +.I xfs_scrub +service for this mount point will be launched. +The default is not to try to repair anything. +If this option is specified but the kernel does not support repairs, the +program will exit. +.TP +.B \-\-supported +Check if the filesystem supports sending health events. +Exits with 0 if it does, and non-zero if not. +.TP +.BI \-V +Prints the version number and exit. + +.SH AUTOFSCK +By default, this program will read the +.I autofsck +filesystem property to decide if it should try to repair corruptions. +If the property is set to these values: + +.RS +.TP +.I repair +Corruptions will be repaired. +.TP +.IR check " or " optimize +Corruptions will be logged. +.TP +.I none +The program will exit. +.RE + +If the property is not set but the filesystem supports any back-reference +metadata (reverse mappings and parent pointers), then corruptions will be +logged. +If no back-reference metadata are present, the program will exit. + +See the +.BR xfs_scrub (8) +manual page for more details on this filesystem property. + +.SH CAVEATS +.B xfs_healer +is an immature utility! +Do not run this program unless you have backups of your data! +This program takes advantage of in-kernel scrubbing to verify a given +data structure with locks held and can keep the filesystem busy for a +long time. +The kernel must be new enough to support the SCRUB_METADATA ioctl. +.PP +If errors are found and cannot be repaired, the filesystem must be +unmounted and repaired. +.SH SEE ALSO +.BR xfs_repair (8) +and +.BR xfs_scrub (8). diff --git a/man/man8/xfs_healer_start.8 b/man/man8/xfs_healer_start.8 new file mode 100644 index 00000000..0b755fd5 --- /dev/null +++ b/man/man8/xfs_healer_start.8 @@ -0,0 +1,37 @@ +.TH xfs_healer_start 8 +.SH NAME +xfs_healer_start \- starts xfs_healer instances +.SH SYNOPSIS +.B xfs_healer_start +[ +.B OPTIONS +] +.br +.B xfs_healer_start \-V +.SH DESCRIPTION +.B xfs_healer_start +starts the xfs_healer service whenever the kernel mounts an XFS filesystem in +the current mount namespace. +.PP +.B WARNING! +This program is +.BR EXPERIMENTAL "," +which means that its behavior and interface +could change at any time! + +Normally this program runs as a systemd service. + +.SH OPTIONS +.TP +.B \-\-supported +Check if the kernel supports listening for mount events. +Exits with 0 if it does, and non-zero if not. +.TP +.BI "\-\-mountns " path +Monitor the given mount namespace. +Defaults to the mount namespace associated with the process itself. +.TP +.BI \-V +Prints the version number and exit. +.SH SEE ALSO +.BR xfs_healer (8).