NAME
----
-btrfs-check - check or repair an unmounted btrfs filesystem
+btrfs-check - check or repair a btrfs filesystem
SYNOPSIS
--------
DESCRIPTION
-----------
-*btrfs check* is used to check or repair an unmounted btrfs filesystem.
-NOTE: Since btrfs is under development, the *btrfs check* capabilities are
-continuously enhanced. It's highly recommended to read the following btrfs
-wiki before executing *btrfs check* with '--repair' option: +
-https://btrfs.wiki.kernel.org/index.php/Btrfsck
+The filesystem checker is used to verify structural integrity of a filesystem
+and attempt to repair it if requested. It is recommended to unmount the
+filesystem prior to running the check, but it is possible to start checking a
+mounted filesystem (see '--force').
+
+By default, *btrfs check* will not modify the device but you can reaffirm that
+by the option '--readonly'.
*btrfsck* is an alias of *btrfs check* command and is now deprecated.
-OPTIONS
--------
--s|--super <superblock>::
-use <superblock>th superblock copy, valid values are 0 up to 2 if the
-respective superblock offset is within the fileystem
---repair::
-try to repair the filesystem
---init-csum-tree::
-create a new CRC tree and recalculate all checksums
---init-extent-tree::
-create a new extent tree
+WARNING: Do not use '--repair' unless you are advised to do so by a developer
+or an experienced user, and then only after having accepted that no 'fsck'
+successfully repair all types of filesystem corruption. Eg. some other software
+or hardware bugs can fatally damage a volume.
+
+The structural integrity check verifies if internal filesystem objects or
+data structures satisfy the constraints, point to the right objects or are
+correctly connected together.
+
+There are several cross checks that can detect wrong reference counts of shared
+extents, backreferences, missing extents of inodes, directory and inode
+connectivity etc.
+
+The amount of memory required can be high, depending on the size of the
+filesystem, similarly the run time.
+
+SAFE OR ADVISORY OPTIONS
+------------------------
+
+-b|--backup::
+use the first valid set of backup roots stored in the superblock
++
+This can be combined with '--super' if some of the superblocks are damaged.
+
--check-data-csum::
-verify checkums of data blocks
+verify checksums of data blocks
++
+This expects that the filesystem is otherwise OK, and is basically and offline
+'scrub' but does not repair data from spare copies.
+
+--chunk-root <bytenr>::
+use the given offset 'bytenr' for the chunk tree root
+
+-E|--subvol-extents <subvolid>::
+show extent state for the given subvolume
+
-p|--progress::
indicate progress at various checking phases
---qgroup-report::
+
+-Q|--qgroup-report::
verify qgroup accounting and compare against filesystem accounting
---subvol-extents <subvolid>::
-show extent state for a subvolume
---tree-root <bytenr>::
-use the given bytenr for the tree root
+
+-r|--tree-root <bytenr>::
+use the given offset 'bytenr' for the tree root
+
+--readonly::
+(default)
+run in read-only mode, this option exists to calm potential panic when users
+are going to run the checker
+
+-s|--super <superblock>::
+use 'superblock'th superblock copy, valid values are 0, 1 or 2 if the
+respective superblock offset is within the device size
++
+This can be used to use a different starting point if some of the primary
+superblock is damaged.
+
+--clear-space-cache v1|v2::
+completely wipe all free space cache of given type
++
+For free space cache 'v1', the 'clear_cache' kernel mount option only rebuilds
+the free space cache for block groups that are modified while the filesystem is
+mounted with that option. Thus, using this option with 'v1' makes it possible
+to actually clear the entire free space cache.
++
+For free space cache 'v2', the 'clear_cache' kernel mount option destroys
+the entire free space cache. This option, with 'v2' provides an alternative
+method of clearing the free space cache that doesn't require mounting the
+filesystem.
+
+
+DANGEROUS OPTIONS
+-----------------
+
+--repair::
+enable the repair mode and attempt to fix problems where possible
+--init-csum-tree::
+create a new checksum tree and recalculate checksums in all files
++
+NOTE: Do not blindly use this option to fix checksum mismatch problems.
+
+--init-extent-tree::
+build the extent tree from scratch
++
+NOTE: Do not use unless you know what you're doing.
+
+--mode=MODE::
+select mode of operation regarding memory and IO
++
+The 'MODE' can be one of 'original' and 'lowmem'. The original mode is mostly
+unoptimized regarding memory consumption and can lead to out-of-memory
+conditions on large filesystems. The possible workaround is to export the block
+device over network to a machine with enough memory. The low memory mode is
+supposed to address the memory consumption, at the cost of increased IO when it
+needs to re-read blocks when needed. This may increase run time.
+
+NOTE: 'lowmem' mode does not work with '--repair' yet, and is still considered
+experimental.
+
+--force::
+allow work on a mounted filesystem. Note that this should work fine on a
+quiescent or read-only mounted filesystem but may crash if the device is
+changed externally, eg. by the kernel module. Repair without mount checks is
+not supported right now.
EXIT STATUS
-----------
projects / platform / upstream / btrfs-progs.git / blobdiff