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:

  • snapshot is not a snapshot path or dataset is 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)

  • dataset already 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"}
}
Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: data

data

Type: object

Clone parameters for cloning ZFS snapshots.

No Additional Properties

Snapshot

Type: string

Source snapshot path to clone (e.g., 'pool/dataset@snapshot').

Must be at least 1 characters long

Dataset

Type: string

Destination dataset path for the clone (e.g., 'pool/clone').

Must be at least 1 characters long

ZFSResourceSnapshotCloneProperties

Type: object

ZFS 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 Properties

Aclinherit

Default: null

ACL inheritance behavior for new files and directories.

Type: enum (of string)
Must be one of:
  • "discard"
  • "noallow"
  • "restricted"
  • "passthrough"
  • "passthrough-x"
Type: null

Aclmode

Default: null

How ACLs are modified during chmod operations.

Type: enum (of string)
Must be one of:
  • "discard"
  • "groupmask"
  • "passthrough"
  • "restricted"
Type: null

Acltype

Default: null

The type of ACL to use (off, posix, or nfsv4).

Type: enum (of string)
Must be one of:
  • "off"
  • "posix"
  • "nfsv4"
Type: null

Atime

Default: null

Whether file access times are updated on read.

Type: enum (of string)
Must be one of:
  • "off"
  • "on"
Type: null

Checksum

Default: null

Checksum algorithm used to verify data integrity.

Type: enum (of string)
Must be one of:
  • "on"
  • "off"
  • "fletcher2"
  • "fletcher4"
  • "sha256"
  • "sha512"
  • "skein"
  • "edonr"
  • "blake3"
Type: null

Compression

Default: null

Compression algorithm for the resource.

Type: enum (of string)
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"
Type: null

Copies

Default: null

Number of copies of data blocks to store (1, 2, or 3).

Type: integer

Value must be greater or equal to 1 and lesser or equal to 3

Type: null

Dedup

Default: null

Deduplication setting for the resource.

Type: enum (of string)
Must be one of:
  • "on"
  • "off"
  • "verify"
  • "sha256"
  • "sha256,verify"
  • "sha512"
  • "sha512,verify"
  • "skein"
  • "skein,verify"
  • "edonr,verify"
  • "blake3"
  • "blake3,verify"
Type: null

Exec

Default: null

Whether programs can be executed from the filesystem.

Type: enum (of string)
Must be one of:
  • "off"
  • "on"
Type: null

Quota

Default: null

Maximum space the dataset and its descendants may consume. Takes a size as described for 'volsize'. 'none' or 0 removes the limit.

Type: integer
Type: null

Readonly

Default: null

Whether the resource can be modified.

Type: enum (of string)
Must be one of:
  • "off"
  • "on"
Type: null

Recordsize

Default: null

Suggested block size for files in the filesystem. Takes a size as described for 'volsize'.

Type: integer
Type: null

Refquota

Default: null

Maximum space the dataset itself may consume. Takes a size as described for 'volsize'. 'none' or 0 removes the limit.

Type: integer
Type: null

Refreservation

Default: null

Minimum 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.

Type: integer
Type: const
Specific value: "auto"
Type: null

Reservation

Default: null

Minimum space reserved for the dataset and its descendants. Takes a size as described for 'volsize'. 'none' or 0 removes the reservation.

Type: integer
Type: null

Snapdev

Default: null

Snapshot device visibility under /dev/zvol.

Type: enum (of string)
Must be one of:
  • "hidden"
  • "visible"
Type: null

Snapdir

Default: null

Visibility of the .zfs/snapshot directory.

Type: enum (of string)
Must be one of:
  • "hidden"
  • "visible"
  • "disabled"
Type: null

Special Small Blocks

Default: null

Size 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.

Type: integer
Type: null

Sync

Default: null

Synchronous write behavior.

Type: enum (of string)
Must be one of:
  • "standard"
  • "always"
  • "disabled"
Type: null

Xattr

Default: null

Extended attribute storage mode. Defaults to 'sa' for performance.

Type: enum (of string)
Must be one of:
  • "off"
  • "sa"
  • "dir"
Type: null

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: string

No Mount

Type: boolean Default: false

Do not mount the clone after creating it. Volume clones are never mounted.

Result

Type: null


Required roles: SNAPSHOT_WRITE