xfs_repair - repair an XFS filesystem


SYNOPSIS

       xfs_repair [ -nLvV ] [ -o subopt[=value] ]
            [-l logdev] [-r rtdev] xfs_special

       xfs_repair -f [ -nLvV ] [ -o subopt[=value] ]
            [-l logfile] [-r rtfile] file


DESCRIPTION

       xfs_repair repairs corrupt or damaged XFS filesystems (see
       xfs(5)).  The filesystem is specified using  the  xfs_spe­
       cial  argument which should be the device name of the disk
       partition or volume containing the filesystem.   If  given
       the  name  of  a  block device, xfs_repair will attempt to
       find the raw device associated with  the  specified  block
       device and will use the raw device instead.

       Regardless,   the   filesystem  to  be  repaired  must  be
       unmounted, otherwise,  the  resulting  filesystem  may  be
       inconsistent or corrupt.

       The options to xfs_repair are:

       -f     Specifies  that  the  special  device is actually a
              file (see the mkfs.xfs -d file option).  This might
              happen  if  an  image copy of a filesystem has been
              copied or written  into  an  ordinary  file.   This
              option  implies  that  any external log or realtime
              section is also in an ordinary file.

       -L     Force Log Zeroing.  Forces xfs_repair to  zero  the
              log   even   if  it  is  dirty  (contains  metadata
              changes).  When using this  option  the  filesystem
              will likely appear to be corrupt, and can cause the
              loss of user files and/or data.

       -l     Specifies  the  device  special  file   where   the
              filesystem's  external log resides.  Only for those
              filesystems which use an  external  log.   See  the
              mkfs.xfs  -l  option,  and  refer  to  xfs(5) for a
              detailed description of the XFS log.

       -r     Specifies  the  device  special  file   where   the
              filesystem's  realtime  section  resides.  Only for
              those filesystems which  use  a  realtime  section.
              See the mkfs.xfs -r option, and refer to xfs(5) for
              a detailed description of the XFS realtime section.

       -n     No  modify  mode.  Specifies that xfs_repair should
              not modify the filesystem but should only scan  the
              filesystem  and  indicate  what  repairs would have
              been made.

              filesystem if left to its own devices.

              The   assume_xfs   suboption   specifies  that  the
              filesystem is  an  XFS  filesystem.   Normally,  if
              xfs_repair cannot find an XFS superblock, it checks
              to see if  the  filesystem  is  an  EFS  filesystem
              before  it  tries to regenerate the XFS superblock.
              If the assume_xfs option is in  effect,  xfs_repair
              will  assume that the filesystem is an XFS filesys­
              tem and will ignore an EFS  superblock  if  one  is
              found.

       -v     Verbose output.

   Checks Performed
       Inconsistencies corrected include the following:

       1.     Inode  and  inode blockmap (addressing) checks: bad
              magic number in inode, bad magic numbers  in  inode
              blockmap  blocks,  extents  out of order, incorrect
              number of records in inode blockmap blocks,  blocks
              claimed  that  are  not in a legal data area of the
              filesystem, blocks that are claimed  by  more  than
              one inode.

       2.     Inode  allocation  map  checks: bad magic number in
              inode map blocks, inode state as indicated  by  map
              (free  or in-use) inconsistent with state indicated
              by the inode, inodes referenced by  the  filesystem
              that  do  not  appear  in the inode allocation map,
              inode allocation map referencing blocks that do not
              appear to contain inodes.

       3.     Size  checks:  number  of  blocks  claimed by inode
              inconsistent with inode size,  directory  size  not
              block aligned, inode size not consistent with inode
              format.

       4.     Directory checks: bad magic  numbers  in  directory
              blocks,  incorrect number of entries in a directory
              block, bad freespace  information  in  a  directory
              leaf block, entry pointing to an unallocated (free)
              or out of range inode, overlapping entries, missing
              or incorrect dot and dotdot entries, entries out of
              hashvalue  order,  incorrect   internal   directory
              pointers,  directory type not consistent with inode
              format and size.

       5.     Pathname checks: files or  directories  not  refer­
              enced  by  a  pathname starting from the filesystem
              root, illegal pathname components.

       6.     Link count checks: link counts that  do  not  agree

              inode.

       7.     Freemap checks: blocks claimed free by the  freemap
              but  also  claimed by an inode, blocks unclaimed by
              any inode but not appearing in the freemap.

       8.     Super Block checks: total free block and/or free i-
              node count incorrect, filesystem geometry inconsis­
              tent, secondary and primary superblocks  contradic­
              tory.

       Orphaned  files  and  directories  (allocated,  in-use but
       unreferenced) are  reconnected  by  placing  them  in  the
       lost+found directory.  The name assigned is the inode num­
       ber.

   Disk Errors
       xfs_repair aborts on most disk I/O errors.  Therefore,  if
       you are trying to repair a filesystem that was damaged due
       to a disk drive failure, steps should be taken  to  ensure
       that  all blocks in the filesystem are readable and write­
       able before attempting to use  xfs_repair  to  repair  the
       filesystem.   A possible method is using dd(8) to copy the
       data onto a good disk.

   lost+found
       The directory lost+found does not have to already exist in
       the  filesystem being repaired.  If the directory does not
       exist, it is automatically  created.   If  the  lost+found
       directory  already  exists,  the  lost+found  directory is
       deleted and recreated every time  xfs_repair  runs.   This
       ensures  that  there  are no name conflicts in lost+found.
       However, if you rename a file in lost+found and  leave  it
       there,  if  xfs_repair  is run again, that file is renamed
       back to its inode number.

   Corrupted Superblocks
       XFS  has   both   primary   and   secondary   superblocks.
       xfs_repair  uses  information in the primary superblock to
       automatically find and  validate  the  primary  superblock
       against   the  secondary  superblocks  before  proceeding.
       Should the primary be too corrupted to be useful in locat­
       ing  the  secondary  superblocks,  the  program  scans the
       filesystem until it finds  and  validates  some  secondary
       superblocks.   At  that  point,  it  generates  a  primary
       superblock.

   Quotas
       If quotas are in use, it is possible that xfs_repair  will
       clear some or all of the filesystem quota information.  If
       so, the program issues a warning  just  before  it  termi­
       nates.   If all quota information is lost, quotas are dis­
       abled and the program issues a warning to that effect.

       limits.   It is recommended that you check the quota limit
       information manually after xfs_repair.  Also, space  usage
       information is automatically regenerated the next time the
       filesystem is mounted with quotas turned on, so  the  next
       quota mount of the filesystem may take some time.


DIAGNOSTICS

       xfs_repair  issues  informative  messages  as  it proceeds
       indicating what it has found that is abnormal or any  cor­
       rective  action  that  it has taken.  Most of the messages
       are completely understandable only to those who are knowl­
       edgeable  about  the structure of the filesystem.  Some of
       the more common messages are explained  here.   Note  that
       the  language  of  the  messages  is slightly different if
       xfs_repair is run in no-modify mode because the program is
       not  changing  anything on disk.  No-modify mode indicates
       what it would do to repair the filesystem if  run  without
       the no-modify flag.

       disconnected inode xxxx, moving to lost+found

              An  inode  numbered  xxxx  was not connected to the
              filesystem directory tree and  was  reconnected  to
              the  lost+found  directory.   The inode is assigned
              the name of its  inode  number  (i-number).   If  a
              lost+found directory does not exist, it is automat­
              ically created.

       disconnected dir inode xxxx, moving to lost+found

              As above only the inode is a directory inode.  If a
              directory  inode  is attached to lost+found, all of
              its children (if any) stay attached to  the  direc­
              tory  and  therefore  get automatically reconnected
              when the directory is reconnected.

       imap claims in-use inode xxxx is free, correcting imap

              The inode allocation map thinks that inode xxxx  is
              free  whereas  examination  of  the inode indicates
              that the inode may be in use (although  it  may  be
              disconnected).  The program updates the inode allo­
              cation map.

       imap claims free inode xxxx is in use, correcting imap

              The inode allocation map thinks that inode xxxx  is
              in  use  whereas examination of the inode indicates
              that the inode is not in use and therefore is free.
              The program updates the inode allocation map.

       resetting inode xxxx nlinks from x to y

              of valid directory entries referencing  inode  xxxx
              and  the number of references recorded in the inode
              and corrected the the number in the inode.

       fork-type fork in ino xxxx claims used block yyyy

              Inode  xxxx  claims  a  block  yyyy  that  is  used
              (claimed) by either another inode or the filesystem
              itself for  metadata  storage.   The  fork-type  is
              either  data or attr indicating whether the problem
              lies in the portion of the inode that tracks  regu­
              lar  data  or  the portion of the inode that stores
              XFS attributes.  If the inode is a  real-time  (rt)
              inode,  the message says so.  Any inode that claims
              blocks used by the filesystem is deleted.   If  two
              or  more inodes claim the same block, they are both
              deleted.

       fork-type fork in ino xxxx claims dup extent ...

              Inode xxxx claims a block in an extent known to  be
              claimed  more  than once.  The offset in the inode,
              start and length of the extent is given.  The  mes­
              sage  is slightly different if the inode is a real-
              time (rt) inode and the extent is therefore a real-
              time (rt) extent.

       inode xxxx - bad extent ...

              An  extent  record  in  the  blockmap of inode xxxx
              claims blocks that are out of the  legal  range  of
              the  filesystem.   The  message supplies the start,
              end, and file offset of the extent.  The message is
              slightly  different  if  the  extent is a real-time
              (rt) exent.

       bad fork-type fork in inode xxxx

              There was something structurally wrong or inconsis­
              tent  with  the data structures that map offsets to
              filesystem blocks.

       cleared inode xxxx

              There was something wrong with the inode  that  was
              uncorrectable so the program freed the inode.  This
              usually happens because  the  inode  claims  blocks
              that are used by something else or the inode itself
              is badly corrupted.   Typically,  this  message  is
              preceded by one or more messages indicating why the
              inode needed to be cleared.

       bad attribute fork in inode xxxx, clearing attr fork

              inode  that  stores  XFS  attributes (the attribute
              fork) so the program reset the attribute fork.   As
              a  result of this, all attributes on that inode are
              lost.

       correcting nextents for inode xxxx, was x - counted y

              The program found that the number of  extents  used
              to  store  the  data in the inode is wrong and cor­
              rected the number.  The message refers to  nextents
              if the count is wrong on the number of extents used
              to store attribute information.

       entry "name" in dir xxxx not  consistent  with  ..   value
       (yyyy)  in dir ino xxxx, junking entry "name" in directory
       inode xxxx

              The entry "name" in directory inode xxxx references
              a  directory  inode yyyy.  However, the .. entry in
              directory yyyy does not  point  back  to  directory
              xxxx,  so  the  program deletes the entry "name" in
              directory inode xxxx.  If the directory inode  yyyy
              winds  up becoming a disconnected inode as a result
              of this, it is moved to lost+found later.

       entry "name" in dir xxxx references already connected  dir
       ino yyyy, junking entry "name" in directory inode xxxx

              The  entry "name" in directory inode xxxx points to
              a directory inode yyyy that is known to be a  child
              of  another  directory.   Therefore,  the  entry is
              invalid and is deleted.  This message refers to  an
              entry  in  a small directory.  If this were a large
              directory, the last phrase would read  "will  clear
              entry".

       entry  references  free inode xxxx in directory yyyy, will
       clear entry

              An entry in  directory  inode  yyyy  references  an
              inode  xxxx that is known to be free.  The entry is
              therefore invalid and  is  deleted.   This  message
              refers to a large directory.  If the directory were
              small, the message would read "junking entry  ...".


EXIT STATUS

       xfs_repair  -n  (no modify node) will return a status of 1
       if filesystem corruption was detected and 0 if no filesys­
       tem  corruption  was detected.  xfs_repair run without the
       -n option will always return a status code of 0.


BUGS

       The filesystem to be checked and repaired must  have  been

       cedures (the umount(8) command or system shutdown), not as
       a  result  of  a crash or system reset.  If the filesystem
       has not been unmounted cleanly, mount it  and  unmount  it
       cleanly before running xfs_repair.

       xfs_repair  does  not  do  a  thorough job on XFS extended
       attributes.  The structure of the attribute fork  will  be
       consistent,  but only the contents of attribute forks that
       will fit into an inode are checked.  This limitation  will
       be fixed in the future.

       The no-modify mode (-n option) is not completely accurate.
       It does not catch inconsistencies  in  the  freespace  and
       inode  maps,  particularly lost blocks or subtly corrupted
       maps (trees).

       The no-modify mode can generate  repeated  warnings  about
       the  same  problems  because it cannot fix the problems as
       they are encountered.


SEE ALSO

       dd(1), mkfs.xfs(8), umount(8), xfs_check(8), xfs(5).


Man(1) output converted with man2html