{ "content": [ { "type": "text", "text": "# btrfs-replace (man)\n\n## NAME\n\nbtrfs-replace - replace devices managed by btrfs with other device.\n\n## SYNOPSIS\n\nbtrfs replace \n\n## DESCRIPTION\n\nbtrfs replace is used to replace btrfs managed devices with other device.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **SUBCOMMAND**\n- **EXAMPLES** (1 subsections)\n- **EXIT STATUS**\n- **AVAILABILITY**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "btrfs-replace", "section": "", "mode": "man", "summary": "btrfs-replace - replace devices managed by btrfs with other device.", "synopsis": "btrfs replace ", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "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:", "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/" ], "see_also": [ { "name": "mkfs.btrfs", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/mkfs.btrfs/8/json" }, { "name": "btrfs-device", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/btrfs-device/8/json" }, { "name": "btrfs-filesystem", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/btrfs-filesystem/8/json" }, { "name": "BTRFS-REPLACE", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/BTRFS-REPLACE/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 2, "subsections": [] }, { "name": "SUBCOMMAND", "lines": 52, "subsections": [] }, { "name": "EXAMPLES", "lines": 1, "subsections": [ { "name": "Example 1. Replacing an online drive with a bigger one", "lines": 21 } ] }, { "name": "EXIT STATUS", "lines": 3, "subsections": [] }, { "name": "AVAILABILITY", "lines": 3, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "btrfs-replace - replace devices managed by btrfs with other device.\n", "subsections": [] }, "SYNOPSIS": { "content": "btrfs replace \n", "subsections": [] }, "DESCRIPTION": { "content": "btrfs replace is used to replace btrfs managed devices with other device.\n", "subsections": [] }, "SUBCOMMAND": { "content": "cancel \nCancel a running device replace operation.\n\nstart [options] | \nReplace device of a btrfs filesystem.\n\nOn a live filesystem, duplicate the data to the target device which is currently stored\non the source device. If the source device is not available anymore, or if the -r option\nis set, the data is built only using the RAID redundancy mechanisms. After completion of\nthe operation, the source device is removed from the filesystem. If the is a\nnumerical value, it is assumed to be the device id of the filesystem which is mounted at\n, otherwise it is the path to the source device. If the source device is\ndisconnected, from the system, you have to use the devid parameter format. The\n needs to be same size or larger than the .\n\nNote\nthe filesystem has to be resized to fully take advantage of a larger target device;\nthis can be achieved with btrfs filesystem resize :max /path\nOptions\n\n-r\nonly read from if no other zero-defect mirror exists. (enable this if your\ndrive has lots of read errors, the access would be very slow)\n\n-f\nforce using and overwriting even if it looks like it contains a valid\nbtrfs filesystem.\n\nA valid filesystem is assumed if a btrfs superblock is found which contains a correct\nchecksum. Devices that are currently mounted are never allowed to be used as the\n.\n\n-B\nno background replace.\n\n--enqueue\nwait if there’s another exclusive operation running, otherwise continue\n\n-K|--nodiscard\nDo not perform whole device TRIM operation on devices that are capable of that. This\ndoes not affect discard/trim operation when the filesystem is mounted. Please see the\nmount option discard for that in btrfs(5).\n\nstatus [-1] \nPrint status and progress information of a running device replace operation.\n\nOptions\n\n-1\nprint once instead of print continuously until the replace operation finishes (or is\ncancelled)\n", "subsections": [] }, "EXAMPLES": { "content": "", "subsections": [ { "name": "Example 1. Replacing an online drive with a bigger one", "content": "Given the following filesystem mounted at /mnt/my-vault\n\nLabel: 'MyVault' uuid: ae20903e-b72d-49ba-b944-901fc6d888a1\nTotal devices 2 FS bytes used 1TiB\ndevid 1 size 1TiB used 500.00GiB path /dev/sda\ndevid 2 size 1TiB used 500.00GiB path /dev/sdb\n\nIn order to replace /dev/sda (devid 1) with a bigger drive located at /dev/sdc you would run\nthe following:\n\nbtrfs replace start 1 /dev/sdc /mnt/my-vault/\n\nYou can monitor progress via:\n\nbtrfs replace status /mnt/my-vault/\n\nAfter the replacement is complete, as per the docs at btrfs-filesystem(8) in order to use the\nentire storage space of the new drive you need to run:\n\nbtrfs filesystem resize 1:max /mnt/my-vault/\n" } ] }, "EXIT STATUS": { "content": "btrfs replace returns a zero exit status if it succeeds. Non zero is returned in case of\nfailure.\n", "subsections": [] }, "AVAILABILITY": { "content": "btrfs is part of btrfs-progs. Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for\nfurther details.\n", "subsections": [] }, "SEE ALSO": { "content": "mkfs.btrfs(8), btrfs-device(8), btrfs-filesystem(8),\n\n\n\nBtrfs v5.16.2 02/16/2022 BTRFS-REPLACE(8)", "subsections": [] } } } }