man/man8/xfs_repair.8

   1 .TH xfs_repair 8
   2 .SH NAME
   3 xfs_repair \- repair an XFS filesystem
   4 .SH SYNOPSIS
   5 .nf
   6 \f3xfs_repair\f1 [ \f3\-n\f1 ] [ \f3\-o\f1 subopt[=value] ] xfs_special
   7 .sp .8v
   8 \f3xfs_repair\f1 \f3\-f\f1 [ \f3\-n\f1 ] [ \f3\-o\f1 subopt[=value] ] ... file
   9 .fi
  10 .SH DESCRIPTION
  11 .I xfs_repair
  12 repairs corrupt or damaged XFS filesystems
  13 (see
  14 .IR xfs (5)).
  15 The filesystem is specified using the
  16 .I xfs_special
  17 argument which should be the device name of the
  18 disk partition or volume containing
  19 the filesystem.
  20 If given the name of a block device,
  21 .I xfs_repair
  22 will attempt to find the raw device associated
  23 with the specified block device and will use the raw device
  24 instead.
  25 .PP
  26 Regardless, the filesystem to be repaired
  27 must be unmounted,
  28 otherwise, the resulting filesystem may be inconsistent or corrupt.
  29 .PP
  30 The options to \f2xfs_repair\f1 are:
  31 .TP
  32 .B \-f
  33 Specifies that the special device is actually a file (see the
  34 \f2mkfs.xfs\f1 \f3\-d\f1 \f2file\f1 option).
  35 This might happen if an image copy
  36 of a filesystem has been copied or written into an ordinary file.
  37 .TP
  38 .B \-n
  39 No modify mode.
  40 Specifies that
  41 .I xfs_repair
  42 should not modify the filesystem but should only scan the
  43 filesystem and indicate what repairs would have been made.
  44 .TP
  45 .B \-o
  46 Override what the program might conclude about the filesystem
  47 if left to its own devices.
  48 .IP
  49 The
  50 .B assume_xfs
  51 suboption
  52 specifies that the filesystem is an XFS filesystem.
  53 Normally, if
  54 .I xfs_repair
  55 cannot find an XFS superblock, it checks to see if the
  56 filesystem is an EFS filesystem before it tries to
  57 regenerate the XFS superblock.
  58 If the
  59 .B assume_xfs
  60 option is in effect,
  61 .I xfs_repair
  62 will assume that the filesystem is an XFS filesystem and
  63 will ignore an EFS superblock if one is found.
  64 .SS Checks Performed
  65 Inconsistencies corrected include the following:
  66 .TP
  67 1.
  68 Inode and inode blockmap (addressing) checks:
  69 bad magic number in inode,
  70 bad magic numbers in inode blockmap blocks,
  71 extents out of order,
  72 incorrect number of records in inode blockmap blocks,
  73 blocks claimed that are not in a legal data area of the filesystem,
  74 blocks that are claimed by more than one inode.
  75 .TP
  76 2.
  77 Inode allocation map checks:
  78 bad magic number in inode map blocks,
  79 inode state as indicated by map (free or in-use) inconsistent
  80 with state indicated by the inode,
  81 inodes referenced by the filesystem that do not appear in
  82 the inode allocation map,
  83 inode allocation map referencing blocks that do not appear
  84 to contain inodes.
  85 .TP
  86 3.
  87 Size checks:
  88 number of blocks claimed by inode inconsistent with inode size,
  89 directory size not block aligned,
  90 inode size not consistent with inode format.
  91 .TP
  92 4.
  93 Directory checks:
  94 bad magic numbers in directory blocks,
  95 incorrect number of entries in a directory block,
  96 bad freespace information in a directory leaf block,
  97 entry pointing to an unallocated (free) or out
  98 of range inode,
  99 overlapping entries,
 100 missing or incorrect dot and dotdot entries,
 101 entries out of hashvalue order,
 102 incorrect internal directory pointers,
 103 directory type not consistent with inode format and size.
 104 .TP
 105 5.
 106 Pathname checks:
 107 files or directories not referenced by a pathname starting from
 108 the filesystem root,
 109 illegal pathname components.
 110 .TP
 111 6.
 112 Link count checks:
 113 link counts that do not agree with the number of
 114 directory references to the inode.
 115 .TP
 116 7.
 117 Freemap checks:
 118 blocks claimed free by the freemap but also claimed by an inode,
 119 blocks unclaimed by any inode but not appearing in the freemap.
 120 .TP
 121 8.
 122 Super Block checks:
 123 total free block and/or free i-node count incorrect,
 124 filesystem geometry inconsistent,
 125 secondary and primary superblocks contradictory.
 126 .PP
 127 Orphaned files and directories (allocated, in-use but unreferenced) are
 128 reconnected by placing them in the
 129 .I lost+found
 130 directory.
 131 The name assigned is the inode number.
 132 .SS Disk Errors
 133 .I xfs_repair
 134 aborts on most disk I/O errors.
 135 Therefore, if you are trying
 136 to repair a filesystem that was damaged due to a disk drive failure,
 137 steps should be taken to ensure that
 138 all blocks in the filesystem are readable and writeable
 139 before attempting to use
 140 .I xfs_repair
 141 to repair the filesystem.
 142 A possible method is using
 143 .IR dd (8)
 144 to copy the data onto a good disk.
 145 .SS lost+found
 146 The directory
 147 .I lost+found
 148 does not have to already exist in the filesystem being repaired.
 149 If the directory does not exist, it is automatically created.
 150 If the \f2lost+found\f1 directory already exists,
 151 the \f2lost+found\f1
 152 directory is deleted and recreated every time \f2xfs_repair\f1
 153 runs.
 154 This ensures that there are no name conflicts in \f2lost+found\f1.
 155 However, if you rename a file in \f2lost+found\f1 and leave it there,
 156 if \f2xfs_repair\f1 is run again, that file is renamed back to
 157 its inode number.
 158 .SS Corrupted Superblocks
 159 XFS has both primary and secondary superblocks.
 160 \f2xfs_repair\f1 uses information in the primary superblock
 161 to automatically find and validate the primary superblock
 162 against the secondary superblocks before proceeding.
 163 Should the primary be too corrupted to be useful in locating
 164 the secondary superblocks, the program scans the filesystem
 165 until it finds and validates some secondary superblocks.
 166 At that point, it generates a primary superblock.
 167 .SS Quotas
 168 If quotas are in use, it is possible that \f2xfs_repair\f1 will clear
 169 some or all of the filesystem quota information.
 170 If so, the program issues a warning just before it terminates.
 171 If all quota information is lost, quotas are disabled and the
 172 program issues a warning to that effect.
 173 .PP
 174 Note that \f2xfs_repair\f1 does not check the validity of quota limits.
 175 It is recommended that you check the quota limit information manually
 176 after \f2xfs_repair\f1.
 177 Also, space usage information is automatically regenerated the
 178 next time the filesystem is mounted with quotas turned on, so the
 179 next quota mount of the filesystem may take some time.
 180 .SH DIAGNOSTICS
 181 .I xfs_repair
 182 issues informative messages as it proceeds
 183 indicating what it has found that is abnormal or any corrective
 184 action that it has taken.
 185 Most of the messages are completely understandable only to those
 186 who are knowledgeable about the structure of the filesystem.
 187 Some of the more common messages are explained here.
 188 Note that the language of the messages is slightly different
 189 if \f2xfs_repair\f1 is run in no-modify mode because the program is not
 190 changing anything on disk.
 191 No-modify mode indicates what it would do to repair the filesystem
 192 if run without the no-modify flag.
 193 .PP
 194 disconnected inode \f3xxxx\f1, moving to \f2lost+found\f1
 195 .IP
 196 An inode numbered
 197 .B xxxx
 198 was not connected to the filesystem
 199 directory tree and was reconnected to the \f2lost+found\f1 directory.
 200 The inode is assigned the name of its inode number (i-number).
 201 If a \f2lost+found\f1 directory does not exist, it is automatically
 202 created.
 203 .PP
 204 disconnected dir inode \f3xxxx\f1, moving to \f2lost+found\f1
 205 .IP
 206 As above only the inode is a directory inode.
 207 If a directory inode is attached to \f2lost+found\f1, all of its
 208 children (if any) stay attached to the directory and therefore
 209 get automatically reconnected when the directory is reconnected.
 210 .PP
 211 imap claims in-use inode \f3xxxx\f1 is free, correcting imap
 212 .IP
 213 The inode allocation map thinks that inode \f3xxxx\f1 is
 214 free whereas examination of the inode indicates that the
 215 inode may be in use (although it may be disconnected).
 216 The program updates the inode allocation map.
 217 .PP
 218 imap claims free inode \f3xxxx\f1 is in use, correcting imap
 219 .IP
 220 The inode allocation map thinks that inode \f3xxxx\f1 is
 221 in use whereas examination of the inode indicates that the
 222 inode is not in use and therefore is free.
 223 The program updates the inode allocation map.
 224 .PP
 225 resetting inode \f3xxxx\f1 nlinks from \f3x\f1 to \f3y\f1
 226 .IP
 227 The program detected a mismatch between the
 228 number of valid directory entries referencing inode \f3xxxx\f1
 229 and the number of references recorded in the inode and corrected the
 230 the number in the inode.
 231 .PP
 232 \f3fork-type\f1 fork in ino \f3xxxx\f1 claims used block \f3yyyy\f1
 233 .IP
 234 Inode \f3xxxx\f1 claims a block \f3yyyy\f1 that is used (claimed)
 235 by either another inode or the filesystem itself for metadata storage.
 236 The \f3fork-type\f1 is either \f3data\f1 or \f3attr\f1
 237 indicating whether the problem lies in the portion of the
 238 inode that tracks regular data or the portion of the inode
 239 that stores XFS attributes.
 240 If the inode is a real-time (rt) inode, the message says so.
 241 Any inode that claims blocks used by the filesystem is deleted.
 242 If two or more inodes claim the same block, they are both deleted.
 243 .PP
 244 \f3fork-type\f1 fork in ino \f3xxxx\f1 claims dup extent ...
 245 .IP
 246 Inode \f3xxxx\f1 claims a block in an extent known to be
 247 claimed more than once.
 248 The offset in the inode, start and length of the extent is given.
 249 The message is slightly different
 250 if the inode is a real-time (rt) inode and the extent is therefore
 251 a real-time (rt) extent.
 252 .PP
 253 inode \f3xxxx\f1 - bad extent ...
 254 .IP
 255 An extent record in the blockmap of inode \f3xxxx\f1 claims
 256 blocks that are out of the legal range of the filesystem.
 257 The message supplies the start, end, and file offset of
 258 the extent.
 259 The message is slightly different
 260 if the extent is a real-time (rt) exent.
 261 .PP
 262 bad \f3fork-type\f1 fork in inode \f3xxxx\f1
 263 .IP
 264 There was something structurally wrong or inconsistent with the
 265 data structures that map offsets to filesystem blocks.
 266 .PP
 267 cleared inode \f3xxxx\f1
 268 .IP
 269 There was something wrong with the inode that
 270 was uncorrectable so the program freed the inode.
 271 This usually happens because the inode claims
 272 blocks that are used by something else or the inode itself
 273 is badly corrupted.
 274 Typically, this message
 275 is preceded by one or more messages indicating why the
 276 inode needed to be cleared.
 277 .PP
 278 bad attribute fork in inode \f3xxxx\f1, clearing attr fork
 279 .IP
 280 There was something wrong with the portion of the inode that
 281 stores XFS attributes (the attribute fork) so the program reset
 282 the attribute fork.
 283 As a result of this, all attributes on that inode are lost.
 284 .PP
 285 correcting nextents for inode \f3xxxx\f1, was \f3x\f1 - counted \f3y\f1
 286 .IP
 287 The program found that the number of extents used to store
 288 the data in the inode is wrong and corrected the number.
 289 The message refers to nextents if the count is wrong
 290 on the number of extents used to store attribute information.
 291 .PP
 292 entry \f3"name"\f1 in dir \f3xxxx\f1 not consistent
 293 with ..
 294 value (\f3yyyy\f1) in dir ino \f3xxxx\f1,
 295 junking entry \f3"name"\f1 in directory inode \f3xxxx\f1
 296 .IP
 297 The entry \f3"name"\f1 in directory inode \f3xxxx\f1 references a
 298 directory inode \f3yyyy\f1.
 299 However, the ..\& entry in directory \f3yyyy\f1 does not point
 300 back to directory \f3xxxx\f1,
 301 so the program deletes the entry \f3"name"\f1 in directory inode
 302 \f3xxxx\f1.
 303 If the directory inode \f3yyyy\f1 winds up becoming a disconnected
 304 inode as a result of this, it is moved to \f2lost+found\f1 later.
 305 .PP
 306 entry \f3"name"\f1 in dir \f3xxxx\f1 references already
 307 connected dir ino \f3yyyy\f1,
 308 junking entry \f3"name"\f1 in directory inode \f3xxxx\f1
 309 .IP
 310 The entry \f3"name"\f1 in directory inode \f3xxxx\f1 points to a
 311 directory inode \f3yyyy\f1 that is known to be a child of another
 312 directory.
 313 Therefore, the entry is invalid and is deleted.
 314 This message refers to an entry in a small directory.
 315 If this were a large directory, the last phrase would read
 316 "will clear entry".
 317 .PP
 318 entry references free inode \f3xxxx\f1 in directory \f3yyyy\f1,
 319 will clear entry
 320 .IP
 321 An entry in directory inode \f3yyyy\f1 references an inode \f3xxxx\f1
 322 that is known to be free.
 323 The entry is therefore invalid and is deleted.
 324 This message refers to a large directory.
 325 If the directory were small, the message would read "junking entry ...".
 326 .SH EXIT STATUS
 327 .I xfs_repair -n
 328 (no modify node)
 329 will return a status of 1 if filesystem corruption was detected and
 330 0 if no filesystem corruption was detected.
 331 .I xfs_repair
 332 run without the -n option will always return a status code of 0.
 333 .SH BUGS
 334 .I xfs_repair
 335 does not do a thorough job on XFS extended attributes.
 336 The structure of the attribute fork will be consistent,
 337 but only the contents of attribute forks that will fit into
 338 an inode are checked.
 339 This limitation will be fixed in the future.
 340 .PP
 341 The no-modify mode (\f3\-n\f1 option) is not completely
 342 accurate.
 343 It does not catch inconsistencies in the freespace and inode
 344 maps, particularly lost blocks or subtly corrupted maps (trees).
 345 .PP
 346 The no-modify mode can generate repeated warnings about
 347 the same problems because it cannot fix the problems as they
 348 are encountered.
 349 .SH SEE ALSO
 350 dd(1),
 351 mkfs.xfs(8),
 352 xfs_check(8),
 353 xfs(5).