Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
zfs receive -e
1.2. Name of Document Author/Supplier:
Author: Tom Erickson
1.3 Date of This Document:
04 December, 2009
4. Technical Description
4. Technical Description
'zfs receive' destination control
A. SUMMARY
This case adds a -e option to the 'zfs receive' command to request that
only the tail of the sent snapshot path be used to determine the name of
the new received snapshot. Also, it removes the restriction that a
replication stream package sent with 'zfs send -R' must be received
using 'zfs send -d', allowing the administrator to specify the exact
receive path.
B. PROBLEM
Today it is not possible to specify the exact receive path of a
replication stream package, since it is assumed that the administrator
wants to replicate all but the pool name from the snapshot path on the
sending side.
The current behavior is that 'zfs send -R a/b/c | zfs recv -d d/e' will
create d/e/b/c (and descendants). Fishworks wants an option that will
instead create d/e/c (and descendants). Also, backup and restore
capabilities planned for ndmpd require the ability to specify the exact
receive path.
C. PROPOSED SOLUTION
C.1. Overview
The solution adds a -e option to 'zfs receive' similar to the existing
-d option, except that it appends only the tail of sent path to the
specified filesystem. Also it allows the exact path to be specified
where 'zfs send -R' previously restricted the received path to that
derived from the -d option.
C.2. Version Compatibility
There are no compatibility issues. This feature will work the same on
all pool versions.
C.3. Changes to Existing Subcommands
C.3.1 zfs receive
C.3.1.1 zfs receive -e
'zfs receive -d' works as before, appending all but the sent pool name
to the filesystem specified with -d:
% zfs send -R a/b/c at 1 | zfs recv -d d/e
% zfs list -t all
: tomee at heavy[13]; zfs list -t all
NAME USED AVAIL REFER MOUNTPOINT
..
d/e/b 43.5K 457G 21K /d/e/b
d/e/b/c 22.5K 457G 22.5K /d/e/b/c
d/e/b/c at 1 0 - 22.5K -
...
The new 'zfs receive -e' specifies the same filesystem but appends only
the tail of the sent snapshot path:
% zfs send -R a/b/c at 1 | zfs recv -e d/e
% zfs list -t all
NAME USED AVAIL REFER MOUNTPOINT
...
d/e/c 22.5K 457G 22.5K /d/e/c
d/e/c at 1 0 - 22.5K -
...
'zfs receive' without the -d or -e option now allows the exact receive
path to be specified where 'zfs send -R' previously restricted the
receive path to that derived by -d:
% zfs send -R a/b/c at 1 | zfs recv d/e/test
% zfs list -t all
...
d/e/test 22.5K 457G 22.5K /d/e/test
d/e/test at 1 0 - 22.5K -
...
%
C.4. Manpage diffs
< zfs receive [-vnF] -d filesystem
> zfs receive [-vnF] [-d | -e] filesystem
...
zfs receive [-vnF] filesystem|volume|snapshot
zfs receive [-vnF] [-d | -e] filesystem
...
The name of the snapshot (and file system, if a full
stream is received) that this subcommand creates depends
< on the argument type and the -d option.
> on the argument type and the -d or -e option.
If the argument is a snapshot name, the specified
snapshot is created. If the argument is a filesystem or
volume name, a snapshot with the same name as the sent
snapshot is created within the specified filesystem or
< volume. If the -d option is specified, the snapshot name
< is determined by appending the sent snapshot's name to
< the specified filesystem. If the -d option is specified,
< any required file systems within the specified one are
< created.
> volume. If the -d or -e option is specified, the snapshot
> name is determined by appending the sent snapshot's name
> to the specified filesystem. If the -d option is specified,
> all but the pool name of the sent snapshot path is appended
> (e.g. b/c at 1 appended from sent snapshot a/b/c at 1), and if
> the -e option is specified, only the tail of the sent snapshot
> path is appended (e.g. c at 1 appended from sent snapshot
> a/b/c at 1). In the case of -d, any filesystems needed to
> replicate the path of the sent snapshot are created within
> the specified filesystem.
-d
< Use the name of the sent snapshot to determine the
< name of the new snapshot as described in the para-
< graph above.
> Use all but the first element of the sent snapshot
> path (all but the pool name) to determine the name
> of the new snapshot as described in the paragraph
> above.
>
>
> -e
>
> Use the last element of the sent snapshot path
> to determine the name of the new snapshot
> as described in the paragraph above.
Stability
This case requests patch/micro release binding. The new interfaces are
committed.
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
