1BTRFS-RECEIVE(8)                     BTRFS                    BTRFS-RECEIVE(8)
2
3
4

NAME

6       btrfs-receive - receive subvolumes from send stream
7

SYNOPSIS

9       btrfs receive [options] <path>
10
11       or
12
13       btrfs receive --dump [options]
14

DESCRIPTION

16       Receive  a  stream of changes and replicate one or more subvolumes that
17       were previously generated by btrfs send. The  received  subvolumes  are
18       stored to path, unless --dump option is given.
19
20       If  --dump  option is specified, btrfs receive will only do the valida‐
21       tion of the stream, and print the stream metadata,  one  operation  per
22       line.
23
24       btrfs receive will fail in the following cases:
25
26       1. receiving subvolume already exists
27
28       2. previously received subvolume has been changed after it was received
29
30       3. default  subvolume has changed or you didn't mount the filesystem at
31          the toplevel subvolume
32
33       A subvolume is made read-only after the receiving process finishes suc‐
34       cessfully (see BUGS below).
35
36       Options
37
38       -f <FILE>
39              read the stream from FILE instead of stdin,
40
41       -C|--chroot
42              confine the process to path using chroot(1)
43
44       -e     terminate after receiving an end cmd marker in the stream.
45
46              Without this option the receiver side terminates only in case of
47              an error on end of file.
48
49       -E|--max-errors <NERR>
50              terminate as soon as NERR errors occur while  stream  processing
51              commands from the stream
52
53              Default value is 1. A value of 0 means no limit.
54
55       -m <ROOTMOUNT>
56              the root mount point of the destination filesystem
57
58              By  default the mountpoint is searched in /proc/self/mounts.  If
59              /proc is not accessible, eg. in a chroot environment,  use  this
60              option to tell us where this filesystem is mounted.
61
62       --dump dump the stream metadata, one line per operation
63
64              Does  not require the path parameter. The filesystem remains un‐
65              changed.
66
67       -q|--quiet
68              (deprecated) alias for global -q option
69
70       -v     (deprecated) alias for global -v option
71
72       Global options
73
74       -v|--verbose
75              increase verbosity about performed actions, print details  about
76              each operation
77
78       -q|--quiet
79              suppress all messages except errors
80

BUGS

82       btrfs  receive sets the subvolume read-only after it completes success‐
83       fully.  However, while the receive is in progress, users who have write
84       access  to  files or directories in the receiving path can add, remove,
85       or modify files, in which case the resulting read-only  subvolume  will
86       not be an exact copy of the sent subvolume.
87
88       If  the intention is to create an exact copy, the receiving path should
89       be protected from access by users until the receive operation has  com‐
90       pleted and the subvolume is set to read-only.
91
92       Additionally, receive does not currently do a very good job of validat‐
93       ing that an incremental send stream actually makes  sense,  and  it  is
94       thus possible for a specially crafted send stream to create a subvolume
95       with reflinks to arbitrary files in the same  filesystem.   Because  of
96       this,  users  are advised to not use btrfs receive on send streams from
97       untrusted sources, and to protect trusted  streams  when  sending  them
98       across untrusted networks.
99

EXIT STATUS

101       btrfs  receive  returns  a zero exit status if it succeeds. Non zero is
102       returned in case of failure.
103

AVAILABILITY

105       btrfs  is  part  of  btrfs-progs.   Please  refer  to  the  btrfs  wiki
106       http://btrfs.wiki.kernel.org for further details.
107

SEE ALSO

109       mkfs.btrfs(8), btrfs-send(8)
110

COPYRIGHT

112       2022
113
114
115
116
1175.18                             May 25, 2022                 BTRFS-RECEIVE(8)