noble (8) btrfs-replace.8.gz

NAME

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

SYNOPSIS

       btrfs replace <subcommand> <args>

DESCRIPTION

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

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)

EXAMPLES

   Replacing an online drive with a bigger one
       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:

          btrfs replace start 1 /dev/sdc /mnt/my-vault/

       You can monitor progress via:

          btrfs replace status /mnt/my-vault/

       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:

          btrfs filesystem resize 1:max /mnt/my-vault/

EXIT STATUS

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

AVAILABILITY

       btrfs is part of btrfs-progs.  Please refer to the documentation at https://btrfs.readthedocs.io.

SEE ALSO

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