Manpage/btrfs-receive

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
(Update from git, v5.14.2)
(remove content)
 
Line 1: Line 1:
=btrfs-receive(8) manual page=
 
 
{{GeneratedManpage
 
{{GeneratedManpage
 
|name=btrfs-receive}}
 
|name=btrfs-receive}}
 
==NAME==
 
btrfs-receive - receive subvolumes from send stream
 
 
==SYNOPSIS==
 
 
<p><b>btrfs receive</b> [options] <em>&lt;path&gt;</em></p>
 
<p>or</p>
 
<p><b>btrfs receive</b> --dump [options]</p>
 
==DESCRIPTION==
 
 
<p>Receive a stream of changes and replicate one or more subvolumes that were
 
previously generated by <b>btrfs send</b>. The received subvolumes are stored to
 
<em>path</em>, unless <em>--dump</em> option is given.</p>
 
<p>If <em>--dump</em> option is specified, <b>btrfs receive</b> will only do the validation of
 
the stream, and print the stream metadata, one operation per line.</p>
 
<p><b>btrfs receive</b> will fail in the following cases:</p>
 
<ol>
 
<li>
 
<p>
 
receiving subvolume already exists
 
</p>
 
</li>
 
<li>
 
<p>
 
previously received subvolume has been changed after it was received
 
</p>
 
</li>
 
<li>
 
<p>
 
default subvolume has changed or you didn&#8217;t mount the filesystem at the toplevel subvolume
 
</p>
 
</li>
 
</ol>
 
<p>A subvolume is made read-only after the receiving process finishes successfully (see BUGS below).</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
-f <em>&lt;FILE&gt;</em>
 
<dd>
 
<p>
 
read the stream from <em>&lt;FILE&gt;</em> instead of stdin,
 
</p>
 
 
<dt>
 
-C|--chroot
 
<dd>
 
<p>
 
confine the process to <em>path</em> using [http://man7.org/linux/man-pages/man1/chroot.1.html chroot(1)]
 
</p>
 
 
<dt>
 
-e
 
<dd>
 
<p>
 
terminate after receiving an <em>end cmd</em> marker in the stream.
 
</p>
 
<p>Without this option the receiver side terminates only in case
 
of an error on end of file.</p>
 
 
<dt>
 
-E|--max-errors <em>&lt;NERR&gt;</em>
 
<dd>
 
<p>
 
terminate as soon as NERR errors occur while stream processing commands from
 
the stream
 
</p>
 
<p>Default value is 1. A value of 0 means no limit.</p>
 
 
<dt>
 
-m <em>&lt;ROOTMOUNT&gt;</em>
 
<dd>
 
<p>
 
the root mount point of the destination filesystem
 
</p>
 
<p>By default the mountpoint is searched in <em>/proc/self/mounts</em>.
 
If <em>/proc</em> is not accessible, eg. in a chroot environment, use this option to
 
tell us where this filesystem is mounted.</p>
 
 
<dt>
 
--dump
 
<dd>
 
<p>
 
dump the stream metadata, one line per operation
 
</p>
 
<p>Does not require the <em>path</em> parameter. The filesystem remains unchanged.</p>
 
 
<dt>
 
-q|--quiet
 
<dd>
 
<p>
 
(deprecated) alias for global <em>-q</em> option
 
</p>
 
 
<dt>
 
-v
 
<dd>
 
<p>
 
(deprecated) alias for global <em>-v</em> option
 
</p>
 
 
</dl>
 
<p><tt>Global options</tt></p>
 
<dl>
 
<dt>
 
-v|--verbose
 
<dd>
 
<p>
 
increase verbosity about performed actions, print details about each operation
 
</p>
 
 
<dt>
 
-q|--quiet
 
<dd>
 
<p>
 
suppress all messages except errors
 
</p>
 
 
</dl>
 
==BUGS==
 
 
<p><b>btrfs receive</b> 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 <em>path</em> can add,
 
remove, or modify files, in which case the resulting read-only subvolume
 
will not be an exact copy of the sent subvolume.</p>
 
<p>If the intention is to create an exact copy, the receiving <em>path</em>
 
should be protected from access by users until the receive operation
 
has completed and the subvolume is set to read-only.</p>
 
<p>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 <b>btrfs receive</b> on send streams from
 
untrusted sources, and to protect trusted streams when sending them
 
across untrusted networks.</p>
 
==EXIT STATUS==
 
 
<p><b>btrfs receive</b> returns a zero exit status if it succeeds. Non zero is
 
returned in case of failure.</p>
 
==AVAILABILITY==
 
 
<p><b>btrfs</b> is part of btrfs-progs.
 
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 
further details.</p>
 
==SEE ALSO==
 
 
<p>[[Manpage/mkfs.btrfs|mkfs.btrfs(8)]],
 
[[Manpage/btrfs-send|btrfs-send(8)]]</p>
 
[[Category:Manpage]]
 

Latest revision as of 12:32, 12 January 2022

Note: manual pages are located at read-the-docs site, please update your links.


Personal tools