Debian Codegraph @

upstream/debian-unstable/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 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).