Documentation/btrfs-check.asciidoc

   1 btrfs-check(8)
   2 ==============
   3
   4 NAME
   5 ----
   6 btrfs-check - check or repair a btrfs filesystem
   7
   8 SYNOPSIS
   9 --------
  10 *btrfs check* [options] <device>
  11
  12 DESCRIPTION
  13 -----------
  14
  15 The filesystem checker is used to verify structural integrity of a filesystem
  16 and attempt to repair it if requested.  It is recommended to unmount the
  17 filesystem prior to running the check, but it is possible to start checking a
  18 mounted filesystem (see '--force').
  19
  20 By default, *btrfs check* will not modify the device but you can reaffirm that
  21 by the option '--readonly'.
  22
  23 *btrfsck* is an alias of *btrfs check* command and is now deprecated.
  24
  25 WARNING: Do not use '--repair' unless you are advised to by a developer, an
  26 experienced user or accept the fact that 'fsck' cannot possibly fix all sorts
  27 of damage that could happen to a filesystem because of software and hardware
  28 bugs.
  29
  30 The structural integrity check verifies if internal filesystem objects or
  31 data structures satisfy the constraints, point to the right objects or are
  32 correctly connected together.
  33
  34 There are several cross checks that can detect wrong reference counts of shared
  35 extents, backreferences, missing extents of inodes, directory and inode
  36 connectivity etc.
  37
  38 The amount of memory required can be high, depending on the size of the
  39 filesystem, similarly the run time.
  40
  41 SAFE OR ADVISORY OPTIONS
  42 ------------------------
  43
  44 -b|--backup::
  45 use the first valid set of backup roots stored in the superblock
  46 +
  47 This can be combined with '--super' if some of the superblocks are damaged.
  48
  49 --check-data-csum::
  50 verify checksums of data blocks
  51 +
  52 This expects that the filesystem is otherwise
  53 OK, so this is basically and offline 'scrub' but does not repair data from
  54 spare copies.
  55
  56 --chunk-root <bytenr>::
  57 use the given offset 'bytenr' for the chunk tree root
  58
  59 -E|--subvol-extents <subvolid>::
  60 show extent state for the given subvolume
  61
  62 -p|--progress::
  63 indicate progress at various checking phases
  64
  65 -Q|--qgroup-report::
  66 verify qgroup accounting and compare against filesystem accounting
  67
  68 -r|--tree-root <bytenr>::
  69 use the given offset 'bytenr' for the tree root
  70
  71 --readonly::
  72 (default)
  73 run in read-only mode, this option exists to calm potential panic when users
  74 are going to run the checker
  75
  76 -s|--super <superblock>::
  77 use 'superblock'th superblock copy, valid values are 0, 1 or 2 if the
  78 respective superblock offset is within the device size
  79 +
  80 This can be used to use a different starting point if some of the primary
  81 superblock is damaged.
  82
  83 --clear-space-cache v1|v2::
  84 completely wipe all free space cache of given type
  85 +
  86 For free space cache 'v1', the 'clear_cache' kernel mount option only rebuilds
  87 the free space cache for block groups that are modified while the filesystem is
  88 mounted with that option. Thus, using this option with 'v1' makes it possible
  89 to actually clear the entire free space cache.
  90 +
  91 For free space cache 'v2', the 'clear_cache' kernel mount option does destroy
  92 the entire free space cache. This option with 'v2' provides an alternative
  93 method of clearing the free space cache that doesn't require mounting the
  94 filesystem.
  95
  96
  97 DANGEROUS OPTIONS
  98 -----------------
  99
 100 --repair::
 101 enable the repair mode and attempt to fix problems where possible
 102 --init-csum-tree::
 103 create a new checksum tree and recalculate checksums in all files
 104 +
 105 NOTE: Do not blindly use this option to fix checksum mismatch problems.
 106
 107 --init-extent-tree::
 108 build the extent tree from scratch
 109 +
 110 NOTE: Do not use unless you know what you're doing.
 111
 112 --mode=MODE::
 113 select mode of operation regarding memory and IO
 114 +
 115 The 'MODE' can be one of 'original' and 'lowmem'. The original mode is mostly
 116 unoptimized regarding memory consumption and can lead to out-of-memory
 117 conditions on large filesystems. The possible workaround is to export the block
 118 device over network to a machine with enough memory. The low memory mode is
 119 supposed to address the memory consumption, at the cost of increased IO when it
 120 needs to re-read blocks when needed. This may increase run time.
 121
 122 NOTE: 'lowmem' mode does not work with '--repair' yet, and is still considered
 123 experimental.
 124
 125 --force::
 126 allow to work on a mounted filesystem. Note that this should work fine on a
 127 quiescent or read-only mounted filesystem but may crash if the device is
 128 changed externally, eg. by the kernel module.  Repair without mount checks is
 129 not supported right now.
 130
 131 EXIT STATUS
 132 -----------
 133 *btrfs check* returns a zero exit status if it succeeds. Non zero is
 134 returned in case of failure.
 135
 136 AVAILABILITY
 137 ------------
 138 *btrfs* is part of btrfs-progs.
 139 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 140 further details.
 141
 142 SEE ALSO
 143 --------
 144 `mkfs.btrfs`(8),
 145 `btrfs-scrub`(8),
 146 `btrfs-rescue`(8)