Debian Codegraph @

upstream/debian-unstable/man8/btrfs-receive.8

raw
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-RECEIVE" "8" "May 10, 2026" "7.0" "BTRFS"
32 .SH NAME
33 btrfs-receive \- receive subvolumes from send stream
34 .SH SYNOPSIS
35 .sp
36 \fBbtrfs receive\fP [options] <path>
37 .sp
38 or
39 .sp
40 \fBbtrfs receive\fP \-\-dump [options]
41 .SH DESCRIPTION
42 .sp
43 Receive a stream of changes and replicate one or more subvolumes that were
44 previously generated by \fBbtrfs send\fP\&. The received subvolumes are stored to
45 \fIpath\fP, unless \fI\-\-dump\fP option is given.
46 .sp
47 If \fI\-\-dump\fP option is specified, \fBbtrfs receive\fP will only do the validation of
48 the stream, and print the stream metadata, one operation per line.
49 .sp
50 \fBbtrfs receive\fP will fail in the following cases:
51 .INDENT 0.0
52 .IP 1. 3
53 receiving subvolume already exists
54 .IP 2. 3
55 previously received subvolume has been changed after it was received
56 .IP 3. 3
57 default subvolume has changed or you didn\(aqt mount the filesystem at the toplevel subvolume
58 .UNINDENT
59 .sp
60 A subvolume is made read\-only after the receiving process finishes successfully (see BUGS below).
61 .sp
62 \fBOptions\fP
63 .INDENT 0.0
64 .TP
65 .BI \-f \ <FILE>
66 read the stream from \fIFILE\fP instead of stdin,
67 .UNINDENT
68 .INDENT 0.0
69 .TP
70 .B \-C|\-\-chroot
71 confine the process to \fIpath\fP using chroot(1) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man1/\:chroot\:.1\:.html>
72 .UNINDENT
73 .INDENT 0.0
74 .TP
75 .B \-e
76 terminate after receiving an \fIend cmd\fP marker in the stream.
77 .sp
78 Without this option the receiver side terminates only in case
79 of an error on end of file.
80 .UNINDENT
81 .INDENT 0.0
82 .TP
83 .B \-E|\-\-max\-errors <NERR>
84 terminate as soon as NERR errors occur while stream processing commands from
85 the stream
86 .sp
87 Default value is 1. A value of 0 means no limit.
88 .UNINDENT
89 .INDENT 0.0
90 .TP
91 .BI \-m \ <ROOTMOUNT>
92 the root mount point of the destination filesystem
93 .sp
94 By default the mount point is searched in :\%<file:/\:proc/\:self>/mounts\(ga.
95 If \fB/proc\fP is not accessible, e.g. in a chroot environment, use this option to
96 tell us where this filesystem is mounted.
97 .TP
98 .B \-\-force\-decompress
99 if the stream contains compressed data (see \fI\-\-compressed\-data\fP in
100 btrfs\-send(8) \%<>), always decompress it instead of writing it with
101 encoded I/O
102 .TP
103 .B \-\-dump
104 dump the stream metadata, one line per operation
105 .sp
106 Does not require the \fIpath\fP parameter. The filesystem remains unchanged.
107 Each stream command is on one line in the form of \fIkey=value\fP and separated
108 by one or more spaces. Values that contain special characters (like
109 paths or extended attributes) are encoded in C\-like way, e.g. \fI\(aq\en\(aq\fP or
110 octal escape sequence like \fI\(aq\eNNN\(aq\fP where N is the char value. Same encoding
111 as is used in \fI/proc\fP files.
112 .UNINDENT
113 .INDENT 0.0
114 .TP
115 .B \-q|\-\-quiet
116 (deprecated) alias for global \fI\-q\fP option
117 .UNINDENT
118 .INDENT 0.0
119 .TP
120 .B \-v
121 (deprecated) alias for global \fI\-v\fP option
122 .UNINDENT
123 .sp
124 \fBGlobal options\fP
125 .INDENT 0.0
126 .TP
127 .B \-v|\-\-verbose
128 increase verbosity about performed actions, print details about each operation
129 .TP
130 .B \-q|\-\-quiet
131 suppress all messages except errors
132 .UNINDENT
133 .SH BUGS
134 .sp
135 \fBbtrfs receive\fP sets the subvolume read\-only after it completes
136 successfully. However, while the receive is in progress, users who have
137 write access to files or directories in the receiving \fIpath\fP can add,
138 remove, or modify files, in which case the resulting read\-only subvolume
139 will not be an exact copy of the sent subvolume.
140 .sp
141 If the intention is to create an exact copy, the receiving \fIpath\fP
142 should be protected from access by users until the receive operation
143 has completed and the subvolume is set to read\-only.
144 .sp
145 Additionally, receive does not currently do a very good job of validating
146 that an incremental send stream actually makes sense, and it is thus
147 possible for a specially crafted send stream to create a subvolume with
148 reflinks to arbitrary files in the same filesystem. Because of this,
149 users are advised to not use \fIbtrfs receive\fP on send streams from
150 untrusted sources, and to protect trusted streams when sending them
151 across untrusted networks.
152 .SH EXIT STATUS
153 .sp
154 \fBbtrfs receive\fP returns a zero exit status if it succeeds. Non zero is
155 returned in case of failure.
156 .SH AVAILABILITY
157 .sp
158 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
159 \%<https://\:btrfs\:.readthedocs\:.io>\&.
160 .SH SEE ALSO
161 .sp
162 btrfs\-send(8) \%<>,
163 mkfs.btrfs(8) \%<>
164 .\" End of generated man page.