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 NOTE: Only v1 free space cache supported is implemented.
  85 +
  86 Kernel mount option 'clear_cache' is only designed to rebuild free space cache
  87 which is modified during the lifetime of that mount option.  It doesn't rebuild
  88 all free space cache, nor clear them out.
  89
  90
  91 DANGEROUS OPTIONS
  92 -----------------
  93
  94 --repair::
  95 enable the repair mode and attempt to fix problems where possible
  96 --init-csum-tree::
  97 create a new checksum tree and recalculate checksums in all files
  98 +
  99 NOTE: Do not blindly use this option to fix checksum mismatch problems.
 100
 101 --init-extent-tree::
 102 build the extent tree from scratch
 103 +
 104 NOTE: Do not use unless you know what you're doing.
 105
 106 --mode=MODE::
 107 select mode of operation regarding memory and IO
 108 +
 109 The 'MODE' can be one of 'original' and 'lowmem'. The original mode is mostly
 110 unoptimized regarding memory consumpption and can lead to out-of-memory
 111 conditions on large filesystems. The possible workaround is to export the block
 112 device over network to a machine with enough memory. The low memory mode is
 113 supposed to address the memory consumption, at the cost of increased IO when it
 114 needs to re-read blocks when needed. This may increase run time.
 115
 116 NOTE: 'lowmem' mode does not work with '--repair' yet, and is still considered
 117 experimental.
 118
 119 EXIT STATUS
 120 -----------
 121 *btrfs check* returns a zero exit status if it succeeds. Non zero is
 122 returned in case of failure.
 123
 124 AVAILABILITY
 125 ------------
 126 *btrfs* is part of btrfs-progs.
 127 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 128 further details.
 129
 130 SEE ALSO
 131 --------
 132 `mkfs.btrfs`(8),
 133 `btrfs-scrub`(8),
 134 `btrfs-rescue`(8)