How to replace a device in BTRFS RAID-1 filesystem?

Currently, btrfs does not support n-way mirrors.

Btrfs does have a special replace subcommand:

btrfs replace start /dev/left /dev/new_device /mnt/foo

Reading between the lines of the btrfs-replace man page, this command should be able to use both existing legs - e.g. for situations where both legs have read errors - but both error sets are disjoint.

The btrfs replace command is executed in the background - you can check its status via the status subcommand, e.g.:

btrfs replace status /mnt/foo
45.4% done, 0 write errs, 0 uncorr. read errs

Alternatively, one can also add a device to raid-1 filesytem and then delete an existing leg:

btrfs dev add /dev/mapper/new_device /mnt/foo
btrfs dev delete /dev/mapper/right  /mnt/foo

The add should return fast, since it justs adds the device (issue a btrfs fi show to confirm).

The following delete should trigger a balancing between the remaining devices such that each extend is available on each remaining device. Thus, the command is potentially very long running. This method also works to deal with the situation described in the question.

In comparison with btrfs replace the add/delete cycle spams the syslog with low-level info messages. Also, it takes much longer to finish (e.g. 2-3 times longer, in my test system with 3 TB SATA drives, 80 % FS usage).

Finally, after the actual replacement, if the newer devices are larger than the original devices, you will need to issue a btrfs fi resize on each device to utilize the entire disk space available. For the replace example at the top, this looks like something like:

btrfs fi resize <devid>:max /mnt/foo

where devid stands for the device id which btrfs fi show returns.