zfs.resource.snapshot.clone¶
Clone a ZFS snapshot to create a new filesystem or volume, of the type the snapshot was taken of.
A validation error is raised when:
snapshotis not a snapshot path ordatasetis one (EINVAL)a property does not apply to the type of the clone, or its value is refused (
EINVAL)a user property name or value is invalid (
EINVAL)the source snapshot does not exist (
ENOENT)datasetalready exists (EEXIST)either path is a protected path (
EACCES)
A filesystem clone that cannot be mounted is kept, and the error names it.
Examples:
Clone a snapshot to a new dataset:
{"snapshot": "tank/data@backup", "dataset": "tank/data_clone"}
Clone with properties:
{
"snapshot": "tank/data@backup",
"dataset": "tank/data_clone",
"properties": {"compression": "lz4", "quota": "10G"},
"user_properties": {"org.truenas:origin": "backup"}
}
No Additional Items
Tuple Validation
Parameter 1: data
data
Type: objectClone parameters for cloning ZFS snapshots.
No Additional PropertiesSnapshot
Type: stringSource snapshot path to clone (e.g., 'pool/dataset@snapshot').
Must be at least 1 characters long
Dataset
Type: stringDestination dataset path for the clone (e.g., 'pool/clone').
Must be at least 1 characters long
ZFSResourceSnapshotCloneProperties
Type: objectZFS properties to set on the clone. A property left as null is not sent to ZFS and inherits as usual. Any property not in this model may not be set on a clone, and a property that applies only to a filesystem or only to a volume is refused for the other type.
On a filesystem clone an explicit 'acltype' also defaults the coupled acl properties. An nfsv4 acltype defaults 'aclinherit' to 'passthrough' while a posix or off acltype defaults both 'aclmode' and 'aclinherit' to 'discard'.
No Additional PropertiesAclinherit
Default: nullACL inheritance behavior for new files and directories.
Must be one of:
- "discard"
- "noallow"
- "restricted"
- "passthrough"
- "passthrough-x"
Aclmode
Default: nullHow ACLs are modified during chmod operations.
Must be one of:
- "discard"
- "groupmask"
- "passthrough"
- "restricted"
Acltype
Default: nullThe type of ACL to use (off, posix, or nfsv4).
Must be one of:
- "off"
- "posix"
- "nfsv4"
Atime
Default: nullWhether file access times are updated on read.
Must be one of:
- "off"
- "on"
Checksum
Default: nullChecksum algorithm used to verify data integrity.
Must be one of:
- "on"
- "off"
- "fletcher2"
- "fletcher4"
- "sha256"
- "sha512"
- "skein"
- "edonr"
- "blake3"
Compression
Default: nullCompression algorithm for the resource.
Must be one of:
- "on"
- "off"
- "lzjb"
- "gzip"
- "gzip-1"
- "gzip-2"
- "gzip-3"
- "gzip-4"
- "gzip-5"
- "gzip-6"
- "gzip-7"
- "gzip-8"
- "gzip-9"
- "zle"
- "lz4"
- "zstd"
- "zstd-1"
- "zstd-2"
- "zstd-3"
- "zstd-4"
- "zstd-5"
- "zstd-6"
- "zstd-7"
- "zstd-8"
- "zstd-9"
- "zstd-10"
- "zstd-11"
- "zstd-12"
- "zstd-13"
- "zstd-14"
- "zstd-15"
- "zstd-16"
- "zstd-17"
- "zstd-18"
- "zstd-19"
- "zstd-fast"
- "zstd-fast-1"
- "zstd-fast-2"
- "zstd-fast-3"
- "zstd-fast-4"
- "zstd-fast-5"
- "zstd-fast-6"
- "zstd-fast-7"
- "zstd-fast-8"
- "zstd-fast-9"
- "zstd-fast-10"
- "zstd-fast-20"
- "zstd-fast-30"
- "zstd-fast-40"
- "zstd-fast-50"
- "zstd-fast-60"
- "zstd-fast-70"
- "zstd-fast-80"
- "zstd-fast-90"
- "zstd-fast-100"
- "zstd-fast-500"
- "zstd-fast-1000"
Copies
Default: nullNumber of copies of data blocks to store (1, 2, or 3).
Value must be greater or equal to 1 and lesser or equal to 3
Dedup
Default: nullDeduplication setting for the resource.
Must be one of:
- "on"
- "off"
- "verify"
- "sha256"
- "sha256,verify"
- "sha512"
- "sha512,verify"
- "skein"
- "skein,verify"
- "edonr,verify"
- "blake3"
- "blake3,verify"
Exec
Default: nullWhether programs can be executed from the filesystem.
Must be one of:
- "off"
- "on"
Quota
Default: nullMaximum space the dataset and its descendants may consume. Takes a size as described for 'volsize'. 'none' or 0 removes the limit.
Readonly
Default: nullWhether the resource can be modified.
Must be one of:
- "off"
- "on"
Recordsize
Default: nullSuggested block size for files in the filesystem. Takes a size as described for 'volsize'.
Refquota
Default: nullMaximum space the dataset itself may consume. Takes a size as described for 'volsize'. 'none' or 0 removes the limit.
Refreservation
Default: nullMinimum space reserved for the clone itself, as a byte count or a size string such as '10G'. 'none' or 0 reserves nothing. 'auto' reserves the space a volume's size requires and is accepted for volume clones only.
Specific value:
"auto"
Reservation
Default: nullMinimum space reserved for the dataset and its descendants. Takes a size as described for 'volsize'. 'none' or 0 removes the reservation.
Snapdev
Default: nullSnapshot device visibility under /dev/zvol.
Must be one of:
- "hidden"
- "visible"
Snapdir
Default: nullVisibility of the .zfs/snapshot directory.
Must be one of:
- "hidden"
- "visible"
- "disabled"
Special Small Blocks
Default: nullSize threshold below which blocks are stored on the SPECIAL vdev. Takes a size as described for 'volsize'. 0 stores no data blocks on the SPECIAL vdev.
Sync
Default: nullSynchronous write behavior.
Must be one of:
- "standard"
- "always"
- "disabled"
Xattr
Default: nullExtended attribute storage mode. Defaults to 'sa' for performance.
Must be one of:
- "off"
- "sa"
- "dir"
User Properties
Type: object Default: {}User properties to set on the clone, keyed by their full name (e.g. 'org.truenas:custom'). A name must contain a colon, may consist only of lowercase letters, digits and the characters ':', '.', '_' and '-', and must be shorter than 256 characters. A value must be shorter than 8192 bytes.
Each additional property must conform to the following schema
Type: stringNo Mount
Type: boolean Default: falseDo not mount the clone after creating it. Volume clones are never mounted.
Result
Type: nullRequired roles: SNAPSHOT_WRITE