Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 398 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man8/btrfs-scrub.8 b/upstream/mageia-cauldron/man8/btrfs-scrub.8
new file mode 100644
index 00000000..5e794ead
--- /dev/null
+++ b/upstream/mageia-cauldron/man8/btrfs-scrub.8
@@ -0,0 +1,398 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "BTRFS-SCRUB" "8" "Jan 09, 2024" "6.6.3" "BTRFS"
+.SH NAME
+btrfs-scrub \- scrub btrfs filesystem, verify block checksums
+.SH SYNOPSIS
+.sp
+\fBbtrfs scrub\fP <subcommand> <args>
+.SH DESCRIPTION
+.sp
+Scrub is a pass over all filesystem data and metadata and verifying the
+checksums. If a valid copy is available (replicated block group profiles) then
+the damaged one is repaired. All copies of the replicated profiles are validated.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Scrub is not a filesystem checker (fsck) and does not verify nor repair
+structural damage in the filesystem. It really only checks checksums of data
+and tree blocks, it doesn\(aqt ensure the content of tree blocks is valid and
+consistent. There\(aqs some validation performed when metadata blocks are read
+from disk (\fI\%Tree checker\fP) but it\(aqs not extensive and cannot substitute
+full \fI\%btrfs\-check(8)\fP run.
+.UNINDENT
+.UNINDENT
+.sp
+The user is supposed to run it manually or via a periodic system service. The
+recommended period is a month but it could be less. The estimated device bandwidth
+utilization is about 80% on an idle filesystem.
+.sp
+The scrubbing status is recorded in \fB/var/lib/btrfs/\fP in textual files named
+\fIscrub.status.UUID\fP for a filesystem identified by the given UUID. (Progress
+state is communicated through a named pipe in file \fIscrub.progress.UUID\fP in the
+same directory.) The status file is updated every 5 seconds. A resumed scrub
+will continue from the last saved position.
+.sp
+Scrub can be started only on a mounted filesystem, though it\(aqs possible to
+scrub only a selected device. See \fI\%btrfs scrub start\fP for more.
+.SS Bandwidth and IO limiting
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The \fBionice(1)\fP may not be generally supported by all IO schedulers and
+the options to \fBbtrfs scrub start\fP may not work as expected.
+.UNINDENT
+.UNINDENT
+.sp
+In the past when the \fI\%CFQ IO scheduler\fP was generally used
+the \fBionice(1)\fP syscalls set the priority to \fIidle\fP so the IO would not
+interfere with regular IO. Since the kernel 5.0 the CFQ is not available.
+.sp
+The IO scheduler known to support that is \fI\%BFQ\fP, but first read the
+documentation before using it!
+.sp
+For other commonly used schedulers like \fI\%mq\-deadline\fP it\(aqs recommended to use
+\fIcgroup2 IO controller\fP which could be managed by e.g. \fIsystemd\fP
+(documented in \fBsystemd.resource\-control\fP). However, starting scrub like that
+is not yet completely straightforward. The IO controller must know the physical
+device of the filesystem and create a slice so all processes started from that
+belong to the same accounting group.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ systemd\-run \-p \(dqIOBandwidthReadMax=/dev/sdx 10M\(dq btrfs scrub start \-B /
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Since linux 5.14 it\(aqs possible to set the per\-device bandwidth limits in a
+BTRFS\-specific way using files \fB/sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max\fP\&.
+This setting is not persistent, lasts until the filesystem is unmounted.
+Currently set limits can be displayed by command \fI\%btrfs scrub
+limit\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ echo 100m > /sys/fs/btrfs/9b5fd16e\-1b64\-4f9b\-904a\-74e74c0bbadc/devinfo/1/scrub_speed_max
+$ btrfs scrub limit /
+UUID: 9b5fd16e\-1b64\-4f9b\-904a\-74e74c0bbadc
+Id      Limit      Path
+\-\-  \-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-
+ 1  100.00MiB  /dev/sdx
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SUBCOMMAND
+.INDENT 0.0
+.TP
+.B cancel <path>|<device>
+If a scrub is running on the filesystem identified by \fIpath\fP or
+\fIdevice\fP, cancel it.
+.sp
+If a \fIdevice\fP is specified, the corresponding filesystem is found and
+\fBbtrfs scrub cancel\fP behaves as if it was called on that filesystem.
+The progress is saved in the status file so \fBbtrfs scrub resume\fP can
+continue from the last position.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B limit [options] <path>
+Show or set scrub limits on devices of the given filesystem.
+.sp
+\fBOptions\fP
+.INDENT 7.0
+.TP
+.B \-d|\-\-devid DEVID
+select the device by DEVID to apply the limit
+.TP
+.B \-l|\-\-limit SIZE
+set the limit of the device to SIZE (size units with suffix),
+or 0 to reset to \fIunlimited\fP
+.TP
+.B \-a|\-\-all
+apply the limit to all devices
+.UNINDENT
+.INDENT 7.0
+.TP
+.B  \-\-raw
+print all numbers raw values in bytes without the \fIB\fP suffix
+.TP
+.B  \-\-human\-readable
+print human friendly numbers, base 1024, this is the default
+.TP
+.B  \-\-iec
+select the 1024 base for the following options, according to
+the IEC standard
+.TP
+.B  \-\-si
+select the 1000 base for the following options, according to the SI standard
+.TP
+.B  \-\-kbytes
+show sizes in KiB, or kB with \-\-si
+.TP
+.B  \-\-mbytes
+show sizes in MiB, or MB with \-\-si
+.TP
+.B  \-\-gbytes
+show sizes in GiB, or GB with \-\-si
+.TP
+.B  \-\-tbytes
+show sizes in TiB, or TB with \-\-si
+.UNINDENT
+.TP
+.B resume [\-BdqrR] <path>|<device>
+Resume a cancelled or interrupted scrub on the filesystem identified by
+\fIpath\fP or on a given \fIdevice\fP\&. The starting point is read from the
+status file if it exists.
+.sp
+This does not start a new scrub if the last scrub finished successfully.
+.sp
+\fBOptions\fP
+.sp
+see \fBscrub start\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B start [\-BdrRf] <path>|<device>
+Start a scrub on all devices of the mounted filesystem identified by
+\fIpath\fP or on a single \fIdevice\fP\&. If a scrub is already running, the new
+one will not start. A device of an unmounted filesystem cannot be
+scrubbed this way.
+.sp
+Without options, scrub is started as a background process. The
+automatic repairs of damaged copies are performed by default for block
+group profiles with redundancy. No\-repair can be enabled by option \fI\-r\fP\&.
+.sp
+\fBOptions\fP
+.INDENT 7.0
+.TP
+.B  \-B
+do not background and print scrub statistics when finished
+.TP
+.B  \-d
+print separate statistics for each device of the filesystem
+(\fI\-B\fP only) at the end
+.TP
+.B  \-r
+run in read\-only mode, do not attempt to correct anything, can
+be run on a read\-only filesystem
+.TP
+.B  \-R
+raw print mode, print full data instead of summary
+.TP
+.B  \-f
+force starting new scrub even if a scrub is already running,
+this can useful when scrub status file is damaged and reports a
+running scrub although it is not, but should not normally be
+necessary
+.UNINDENT
+.sp
+\fBDeprecated options\fP
+.INDENT 7.0
+.TP
+.BI \-c \ <ioprio_class>
+set IO priority class (see \fBionice(1)\fP manual page) if the IO
+scheduler configured for the device supports ionice. This is
+only supported by BFQ or Kyber but is \fInot\fP supported by
+mq\-deadline. Please read the section about
+\fI\%IO limiting\fP\&.
+.TP
+.BI \-n \ <ioprio_classdata>
+set IO priority classdata (see \fBionice(1)\fP manpage)
+.TP
+.B  \-q
+(deprecated) alias for global \fI\-q\fP option
+.UNINDENT
+.TP
+.B status [options] <path>|<device>
+Show status of a running scrub for the filesystem identified by \fIpath\fP
+or for the specified \fIdevice\fP\&.
+.sp
+If no scrub is running, show statistics of the last finished or
+cancelled scrub for that filesystem or device.
+.sp
+\fBOptions\fP
+.INDENT 7.0
+.TP
+.B  \-d
+print separate statistics for each device of the filesystem
+.TP
+.B  \-R
+print all raw statistics without postprocessing as returned by
+the status ioctl
+.TP
+.B  \-\-raw
+print all numbers raw values in bytes without the \fIB\fP suffix
+.TP
+.B  \-\-human\-readable
+print human friendly numbers, base 1024, this is the default
+.TP
+.B  \-\-iec
+select the 1024 base for the following options, according to
+the IEC standard
+.TP
+.B  \-\-si
+select the 1000 base for the following options, according to the SI standard
+.TP
+.B  \-\-kbytes
+show sizes in KiB, or kB with \-\-si
+.TP
+.B  \-\-mbytes
+show sizes in MiB, or MB with \-\-si
+.TP
+.B  \-\-gbytes
+show sizes in GiB, or GB with \-\-si
+.TP
+.B  \-\-tbytes
+show sizes in TiB, or TB with \-\-si
+.UNINDENT
+.sp
+A status on a filesystem without any error looks like the following:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# btrfs scrub start /
+# btrfs scrub status /
+UUID:             76fac721\-2294\-4f89\-a1af\-620cde7a1980
+Scrub started:    Wed Apr 10 12:34:56 2023
+Status:           running
+Duration:         0:00:05
+Time left:        0:00:05
+ETA:              Wed Apr 10 12:35:01 2023
+Total to scrub:   28.32GiB
+Bytes scrubbed:   13.76GiB  (48.59%)
+Rate:             2.75GiB/s
+Error summary:    no errors found
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+With some errors found:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+Error summary:    csum=72
+  Corrected:      2
+  Uncorrectable:  72
+  Unverified:     0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+\fICorrected\fP \-\- number of bad blocks that were repaired from another copy
+.IP \(bu 2
+\fIUncorrectable\fP \-\- errors detected at read time but not possible to repair from other copy
+.IP \(bu 2
+\fIUnverified\fP \-\- transient errors, first read failed but a retry
+succeeded, may be affected by lower layers that group or split IO requests
+.IP \(bu 2
+\fIError summary\fP \-\- followed by a more detailed list of errors found
+.INDENT 2.0
+.IP \(bu 2
+\fIcsum\fP \-\- checksum mismatch
+.IP \(bu 2
+\fIsuper\fP \-\- super block errors, unless the error is fixed
+immediately, the next commit will overwrite superblock
+.IP \(bu 2
+\fIverify\fP \-\- metadata block header errors
+.IP \(bu 2
+\fIread\fP \-\- blocks can\(aqt be read due to IO errors
+.UNINDENT
+.UNINDENT
+.sp
+It\(aqs possible to set a per\-device limit via file
+\fBsysfs/fs/btrfs/FSID/devinfo/scrub_speed_max\fP\&. In that case
+the limit is printed on the \fIRate:\fP line if option \fI\-d\fP is specified,
+or without it on a single\-device filesystem.  Read more about tat in
+section about \fI\%scrub IO limiting\fP\&.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+Rate:             989.0MiB/s (limit 1.0G/s)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On a multi\-device filesystem with at least one device limit the
+overall stats cannot print the limit without \fI\-d\fP so there\(aqs a not that
+some limits are set:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+Rate:             36.37MiB/s (some device limits set)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SH EXIT STATUS
+.sp
+\fBbtrfs scrub\fP returns a zero exit status if it succeeds. Non zero is
+returned in case of failure:
+.INDENT 0.0
+.TP
+.B 1
+scrub couldn\(aqt be performed
+.TP
+.B 2
+there is nothing to resume
+.TP
+.B 3
+scrub found uncorrectable errors
+.UNINDENT
+.SH AVAILABILITY
+.sp
+\fBbtrfs\fP is part of btrfs\-progs.  Please refer to the documentation at
+\fI\%https://btrfs.readthedocs.io\fP\&.
+.SH SEE ALSO
+.sp
+\fI\%mkfs.btrfs(8)\fP
+.\" Generated by docutils manpage writer.
+.