|
|
| 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><path></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’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><FILE></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | read the stream from <em><FILE></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><NERR></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><ROOTMOUNT></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]]
| |
