Debian Codegraph @

upstream/debian-trixie/man8/xfs_scrub.8

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