btrfs-replace(8)

1BTRFS-REPLACE(8)                 Btrfs Manual                 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
13       device.
14

SUBCOMMAND

16       cancel <mount_point>
17           Cancel a running device replace operation.
18
19       start [-Bfr] <srcdev>|<devid> <targetdev> <path>
20           Replace device of a btrfs filesystem.
21
22           On a live filesystem, duplicate the data to the target device which
23           is currently stored on the source device. If the source device is
24           not available anymore, or if the -r option is set, the data is
25           built only using the RAID redundancy mechanisms. After completion
26           of the operation, the source device is removed from the filesystem.
27           If the <srcdev> is a numerical value, it is assumed to be the
28           device id of the filesystem which is mounted at <path>, otherwise
29           it is the path to the source device. If the source device is
30           disconnected, from the system, you have to use the devid parameter
31           format. The <targetdev> needs to be same size or larger than the
32           <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           Options
39
40           -r
41               only read from <srcdev> if no other zero-defect mirror exists.
42               (enable this if your drive has lots of read errors, the access
43               would be very slow)
44
45           -f
46               force using and overwriting <targetdev> even if it looks like
47               it contains a valid btrfs filesystem.
48
49               A valid filesystem is assumed if a btrfs superblock is found
50               which contains a correct checksum. Devices that are currently
51               mounted are never allowed to be used as the <targetdev>.
52
53           -B
54               no background replace.
55
56       status [-1] <mount_point>
57           Print status and progress information of a running device replace
58           operation.
59
60           Options
61
62           -1
63               print once instead of print continuously until the replace
64               operation finishes (or is cancelled)
65

EXAMPLES

67   Replacing an online drive with a bigger one
68       Given the filesystem:
69
70           Label: 'MyVault'  uuid: ae20903e-b72d-49ba-b944-901fc6d888a1
71                   Total devices 2 FS bytes used 1TiB
72                   devid    1 size 1TiB used 500.00GiB path /dev/sda
73                   devid    2 size 1TiB used 500.00GiB path /dev/sdb
74
75       In order to replace /dev/sda (devid 1) with a bigger drive located at
76       /dev/sdc you would run the following:
77
78           btrfs replace start 1 /dev/sdc /mnt/my-vault/
79
80       You can monitor progress by:
81
82           btrfs replace status /mnt/my-vault/
83
84       After the replacement is complete, as per the docs at
85       btrfs-filesystem(8) in order to use the entire storage space of the new
86       drive you need to run:
87
88           btrfs filesystem resize 1:max /mnt/my-vault/
89

EXIT STATUS

91       btrfs replace returns a zero exit status if it succeeds. Non zero is
92       returned in case of failure.
93

AVAILABILITY

95       btrfs is part of btrfs-progs. Please refer to the btrfs wiki
96       http://btrfs.wiki.kernel.org for further details.
97