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 received properties
1.2. Name of Document Author/Supplier:
Author: Tom Erickson
1.3 Date of This Document:
24 September, 2009
4. Technical Description
ZFS received properties
A. SUMMARY
This case adds received property values to ZFS so that 'zfs receive'
preserves local properties and the administrator can revert to received
values if desired. Also, it adds the option to include a sent dataset's
properties without also replicating its child datasets.
B. PROBLEM
Many customers have asked for the ability to have different properties
for datasets on the disaster recovery site than on the primary site. For
example, they may want to compress data on the DR site, or have a
different set of NFS exports, or a different automatic snapshot policy
(which is governed in the Fishworks stack by a ZFS dataset user
property). To facilitate this, there should be a way of setting a
property in ZFS that will not be overwritten by 'zfs receive'. Ideally,
it would be possible to observe the state of this property (overridden
locally vs. received) as well as revert to its received value.
Also, it will be generally useful to be able to include properties in
the send stream without also including child datasets. That option will
be used by NDMP backup in an upcoming Fishworks project.
C. PROPOSED SOLUTION
C.1. Overview
A ZFS dataset property can now have both a local and a received value.
A newly received dataset uses received property values by default until
they are explicitly overridden by setting or inheriting properties
locally with 'zfs set' or 'zfs inherit'. However, since the received
values still exist, it remains possible to activate them again by
clearing the local settings. The 'zfs receive' command now overwrites
any existing received values but leaves the locally set values intact.
(Previously all local settings were overwritten.) Values inherited
locally from a parent dataset also override received values. That is,
the effects of 'zfs inherit' are also left intact by 'zfs receive'. The
'zfs inherit' subcommand has a new -S option to clear any locally set
value or explicit inheritance and revert to the received value. (In the
case where there is no received value, the property is implicitly
inherited.) The 'zfs get' subcommand also adds a non-default "received"
column, making it possible to display received property values even when
they are overridden locally.
C.2. Version Compatibility
Using this feature requires a pool upgrade. Properties received on
earlier pool versions will be cleared by the first 'zfs receive' after
the upgrade, otherwise the older received values would override the
newly received values just as if the older values had been set locally.
Properties set locally by 'zfs set' on earlier pool versions will also
be cleared by the first 'zfs receive' after the upgrade, since they are
indistinguishable from pre-upgrade received properties. That is, the
first 'zfs receive' after the upgrade will have the same behavior as
'zfs receive' before the upgrade (not preserving local properties).
C.3. Changes to Existing Subcommands
C.3.1 zfs get
C.3.1.1 zfs get -o
The -o option to specify the set of fields to display now takes some new
option arguments. The previous syntax:
[-o field[,field]...]
is now
[-o all | field[,field]...]
and field is expanded to include a new "received" value:
-o Set of fields to display. One of "name,property,value,
received,source". Default is "name,property,value,source".
"all" is an alias for all five.
C.3.1.2 zfs get -s
The -s option to specify the set of allowed sources now takes an
additional "received" source:
-s Set of sources to allow. One of
"local,default,inherited,received,temporary,none".
Default is all six.
For example, to see all received properties, whether or not they are
overridden locally:
# zfs get -o all -s local,inherited,received all srecv.dst/tom
NAME PROPERTY VALUE RECEIVED SOURCE
srecv.dst/tom compression on off local
srecv.dst/tom tom:color blue red local
srecv.dst/tom tom:word apple apple received
srecv.dst/tom tom:shape triangle square inherited
from srecv.dst
#
The effective value is displayed under the VALUE column, and the source
of that value under the SOURCE column. If desired, the administrator can
revert to the value under the RECEIVED column using 'zfs inherit -S'.
C.3.2 zfs inherit -S
The 'zfs inherit' subcommand now takes a -S option, which reverts a
property to its received value (if any) by clearing any locally set
value. If there is no received value, then 'zfs inherit -S' has exactly
the same behavior as inherit without the -S option.
Note that 'zfs inherit' without the -S option now overrides the received
value by explicitly inheriting from the parent dataset. In the example
above, the tom:shape property inherited from the parent dataset can
still be reverted to the received value as follows:
# zfs inherit -S tom:shape srecv.dst/tom
# zfs get -o all tom:shape srecv.dst/tom
NAME PROPERTY VALUE RECEIVED SOURCE
srecv.dst/tom tom:shape square square received
#
C.3.3 zfs send -p
The 'zfs send' subcommand now takes a -p option that is like
'zfs send -R' in that it includes properties, but it does not include
child datasets.
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
