| 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-IMAGE" "8" "May 10, 2026" "7.0" "BTRFS" |
| 32 |
.SH NAME |
| 33 |
btrfs-image \- create/restore an image of the filesystem |
| 34 |
.SH SYNOPSIS |
| 35 |
.sp |
| 36 |
\fBbtrfs\-image\fP [options] <source> <target> |
| 37 |
.SH DESCRIPTION |
| 38 |
.sp |
| 39 |
\fBbtrfs\-image\fP is used to create an image of a btrfs filesystem. |
| 40 |
All data will be zeroed, but metadata and the like is preserved. |
| 41 |
Mainly used for debugging purposes. |
| 42 |
.sp |
| 43 |
In the dump mode, source is the btrfs device/file and target is the output |
| 44 |
file (use \fI\-\fP for stdout). |
| 45 |
.sp |
| 46 |
In the restore mode (option \fI\-r\fP), source is the dumped image and target is the btrfs device/file. |
| 47 |
.SH OPTIONS |
| 48 |
.INDENT 0.0 |
| 49 |
.TP |
| 50 |
.B \-r |
| 51 |
Restore metadump image. By default, this fixes super\(aqs chunk tree, by |
| 52 |
using 1 stripe pointing to primary device, so that file system can be |
| 53 |
restored by running tree log reply if possible. To restore without |
| 54 |
changing number of stripes in chunk tree check \fI\-o\fP option. |
| 55 |
.TP |
| 56 |
.BI \-c \ <value> |
| 57 |
Compression level (0 ~ 9). |
| 58 |
.TP |
| 59 |
.BI \-t \ <value> |
| 60 |
Number of threads (1 ~ 32) to be used to process the image dump or restore. |
| 61 |
.TP |
| 62 |
.B \-o |
| 63 |
Use the old restore method, this does not fixup the chunk tree so the restored |
| 64 |
file system will not be able to be mounted. |
| 65 |
.TP |
| 66 |
.B \-s |
| 67 |
Sanitize the file names when generating the image. Not recommended as |
| 68 |
this would introduce new file name hash mismatches, thus if your |
| 69 |
problem involves subvolume tress, it can even mask existing problems. |
| 70 |
Furthermore kernels can not do proper path resolution due to the |
| 71 |
introduced hash mismatches. |
| 72 |
.sp |
| 73 |
One \fI\-s\fP means just generate random garbage, which means that the |
| 74 |
directory hash won\(aqt match its file names. Using two \fI\-s\fP will |
| 75 |
calculate a collision for the file name so that the hashes match, and |
| 76 |
if it can\(aqt calculate a collision then it will just generate garbage. |
| 77 |
The collision calculator is very time and CPU intensive. |
| 78 |
.TP |
| 79 |
.B \-w |
| 80 |
Walk all the trees manually and copy any blocks that are referenced. Use this |
| 81 |
option if your extent tree is corrupted to make sure that all of the metadata is |
| 82 |
captured. |
| 83 |
.TP |
| 84 |
.B \-m |
| 85 |
Restore for multiple devices, more than 1 device should be provided. |
| 86 |
.TP |
| 87 |
.B \-\-version |
| 88 |
Print the \fBbtrfs\-image\fP version, builtin features and exit. |
| 89 |
.UNINDENT |
| 90 |
.SH EXIT STATUS |
| 91 |
.sp |
| 92 |
\fBbtrfs\-image\fP will return 0 if no error happened. |
| 93 |
If any problems happened, 1 will be returned. |
| 94 |
.SH SEE ALSO |
| 95 |
.sp |
| 96 |
mkfs.btrfs(8) \%<> |
| 97 |
.\" End of generated man page. |