Debian Codegraph @

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

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