From 5079ae684a7a68dd2fa9584a4ea01a0a3f815f98 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Fri, 6 May 2016 14:45:57 +0200 Subject: [PATCH] btrfs-progs: docs: update btrfs-check Signed-off-by: David Sterba --- Documentation/btrfs-check.asciidoc | 97 ++++++++++++++++++++++-------- 1 file changed, 71 insertions(+), 26 deletions(-) diff --git a/Documentation/btrfs-check.asciidoc b/Documentation/btrfs-check.asciidoc index 7371a23c..74a2ad21 100644 --- a/Documentation/btrfs-check.asciidoc +++ b/Documentation/btrfs-check.asciidoc @@ -11,42 +11,87 @@ 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. The filesystem must be unmounted. + +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 :: -use th superblock copy, valid values are 0 up to 2 if the -respective superblock offset is within the filesystem +WARNING: Do not use '--repair' unless you are adviced to by a developer, an +experienced user or accept the fact that 'fsck' cannot possibly fix all sorts +of damage that could happen to a filesystem because of software and hardware +bugs. + +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, backrefrences, missing extents of inodes, directory and inode +connectivity etc. + +The amount of memory required can be high, depending on the size of the +filesystem, smililarly the run time. + +SAFE OR ADVISORY OPTIONS +------------------------ + -b|--backup:: -use the first backup roots stored in the superblock that is valid ---repair:: -try to repair the filesystem ---readonly:: -run in read-only mode (default) ---init-csum-tree:: -create a new CRC tree and recalculate all checksums ---init-extent-tree:: -create a new extent tree +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 checksums of data blocks --p|--progress:: -indicate progress at various checking phases ---qgroup-report:: -verify qgroup accounting and compare against filesystem accounting ++ +This expects that the filesystem is otherwise +OK, so this is basically and offline 'scrub' but does not repair data from +spare coipes. + +--chunk-root :: +use the given offset 'bytenr' for the chunk tree root + -E|--subvol-extents :: show extent state for the given subvolume + +-p|--progress:: +indicate progress at various checking phases + +--qgroup-report:: +verify qgroup accounting and compare against filesystem accounting + -r|--tree-root :: -use the given bytenr for the tree root ---chunk-root :: -use the given bytenr for the chunk tree root +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 :: +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. + +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. EXIT STATUS -----------