1BTRFS-CHECK(8)                       BTRFS                      BTRFS-CHECK(8)
2
3
4

NAME

6       btrfs-check - check or repair a btrfs filesystem
7

SYNOPSIS

9       btrfs check [options] <device>
10

DESCRIPTION

12       The  filesystem  checker  is  used  to verify structural integrity of a
13       filesystem and attempt to repair it if requested.  It is recommended to
14       unmount  the  filesystem prior to running the check, but it is possible
15       to start checking a mounted filesystem (see --force).
16
17       By default, btrfs check will not modify the device but you can reaffirm
18       that by the option --readonly.
19
20       btrfsck is an alias of btrfs check command and is now deprecated.
21
22       WARNING:
23          Do  not  use --repair unless you are advised to do so by a developer
24          or an experienced user, and then only after having accepted that  no
25          fsck  successfully  repair  all types of filesystem corruption. E.g.
26          some other software or hardware bugs can fatally damage a volume.
27
28       The structural integrity check verifies if internal filesystem  objects
29       or  data structures satisfy the constraints, point to the right objects
30       or are correctly connected together.
31
32       There are several cross checks that can detect wrong  reference  counts
33       of shared extents, backreferences, missing extents of inodes, directory
34       and inode connectivity etc.
35
36       The amount of memory required can be high, depending on the size of the
37       filesystem,  similarly  the run time. Check the modes that can also af‐
38       fect that.
39

SAFE OR ADVISORY OPTIONS

41       -b|--backup
42              use the first valid set of backup roots stored in the superblock
43
44              This can be combined with --super if some of the superblocks are
45              damaged.
46
47       --check-data-csum
48              verify checksums of data blocks
49
50              This  expects  that the filesystem is otherwise OK, and is basi‐
51              cally an offline scrub that does  not  repair  data  from  spare
52              copies.
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       -Q|--qgroup-report
64              verify qgroup accounting and compare against filesystem account‐
65              ing
66
67       -r|--tree-root <bytenr>
68              use the given offset 'bytenr' for the tree root
69
70       --readonly
71              (default) run in read-only mode, this option exists to calm  po‐
72              tential panic when users are going to run the checker
73
74       -s|--super <N>
75              use  Nth  superblock copy, valid values are 0, 1 or 2 if the re‐
76              spective superblock offset is within the device size
77
78              This can be used to use a different starting point  if  some  of
79              the primary 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
85              only rebuilds the free space cache for  block  groups  that  are
86              modified while the filesystem is mounted with that option. Thus,
87              using this option with v1 makes it possible  to  actually  clear
88              the entire free space cache.
89
90              For free space cache v2, the clear_cache kernel mount option de‐
91              stroys the entire free space cache. This option,  with  v2  pro‐
92              vides  an  alternative  method  of clearing the free space cache
93              that doesn't require mounting the filesystem.
94
95       --clear-ino-cache
96              remove leftover items pertaining to  the  deprecated  inode  map
97              feature
98

DANGEROUS OPTIONS

100       --repair
101              enable  the repair mode and attempt to fix problems where possi‐
102              ble
103
104              NOTE:
105                 There's a warning and 10 second delay when this option is run
106                 without  --force to give users a chance to think twice before
107                 running repair, the warnings in documentation have  shown  to
108                 be insufficient
109
110       --init-csum-tree
111              create  a  new  checksum  tree  and recalculate checksums in all
112              files
113
114              WARNING:
115                 Do not blindly use this option to fix checksum mismatch prob‐
116                 lems.
117
118       --init-extent-tree
119              build the extent tree from scratch
120
121              WARNING:
122                 Do not use unless you know what you're doing.
123
124       --mode <MODE>
125              select mode of operation regarding memory and IO
126
127              The MODE can be one of:
128
129              original
130                     The  metadata are read into memory and verified, thus the
131                     requirements are high on large filesystems and  can  even
132                     lead  to  out-of-memory  conditions.   The possible work‐
133                     around is to export the block device over  network  to  a
134                     machine with enough memory.
135
136              lowmem This mode is supposed to address the high memory consump‐
137                     tion at the cost of increased IO when it needs to re-read
138                     blocks.  This may increase run time.
139
140              NOTE:
141                 lowmem  mode  does  not  work with --repair yet, and is still
142                 considered experimental.
143
144       --force
145              allow work on a mounted filesystem. Note that this  should  work
146              fine  on  a  quiescent  or  read-only mounted filesystem but may
147              crash if the device is changed externally, e.g.  by  the  kernel
148              module.  Repair without mount checks is not supported right now.
149
150              This  option also skips the delay and warning in the repair mode
151              (see --repair).
152

EXIT STATUS

154       btrfs check returns a zero exit status if it succeeds. Non zero is  re‐
155       turned in case of failure.
156

AVAILABILITY

158       btrfs  is  part  of  btrfs-progs.  Please refer to the documentation at
159       https://btrfs.readthedocs.io or wiki  http://btrfs.wiki.kernel.org  for
160       further information.
161

SEE ALSO

163       mkfs.btrfs(8), btrfs-scrub(8), btrfs-rescue(8)
164
165
166
167
1686.1.3                            Jan 25, 2023                   BTRFS-CHECK(8)
Impressum