Debian Codegraph @

upstream/debian-trixie/man8/btrfs-replace.8

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