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