2014-04-02 08:29:22 +00:00
|
|
|
btrfs-receive(8)
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
NAME
|
|
|
|
|
----
|
2016-05-06 11:12:42 +00:00
|
|
|
btrfs-receive - receive subvolumes from send stream
|
2014-04-02 08:29:22 +00:00
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
|
--------
|
2016-06-14 05:50:19 +00:00
|
|
|
*btrfs receive* [options] <path>
|
2014-04-02 08:29:22 +00:00
|
|
|
|
2016-09-07 00:29:34 +00:00
|
|
|
or
|
|
|
|
|
|
|
|
|
|
*btrfs receive* --dump [options]
|
|
|
|
|
|
2014-04-02 08:29:22 +00:00
|
|
|
DESCRIPTION
|
|
|
|
|
-----------
|
|
|
|
|
|
2016-05-06 11:12:42 +00:00
|
|
|
Receive a stream of changes and replicate one or more subvolumes that were
|
2016-11-21 17:19:57 +00:00
|
|
|
previously generated by *btrfs send*. The received subvolumes are stored to
|
|
|
|
|
'path', unless '--dump' option is given.
|
2016-09-07 00:29:34 +00:00
|
|
|
|
2016-11-21 17:19:57 +00:00
|
|
|
If '--dump' option is specified, *btrfs receive* will only do the validation of
|
|
|
|
|
the stream, and print the stream metadata, one operation per line.
|
2014-04-02 08:29:22 +00:00
|
|
|
|
2017-01-27 17:08:26 +00:00
|
|
|
*btrfs receive* will fail in the following cases:
|
2014-04-02 08:29:22 +00:00
|
|
|
|
2016-05-06 11:12:42 +00:00
|
|
|
1. receiving subvolume already exists
|
2014-04-02 08:29:22 +00:00
|
|
|
|
2016-11-21 17:19:57 +00:00
|
|
|
2. previously received subvolume has been changed after it was received
|
2014-04-02 08:29:22 +00:00
|
|
|
|
2016-11-21 17:19:57 +00:00
|
|
|
3. default subvolume has changed or you didn't mount the filesystem at the toplevel subvolume
|
2016-05-06 11:12:42 +00:00
|
|
|
|
2017-02-21 23:14:38 +00:00
|
|
|
A subvolume is made read-only after the receiving process finishes successfully (see BUGS below).
|
2014-04-02 08:29:22 +00:00
|
|
|
|
|
|
|
|
`Options`
|
|
|
|
|
|
2016-11-21 17:19:57 +00:00
|
|
|
-f <FILE>::
|
|
|
|
|
read the stream from <FILE> instead of stdin,
|
2016-05-06 11:12:42 +00:00
|
|
|
|
2015-04-19 11:46:28 +00:00
|
|
|
-C|--chroot::
|
2016-06-14 05:50:19 +00:00
|
|
|
confine the process to 'path' using `chroot`(1)
|
2016-05-06 11:12:42 +00:00
|
|
|
|
2014-04-02 08:29:22 +00:00
|
|
|
-e::
|
2016-05-06 11:12:42 +00:00
|
|
|
terminate after receiving an 'end cmd' marker in the stream.
|
|
|
|
|
+
|
2016-11-21 17:19:57 +00:00
|
|
|
Without this option the receiver side terminates only in case
|
|
|
|
|
of an error on end of file.
|
2016-05-06 11:12:42 +00:00
|
|
|
|
2016-11-21 17:19:57 +00:00
|
|
|
-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.
|
2016-05-06 11:12:42 +00:00
|
|
|
|
2016-11-21 17:19:57 +00:00
|
|
|
-m <ROOTMOUNT>::
|
2016-05-06 11:12:42 +00:00
|
|
|
the root mount point of the destination filesystem
|
2015-05-27 17:51:29 +00:00
|
|
|
+
|
2016-05-06 11:12:42 +00:00
|
|
|
By default the mountpoint is searched in '/proc/self/mounts'.
|
2016-11-21 17:19:57 +00:00
|
|
|
If '/proc' is not accessible, eg. in a chroot environment, use this option to
|
|
|
|
|
tell us where this filesystem is mounted.
|
2014-04-02 08:29:22 +00:00
|
|
|
|
2016-09-07 00:29:34 +00:00
|
|
|
--dump::
|
2016-11-21 17:19:57 +00:00
|
|
|
dump the stream metadata, one line per operation
|
2016-09-07 00:29:34 +00:00
|
|
|
+
|
2017-02-21 23:14:38 +00:00
|
|
|
Does not require the 'path' parameter. The filesystem remains unchanged.
|
2016-09-07 00:29:34 +00:00
|
|
|
|
2020-06-26 20:20:56 +00:00
|
|
|
-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
|
|
|
|
|
|
2017-02-03 19:38:05 +00:00
|
|
|
BUGS
|
|
|
|
|
----
|
|
|
|
|
*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
|
2017-12-07 20:26:09 +00:00
|
|
|
that an incremental send stream actually makes sense, and it is thus
|
2017-02-03 19:38:05 +00:00
|
|
|
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.
|
|
|
|
|
|
2014-04-02 08:29:22 +00:00
|
|
|
EXIT STATUS
|
|
|
|
|
-----------
|
2014-09-19 01:49:59 +00:00
|
|
|
*btrfs receive* returns a zero exit status if it succeeds. Non zero is
|
2014-04-02 08:29:22 +00:00
|
|
|
returned in case of failure.
|
|
|
|
|
|
|
|
|
|
AVAILABILITY
|
|
|
|
|
------------
|
2014-05-19 16:04:26 +00:00
|
|
|
*btrfs* is part of btrfs-progs.
|
2014-04-02 08:29:22 +00:00
|
|
|
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
|
|
|
|
|
further details.
|
|
|
|
|
|
|
|
|
|
SEE ALSO
|
|
|
|
|
--------
|
|
|
|
|
`mkfs.btrfs`(8),
|
|
|
|
|
`btrfs-send`(8)
|
