Manpage/btrfs-replace

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
(Update from git, v5.14.2)
(remove content)
 
Line 1: Line 1:
=btrfs-replace(8) manual page=
 
 
{{GeneratedManpage
 
{{GeneratedManpage
 
|name=btrfs-replace}}
 
|name=btrfs-replace}}
 
==NAME==
 
btrfs-replace - replace devices managed by btrfs with other device.
 
 
==SYNOPSIS==
 
 
<p><b>btrfs replace</b> <em>&lt;subcommand&gt;</em> <em>&lt;args&gt;</em></p>
 
==DESCRIPTION==
 
 
<p><b>btrfs replace</b> is used to replace btrfs managed devices with other device.</p>
 
==SUBCOMMAND==
 
 
<dl>
 
<dt>
 
<b>cancel</b> <em>&lt;mount_point&gt;</em>
 
<dd>
 
<p>
 
Cancel a running device replace operation.
 
</p>
 
 
<dt>
 
<b>start</b> [options] <em>&lt;srcdev&gt;</em>|<em>&lt;devid&gt;</em> <em>&lt;targetdev&gt;</em> <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Replace device of a btrfs filesystem.
 
</p>
 
<p>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 <em>&lt;srcdev&gt;</em> is a numerical value, it is assumed to be the device id
 
of the filesystem which is mounted at <em>&lt;path&gt;</em>, 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 <em>&lt;targetdev&gt;</em> needs to be same size or larger than the <em>&lt;srcdev&gt;</em>.</p>
 
<blockquote><b>Note:</b>
 
the filesystem has to be resized to fully take advantage of a
 
larger target device; this can be achieved with
 
<tt>btrfs filesystem resize &lt;devid&gt;:max /path</tt></blockquote>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
-r
 
<dd>
 
<p>
 
only read from <em>&lt;srcdev&gt;</em> if no other zero-defect mirror exists.
 
(enable this if your drive has lots of read errors, the access would be very
 
slow)
 
</p>
 
 
<dt>
 
-f
 
<dd>
 
<p>
 
force using and overwriting <em>&lt;targetdev&gt;</em> even if it looks like
 
it contains a valid btrfs filesystem.
 
</p>
 
<p>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 <em>&lt;targetdev&gt;</em>.</p>
 
 
<dt>
 
-B
 
<dd>
 
<p>
 
no background replace.
 
</p>
 
 
<dt>
 
--enqueue
 
<dd>
 
<p>
 
wait if there&#8217;s another exclusive operation running, otherwise continue
 
</p>
 
 
<dt>
 
-K|--nodiscard
 
<dd>
 
<p>
 
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 <em>discard</em> for that in [[Manpage/btrfs|btrfs(5)]].
 
</p>
 
 
</dl>
 
 
<dt>
 
<b>status</b> [-1] <em>&lt;mount_point&gt;</em>
 
<dd>
 
<p>
 
Print status and progress information of a running device replace operation.
 
</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
-1
 
<dd>
 
<p>
 
print once instead of print continuously until the replace
 
operation finishes (or is cancelled)
 
</p>
 
 
</dl>
 
 
</dl>
 
==EXAMPLES==
 
 
<table frame="void" width="100%" cellpadding="4">
 
<tr><td style="border-left: 2px solid silver;">
 
<p>Given the following filesystem mounted at <tt>/mnt/my-vault</tt></p>
 
<pre>Label: 'MyVault'  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</pre>
 
<p>In order to replace <em>/dev/sda</em> (<em>devid 1</em>) with a bigger drive located at
 
<em>/dev/sdc</em> you would run the following:</p>
 
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><!-- Generator: GNU source-highlight
 
by Lorenzo Bettini
 
http://www.lorenzobettini.it
 
http://www.gnu.org/software/src-highlite -->
 
<pre><tt>btrfs replace start <font color="#993399">1</font> /dev/sdc /mnt/my-vault<font color="#990000">/</font></tt></pre></td></tr></table>
 
<p>You can monitor progress via:</p>
 
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><!-- Generator: GNU source-highlight
 
by Lorenzo Bettini
 
http://www.lorenzobettini.it
 
http://www.gnu.org/software/src-highlite -->
 
<pre><tt>btrfs replace status /mnt/my-vault<font color="#990000">/</font></tt></pre></td></tr></table>
 
<p>After the replacement is complete, as per the docs at [[Manpage/btrfs-filesystem|btrfs-filesystem(8)]] in
 
order to use the entire storage space of the new drive you need to run:</p>
 
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><!-- Generator: GNU source-highlight
 
by Lorenzo Bettini
 
http://www.lorenzobettini.it
 
http://www.gnu.org/software/src-highlite -->
 
<pre><tt>btrfs filesystem resize <font color="#993399">1</font><font color="#990000">:</font>max /mnt/my-vault<font color="#990000">/</font></tt></pre></td></tr></table>
 
</td></tr></table>
 
<p><b>Example 1. </b>Replacing an online drive with a bigger one</p>
 
==EXIT STATUS==
 
 
<p><b>btrfs replace</b> returns a zero exit status if it succeeds. Non zero is
 
returned in case of failure.</p>
 
==AVAILABILITY==
 
 
<p><b>btrfs</b> is part of btrfs-progs.
 
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 
further details.</p>
 
==SEE ALSO==
 
 
<p>[[Manpage/mkfs.btrfs|mkfs.btrfs(8)]],
 
[[Manpage/btrfs-device|btrfs-device(8)]],
 
[[Manpage/btrfs-filesystem|btrfs-filesystem(8)]],</p>
 
[[Category:Manpage]]
 

Latest revision as of 12:32, 12 January 2022

Note: manual pages are located at read-the-docs site, please update your links.


Personal tools