1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BTRFS-REPLACE" "8" "Feb 28, 2024" "6.6.3" "BTRFS"
.SH NAME
btrfs-replace \- replace devices managed by btrfs with other device
.SH SYNOPSIS
.sp
\fBbtrfs replace\fP <subcommand> <args>
.SH DESCRIPTION
.sp
\fBbtrfs replace\fP is used to replace btrfs managed devices with other device.
.SH SUBCOMMAND
.INDENT 0.0
.TP
.B cancel <mount_point>
Cancel a running device replace operation.
.TP
.B start [options] <srcdev>|<devid> <targetdev> <path>
Replace device of a btrfs filesystem.
.sp
On a live filesystem, duplicate the data to the target device which
is currently stored on the source device.
If the source device is not available anymore, or if the \-r option is set,
the data is built only using the RAID redundancy mechanisms.
After completion of the operation, the source device is removed from the
filesystem.
If the \fIsrcdev\fP is a numerical value, it is assumed to be the device id
of the filesystem which is mounted at \fIpath\fP, otherwise it is
the path to the source device. If the source device is disconnected,
from the system, you have to use the devid parameter format.
The \fItargetdev\fP needs to be same size or larger than the \fIsrcdev\fP\&.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The filesystem has to be resized to fully take advantage of a
larger target device; this can be achieved with
\fBbtrfs filesystem resize <devid>:max /path\fP
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.INDENT 7.0
.TP
.B \-r
only read from \fIsrcdev\fP if no other zero\-defect mirror exists.
(enable this if your drive has lots of read errors, the access would be very
slow)
.TP
.B \-f
force using and overwriting \fItargetdev\fP even if it looks like
it contains a valid btrfs filesystem.
.sp
A valid filesystem is assumed if a btrfs superblock is found which contains a
correct checksum. Devices that are currently mounted are
never allowed to be used as the \fItargetdev\fP\&.
.TP
.B \-B
no background replace.
.TP
.B \-\-enqueue
wait if there\(aqs another exclusive operation running, otherwise continue
.UNINDENT
.INDENT 7.0
.TP
.B \-K|\-\-nodiscard
Do not perform whole device TRIM operation on devices that are capable of that.
This does not affect discard/trim operation when the filesystem is mounted.
Please see the mount option \fIdiscard\fP for that in \fI\%btrfs(5)\fP\&.
.UNINDENT
.TP
.B status [\-1] <mount_point>
Print status and progress information of a running device replace operation.
.sp
\fBOptions\fP
.INDENT 7.0
.TP
.B \-1
print once instead of print continuously until the replace
operation finishes (or is cancelled)
.UNINDENT
.UNINDENT
.SH EXAMPLES
.SS Replacing an online drive with a bigger one
.sp
Given the following filesystem mounted at \fB/mnt/my\-vault\fP
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Label: \(aqMyVault\(aq uuid: ae20903e\-b72d\-49ba\-b944\-901fc6d888a1
Total devices 2 FS bytes used 1TiB
devid 1 size 1TiB used 500.00GiB path /dev/sda
devid 2 size 1TiB used 500.00GiB path /dev/sdb
.EE
.UNINDENT
.UNINDENT
.sp
In order to replace \fB/dev/sda\fP (\fIdevid 1\fP) with a bigger drive located at
\fB/dev/sdc\fP you would run the following:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
btrfs replace start 1 /dev/sdc /mnt/my\-vault/
.EE
.UNINDENT
.UNINDENT
.sp
You can monitor progress via:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
btrfs replace status /mnt/my\-vault/
.EE
.UNINDENT
.UNINDENT
.sp
After the replacement is complete, as per the docs at \fI\%btrfs\-filesystem(8)\fP in
order to use the entire storage space of the new drive you need to run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
btrfs filesystem resize 1:max /mnt/my\-vault/
.EE
.UNINDENT
.UNINDENT
.SH EXIT STATUS
.sp
\fBbtrfs replace\fP returns a zero exit status if it succeeds. Non zero is
returned in case of failure.
.SH AVAILABILITY
.sp
\fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
\fI\%https://btrfs.readthedocs.io\fP\&.
.SH SEE ALSO
.sp
\fI\%btrfs\-device(8)\fP,
\fI\%btrfs\-filesystem(8)\fP,
\fI\%mkfs.btrfs(8)\fP
.\" Generated by docutils manpage writer.
.
|
