summaryrefslogtreecommitdiff
path: root/Documentation/btrfs-restore.8
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/btrfs-restore.8')
-rw-r--r--Documentation/btrfs-restore.8160
1 files changed, 160 insertions, 0 deletions
diff --git a/Documentation/btrfs-restore.8 b/Documentation/btrfs-restore.8
new file mode 100644
index 00000000..db635693
--- /dev/null
+++ b/Documentation/btrfs-restore.8
@@ -0,0 +1,160 @@
+'\" t
+.\" Title: btrfs-restore
+.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\" Date: 12/05/2018
+.\" Manual: Btrfs Manual
+.\" Source: Btrfs v4.19.1
+.\" Language: English
+.\"
+.TH "BTRFS\-RESTORE" "8" "12/05/2018" "Btrfs v4\&.19\&.1" "Btrfs Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+btrfs-restore \- try to restore files from a damaged btrfs filesystem image
+.SH "SYNOPSIS"
+.sp
+\fBbtrfs restore\fR [options] \fI<device>\fR \fI<path>\fR | \-l \fI<device>\fR
+.SH "DESCRIPTION"
+.sp
+\fBbtrfs restore\fR is used to try to salvage files from a damaged filesystem and restore them into \fI<path>\fR or just list the subvolume tree roots\&. The filesystem image is not modified\&.
+.sp
+If the filesystem is damaged and cannot be repaired by the other tools (\fBbtrfs\-check\fR(8) or \fBbtrfs\-rescue\fR(8)), \fBbtrfs restore\fR 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\(cqre available\&.
+.sp
+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\&.
+.sp
+For images with damaged tree structures, there are several options to point the process to some spare copy\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+It is recommended to read the following btrfs wiki page if your data is not salvaged with default option: \m[blue]\fBhttps://btrfs\&.wiki\&.kernel\&.org/index\&.php/Restore\fR\m[]
+.sp .5v
+.RE
+.SH "OPTIONS"
+.PP
+\-s|\-\-snapshots
+.RS 4
+get also snapshots that are skipped by default
+.RE
+.PP
+\-x|\-\-xattr
+.RS 4
+get extended attributes
+.RE
+.PP
+\-m|\-\-metadata
+.RS 4
+restore owner, mode and times for files and directories
+.RE
+.PP
+\-S|\-\-symlinks
+.RS 4
+restore symbolic links as well as normal files
+.RE
+.PP
+\-v|\-\-verbose
+.RS 4
+be verbose and print what is being restored
+.RE
+.PP
+\-i|\-\-ignore\-errors
+.RS 4
+ignore errors during restoration and continue
+.RE
+.PP
+\-o|\-\-overwrite
+.RS 4
+overwrite directories/files in
+\fI<path>\fR, eg\&. for repeated runs
+.RE
+.PP
+\-t \fI<bytenr>\fR
+.RS 4
+use
+\fI<bytenr>\fR
+to read the root tree
+.RE
+.PP
+\-f \fI<bytenr>\fR
+.RS 4
+only restore files that are under specified subvolume root pointed by
+\fI<bytenr>\fR
+.RE
+.PP
+\-u|\-\-super \fI<mirror>\fR
+.RS 4
+use given superblock mirror identified by
+\fI<mirror>\fR, it can be 0,1 or 2
+.RE
+.PP
+\-r|\-\-root \fI<rootid>\fR
+.RS 4
+only restore files that are under a specified subvolume whose objectid is
+\fI<rootid>\fR
+.RE
+.PP
+\-d
+.RS 4
+find directory
+.RE
+.PP
+\-l|\-\-list\-roots
+.RS 4
+list subvolume tree roots, can be used as argument for
+\fI\-r\fR
+.RE
+.PP
+\-D|\-\-dry\-run
+.RS 4
+dry run (only list files that would be recovered)
+.RE
+.PP
+\-\-path\-regex \fI<regex>\fR
+.RS 4
+restore only filenames matching a regular expression (\fBregex\fR(7)) with a mandatory format
+.sp
+\fB^/(|home(|/username(|/Desktop(|/\&.*))))$\fR
+.sp
+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 hierarchy\&.
+.RE
+.PP
+\-c
+.RS 4
+ignore case (\-\-path\-regex only)
+.RE
+.SH "EXIT STATUS"
+.sp
+\fBbtrfs restore\fR returns a zero exit status if it succeeds\&. Non zero is returned in case of failure\&.
+.SH "AVAILABILITY"
+.sp
+\fBbtrfs\fR is part of btrfs\-progs\&. Please refer to the btrfs wiki \m[blue]\fBhttp://btrfs\&.wiki\&.kernel\&.org\fR\m[] for further details\&.
+.SH "SEE ALSO"
+.sp
+\fBmkfs\&.btrfs\fR(8), \fBbtrfs\-rescue\fR(8), \fBbtrfs\-check\fR(8)