| 1 |
.TH xfs_scrub 8 |
| 2 |
.SH NAME |
| 3 |
xfs_scrub \- check and repair the contents of a mounted XFS filesystem |
| 4 |
.SH SYNOPSIS |
| 5 |
.B xfs_scrub |
| 6 |
[ |
| 7 |
.B \-abCeMmnpTvx |
| 8 |
] |
| 9 |
.I mount-point |
| 10 |
.br |
| 11 |
.B xfs_scrub \-V |
| 12 |
.SH DESCRIPTION |
| 13 |
.B xfs_scrub |
| 14 |
attempts to check and repair all metadata in a mounted XFS filesystem. |
| 15 |
.PP |
| 16 |
.B xfs_scrub |
| 17 |
asks the kernel to scrub all metadata objects in the filesystem. |
| 18 |
Metadata records are scanned for obviously bad values and then |
| 19 |
cross-referenced against other metadata. |
| 20 |
The goal is to establish a reasonable confidence about the consistency |
| 21 |
of the overall filesystem by examining the consistency of individual |
| 22 |
metadata records against the other metadata in the filesystem. |
| 23 |
Damaged metadata can be rebuilt from other metadata if there exists |
| 24 |
redundant data structures which are intact. |
| 25 |
.PP |
| 26 |
Filesystem corruption and optimization opportunities will be logged to |
| 27 |
the standard error stream. |
| 28 |
Enabling verbose mode will increase the amount of status information |
| 29 |
sent to the output. |
| 30 |
.PP |
| 31 |
If the kernel scrub reports that metadata needs repairs or optimizations and |
| 32 |
the user does not pass |
| 33 |
.B -n |
| 34 |
on the command line, this program will ask the kernel to make the repairs and |
| 35 |
to perform the optimizations. |
| 36 |
See the sections about optimizations and repairs for a list of optimizations |
| 37 |
and repairs known to this program. |
| 38 |
The kernel may not support repairing or optimizing the filesystem. |
| 39 |
If this is the case, the filesystem must be unmounted and |
| 40 |
.BR xfs_repair (8) |
| 41 |
run on the filesystem to fix the problems. |
| 42 |
.SH OPTIONS |
| 43 |
.TP |
| 44 |
.BI \-a " errors" |
| 45 |
Abort if more than this many errors are found on the filesystem. |
| 46 |
.TP |
| 47 |
.B \-b |
| 48 |
Run in background mode. |
| 49 |
If the option is specified once, only run a single scrubbing thread at a |
| 50 |
time. |
| 51 |
If given more than once, an artificial delay of 100us is added to each |
| 52 |
scrub call to reduce CPU overhead even further. |
| 53 |
.TP |
| 54 |
.BI \-C " fd" |
| 55 |
This option causes xfs_scrub to write progress information to the |
| 56 |
specified file description so that the progress of the filesystem check |
| 57 |
can be monitored. |
| 58 |
If the file description is a tty, a fancy progress bar is rendered. |
| 59 |
Otherwise, a simple numeric status dump compatible with the |
| 60 |
.B fsck -C |
| 61 |
format is output. |
| 62 |
.TP |
| 63 |
.B \-e |
| 64 |
Specifies what happens when errors are detected. |
| 65 |
If |
| 66 |
.IR shutdown |
| 67 |
is given, the filesystem will be taken offline if errors are found. |
| 68 |
If |
| 69 |
.IR continue |
| 70 |
is given, no action is taken if errors are found; this is the default |
| 71 |
behavior. |
| 72 |
.TP |
| 73 |
.B \-k |
| 74 |
Do not call TRIM on the free space. |
| 75 |
.TP |
| 76 |
.BI \-M " real-mount-point" |
| 77 |
Open the this path for issuing scrub system calls to the kernel. |
| 78 |
The positional |
| 79 |
.I mount-point |
| 80 |
parameter will be used for displaying informational messages and logging. |
| 81 |
This parameter exists to enable process sandboxing for service mode. |
| 82 |
.TP |
| 83 |
.BI \-m " file" |
| 84 |
Search this file for mounted filesystems instead of /etc/mtab. |
| 85 |
.TP |
| 86 |
.B \-n |
| 87 |
Only check filesystem metadata. |
| 88 |
Do not repair or optimize anything. |
| 89 |
.HP |
| 90 |
.B \-o |
| 91 |
.I subopt\c |
| 92 |
[\c |
| 93 |
.B =\c |
| 94 |
.IR value ] |
| 95 |
.BR |
| 96 |
Override what the program might conclude about the filesystem |
| 97 |
if left to its own devices. |
| 98 |
.IP |
| 99 |
The |
| 100 |
.IR subopt ions |
| 101 |
supported are: |
| 102 |
.RS 1.0i |
| 103 |
.TP |
| 104 |
.B autofsck |
| 105 |
Decide the operating mode from the value of the |
| 106 |
.I autofsck |
| 107 |
filesystem property. |
| 108 |
See the |
| 109 |
.B filesystem properties |
| 110 |
section for more details. |
| 111 |
.TP |
| 112 |
.BI fstrim_pct= percentage |
| 113 |
To constrain the amount of time spent on fstrim activities during phase 8, |
| 114 |
this program tries to balance estimated runtime against completeness of the |
| 115 |
trim. |
| 116 |
In short, the program avoids small trim requests to save time. |
| 117 |
|
| 118 |
During phase 7, a log-scale histogram of free space extents is constructed. |
| 119 |
At the start of phase 8, a CDF is computed in decreasing order of extent |
| 120 |
length from the histogram buckets. |
| 121 |
A point corresponding to the fstrim percentage target is chosen from the CDF |
| 122 |
and mapped back to a histogram bucket. |
| 123 |
Free space extents at least as long as the bucket size are trimmed. |
| 124 |
Smaller extents are ignored. |
| 125 |
|
| 126 |
By default, the percentage threshold is 99%. |
| 127 |
.TP |
| 128 |
.BI iwarn |
| 129 |
Treat informational messages as warnings. |
| 130 |
This will result in a nonzero return code, and a higher logging level. |
| 131 |
.RE |
| 132 |
.TP |
| 133 |
.B \-p |
| 134 |
Only optimize filesystem metadata. |
| 135 |
If repairs are required, report them and exit. |
| 136 |
.TP |
| 137 |
.BI \-T |
| 138 |
Print timing and memory usage information for each phase. |
| 139 |
.TP |
| 140 |
.B \-v |
| 141 |
Enable verbose mode, which prints periodic status updates. |
| 142 |
.TP |
| 143 |
.B \-V |
| 144 |
Prints the version number and exits. |
| 145 |
.TP |
| 146 |
.B \-x |
| 147 |
Read all file data extents to look for disk errors. |
| 148 |
.B xfs_scrub |
| 149 |
will issue O_DIRECT reads to the block device directly. |
| 150 |
If the block device is a SCSI disk, it will instead issue READ VERIFY commands |
| 151 |
directly to the disk. |
| 152 |
If media errors are found, the error report will include the disk offset, in |
| 153 |
bytes. |
| 154 |
If the media errors affect a file, the report will also include the inode |
| 155 |
number and file offset, in bytes. |
| 156 |
These actions will confirm that all file data blocks can be read from storage. |
| 157 |
.SH OPTIMIZATIONS |
| 158 |
Optimizations supported by this program include, but are not limited to: |
| 159 |
.IP \[bu] 2 |
| 160 |
Instructing the underlying storage to discard unused extents via the |
| 161 |
.B TRIM |
| 162 |
ioctl. |
| 163 |
.IP \[bu] |
| 164 |
Updating secondary superblocks to match the primary superblock. |
| 165 |
.IP \[bu] |
| 166 |
Turning off shared block write checks for files that no longer share blocks. |
| 167 |
.SH REPAIRS |
| 168 |
Repairs are performed by calling into the kernel. |
| 169 |
This limits the scope of repair activities to rebuilding primary data |
| 170 |
structures from secondary data structures, or secondary structures from |
| 171 |
primary structures. |
| 172 |
The existence of secondary data structures may require features that can |
| 173 |
only be turned on from |
| 174 |
.BR mkfs.xfs (8). |
| 175 |
If errors cannot be repaired, the filesystem must be |
| 176 |
unmounted and |
| 177 |
.BR xfs_repair (8) |
| 178 |
run. |
| 179 |
Repairs supported by the kernel include, but are not limited to: |
| 180 |
.IP \[bu] 2 |
| 181 |
Reconstructing extent allocation data. |
| 182 |
.IP \[bu] |
| 183 |
Rebuilding free space information. |
| 184 |
.IP \[bu] |
| 185 |
Rebuilding inode indexes. |
| 186 |
.IP \[bu] |
| 187 |
Fixing minor corruptions of inode records. |
| 188 |
.IP \[bu] |
| 189 |
Recalculating reference count information. |
| 190 |
.IP \[bu] |
| 191 |
Reconstructing reverse mapping data from primary extent allocation data. |
| 192 |
.IP \[bu] |
| 193 |
Scheduling a quotacheck for the next mount. |
| 194 |
.PP |
| 195 |
If corrupt metadata is successfully repaired, this program will log that |
| 196 |
a repair has succeeded instead of a corruption report. |
| 197 |
.SH FILESYSTEM PROPERTIES |
| 198 |
System administrators can convey their preferences for scrubbing of a |
| 199 |
particular filesystem by setting the filesystem property |
| 200 |
.B autofsck |
| 201 |
via the |
| 202 |
.BR xfs_property (8) |
| 203 |
command on the filesystem. |
| 204 |
These preferences will be honored if the |
| 205 |
.B -o autofsck |
| 206 |
option is specified. |
| 207 |
|
| 208 |
Recognized values for the |
| 209 |
.B autofsck |
| 210 |
property are: |
| 211 |
.RS |
| 212 |
.TP |
| 213 |
.I none |
| 214 |
Do not scan the filesystem at all. |
| 215 |
.TP |
| 216 |
.I check |
| 217 |
Scan and report corruption and opportunities for optimization, but do not |
| 218 |
change anything. |
| 219 |
.TP |
| 220 |
.I optimize |
| 221 |
Scan the filesystem and optimize where possible. |
| 222 |
Report corruptions, but do not fix them. |
| 223 |
.TP |
| 224 |
.I repair |
| 225 |
Scan the filesystem, fix corruptions, and optimize where possible. |
| 226 |
.RE |
| 227 |
|
| 228 |
If the property is not set, the default is |
| 229 |
.I check |
| 230 |
if the filesystem has either reverse mapping btrees or parent pointers enabled, |
| 231 |
or |
| 232 |
.I none |
| 233 |
otherwise. |
| 234 |
|
| 235 |
.SH EXIT CODE |
| 236 |
The exit code returned by |
| 237 |
.B xfs_scrub |
| 238 |
is the sum of the following conditions: |
| 239 |
.br |
| 240 |
\ 0\ \-\ No errors |
| 241 |
.br |
| 242 |
\ 1\ \-\ File system errors left uncorrected |
| 243 |
.br |
| 244 |
\ 2\ \-\ File system optimizations possible |
| 245 |
.br |
| 246 |
\ 4\ \-\ Operational error |
| 247 |
.br |
| 248 |
\ 8\ \-\ Usage or syntax error |
| 249 |
.br |
| 250 |
.SH CAVEATS |
| 251 |
.B xfs_scrub |
| 252 |
is an immature utility! |
| 253 |
Do not run this program unless you have backups of your data! |
| 254 |
This program takes advantage of in-kernel scrubbing to verify a given |
| 255 |
data structure with locks held and can keep the filesystem busy for a |
| 256 |
long time. |
| 257 |
The kernel must be new enough to support the SCRUB_METADATA ioctl. |
| 258 |
.PP |
| 259 |
If errors are found and cannot be repaired, the filesystem must be |
| 260 |
unmounted and repaired. |
| 261 |
.SH SEE ALSO |
| 262 |
.BR xfs_repair (8). |