File: btrfs-receive.rst

package info (click to toggle)
btrfs-progs 6.16-2
  • links: PTS, VCS
  • area: main
  • in suites: forky
  • size: 20,504 kB
  • sloc: ansic: 126,181; sh: 7,642; python: 1,386; makefile: 900; asm: 296
file content (126 lines) | stat: -rw-r--r-- 4,026 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
btrfs-receive(8)
================

SYNOPSIS
--------

**btrfs receive** [options] <path>

or

**btrfs receive** --dump [options]

DESCRIPTION
-----------

Receive a stream of changes and replicate one or more subvolumes that were
previously generated by :command:`btrfs send`. The received subvolumes are stored to
*path*, unless *--dump* option is given.

If *--dump* option is specified, :command:`btrfs receive` will only do the validation of
the stream, and print the stream metadata, one operation per line.

:command:`btrfs receive` will fail in the following cases:

1. receiving subvolume already exists

2. previously received subvolume has been changed after it was received

3. default subvolume has changed or you didn't mount the filesystem at the toplevel subvolume

A subvolume is made read-only after the receiving process finishes successfully (see BUGS below).

``Options``

-f <FILE>
        read the stream from *FILE* instead of stdin,

-C|--chroot
        confine the process to *path* using :manref:`chroot(1)`

-e
        terminate after receiving an *end cmd* marker in the stream.

        Without this option the receiver side terminates only in case
        of an error on end of file.

-E|--max-errors <NERR>
        terminate as soon as NERR errors occur while stream processing commands from
        the stream

        Default value is 1. A value of 0 means no limit.

-m <ROOTMOUNT>
        the root mount point of the destination filesystem

        By default the mount point is searched in :file:/proc/self/mounts`.
        If :file:`/proc` is not accessible, e.g. in a chroot environment, use this option to
        tell us where this filesystem is mounted.

--force-decompress
        if the stream contains compressed data (see *--compressed-data* in
        :doc:`btrfs-send`), always decompress it instead of writing it with
        encoded I/O

--dump
        dump the stream metadata, one line per operation

        Does not require the *path* parameter. The filesystem remains unchanged.
        Each stream command is on one line in the form of *key=value* and separated
        by one or more spaces.  Values that contain special characters (like
        paths or extended attributes) are encoded in C-like way, e.g. *'\\n'* or
        octal escape sequence like *'\\NNN'* where N is the char value. Same encoding
        as is used in */proc* files.

-q|--quiet
        (deprecated) alias for global *-q* option

-v
        (deprecated) alias for global *-v* option

``Global options``

-v|--verbose
        increase verbosity about performed actions, print details about each operation

-q|--quiet
        suppress all messages except errors

BUGS
----

:command:`btrfs receive` sets the subvolume read-only after it completes
successfully.  However, while the receive is in progress, users who have
write access to files or directories in the receiving *path* can add,
remove, or modify files, in which case the resulting read-only subvolume
will not be an exact copy of the sent subvolume.

If the intention is to create an exact copy, the receiving *path*
should be protected from access by users until the receive operation
has completed and the subvolume is set to read-only.

Additionally, receive does not currently do a very good job of validating
that an incremental send stream actually makes sense, and it is thus
possible for a specially crafted send stream to create a subvolume with
reflinks to arbitrary files in the same filesystem.  Because of this,
users are advised to not use *btrfs receive* on send streams from
untrusted sources, and to protect trusted streams when sending them
across untrusted networks.

EXIT STATUS
-----------

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

AVAILABILITY
------------

**btrfs** is part of btrfs-progs.  Please refer to the documentation at
`https://btrfs.readthedocs.io <https://btrfs.readthedocs.io>`_.

SEE ALSO
--------

:doc:`btrfs-send`,
:doc:`mkfs.btrfs`