Documentation/btrfs-check.asciidoc

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