| 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. |