Manpage/btrfs-replace

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
(git 5.4)
(Update from git, v5.14.2)
 
Line 23: Line 23:
  
 
<dt>
 
<dt>
<b>start</b> [-Bfr] <em>&lt;srcdev&gt;</em>|<em>&lt;devid&gt;</em> <em>&lt;targetdev&gt;</em> <em>&lt;path&gt;</em>
+
<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>
 
<dd>
 
<p>
 
<p>
Line 70: Line 70:
 
<p>
 
<p>
 
no background replace.
 
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>
 
</p>
  
Line 95: Line 111:
 
==EXAMPLES==
 
==EXAMPLES==
  
===Replacing an online drive with a bigger one===
+
<table frame="void" width="100%" cellpadding="4">
 
+
<tr><td style="border-left: 2px solid silver;">
<p>Given the filesystem:</p>
+
<p>Given the following filesystem mounted at <tt>/mnt/my-vault</tt></p>
 
<pre>Label: 'MyVault'  uuid: ae20903e-b72d-49ba-b944-901fc6d888a1
 
<pre>Label: 'MyVault'  uuid: ae20903e-b72d-49ba-b944-901fc6d888a1
 
         Total devices 2 FS bytes used 1TiB
 
         Total devices 2 FS bytes used 1TiB
Line 109: Line 125:
 
http://www.gnu.org/software/src-highlite -->
 
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>
 
<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 by:</p>
+
<p>You can monitor progress via:</p>
 
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><!-- Generator: GNU source-highlight
 
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><!-- Generator: GNU source-highlight
 
by Lorenzo Bettini
 
by Lorenzo Bettini
Line 122: Line 138:
 
http://www.gnu.org/software/src-highlite -->
 
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>
 
<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==
 
==EXIT STATUS==
  

Latest revision as of 17:11, 19 October 2021

Contents

[edit] btrfs-replace(8) manual page

Warning: this page is automatically generated from git, all edits will be lost. Current git version.


[edit] NAME

btrfs-replace - replace devices managed by btrfs with other device.

[edit] SYNOPSIS

btrfs replace <subcommand> <args>

[edit] DESCRIPTION

btrfs replace is used to replace btrfs managed devices with other device.

[edit] SUBCOMMAND

cancel <mount_point>

Cancel a running device replace operation.

start [options] <srcdev>|<devid> <targetdev> <path>

Replace device of a btrfs filesystem.

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 <srcdev> is a numerical value, it is assumed to be the device id of the filesystem which is mounted at <path>, 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 <targetdev> needs to be same size or larger than the <srcdev>.

Note: the filesystem has to be resized to fully take advantage of a larger target device; this can be achieved with btrfs filesystem resize <devid>:max /path

Options

-r

only read from <srcdev> if no other zero-defect mirror exists. (enable this if your drive has lots of read errors, the access would be very slow)

-f

force using and overwriting <targetdev> even if it looks like it contains a valid btrfs filesystem.

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

-B

no background replace.

--enqueue

wait if there’s another exclusive operation running, otherwise continue

-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 discard for that in btrfs(5).

status [-1] <mount_point>

Print status and progress information of a running device replace operation.

Options

-1

print once instead of print continuously until the replace operation finishes (or is cancelled)

[edit] EXAMPLES

Given the following filesystem mounted at /mnt/my-vault

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

In order to replace /dev/sda (devid 1) with a bigger drive located at /dev/sdc you would run the following:

<tt>btrfs replace start <font color="#993399">1</font> /dev/sdc /mnt/my-vault<font color="#990000">/</font></tt>

You can monitor progress via:

<tt>btrfs replace status /mnt/my-vault<font color="#990000">/</font></tt>

After the replacement is complete, as per the docs at btrfs-filesystem(8) in order to use the entire storage space of the new drive you need to run:

<tt>btrfs filesystem resize <font color="#993399">1</font><font color="#990000">:</font>max /mnt/my-vault<font color="#990000">/</font></tt>

Example 1. Replacing an online drive with a bigger one

[edit] EXIT STATUS

btrfs replace returns a zero exit status if it succeeds. Non zero is returned in case of failure.

[edit] AVAILABILITY

btrfs is part of btrfs-progs. Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for further details.

[edit] SEE ALSO

mkfs.btrfs(8), btrfs-device(8), btrfs-filesystem(8),

Personal tools