path: root/Documentation/btrfs-restore.asciidoc
diff options
Diffstat (limited to 'Documentation/btrfs-restore.asciidoc')
1 files changed, 108 insertions, 0 deletions
diff --git a/Documentation/btrfs-restore.asciidoc b/Documentation/btrfs-restore.asciidoc
new file mode 100644
index 00000000..41e90e2f
--- /dev/null
+++ b/Documentation/btrfs-restore.asciidoc
@@ -0,0 +1,108 @@
+btrfs-restore - try to restore files from a damaged btrfs filesystem image
+*btrfs restore* [options] <device> <path> | -l <device>
+*btrfs restore* is used to try to salvage files from a damaged filesystem and
+restore them into <path> or just list the subvolume tree roots. The filesystem
+image is not modified.
+If the filesystem is damaged and cannot be repaired by the other tools
+(`btrfs-check`(8) or `btrfs-rescue`(8)), *btrfs restore* could be used to
+retrieve file data, as far as the metadata are readable. The checks done by
+restore are less strict and the process is usually able to get far enough to
+retrieve data from the whole filesystem. This comes at a cost that some data
+might be incomplete or from older versions if they're available.
+There are several options to attempt restoration of various file metadata type.
+You can try a dry run first to see how well the process goes and use further
+options to extend the set of restored metadata.
+For images with damaged tree structures, there are several options to point the
+process to some spare copy.
+NOTE: It is recommended to read the following btrfs wiki page if your data is
+not salvaged with default option: +
+get also snapshots that are skippped by default
+get extended attributes
+restore owner, mode and times for files and directories
+restore symbolic links as well as normal files
+be verbose and print what is being restored
+ignore errors during restoration and continue
+overwrite directories/files in <path>, eg. for repeated runs
+-t <bytenr>::
+use <bytenr> to read the root tree
+-f <bytenr>::
+only restore files that are under specified subvolume root pointed by <bytenr>
+-u|--super <mirror>::
+use given superblock mirror identified by <mirror>, it can be 0,1 or 2
+-r|--root <rootid>::
+only restore files that are under a specified subvolume whose objectid is <rootid>
+find directory
+list subvolume tree roots, can be used as argument for '-r'
+dry run (only list files that would be recovered)
+--path-regex <regex>::
+restore only filenames matching a regular expression (`regex`(7)) with a
+mandatory format
+The format is not very comfortable and restores all files in the directories
+in the whole path, so this is not useful for restoring single file in a deep
+ignore case (--path-regex only)
+*btrfs restore* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki for
+further details.