{ "content": [ { "type": "text", "text": "# BTRFS-SCRUB (man)\n\n## NAME\n\nbtrfs-scrub - scrub btrfs filesystem, verify block checksums\n\n## SYNOPSIS\n\nbtrfs scrub \n\n## DESCRIPTION\n\nScrub is a pass over all filesystem data and metadata and verifying the checksums. If a valid\ncopy is available (replicated block group profiles) then the damaged one is repaired. All\ncopies of the replicated profiles are validated.\n\n## TLDR\n\n> Scrub btrfs filesystems to verify data integrity.\n\n- Start a scrub:\n `sudo btrfs {{sc|scrub}} start {{path/to/btrfs_mount}}`\n- Show the status of an ongoing or last completed scrub:\n `sudo btrfs {{sc|scrub}} status {{path/to/btrfs_mount}}`\n- Cancel an ongoing scrub:\n `sudo btrfs {{sc|scrub}} {{c|cancel}} {{path/to/btrfs_mount}}`\n- Resume a previously cancelled scrub:\n `sudo btrfs {{sc|scrub}} {{r|resume}} {{path/to/btrfs_mount}}`\n- Start a scrub, but do not put the program in the [B]ackground:\n `sudo btrfs {{sc|scrub}} start -B {{path/to/btrfs_mount}}`\n- Start a scrub in quiet mode (does not print errors or statistics):\n `sudo btrfs {{sc|scrub}} start {{-q|--quiet}} {{path/to/btrfs_mount}}`\n\n*Source: tldr-pages*\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (3 subsections)\n- **SUBCOMMAND** (6 subsections)\n- **EXIT STATUS**\n- **AVAILABILITY**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "BTRFS-SCRUB", "section": "", "mode": "man", "summary": "btrfs-scrub - scrub btrfs filesystem, verify block checksums", "synopsis": "btrfs scrub ", "tldr_summary": "Scrub btrfs filesystems to verify data integrity.", "tldr_examples": [ { "description": "Start a scrub", "command": "sudo btrfs {{sc|scrub}} start {{path/to/btrfs_mount}}" }, { "description": "Show the status of an ongoing or last completed scrub", "command": "sudo btrfs {{sc|scrub}} status {{path/to/btrfs_mount}}" }, { "description": "Cancel an ongoing scrub", "command": "sudo btrfs {{sc|scrub}} {{c|cancel}} {{path/to/btrfs_mount}}" }, { "description": "Resume a previously cancelled scrub", "command": "sudo btrfs {{sc|scrub}} {{r|resume}} {{path/to/btrfs_mount}}" }, { "description": "Start a scrub, but do not put the program in the [B]ackground", "command": "sudo btrfs {{sc|scrub}} start -B {{path/to/btrfs_mount}}" }, { "description": "Start a scrub in quiet mode (does not print errors or statistics)", "command": "sudo btrfs {{sc|scrub}} start {{-q|--quiet}} {{path/to/btrfs_mount}}" } ], "tldr_source": "official", "flags": [ { "flag": "-q", "long": null, "arg": null, "description": "" } ], "examples": [], "see_also": [ { "name": "mkfs.btrfs", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/mkfs.btrfs/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 4, "subsections": [ { "name": "NOTE:", "lines": 18 }, { "name": "Bandwidth and IO limiting", "lines": 1 }, { "name": "NOTE:", "lines": 30 } ] }, { "name": "SUBCOMMAND", "lines": 1, "subsections": [ { "name": "cancel |", "lines": 6 }, { "name": "limit [options] ", "lines": 35 }, { "name": "resume [-BdqrR] |", "lines": 9 }, { "name": "start [-BdrRf] |", "lines": 34 }, { "name": "-q (deprecated)", "lines": 1, "flag": "-q" }, { "name": "status [options] |", "lines": 86 } ] }, { "name": "EXIT STATUS", "lines": 9, "subsections": [] }, { "name": "AVAILABILITY", "lines": 3, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] } ], "sections": { "NAME": { "content": "btrfs-scrub - scrub btrfs filesystem, verify block checksums\n", "subsections": [] }, "SYNOPSIS": { "content": "btrfs scrub \n", "subsections": [] }, "DESCRIPTION": { "content": "Scrub is a pass over all filesystem data and metadata and verifying the checksums. If a valid\ncopy is available (replicated block group profiles) then the damaged one is repaired. All\ncopies of the replicated profiles are validated.\n", "subsections": [ { "name": "NOTE:", "content": "Scrub is not a filesystem checker (fsck) and does not verify nor repair structural damage\nin the filesystem. It really only checks checksums of data and tree blocks, it doesn't en‐\nsure the content of tree blocks is valid and consistent. There's some validation performed\nwhen metadata blocks are read from disk (Tree checker) but it's not extensive and cannot\nsubstitute full btrfs-check(8) run.\n\nThe user is supposed to run it manually or via a periodic system service. The recommended pe‐\nriod is a month but it could be less. The estimated device bandwidth utilization is about 80%\non an idle filesystem.\n\nThe scrubbing status is recorded in /var/lib/btrfs/ in textual files named scrub.status.UUID\nfor a filesystem identified by the given UUID. (Progress state is communicated through a\nnamed pipe in file scrub.progress.UUID in the same directory.) The status file is updated\nevery 5 seconds. A resumed scrub will continue from the last saved position.\n\nScrub can be started only on a mounted filesystem, though it's possible to scrub only a se‐\nlected device. See btrfs scrub start for more.\n" }, { "name": "Bandwidth and IO limiting", "content": "" }, { "name": "NOTE:", "content": "The ionice(1) may not be generally supported by all IO schedulers and the options to btrfs\nscrub start may not work as expected.\n\nIn the past when the CFQ IO scheduler was generally used the ionice(1) syscalls set the pri‐\nority to idle so the IO would not interfere with regular IO. Since the kernel 5.0 the CFQ is\nnot available.\n\nThe IO scheduler known to support that is BFQ, but first read the documentation before using\nit!\n\nFor other commonly used schedulers like mq-deadline it's recommended to use cgroup2 IO con‐\ntroller which could be managed by e.g. systemd (documented in systemd.resource-control). How‐\never, starting scrub like that is not yet completely straightforward. The IO controller must\nknow the physical device of the filesystem and create a slice so all processes started from\nthat belong to the same accounting group.\n\n$ systemd-run -p \"IOBandwidthReadMax=/dev/sdx 10M\" btrfs scrub start -B /\n\nSince linux 5.14 it's possible to set the per-device bandwidth limits in a BTRFS-specific way\nusing files /sys/fs/btrfs/FSID/devinfo/DEVID/scrubspeedmax. This setting is not persis‐\ntent, lasts until the filesystem is unmounted. Currently set limits can be displayed by com‐\nmand btrfs scrub limit.\n\n$ echo 100m > /sys/fs/btrfs/9b5fd16e-1b64-4f9b-904a-74e74c0bbadc/devinfo/1/scrubspeedmax\n$ btrfs scrub limit /\nUUID: 9b5fd16e-1b64-4f9b-904a-74e74c0bbadc\nId Limit Path\n-- --------- --------\n1 100.00MiB /dev/sdx\n" } ] }, "SUBCOMMAND": { "content": "", "subsections": [ { "name": "cancel |", "content": "If a scrub is running on the filesystem identified by path or device, cancel it.\n\nIf a device is specified, the corresponding filesystem is found and btrfs scrub cancel\nbehaves as if it was called on that filesystem. The progress is saved in the status\nfile so btrfs scrub resume can continue from the last position.\n" }, { "name": "limit [options] ", "content": "Show or set scrub limits on devices of the given filesystem.\n\nOptions\n\n-d|--devid DEVID\nselect the device by DEVID to apply the limit\n\n-l|--limit SIZE\nset the limit of the device to SIZE (size units with suffix), or 0 to reset to\nunlimited\n\n-a|--all\napply the limit to all devices\n\n--raw print all numbers raw values in bytes without the B suffix\n\n--human-readable\nprint human friendly numbers, base 1024, this is the default\n\n--iec select the 1024 base for the following options, according to the IEC standard\n\n--si select the 1000 base for the following options, according to the SI standard\n\n--kbytes\nshow sizes in KiB, or kB with --si\n\n--mbytes\nshow sizes in MiB, or MB with --si\n\n--gbytes\nshow sizes in GiB, or GB with --si\n\n--tbytes\nshow sizes in TiB, or TB with --si\n" }, { "name": "resume [-BdqrR] |", "content": "Resume a cancelled or interrupted scrub on the filesystem identified by path or on a\ngiven device. The starting point is read from the status file if it exists.\n\nThis does not start a new scrub if the last scrub finished successfully.\n\nOptions\n\nsee scrub start.\n" }, { "name": "start [-BdrRf] |", "content": "Start a scrub on all devices of the mounted filesystem identified by path or on a sin‐\ngle device. If a scrub is already running, the new one will not start. A device of an\nunmounted filesystem cannot be scrubbed this way.\n\nWithout options, scrub is started as a background process. The automatic repairs of\ndamaged copies are performed by default for block group profiles with redundancy.\nNo-repair can be enabled by option -r.\n\nOptions\n\n-B do not background and print scrub statistics when finished\n\n-d print separate statistics for each device of the filesystem (-B only) at the\nend\n\n-r run in read-only mode, do not attempt to correct anything, can be run on a\nread-only filesystem\n\n-R raw print mode, print full data instead of summary\n\n-f force starting new scrub even if a scrub is already running, this can useful\nwhen scrub status file is damaged and reports a running scrub although it is\nnot, but should not normally be necessary\n\nDeprecated options\n\n-c \nset IO priority class (see ionice(1) manual page) if the IO scheduler config‐\nured for the device supports ionice. This is only supported by BFQ or Kyber but\nis not supported by mq-deadline. Please read the section about IO limiting.\n\n-n \nset IO priority classdata (see ionice(1) manpage)\n" }, { "name": "-q (deprecated)", "content": "", "flag": "-q" }, { "name": "status [options] |", "content": "Show status of a running scrub for the filesystem identified by path or for the speci‐\nfied device.\n\nIf no scrub is running, show statistics of the last finished or cancelled scrub for\nthat filesystem or device.\n\nOptions\n\n-d print separate statistics for each device of the filesystem\n\n-R print all raw statistics without postprocessing as returned by the status ioctl\n\n--raw print all numbers raw values in bytes without the B suffix\n\n--human-readable\nprint human friendly numbers, base 1024, this is the default\n\n--iec select the 1024 base for the following options, according to the IEC standard\n\n--si select the 1000 base for the following options, according to the SI standard\n\n--kbytes\nshow sizes in KiB, or kB with --si\n\n--mbytes\nshow sizes in MiB, or MB with --si\n\n--gbytes\nshow sizes in GiB, or GB with --si\n\n--tbytes\nshow sizes in TiB, or TB with --si\n\nA status on a filesystem without any error looks like the following:\n\n# btrfs scrub start /\n# btrfs scrub status /\nUUID: 76fac721-2294-4f89-a1af-620cde7a1980\nScrub started: Wed Apr 10 12:34:56 2023\nStatus: running\nDuration: 0:00:05\nTime left: 0:00:05\nETA: Wed Apr 10 12:35:01 2023\nTotal to scrub: 28.32GiB\nBytes scrubbed: 13.76GiB (48.59%)\nRate: 2.75GiB/s\nError summary: no errors found\n\nWith some errors found:\n\nError summary: csum=72\nCorrected: 2\nUncorrectable: 72\nUnverified: 0\n\n• Corrected -- number of bad blocks that were repaired from another copy\n\n• Uncorrectable -- errors detected at read time but not possible to repair from other\ncopy\n\n• Unverified -- transient errors, first read failed but a retry succeeded, may be af‐\nfected by lower layers that group or split IO requests\n\n• Error summary -- followed by a more detailed list of errors found\n\n• csum -- checksum mismatch\n\n• super -- super block errors, unless the error is fixed immediately, the next com‐\nmit will overwrite superblock\n\n• verify -- metadata block header errors\n\n• read -- blocks can't be read due to IO errors\n\nIt's possible to set a per-device limit via file sysfs/fs/btrfs/FSID/dev‐\ninfo/scrubspeedmax. In that case the limit is printed on the Rate: line if option -d\nis specified, or without it on a single-device filesystem. Read more about tat in\nsection about scrub IO limiting.\n\nRate: 989.0MiB/s (limit 1.0G/s)\n\nOn a multi-device filesystem with at least one device limit the overall stats cannot\nprint the limit without -d so there's a not that some limits are set:\n\nRate: 36.37MiB/s (some device limits set)\n" } ] }, "EXIT STATUS": { "content": "btrfs scrub returns a zero exit status if it succeeds. Non zero is returned in case of fail‐\nure:\n\n1 scrub couldn't be performed\n\n2 there is nothing to resume\n\n3 scrub found uncorrectable errors\n", "subsections": [] }, "AVAILABILITY": { "content": "btrfs is part of btrfs-progs. Please refer to the documentation at\nhttps://btrfs.readthedocs.io.\n", "subsections": [] }, "SEE ALSO": { "content": "mkfs.btrfs(8)\n\n\n6.6.3 Mar 31, 2024 BTRFS-SCRUB(8)", "subsections": [] } } } }