Make createtxg and guid properties public

Document the existence of `createtxg` and `guid` native properties
in man pages and zfs command output.

One of the great features of ZFS is incremental replication of
snapshots, possibly between pools on different machines.

Shell scripts are commonly used to auomate this procedure. They have to
find the most recent common snapshot between both sides and then
perform incremental send & recv.
Currently, scripts rely on the sorting order of `zfs list`, which
defaults to `createtxg`, and the assumption that snapshot names on
either side do not change.

By making `createtxg` and `guid` part of the public ZFS interface,
scripts are enabled to use

  a) `createtxg` to determine the logical & temporal order of snapshots
     (the creation property is not an equivalent substitute since
      multiple snapshots may be created within one second)
  b) `guid` to uniquely identify a snapshot, independent of its current
      display name

This has the potential of making scripts safer and correct.

Reviewed-by: George Melikov <mail@gmelikov.ru>
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Reviewed-by: DHE <git@dehacked.net>
Reviewed-by: Richard Laager <rlaager@wiktel.com>
Signed-off-by: Christian Schwarz <me@cschwarz.com>
Closes #6102

diff --git a/include/sys/fs/zfs.h b/include/sys/fs/zfs.h
index ba64876121f40cd687d85b77bdb0e60a1d64c9d2..5b7bbb6898033c5f02d3292fd0ba6f091ad44f8e 100644 (file)
--- a/include/sys/fs/zfs.h
+++ b/include/sys/fs/zfs.h
@@ -113,7 +113,7 @@ typedef enum {
        ZFS_PROP_SNAPDIR,
        ZFS_PROP_PRIVATE,               /* not exposed to user, temporary */
        ZFS_PROP_ACLINHERIT,
-       ZFS_PROP_CREATETXG,             /* not exposed to the user */
+       ZFS_PROP_CREATETXG,
        ZFS_PROP_NAME,                  /* not exposed to the user */
        ZFS_PROP_CANMOUNT,
        ZFS_PROP_ISCSIOPTIONS,          /* not exposed to the user */

diff --git a/lib/libzfs/libzfs_dataset.c b/lib/libzfs/libzfs_dataset.c
index 0f18fd6900d57c37c2ea04cb9432d63963bcd91c..f1346b69c6f43316a46ac07328d733982643c900 100644 (file)
--- a/lib/libzfs/libzfs_dataset.c
+++ b/lib/libzfs/libzfs_dataset.c
@@ -2695,6 +2695,7 @@ zfs_prop_get(zfs_handle_t *zhp, zfs_prop_t prop, char *propbuf, size_t proplen,
                break;
 
        case ZFS_PROP_GUID:
+       case ZFS_PROP_CREATETXG:
                /*
                 * GUIDs are stored as numbers, but they are identifiers.
                 * We don't want them to be pretty printed, because pretty

diff --git a/man/man8/zfs.8 b/man/man8/zfs.8
index 6720796378e88d4db6926b1a34ae0f8e1a1d4185..5d0b79b9965039b33c4f2f84477197dc711873d1 100644 (file)
--- a/man/man8/zfs.8
+++ b/man/man8/zfs.8
@@ -438,6 +438,18 @@ This property can also be referred to by its shortened column name, \fBavail\fR.
 For non-snapshots, the compression ratio achieved for the \fBused\fR space of this dataset, expressed as a multiplier.  The \fBused\fR property includes descendant datasets, and, for clones, does not include the space shared with the origin snapshot.  For snapshots, the \fBcompressratio\fR is the same as the \fBrefcompressratio\fR property.  The \fBcompression\fR property controls whether compression is enabled on a dataset.
 .RE
 
+.sp
+.ne 2
+.na
+\fB\fBcreatetxg\fR
+.ad
+.sp .6
+.RS 4n
+The transaction group (TXG) in which the dataset was created. Bookmarks have the same \fBcreatetxg\fR as the snapshot they are initially tied to.
+.sp
+\fBcreatetxg\fR is suitable for ordering a list of snapshots, e.g. for incremental \fBsend\fR & \fBrecv\fR.
+.RE
+
 .sp
 .ne 2
 .na
@@ -485,6 +497,18 @@ dataset tree.  This value is only available when a \fBfilesystem_limit\fR has
 been set somewhere in the tree under which the dataset resides.
 .RE
 
+.sp
+.ne 2
+.na
+\fB\fBguid\fR
+.ad
+.sp .6
+.RS 4n
+The 64 bit GUID of this dataset or bookmark, which does not change over its entire lifetime.
+.sp
+When a snapshot is sent to another pool, the received snapshot has the same GUID. Thus, \fBguid\fR is suitable to identify a snapshot across pools.
+.RE
+
 .sp
 .ne 2
 .na

diff --git a/module/zcommon/zfs_prop.c b/module/zcommon/zfs_prop.c
index 82641b490ca88d181a581599b469289c617d504f..97736ee278bf3a330d1b4040f281d5e8373070c6 100644 (file)
--- a/module/zcommon/zfs_prop.c
+++ b/module/zcommon/zfs_prop.c
@@ -439,6 +439,10 @@ zfs_prop_init(void)
        zprop_register_number(ZFS_PROP_SNAPSHOT_COUNT, "snapshot_count",
            UINT64_MAX, PROP_READONLY, ZFS_TYPE_FILESYSTEM | ZFS_TYPE_VOLUME,
            "<count>", "SSCOUNT");
+       zprop_register_number(ZFS_PROP_GUID, "guid", 0, PROP_READONLY,
+           ZFS_TYPE_DATASET | ZFS_TYPE_BOOKMARK, "<uint64>", "GUID");
+       zprop_register_number(ZFS_PROP_CREATETXG, "createtxg", 0, PROP_READONLY,
+           ZFS_TYPE_DATASET | ZFS_TYPE_BOOKMARK, "<uint64>", "CREATETXG");
 
        /* default number properties */
        zprop_register_number(ZFS_PROP_QUOTA, "quota", 0, PROP_DEFAULT,
@@ -466,8 +470,6 @@ zfs_prop_init(void)
            ZFS_TYPE_FILESYSTEM, "512 to 1M, power of 2", "RECSIZE");
 
        /* hidden properties */
-       zprop_register_hidden(ZFS_PROP_CREATETXG, "createtxg", PROP_TYPE_NUMBER,
-           PROP_READONLY, ZFS_TYPE_DATASET | ZFS_TYPE_BOOKMARK, "CREATETXG");
        zprop_register_hidden(ZFS_PROP_NUMCLONES, "numclones", PROP_TYPE_NUMBER,
            PROP_READONLY, ZFS_TYPE_SNAPSHOT, "NUMCLONES");
        zprop_register_hidden(ZFS_PROP_NAME, "name", PROP_TYPE_STRING,
@@ -477,8 +479,6 @@ zfs_prop_init(void)
        zprop_register_hidden(ZFS_PROP_STMF_SHAREINFO, "stmf_sbd_lu",
            PROP_TYPE_STRING, PROP_INHERIT, ZFS_TYPE_VOLUME,
            "STMF_SBD_LU");
-       zprop_register_hidden(ZFS_PROP_GUID, "guid", PROP_TYPE_NUMBER,
-           PROP_READONLY, ZFS_TYPE_DATASET | ZFS_TYPE_BOOKMARK, "GUID");
        zprop_register_hidden(ZFS_PROP_USERACCOUNTING, "useraccounting",
            PROP_TYPE_NUMBER, PROP_READONLY, ZFS_TYPE_DATASET,
            "USERACCOUNTING");