]> git.hungrycats.org Git - btrfs-progs/commitdiff
btrfs-progs: replace: add --abort-on-uncorrectable topics/replace-abort-uncorrectable
authorZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Fri, 16 Oct 2026 17:03:37 +0000 (13:03 -0400)
committerZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Fri, 16 Oct 2026 17:03:37 +0000 (13:03 -0400)
Device replace counts blocks that cannot be read from any copy and goes
on without them.  That suits rescuing data from a failing device, but
not replacing a healthy one, where an unreadable block should stop the
replace before the source device is removed.

Add "btrfs replace start --abort-on-uncorrectable", which sets
BTRFS_IOCTL_DEV_REPLACE_ABORT_ON_UNCORRECTABLE in the high bits of
cont_reading_from_srcdev_mode.  Kernels that do not support it reject
the start with EINVAL (or EOPNOTSUPP for a flag they do not know), and
say so when the replace runs in the foreground; an aborted replace fails
with EIO.  dump-tree prints the flag in the dev_replace item's mode.

The kernel side is the patch "btrfs: dev-replace: optionally abort on
uncorrectable read errors" (kernel replace-fixes series), which defines
the flag and keeps it in the dev_replace item.

Assisted-by: Claude:claude-opus-5-5
Documentation/btrfs-replace.rst
cmds/replace.c
kernel-shared/print-tree.c
kernel-shared/uapi/btrfs.h
kernel-shared/uapi/btrfs_tree.h

index 2f2f5b76b4350b6479a43807e50ac6118dcc5ac1..e42ca53e0ac382d29965eea8d05cdc0821b03108 100644 (file)
@@ -55,6 +55,18 @@ start [options] <srcdev>|<devid> <targetdev> <path>
                 only read from *srcdev* if no other zero-defect mirror exists.
                 (enable this if your drive has lots of read errors, the access would be very
                 slow)
+        --abort-on-uncorrectable
+                cancel the replace if a block that is in use cannot be read from
+                any copy. The replace fails, the target device is released and
+                the source device stays in the filesystem. Without this option
+                such blocks are counted ("uncorr. read errs" in ``btrfs replace
+                status``) and skipped, which is what you want when rescuing
+                data from a failing device; with it, a replace of a healthy
+                device stops instead of completing with unreadable data.
+
+                The replace is canceled when the block group being copied is
+                finished, not immediately.  Kernels that do not support this
+                option refuse to start the replace.
         -f
                 force using and overwriting *targetdev* even if it looks like
                 it contains a valid btrfs filesystem.
index bd17ea94842b1bf4838302bdb297cc8a9f7acae3..846267235c48f08cde531d915e4e08f0d957f1cc 100644 (file)
@@ -107,6 +107,9 @@ static const char *const cmd_replace_start_usage[] = {
        OPTLINE("-r", "only read from <srcdev> if no other zero-defect mirror exists "
                "(enable this if your drive has lots of read errors, the access "
                "would be very slow)"),
+       OPTLINE("--abort-on-uncorrectable", "cancel the replace if a block "
+               "cannot be read from any copy, leaving <srcdev> in the "
+               "filesystem (by default such blocks are counted and skipped)"),
        OPTLINE("-f", "force using and overwriting <targetdev> even if it looks like "
                "containing a valid btrfs filesystem. A valid filesystem is "
                "assumed if a btrfs superblock is found which contains a "
@@ -140,13 +143,19 @@ static int cmd_replace_start(const struct cmd_struct *cmd,
        u64 dstdev_size;
        bool enqueue = false;
        bool discard = true;
+       bool abort_on_uncorrectable = false;
 
        optind = 0;
        while (1) {
                int c;
-               enum { GETOPT_VAL_ENQUEUE = GETOPT_VAL_FIRST };
+               enum {
+                       GETOPT_VAL_ENQUEUE = GETOPT_VAL_FIRST,
+                       GETOPT_VAL_ABORT_ON_UNCORRECTABLE,
+               };
                static const struct option long_options[] = {
                        { "enqueue", no_argument, NULL, GETOPT_VAL_ENQUEUE},
+                       { "abort-on-uncorrectable", no_argument, NULL,
+                         GETOPT_VAL_ABORT_ON_UNCORRECTABLE },
                        { "nodiscard", no_argument, NULL, 'K' },
                        { NULL, 0, NULL, 0}
                };
@@ -170,6 +179,9 @@ static int cmd_replace_start(const struct cmd_struct *cmd,
                case GETOPT_VAL_ENQUEUE:
                        enqueue = true;
                        break;
+               case GETOPT_VAL_ABORT_ON_UNCORRECTABLE:
+                       abort_on_uncorrectable = true;
+                       break;
                default:
                        usage_unknown_option(cmd, argv);
                }
@@ -179,6 +191,9 @@ static int cmd_replace_start(const struct cmd_struct *cmd,
                avoid_reading_from_srcdev ?
                 BTRFS_IOCTL_DEV_REPLACE_CONT_READING_FROM_SRCDEV_MODE_AVOID :
                 BTRFS_IOCTL_DEV_REPLACE_CONT_READING_FROM_SRCDEV_MODE_ALWAYS;
+       if (abort_on_uncorrectable)
+               start_args.start.cont_reading_from_srcdev_mode |=
+                       BTRFS_IOCTL_DEV_REPLACE_ABORT_ON_UNCORRECTABLE;
        if (check_argc_exact(argc - optind, 3))
                return 1;
        path = argv[optind + 2];
@@ -335,8 +350,15 @@ static int cmd_replace_start(const struct cmd_struct *cmd,
                                error("ioctl(DEV_REPLACE_START) failed on \"%s\": %m, %s",
                                      path, replace_dev_result2string(start_args.result));
 
-                       if (errno == EOPNOTSUPP)
+                       if (abort_on_uncorrectable &&
+                           (errno == EINVAL || errno == EOPNOTSUPP))
+                               warning("this kernel may not support --abort-on-uncorrectable");
+                       else if (errno == EOPNOTSUPP)
                                warning("device replace of RAID5/6 not supported with this kernel");
+                       if (errno == EIO)
+                               warning("the replace was canceled after a write error to the target%s, see 'btrfs replace status' and the kernel log",
+                                       abort_on_uncorrectable ?
+                                       " or an uncorrectable read error" : "");
 
                        goto leave_with_error;
                }
index 4b3ad093f278866c059d54c1bd193190008246ff..fb11c9ad3cfc864d987a45bc3af150c4f0b52115 100644 (file)
@@ -1432,13 +1432,27 @@ static void print_header_info(struct extent_buffer *eb, unsigned int mode)
 
 static void replace_mode_to_str(u64 flags, char *ret)
 {
+       const u64 mode = flags & BTRFS_DEV_REPLACE_ITEM_MODE_MASK;
+       size_t len;
+
        ret[0] = 0;
-       switch(flags) {
+       switch(mode) {
        CASE_DEV_REPLACE_MODE_ENTRY(ret, ALWAYS);
        CASE_DEV_REPLACE_MODE_ENTRY(ret, AVOID);
        default:
-               snprintf(ret, DEV_REPLACE_STRING_LEN, "unknown(%llu)", flags);
+               snprintf(ret, DEV_REPLACE_STRING_LEN, "unknown(%llu)", mode);
+       }
+       flags &= ~BTRFS_DEV_REPLACE_ITEM_MODE_MASK;
+       len = strlen(ret);
+       if (flags & BTRFS_DEV_REPLACE_ITEM_ABORT_ON_UNCORRECTABLE) {
+               snprintf(ret + len, DEV_REPLACE_STRING_LEN - len,
+                        "|ABORT_ON_UNCORRECTABLE");
+               len = strlen(ret);
+               flags &= ~BTRFS_DEV_REPLACE_ITEM_ABORT_ON_UNCORRECTABLE;
        }
+       if (flags)
+               snprintf(ret + len, DEV_REPLACE_STRING_LEN - len,
+                        "|unknown(0x%llx)", flags);
 }
 #undef DEV_REPLACE_MODE_ENTRY
 
index 7144f3ba07b95fb9fb4b63feae33b173a2293476..21957c198a6f8100b34187cf40eefee5c3c4a544 100644 (file)
@@ -220,6 +220,19 @@ _static_assert(sizeof(struct btrfs_ioctl_scrub_args) == 1024);
 
 #define BTRFS_IOCTL_DEV_REPLACE_CONT_READING_FROM_SRCDEV_MODE_ALWAYS   0
 #define BTRFS_IOCTL_DEV_REPLACE_CONT_READING_FROM_SRCDEV_MODE_AVOID    1
+/*
+ * The low 32 bits of cont_reading_from_srcdev_mode hold one of the modes
+ * above, the high 32 bits hold flags.  Kernels that do not know a flag
+ * fail the start with -EINVAL (before this flag existed) or -EOPNOTSUPP.
+ */
+#define BTRFS_IOCTL_DEV_REPLACE_MODE_MASK              0xffffffffULL
+/*
+ * Cancel the replace, with -EIO, when a sector that is in use cannot be
+ * read from any copy.  Without it such sectors are counted and skipped.
+ */
+#define BTRFS_IOCTL_DEV_REPLACE_ABORT_ON_UNCORRECTABLE (1ULL << 32)
+#define BTRFS_IOCTL_DEV_REPLACE_SUPPORTED_FLAGS                \
+       (BTRFS_IOCTL_DEV_REPLACE_ABORT_ON_UNCORRECTABLE)
 struct btrfs_ioctl_dev_replace_start_params {
        __u64 srcdevid; /* in, if 0, use srcdev_name instead */
        __u64 cont_reading_from_srcdev_mode;    /* in, see #define
index b4532237d996cfc81772576e23b09f148f652871..0360c0e25270bf4cf47948fa63afead0a3bade70 100644 (file)
@@ -1149,6 +1149,13 @@ struct btrfs_dev_stats_item {
 
 #define BTRFS_DEV_REPLACE_ITEM_CONT_READING_FROM_SRCDEV_MODE_ALWAYS    0
 #define BTRFS_DEV_REPLACE_ITEM_CONT_READING_FROM_SRCDEV_MODE_AVOID     1
+/*
+ * Flags in the high 32 bits of cont_reading_from_srcdev_mode, same values as
+ * the BTRFS_IOCTL_DEV_REPLACE_* flags.  Older kernels ignore them and read
+ * the mode as BTRFS_DEV_REPLACE_ITEM_CONT_READING_FROM_SRCDEV_MODE_ALWAYS.
+ */
+#define BTRFS_DEV_REPLACE_ITEM_MODE_MASK                       0xffffffffULL
+#define BTRFS_DEV_REPLACE_ITEM_ABORT_ON_UNCORRECTABLE          (1ULL << 32)
 
 struct btrfs_dev_replace_item {
        /*