btrfs-replace(8)

1BTRFS-REPLACE(8)                     BTRFS                    BTRFS-REPLACE(8)
2
3
4

NAME

6       btrfs-replace - replace devices managed by btrfs with other device
7

SYNOPSIS

9       btrfs replace <subcommand> <args>
10

DESCRIPTION

12       btrfs  replace  is used to replace btrfs managed devices with other de‐
13       vice.
14

SUBCOMMAND

16       cancel <mount_point>
17              Cancel a running device replace operation.
18
19       start [options] <srcdev>|<devid> <targetdev> <path>
20              Replace device of a btrfs filesystem.
21
22              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
34              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
39              Options
40
41              -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
45              -f     force using and overwriting targetdev even  if  it  looks
46                     like it contains a valid btrfs filesystem.
47
48                     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
53              -B     no background replace.
54
55              --enqueue
56                     wait if there's another exclusive operation running, oth‐
57                     erwise continue
58
59              -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
65       status [-1] <mount_point>
66              Print status and progress information of a  running  device  re‐
67              place operation.
68
69              Options
70
71              -1     print  once  instead  of print continuously until the re‐
72                     place operation finishes (or is cancelled)
73

EXAMPLES

75   Replacing an online drive with a bigger one
76       Given the following filesystem mounted at /mnt/my-vault
77
78          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
83       In order to replace /dev/sda (devid 1) with a bigger drive  located  at
84       /dev/sdc you would run the following:
85
86          btrfs replace start 1 /dev/sdc /mnt/my-vault/
87
88       You can monitor progress via:
89
90          btrfs replace status /mnt/my-vault/
91
92       After   the   replacement   is   complete,   as   per   the   docs   at
93       btrfs-filesystem(8) in order to use the entire storage space of the new
94       drive you need to run:
95
96          btrfs filesystem resize 1:max /mnt/my-vault/
97

EXIT STATUS

99       btrfs  replace  returns  a zero exit status if it succeeds. Non zero is
100       returned in case of failure.
101

AVAILABILITY

103       btrfs is part of btrfs-progs.  Please refer  to  the  documentation  at
104       https://btrfs.readthedocs.io.
105