1xfs_repair(8)               System Manager's Manual              xfs_repair(8)
2
3
4

NAME

6       xfs_repair - repair an XFS filesystem
7

SYNOPSIS

9       xfs_repair  [  -dfLPv ] [ -n | -e ] [ -m maxmem ] [ -c subopt=value ] [
10       -o subopt[=value] ] [ -t interval ] [ -l logdev ] [ -r rtdev ] device
11       xfs_repair -V
12

DESCRIPTION

14       xfs_repair repairs corrupt or damaged  XFS  filesystems  (see  xfs(5)).
15       The  filesystem  is specified using the device argument which should be
16       the device name of the disk partition or volume containing the filesys‐
17       tem.  If  given  the name of a block device, xfs_repair will attempt to
18       find the raw device associated with the specified block device and will
19       use the raw device instead.
20
21       Regardless, the filesystem to be repaired must be unmounted, otherwise,
22       the resulting filesystem may be inconsistent or corrupt.
23

OPTIONS

25       -f     Specifies that the filesystem image to be processed is stored in
26              a regular file at device (see the mkfs.xfs -d file option). This
27              might happen if an image copy of a filesystem has been copied or
28              written  into  an  ordinary  file.  This option implies that any
29              external log or realtime section is also in an ordinary file.
30
31       -L     Force Log Zeroing.  Forces xfs_repair to zero the log even if it
32              is  dirty  (contains  metadata changes).  When using this option
33              the filesystem will likely appear to be corrupt, and  can  cause
34              the  loss of user files and/or data.  See the DIRTY LOGS section
35              for more information.
36
37       -l logdev
38              Specifies the device special file where the filesystem's  exter‐
39              nal  log resides. Only for those filesystems which use an exter‐
40              nal log.  See the mkfs.xfs -l option, and refer to xfs(5) for  a
41              detailed description of the XFS log.
42
43       -r rtdev
44              Specifies  the  device special file where the filesystem's real‐
45              time section resides. Only for those  filesystems  which  use  a
46              realtime  section.   See  the  mkfs.xfs  -r option, and refer to
47              xfs(5) for a detailed description of the XFS realtime section.
48
49       -n     No modify mode. Specifies that xfs_repair should not modify  the
50              filesystem but should only scan the filesystem and indicate what
51              repairs would  have  been  made.  This  option  cannot  be  used
52              together with -e.
53
54       -P     Disable  prefetching  of  inode  and  directory blocks. Use this
55              option if you find xfs_repair gets stuck and  stops  proceeding.
56              Interrupting a stuck xfs_repair is safe.
57
58       -m maxmem
59              Specifies   the   approximate   maximum  amount  of  memory,  in
60              megabytes, to use for xfs_repair.  xfs_repair has its own inter‐
61              nal  block  cache  which  will scale out up to the lesser of the
62              process's virtual address limit or about  75%  of  the  system's
63              physical RAM.  This option overrides these limits.
64
65              NOTE:  These memory limits are only approximate and may use more
66              than the specified limit.
67
68       -c subopt=value
69              Change filesystem parameters. Refer to xfs_admin(8) for informa‐
70              tion on changing filesystem parameters.
71
72       -o subopt[=value]
73              Override what the program might conclude about the filesystem if
74              left to its own devices.
75
76              The suboptions supported are:
77
78                 bhash=bhashsize
79                        overrides the default  buffer  cache  hash  size.  The
80                        total  number of buffer cache entries are limited to 8
81                        times this amount. The default size is set to  use  up
82                        the  remainder  of  75%  of  the system's physical RAM
83                        size.
84
85                 ag_stride=ags_per_concat_unit
86                        This creates additional processing threads to parallel
87                        process  AGs that span multiple concat units. This can
88                        significantly reduce  repair  times  on  concat  based
89                        filesystems.
90
91                 force_geometry
92                        Check  the  filesystem  even  if  geometry information
93                        could not be validated.  Geometry information can  not
94                        be  validated if only a single allocation group exists
95                        and thus we do not have a backup superblock available,
96                        or  if  there  are  two  allocation groups and the two
97                        superblocks do not agree on the  filesystem  geometry.
98                        Only  use  this  option  if you validated the geometry
99                        yourself and know what you are doing.  If In doubt run
100                        in no modify mode first.
101
102       -t  interval
103              Modify  reporting  interval,  specified  in seconds. During long
104              runs xfs_repair outputs its progress every 15 minutes. Reporting
105              is only activated when ag_stride is enabled.
106
107       -v     Verbose  output.   May  be  specified multiple times to increase
108              verbosity.
109
110       -d     Repair dangerously. Allow xfs_repair to repair an XFS filesystem
111              mounted  read  only. This is typically done on a root filesystem
112              from single user mode, immediately followed by a reboot.
113
114       -e     If any metadata corruption was repaired, the status returned  is
115              4  instead  of  the usual 0. This option cannot be used together
116              with -n.
117
118       -V     Prints the version number and exits.
119
120   Checks Performed
121       Inconsistencies corrected include the following:
122
123       1.     Inode and inode blockmap (addressing) checks: bad  magic  number
124              in  inode,  bad  magic numbers in inode blockmap blocks, extents
125              out of order, incorrect number  of  records  in  inode  blockmap
126              blocks,  blocks claimed that are not in a legal data area of the
127              filesystem, blocks that are claimed by more than one inode.
128
129       2.     Inode allocation map checks:  bad  magic  number  in  inode  map
130              blocks,  inode state as indicated by map (free or in-use) incon‐
131              sistent with state indicated by the inode, inodes referenced  by
132              the  filesystem  that do not appear in the inode allocation map,
133              inode allocation map referencing blocks that do  not  appear  to
134              contain inodes.
135
136       3.     Size checks: number of blocks claimed by inode inconsistent with
137              inode size, directory size not block  aligned,  inode  size  not
138              consistent with inode format.
139
140       4.     Directory  checks: bad magic numbers in directory blocks, incor‐
141              rect number of entries  in  a  directory  block,  bad  freespace
142              information  in  a  directory  leaf  block, entry pointing to an
143              unallocated (free) or out of range inode,  overlapping  entries,
144              missing  or  incorrect  dot  and  dotdot entries, entries out of
145              hashvalue order, incorrect internal directory  pointers,  direc‐
146              tory type not consistent with inode format and size.
147
148       5.     Pathname  checks: files or directories not referenced by a path‐
149              name starting from the filesystem root, illegal pathname  compo‐
150              nents.
151
152       6.     Link count checks: link counts that do not agree with the number
153              of directory references to the inode.
154
155       7.     Freemap checks: blocks claimed free  by  the  freemap  but  also
156              claimed  by  an  inode,  blocks  unclaimed  by any inode but not
157              appearing in the freemap.
158
159       8.     Super Block checks: total free block and/or  free  i-node  count
160              incorrect,  filesystem geometry inconsistent, secondary and pri‐
161              mary superblocks contradictory.
162
163       Orphaned files and directories (allocated, in-use but unreferenced) are
164       reconnected  by  placing  them  in  the lost+found directory.  The name
165       assigned is the inode number.
166
167   Disk Errors
168       xfs_repair aborts on most disk I/O errors. Therefore, if you are trying
169       to  repair  a  filesystem that was damaged due to a disk drive failure,
170       steps should be taken to ensure that all blocks in the  filesystem  are
171       readable and writable before attempting to use xfs_repair to repair the
172       filesystem. A possible method is using dd(8) to copy the  data  onto  a
173       good disk.
174
175   lost+found
176       The directory lost+found does not have to already exist in the filesys‐
177       tem being repaired.  If the directory does not exist, it  is  automati‐
178       cally  created  if  required.  If it already exists, it will be checked
179       for consistency and if valid  will  be  used  for  additional  orphaned
180       files. Invalid lost+found directories are removed and recreated. Exist‐
181       ing files in a valid lost+found are not removed or renamed.
182
183   Corrupted Superblocks
184       XFS has both primary and secondary superblocks.  xfs_repair uses infor‐
185       mation in the primary superblock to automatically find and validate the
186       primary superblock against the secondary superblocks before proceeding.
187       Should  the  primary be too corrupted to be useful in locating the sec‐
188       ondary superblocks, the program scans the filesystem until it finds and
189       validates  some  secondary  superblocks.  At that point, it generates a
190       primary superblock.
191
192   Quotas
193       If quotas are in use, it is possible that xfs_repair will clear some or
194       all  of  the filesystem quota information.  If so, the program issues a
195       warning just before it terminates.  If all quota information  is  lost,
196       quotas are disabled and the program issues a warning to that effect.
197
198       Note that xfs_repair does not check the validity of quota limits. It is
199       recommended that you check the quota limit information  manually  after
200       xfs_repair.  Also, space usage information is automatically regenerated
201       the next time the filesystem is mounted with quotas turned on,  so  the
202       next quota mount of the filesystem may take some time.
203

DIAGNOSTICS

205       xfs_repair  issues  informative messages as it proceeds indicating what
206       it has found that is abnormal or any  corrective  action  that  it  has
207       taken.   Most  of  the  messages  are completely understandable only to
208       those who are knowledgeable about  the  structure  of  the  filesystem.
209       Some  of  the  more  common messages are explained here.  Note that the
210       language of the messages is slightly different if xfs_repair is run  in
211       no-modify  mode  because  the program is not changing anything on disk.
212       No-modify mode indicates what it would do to repair the  filesystem  if
213       run without the no-modify flag.
214
215       disconnected inode ino, moving to lost+found
216
217              An inode numbered ino was not connected to the filesystem direc‐
218              tory tree and was reconnected to the lost+found  directory.  The
219              inode  is  assigned  the  name  of its inode number (ino).  If a
220              lost+found directory does not exist, it  is  automatically  cre‐
221              ated.
222
223       disconnected dir inode ino, moving to lost+found
224
225              As  above  only  the inode is a directory inode.  If a directory
226              inode is attached to lost+found, all of its  children  (if  any)
227              stay  attached  to the directory and therefore get automatically
228              reconnected when the directory is reconnected.
229
230       imap claims in-use inode ino is free, correcting imap
231
232              The inode allocation map thinks that inode ino is  free  whereas
233              examination  of the inode indicates that the inode may be in use
234              (although it may be  disconnected).   The  program  updates  the
235              inode allocation map.
236
237       imap claims free inode ino is in use, correcting imap
238
239              The inode allocation map thinks that inode ino is in use whereas
240              examination of the inode indicates that the inode is not in  use
241              and therefore is free.  The program updates the inode allocation
242              map.
243
244       resetting inode ino nlinks from x to y
245
246              The program detected a mismatch  between  the  number  of  valid
247              directory entries referencing inode ino and the number of refer‐
248              ences recorded in the inode and corrected the the number in  the
249              inode.
250
251       fork-type fork in ino ino claims used block bno
252
253              Inode  ino  claims  a block bno that is used (claimed) by either
254              another inode or the filesystem itself for metadata storage. The
255              fork-type  is either data or attr indicating whether the problem
256              lies in the portion of the inode that tracks regular data or the
257              portion  of  the inode that stores XFS attributes.  If the inode
258              is a real-time (rt) inode, the message says so.  Any inode  that
259              claims blocks used by the filesystem is deleted.  If two or more
260              inodes claim the same block, they are both deleted.
261
262       fork-type fork in ino ino claims dup extent ...
263
264              Inode ino claims a block in an extent known to be  claimed  more
265              than  once.   The  offset  in the inode, start and length of the
266              extent is given.  The message is slightly different if the inode
267              is  a  real-time  (rt) inode and the extent is therefore a real-
268              time (rt) extent.
269
270       inode ino - bad extent ...
271
272              An extent record in the blockmap of inode ino claims blocks that
273              are  out of the legal range of the filesystem.  The message sup‐
274              plies the start, end, and file offset of the extent.   The  mes‐
275              sage  is  slightly  different  if the extent is a real-time (rt)
276              extent.
277
278       bad fork-type fork in inode ino
279
280              There was something structurally wrong or inconsistent with  the
281              data structures that map offsets to filesystem blocks.
282
283       cleared inode ino
284
285              There  was something wrong with the inode that was uncorrectable
286              so the program freed the inode.  This  usually  happens  because
287              the  inode  claims blocks that are used by something else or the
288              inode itself is badly corrupted. Typically, this message is pre‐
289              ceded by one or more messages indicating why the inode needed to
290              be cleared.
291
292       bad attribute fork in inode ino, clearing attr fork
293
294              There was something wrong with the portion  of  the  inode  that
295              stores  XFS attributes (the attribute fork) so the program reset
296              the attribute fork.  As a result of this, all attributes on that
297              inode are lost.
298
299       correcting nextents for inode ino, was x - counted y
300
301              The  program  found that the number of extents used to store the
302              data in the inode is wrong and corrected the number.   The  mes‐
303              sage  refers  to nextents if the count is wrong on the number of
304              extents used to store attribute information.
305
306       entry name in dir dir_ino not consistent with .. value  (xxxx)  in  dir
307       ino ino, junking entry name in directory inode dir_ino
308
309              The entry name in directory inode dir_ino references a directory
310              inode ino.  However, the .. entry  in  directory  ino  does  not
311              point  back  to  directory  dir_ino,  so the program deletes the
312              entry name in directory inode dir_ino.  If the  directory  inode
313              ino  winds up becoming a disconnected inode as a result of this,
314              it is moved to lost+found later.
315
316       entry name in dir dir_ino references already  connected  dir  ino  ino,
317       junking entry name in directory inode dir_ino
318
319              The  entry name in directory inode dir_ino points to a directory
320              inode ino that is known to be  a  child  of  another  directory.
321              Therefore,  the  entry  is invalid and is deleted.  This message
322              refers to an entry in a small directory.  If this were  a  large
323              directory, the last phrase would read "will clear entry".
324
325       entry references free inode ino in directory dir_ino, will clear entry
326
327              An entry in directory inode dir_ino references an inode ino that
328              is known to be free. The  entry  is  therefore  invalid  and  is
329              deleted.   This  message  refers  to  a large directory.  If the
330              directory were small, the  message  would  read  "junking  entry
331              ...".
332

EXIT STATUS

334       xfs_repair  -n (no modify mode) will return a status of 1 if filesystem
335       corruption was detected and 0 if no filesystem corruption was detected.
336       xfs_repair  run  without the -n option will always return a status code
337       of 0 if it completes without problems, unless the flag -e is  used.  If
338       it  is used, then status 4 is reported when any issue with the filesys‐
339       tem was found, but could be fixed. If a runtime  error  is  encountered
340       during  operation,  it  will  return  a  status  of  1.  In  this case,
341       xfs_repair should be restarted.  If xfs_repair is unable to proceed due
342       to a dirty log, it will return a status of 2.  See below.
343

DIRTY LOGS

345       Due  to  the design of the XFS log, a dirty log can only be replayed by
346       the kernel, on a machine  having  the  same  CPU  architecture  as  the
347       machine which was writing to the log.  xfs_repair cannot replay a dirty
348       log and will exit with a status code of 2 when it detects a dirty log.
349
350       In this situation, the log can be replayed by mounting and  immediately
351       unmounting  the  filesystem  on the same class of machine that crashed.
352       Please make sure that the machine's hardware is reliable before replay‐
353       ing to avoid compounding the problems.
354
355       If mounting fails, the log can be erased by running xfs_repair with the
356       -L option.  All metadata updates in progress at the time of  the  crash
357       will  be  lost,  which  may  cause significant filesystem damage.  This
358       should only be used as a last resort.
359

BUGS

361       The filesystem to be checked and  repaired  must  have  been  unmounted
362       cleanly  using  normal  system administration procedures (the umount(8)
363       command or system shutdown), not as a  result  of  a  crash  or  system
364       reset.   If the filesystem has not been unmounted cleanly, mount it and
365       unmount it cleanly before running xfs_repair.
366
367       xfs_repair does not do a thorough job on XFS extended attributes.   The
368       structure  of  the attribute fork will be consistent, but only the con‐
369       tents of attribute forks that will fit into an inode are checked.  This
370       limitation will be fixed in the future.
371
372       The no-modify mode (-n option) is not completely accurate.  It does not
373       catch inconsistencies in the freespace  and  inode  maps,  particularly
374       lost blocks or subtly corrupted maps (trees).
375
376       The  no-modify mode can generate repeated warnings about the same prob‐
377       lems because it cannot fix the problems as they are encountered.
378
379       If a filesystem fails to be repaired, a metadump image can be generated
380       with  xfs_metadump(8)  and  be sent to an XFS maintainer to be analysed
381       and xfs_repair fixed and/or improved.
382

SEE ALSO

384       dd(1), mkfs.xfs(8), umount(8), xfs_admin(8), xfs_metadump(8), xfs(5).
385
386
387
388                                                                 xfs_repair(8)
Impressum