btrfs-progs/Documentation
Qu Wenruo fe27c052cb btrfs-progs: docs: extra notes about read-only scrub on read-write fs
[BUG]
There is a bug report that read-only scrub on a read-write fs still
causes writes into the fs, and that will be caught if there is a
read-only block device among the storage stack.

This will cause a kernel warning on failed transaction commit:

  BTRFS info (device dm-3): first mount of filesystem e18f0c40-88de-413f-9d7e-dcc8136ad6dd
  BTRFS info (device dm-3): using crc32c (crc32c-intel) checksum algorithm
  BTRFS info (device dm-3): using free-space-tree
  BTRFS info (device dm-3): scrub: started on devid 1
  Trying to write to read-only block-device md127
  btrfs_dev_stat_inc_and_print: 362 callbacks suppressed
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 1, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 2, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 3, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 4, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 5, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 6, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 7, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 8, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 9, rd 0, flush 0, corrupt 0, gen 0
  BTRFS error (device dm-3): bdev /dev/mapper/data errs: wr 10, rd 0, flush 0, corrupt 0, gen 0
  BTRFS: error (device dm-3) in btrfs_commit_transaction:2523: errno=-5 IO failure (Error while writing out transaction)
  BTRFS info (device dm-3 state E): forced readonly
  BTRFS warning (device dm-3 state E): Skipping commit of aborted transaction.
  BTRFS error (device dm-3 state EA): Transaction aborted (error -5)
  BTRFS: error (device dm-3 state EA) in cleanup_transaction:2017: errno=-5 IO failure
  BTRFS warning (device dm-3 state EA): failed setting block group ro: -5
  BTRFS info (device dm-3 state EA): scrub: not finished on devid 1 with status: -5

[CAUSE]
The root cause is inside btrfs_inc_block_group_ro(), where we need to
hold a transaction handle, to prevent the transaction to be committed,
until we hold ro_block_group_mutex.

This will cause an empty transaction by itself, thus even if we can mark
the block group read-only without any extra workload, we still need to
commit the new and empty transaction.

Unfortunately this means RO scrub on RW filesystem will always cause the
fs to be updated.

[FIX]
The best fix is to make btrfs to avoid empty commit transaction, but
even with that done, read-only scrub on rw mount can still cause real
metadata updates (e.g. allocate new chunks and update device error
statistics).

It will be very complex to make read-only scrub to be fully read-only
on a read-write btrfs.

Thankfully read-only scrub on read-write mount with read-only device in
the storage stack is pretty rare, thus a documentation update should be
enough.

Issue: #934
Pull-request: #935
Signed-off-by: Qu Wenruo <wqu@suse.com>
Signed-off-by: David Sterba <dsterba@suse.com>
2025-02-11 20:43:28 +01:00
..
_static btrfs-progs: docs: restyle the landing page 2023-12-01 00:54:27 +01:00
_templates btrfs-progs: docs: update template, more about subvolumes 2022-01-11 15:46:33 +01:00
dev btrfs-progs: docs: mention CONFIG_BTRFS_EXPERIMENTAL if relevant 2025-02-11 20:43:28 +01:00
Administration.rst btrfs-progs: docs: include sysfs to Administration 2024-07-30 20:05:11 +02:00
Auto-repair.rst btrfs-progs: docs: auto-repair editing 2024-11-28 14:40:46 +01:00
Balance.rst btrfs-progs: docs: add balance filter examples 2023-06-09 12:44:03 +02:00
btrfs-balance.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
btrfs-check.rst btrfs-progs: docs: clarify how btrfs check works with replicas 2024-11-28 14:40:46 +01:00
btrfs-convert.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
btrfs-device.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
btrfs-filesystem.rst btrfs-progs: fi resize: warn if new size is < 256M 2024-09-17 16:19:03 +02:00
btrfs-find-root.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
btrfs-image.rst btrfs-progs: docs: add warning for -s option of btrfs-image 2024-07-30 19:56:41 +02:00
btrfs-inspect-internal.rst btrfs-progs: list-chunks: update help and documentation 2024-07-30 19:53:33 +02:00
btrfs-ioctl.rst btrfs-progs: docs: document new ioctl SYNC_WAIT 2025-01-21 21:19:00 +01:00
btrfs-man5.rst btrfs-progs: install btrfs-ioctl manual page 2024-09-17 14:33:22 +02:00
btrfs-map-logical.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
btrfs-property.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
btrfs-qgroup.rst btrfs-progs: clarify unlinked and deleted terminology for subvolumes 2024-05-17 18:13:18 +02:00
btrfs-quota.rst btrfs-progs: docs: document squota 2023-10-03 01:11:54 +02:00
btrfs-receive.rst btrfs-progs: docs: clarify receive --dump encoding 2024-06-24 19:19:04 +02:00
btrfs-replace.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
btrfs-rescue.rst btrfs-progs: docs: update documentation 2025-01-17 21:59:07 +01:00
btrfs-restore.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
btrfs-scrub.rst btrfs-progs: docs: extra notes about read-only scrub on read-write fs 2025-02-11 20:43:28 +01:00
btrfs-select-super.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
btrfs-send.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
btrfs-subvolume.rst btrfs-progs: subvolume delete: add new option for recursive deletion 2024-09-17 17:00:03 +02:00
btrfs.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
btrfsck.8 btrfs-progs: docs: use manual page link instead of symlink 2018-10-23 14:48:39 +02:00
btrfstune.rst btrfs-progs: btrfstune: add ability to remove squotas 2025-01-06 14:19:28 +01:00
ch-balance-examples.rst btrfs-progs: docs: add balance filter examples 2023-06-09 12:44:03 +02:00
ch-balance-filters.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
ch-balance-intro.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
ch-bootloaders.rst btrfs-progs: docs: fixups, references 2023-06-01 20:50:04 +02:00
ch-checksumming.rst btrfs-progs: docs: checksumming editing 2024-11-28 14:40:46 +01:00
ch-compression.rst btrfs-progs: docs: fix incorrect description about compression with O_DIRECT 2024-03-25 22:57:50 +01:00
ch-convert-intro.rst btrfs-progs: docs: clarify potential problems with convert 2024-02-20 10:52:08 +01:00
ch-file-attributes.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
ch-flexibility.rst btrfs-progs: docs: fixups, references 2023-06-01 20:50:04 +02:00
ch-fs-limits.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
ch-hardware-considerations.rst btrfs-progs: docs: update memory related problems 2024-03-25 23:33:25 +01:00
ch-mount-options.rst btrfs-progs: docs: update documentation 2025-01-17 21:59:07 +01:00
ch-quota-intro.rst btrfs-progs: docs: document squota 2023-10-03 01:11:54 +02:00
ch-scrub-intro.rst btrfs-progs: docs: extra notes about read-only scrub on read-write fs 2025-02-11 20:43:28 +01:00
ch-seeding-device.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
ch-subvolume-intro.rst btrfs-progs: docs: subvolume intro editing 2024-11-28 14:40:46 +01:00
ch-swapfile.rst btrfs-progs: docs: clarify swapfile an multi-device filesystem 2024-07-30 20:05:11 +02:00
ch-sysfs.rst btrfs-progs: docs: fix new typos 2024-08-14 23:58:14 +02:00
ch-volume-management-intro.rst btrfs-progs: docs: add warning about balance to replace failing device 2024-11-28 14:40:46 +01:00
ch-zoned-intro.rst btrfs-progs: docs: add zone reclaim 2024-07-30 20:05:11 +02:00
CHANGES.rst btrfs-progs: docs: distinguish Changes title 2022-08-16 15:18:10 +02:00
Checksumming.rst btrfs-progs: docs: add more chapters 2021-12-17 11:53:44 +01:00
CmdLineConventions btrfs-progs: docs: fix typos 2022-12-07 21:00:25 +01:00
CodingConventions btrfs-progs: docs: document conventions 2017-07-03 13:35:10 +02:00
Common-features.rst btrfs-progs: docs: cross references, ioctl updates 2023-12-06 17:44:28 +01:00
Compression.rst btrfs-progs: docs: add more chapters 2021-12-17 11:53:44 +01:00
conf.py btrfs-progs: install btrfs-ioctl manual page 2024-09-17 14:33:22 +02:00
Contributors.rst btrfs-progs: docs: add 6.13 kernel development statistics 2025-01-20 14:53:23 +01:00
Convert.rst btrfs-progs: docs: add more chapters (part 2) 2021-12-17 11:53:44 +01:00
Custom-ioctls.rst btrfs-progs: run codespell throughout fixing typos automagically 2024-07-30 19:56:08 +02:00
Deduplication.rst btrfs-progs: docs: typo fixups and formatting updates 2022-12-22 18:44:47 +01:00
Defragmentation.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
DocConventions.rst btrfs-progs: docs: documentation updates and fixes 2025-01-22 20:24:26 +01:00
Feature-by-version.rst btrfs-progs: docs: update kernel feature updates 2025-01-17 21:59:07 +01:00
fsck.btrfs.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
Glossary.rst btrfs-progs: docs: use manref role for all manual page references 2024-02-16 09:38:16 +01:00
Hardware.rst btrfs-progs: docs: separate chapter for hardware considerations 2022-05-17 21:12:19 +02:00
html-preview.sh btrfs-progs: ci: build html manual page previews if source changed 2024-07-30 19:53:32 +02:00
index.rst btrfs-progs: docs: documentation updates and fixes 2025-01-22 20:24:26 +01:00
Inline-files.rst btrfs-progs: docs: inline files vs tail packing 2024-09-17 16:47:42 +02:00
INSTALL.rst btrfs-progs: docs: link INSTALL to docs 2022-05-12 13:56:03 +02:00
Interoperability.rst btrfs-progs: docs: update status page and features 2025-01-20 18:29:32 +01:00
Introduction.rst btrfs-progs: docs: documentation updates and fixes 2025-01-22 20:24:26 +01:00
Kernel-by-version.rst btrfs-progs: docs: add headings for 6.12 and 6.13 changelogs 2025-01-21 21:31:14 +01:00
Makefile.in btrfs-progs: build: command output format update 2025-01-07 21:31:44 +01:00
man-index.rst btrfs-progs: install btrfs-ioctl manual page 2024-09-17 14:33:22 +02:00
man-preview.sh btrfs-progs: run codespell throughout fixing typos automagically 2024-07-30 19:56:08 +02:00
mkfs.btrfs.rst btrfs-progs: docs: mention CONFIG_BTRFS_EXPERIMENTAL if relevant 2025-02-11 20:43:28 +01:00
plot-contribs.svg btrfs-progs: docs: update 6.13 contribution graphs 2025-01-20 18:29:32 +01:00
plot-patches.svg btrfs-progs: docs: update 6.13 contribution graphs 2025-01-20 18:29:32 +01:00
plot-sloc-lines.svg btrfs-progs: docs: update 6.13 contribution graphs 2025-01-20 18:29:32 +01:00
Qgroups.rst btrfs-progs: docs: add more chapters (part 2) 2021-12-17 11:53:44 +01:00
Reflink.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
requirements.txt btrfs-progs: docs: add config file for readthedocs.io 2023-12-05 16:36:24 +01:00
Resize.rst btrfs-progs: docs: formatting updates 2023-07-26 14:59:10 +02:00
Scrub.rst btrfs-progs: docs: add more chapters (part 2) 2021-12-17 11:53:44 +01:00
Seeding-device.rst btrfs-progs: docs: add more chapters 2021-12-17 11:53:44 +01:00
Send-receive.rst btrfs-progs: docs: clarify btrfs-send checksum 2024-08-14 23:59:47 +02:00
Source-repositories.rst btrfs-progs: docs: update source repositories, workflows 2024-07-30 20:05:11 +02:00
Status.rst btrfs-progs: docs: update status page and features 2025-01-20 18:29:32 +01:00
Subpage.rst btrfs-progs: docs: mkfs and sectorsize updates 2024-01-18 02:44:58 +01:00
Subvolumes.rst btrfs-progs: docs: add more chapters (part 3) 2021-12-17 15:35:10 +01:00
Swapfile.rst btrfs-progs: docs: swapfile and hibernation 2022-12-06 23:19:12 +01:00
Tree-checker.rst btrfs-progs: docs: fix sphinx code-block warnings 2024-01-10 22:49:06 +01:00
Trim.rst btrfs-progs: docs: updates 2023-08-28 17:24:25 +02:00
trouble-index.rst btrfs-progs: docs: clarify transid verify error recoverability 2024-11-26 21:05:34 +01:00
Volume-management.rst btrfs-progs: docs: add more chapters (part 3) 2021-12-17 15:35:10 +01:00
Zoned-mode.rst btrfs-progs: docs: add more chapters (part 3) 2021-12-17 15:35:10 +01:00