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 [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 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           --enqueue
57               wait if there’s another exclusive operation running, otherwise
58               continue
59
60       status [-1] <mount_point>
61           Print status and progress information of a running device replace
62           operation.
63
64           Options
65
66           -1
67               print once instead of print continuously until the replace
68               operation finishes (or is cancelled)
69

EXAMPLES

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

EXIT STATUS

96       btrfs replace returns a zero exit status if it succeeds. Non zero is
97       returned in case of failure.
98

AVAILABILITY

100       btrfs is part of btrfs-progs. Please refer to the btrfs wiki
101       http://btrfs.wiki.kernel.org for further details.
102