1BTRFS-REPLACE(8) BTRFS BTRFS-REPLACE(8)
2
6 btrfs-replace - replace devices managed by btrfs with other device
7
9 btrfs replace <subcommand> <args>
10
12 btrfs replace is used to replace btrfs managed devices with other de‐
13 vice.
14
16 cancel <mount_point>
17 Cancel a running device replace operation.
18 start [options] <srcdev>|<devid> <targetdev> <path>
20 Replace device of a btrfs filesystem.
21 On a live filesystem, duplicate the data to the target device
23 which is currently stored on the source device. If the source
24 device is not available anymore, or if the -r option is set, the
25 data is built only using the RAID redundancy mechanisms. After
26 completion of the operation, the source device is removed from
27 the filesystem. If the srcdev is a numerical value, it is as‐
28 sumed to be the device id of the filesystem which is mounted at
29 path, otherwise it is the path to the source device. If the
30 source device is disconnected, from the system, you have to use
31 the devid parameter format. The targetdev needs to be same size
32 or larger than the srcdev.
33 NOTE:
35 The filesystem has to be resized to fully take advantage of a
36 larger target device; this can be achieved with btrfs
37 filesystem resize <devid>:max /path
38 Options
40 -r only read from srcdev if no other zero-defect mirror ex‐
42 ists. (enable this if your drive has lots of read er‐
43 rors, the access would be very slow)
44 -f force using and overwriting targetdev even if it looks
46 like it contains a valid btrfs filesystem.
47 A valid filesystem is assumed if a btrfs superblock is
49 found which contains a correct checksum. Devices that are
50 currently mounted are never allowed to be used as the
51 targetdev.
52 -B no background replace.
54 --enqueue
56 wait if there's another exclusive operation running, oth‐
57 erwise continue
58 -K|--nodiscard
60 Do not perform whole device TRIM operation on devices
61 that are capable of that. This does not affect dis‐
62 card/trim operation when the filesystem is mounted.
63 Please see the mount option discard for that in btrfs(5).
64 status [-1] <mount_point>
66 Print status and progress information of a running device re‐
67 place operation.
68 Options
70 -1 print once instead of print continuously until the re‐
72 place operation finishes (or is cancelled)
73
75 Replacing an online drive with a bigger one
76 Given the following filesystem mounted at /mnt/my-vault
77 Label: 'MyVault' uuid: ae20903e-b72d-49ba-b944-901fc6d888a1
79 Total devices 2 FS bytes used 1TiB
80 devid 1 size 1TiB used 500.00GiB path /dev/sda
81 devid 2 size 1TiB used 500.00GiB path /dev/sdb
82 In order to replace /dev/sda (devid 1) with a bigger drive located at
84 /dev/sdc you would run the following:
85 btrfs replace start 1 /dev/sdc /mnt/my-vault/
87 You can monitor progress via:
89 btrfs replace status /mnt/my-vault/
91 After the replacement is complete, as per the docs at btrfs-filesys‐
93 tem(8) in order to use the entire storage space of the new drive you
94 need to run:
95 btrfs filesystem resize 1:max /mnt/my-vault/
97
99 btrfs replace returns a zero exit status if it succeeds. Non zero is
100 returned in case of failure.
101
103 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
104 http://btrfs.wiki.kernel.org for further details.
105
107 mkfs.btrfs(8), btrfs-device(8), btrfs-filesystem(8),
108
110 2022
1115.18 May 25, 2022 BTRFS-REPLACE(8)