I am sponsoring the following fast-track on behalf of myself. This
case introduces a new zfs sub-command for describing differences
between snapshots in a zfs hierarchy. A delegated permission and
read-only system attribute are also introduced to support the
sub-command. The case requests micro/patch binding.
Template Version: @(#)sac_nextcase 1.69 02/15/10 SMI
This information is Copyright 2010 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
zfs diff
1.2. Name of Document Author/Supplier:
Author: Tim Haley
1.3 Date of This Document:
28 March, 2010
4. Technical Description
There is a long-standing RFE for zfs to be able to describe
what has changed between the snapshots of a dataset.
To provide this capability, we propose a new 'zfs diff'
sub-command. When run with appropriate privilege the
sub-command describes what file system level changes have
occurred between the requested snapshots. A diff between the
current version of the file system and one of its snapshots is
also supported.
Five types of change are described:
o File/Directory modified
o File/Directory present in older snapshot but not newer
o File/Directory present in newer snapshot but not older
o File/Directory renamed
o File link count changed
Diffs can be performed if the user is delegated the "diff"
permission. The "diff" permission is being introduced by this
case. Diffs can also be performed without the "diff"
permission, if the user has appropriate privilege. For diffs
between existing snapshots, the necessary privilege is
{PRIV_SYS_CONFIG}. For diff between the current file system
and a snapshot {PRIV_SYS_MOUNT} is also necessary.
Also introduced by this case is a system attribute on zfs files
called 'generation'. This attribute is part of the
XATTR_VIEW_READONLY described in PSARC 2007/315. It is
generated automatically by the ZFS module.
Man page changes:
--- fgetattr.3c.rogi Sun Mar 21 18:47:29 2010
+++ fgetattr.3c Sun Mar 21 18:50:50 2010
@@ -97,6 +97,7 @@
XATTR_VIEW_READONLY A_FSID uint64_value
A_OPAQUE boolean_value
A_AV_SCANSTAMP uint8_array[]
+ A_GEN uint64_value
XATTR_VIEW_READWRITE A_READONLY boolean_value
A_HIDDEN boolean_value
A_SYSTEM boolean_value
--- zfs.1m.rogi Sun Mar 21 17:01:04 2010
+++ zfs.1m Sun Mar 28 12:20:04 2010
@@ -165,6 +165,9 @@
zfs release [-r] tag snapshot...
+ zfs diff snapshot snapshot|filesystem
+
+
DESCRIPTION
The zfs command configures ZFS datasets within a ZFS storage
pool, as described in zpool(1M). A dataset is identified by
@@ -1638,7 +1641,41 @@
size, the resulting behavior is undefined.
+ zfs diff snapshot snapshot | filesystem
+ Gives a high level description of the differences between a
+ snapshot and a descendant dataset. The descendant may either
+ be a later snapshot of the dataset or the current dataset.
+ For each file system object that has undergone a change
+ between the original snapshot and the descendant, the type of
+ change is described along with the name of the file or
+ directory. In the case of a rename, both the old and new
+ names are shown.
+
+ The type of change is described with a single character:
+
+ + Indicates the file/directory was added in the later dataset
+ - Indicates the file/directory was removed in the later dataset
+ M Indicates the file/directory was modified in the later dataset
+ R Indicates the file/directory was renamed in the later dataset
+
+ If the modification involved a change in the link count of a
+ file, the change will be expressed as a delta within
+ parentheses on the modification line. Example outputs are
+ below:
+
+ M /myfiles/
+ M /myfiles/link_to_me (+1)
+ R /myfiles/rename_me -> /myfiles/renamed
+ - /myfiles/delete_me
+ + /myfiles/new_file
+
+ Users must be granted the diff permission with zfs allow in
+ order to use this sub-command, unless they already have the
+ {PRIV_SYS_CONFIG} privilege and, in the current file system
+ versus snapshot case, the {PRIV_SYS_MOUNT} privilege.
+
+
zfs destroy [-rRf] filesystem|volume
@@ -2733,6 +2770,7 @@
'mount'
ability in the origin file system
create subcommand Must also have the 'mount' ability
+ diff subcommand
destroy subcommand Must also have the 'mount' ability
hold subcommand Allows adding a user hold to a
snapshot
mount subcommand Allows mount/umount of ZFS datasets
@@ -3551,7 +3589,12 @@
tion Guide.
+NOTES
+ A file or directory described as modified by the diff sub-command
+ may have been modified in multiple ways. Any action which causes
+ a change in the st_ctime (see stat(2)) is grounds for reporting a
+ modification.
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
