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           -K|--nodiscard
61               Do not perform whole device TRIM operation on devices that are
62               capable of that. This does not affect discard/trim operation
63               when the filesystem is mounted. Please see the mount option
64               discard for that in btrfs(5).
65
66       status [-1] <mount_point>
67           Print status and progress information of a running device replace
68           operation.
69
70           Options
71
72           -1
73               print once instead of print continuously until the replace
74               operation finishes (or is cancelled)
75

EXAMPLES

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

EXIT STATUS

102       btrfs replace returns a zero exit status if it succeeds. Non zero is
103       returned in case of failure.
104

AVAILABILITY

106       btrfs is part of btrfs-progs. Please refer to the btrfs wiki
107       http://btrfs.wiki.kernel.org for further details.
108