# salt.modules.zfs

Module for running ZFS command

codeauthor:

  Nitin Madhok <nmadhok@g.clemson.edu>, Jorge Schrauwen <sjorge@blackdot.be>

maintainer:

  Jorge Schrauwen <sjorge@blackdot.be>

maturity:

  new

depends:

  salt.utils.zfs

platform:

  illumos,freebsd,linux

Changed in version 2018.3.1: Big refactor to remove duplicate code, better type conversions and improved consistency in output.

salt.modules.zfs.bookmark(snapshot, bookmark)

  Creates a bookmark of the given snapshot

  Note

  Bookmarks mark the point in time when the snapshot was created, and can be used as the incremental source for a zfs send command.

  This feature must be enabled to be used. See zpool-features(5) for details on ZFS feature flags and the bookmarks feature.

  snapshotstring

    name of snapshot to bookmark

  bookmarkstring

    name of bookmark

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.bookmark myzpool/mydataset@yesterday myzpool/mydataset#complete

salt.modules.zfs.clone(name_a, name_b, **kwargs)

  Creates a clone of the given snapshot.

  name_astring

    name of snapshot

  name_bstring

    name of filesystem or volume

  create_parentboolean

    creates all the non-existing parent datasets. any property specified on the command line using the -o option is ignored.

  propertiesdict

    additional zfs properties (-o)

  Note

  ZFS properties can be specified at the time of creation of the filesystem by passing an additional argument called "properties" and specifying the properties with their respective values in the form of a python dictionary:

      properties="{'property1': 'value1', 'property2': 'value2'}"

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.clone myzpool/mydataset@yesterday myzpool/mydataset_yesterday

salt.modules.zfs.create(name, **kwargs)

  Create a ZFS File System.

  namestring

    name of dataset or volume

  volume_sizestring

    if specified, a zvol will be created instead of a dataset

  sparseboolean

    create sparse volume

  create_parentboolean

    creates all the non-existing parent datasets. any property specified on the command line using the -o option is ignored.

  propertiesdict

    additional zfs properties (-o)

  Note

  ZFS properties can be specified at the time of creation of the filesystem by passing an additional argument called "properties" and specifying the properties with their respective values in the form of a python dictionary:

      properties="{'property1': 'value1', 'property2': 'value2'}"

  Added in version 2015.5.0.

  CLI Example:

      salt '*' zfs.create myzpool/mydataset [create_parent=True|False]
      salt '*' zfs.create myzpool/mydataset properties="{'mountpoint': '/export/zfs', 'sharenfs': 'on'}"
      salt '*' zfs.create myzpool/volume volume_size=1G [sparse=True|False]`
      salt '*' zfs.create myzpool/volume volume_size=1G properties="{'volblocksize': '512'}" [sparse=True|False]

salt.modules.zfs.destroy(name, **kwargs)

  Destroy a ZFS File System.

  namestring

    name of dataset, volume, or snapshot

  forceboolean

    force an unmount of any file systems using the unmount -f command.

  recursiveboolean

    recursively destroy all children. (-r)

  recursive_allboolean

    recursively destroy all dependents, including cloned file systems outside the target hierarchy. (-R)

  Warning

  watch out when using recursive and recursive_all

  Added in version 2015.5.0.

  CLI Example:

      salt '*' zfs.destroy myzpool/mydataset [force=True|False]

salt.modules.zfs.diff(name_a, name_b=None, **kwargs)

  Display the difference between a snapshot of a given filesystem and another snapshot of that filesystem from a later time or the current contents of the filesystem.

  name_astring

    name of snapshot

  name_bstring

    (optional) name of snapshot or filesystem

  show_changetimeboolean

    display the path's inode change time as the first column of output. (default = True)

  show_indicationboolean

    display an indication of the type of file. (default = True)

  parsableboolean

    if true we don't parse the timestamp to a more readable date (default = True)

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.diff myzpool/mydataset@yesterday myzpool/mydataset

salt.modules.zfs.exists(name, **kwargs)

  Check if a ZFS filesystem or volume or snapshot exists.

  namestring

    name of dataset

  typestring

    also check if dataset is of a certain type, valid choices are: filesystem, snapshot, volume, bookmark, or all.

  Added in version 2015.5.0.

  CLI Example:

      salt '*' zfs.exists myzpool/mydataset
      salt '*' zfs.exists myzpool/myvolume type=volume

salt.modules.zfs.get(*dataset, **kwargs)

  Displays properties for the given datasets.

  datasetstring

    name of snapshot(s), filesystem(s), or volume(s)

  propertiesstring

    comma-separated list of properties to list, defaults to all

  recursiveboolean

    recursively list children

  depthint

    recursively list children to depth

  fieldsstring

    comma-separated list of fields to include, the name and property field will always be added

  typestring

    comma-separated list of types to display, where type is one of filesystem, snapshot, volume, bookmark, or all.

    Changed in version 3004.

    type is ignored on Solaris 10 and 11 since not a valid parameter on those platforms

  sourcestring

    comma-separated list of sources to display. Must be one of the following: local, default, inherited, temporary, and none. The default value is all sources.

  parsableboolean

    display numbers in parsable (exact) values (default = True) .. versionadded:: 2018.3.0

  Note

  If no datasets are specified, then the command displays properties for all datasets on the system.

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.get
      salt '*' zfs.get myzpool/mydataset [recursive=True|False]
      salt '*' zfs.get myzpool/mydataset properties="sharenfs,mountpoint" [recursive=True|False]
      salt '*' zfs.get myzpool/mydataset myzpool/myotherdataset properties=available fields=value depth=1

salt.modules.zfs.hold(tag, *snapshot, **kwargs)

  Adds a single reference, named with the tag argument, to the specified snapshot or snapshots.

  Note

  Each snapshot has its own tag namespace, and tags must be unique within that space.

  If a hold exists on a snapshot, attempts to destroy that snapshot by using the zfs destroy command return EBUSY.

  tagstring

    name of tag

  snapshotstring

    name of snapshot(s)

  recursiveboolean

    specifies that a hold with the given tag is applied recursively to the snapshots of all descendent file systems.

  Added in version 2016.3.0.

  Changed in version 2018.3.1.

  Warning

  As of 2018.3.1 the tag parameter no longer accepts a comma-separated value. It's is now possible to create a tag that contains a comma, this was impossible before.

  CLI Example:

      salt '*' zfs.hold mytag myzpool/mydataset@mysnapshot [recursive=True]
      salt '*' zfs.hold mytag myzpool/mydataset@mysnapshot myzpool/mydataset@myothersnapshot

salt.modules.zfs.holds(snapshot, **kwargs)

  Lists all existing user references for the given snapshot or snapshots.

  snapshotstring

    name of snapshot

  recursiveboolean

    lists the holds that are set on the named descendent snapshots also.

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.holds myzpool/mydataset@baseline

salt.modules.zfs.inherit(prop, name, **kwargs)

  Clears the specified property

  propstring

    name of property

  namestring

    name of the filesystem, volume, or snapshot

  recursiveboolean

    recursively inherit the given property for all children.

  revertboolean

    revert the property to the received value if one exists; otherwise operate as if the -S option was not specified.

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.inherit canmount myzpool/mydataset [recursive=True|False]

salt.modules.zfs.list_(name=None, **kwargs)

  Return a list of all datasets or a specified dataset on the system and the values of their used, available, referenced, and mountpoint properties.

  namestring

    name of dataset, volume, or snapshot

  recursiveboolean

    recursively list children

  depthint

    limit recursion to depth

  propertiesstring

    comma-separated list of properties to list, the name property will always be added

  typestring

    comma-separated list of types to display, where type is one of filesystem, snapshot, volume, bookmark, or all.

  sortstring

    property to sort on (default = name)

  orderstring [ascending|descending]

    sort order (default = ascending)

  parsableboolean

    display numbers in parsable (exact) values .. versionadded:: 2018.3.0

  Added in version 2015.5.0.

  CLI Example:

      salt '*' zfs.list
      salt '*' zfs.list myzpool/mydataset [recursive=True|False]
      salt '*' zfs.list myzpool/mydataset properties="sharenfs,mountpoint"

salt.modules.zfs.list_mount()

  List mounted zfs filesystems

  Added in version 2018.3.1.

  CLI Example:

      salt '*' zfs.list_mount

salt.modules.zfs.mount(name=None, **kwargs)

  Mounts ZFS file systems

  namestring

    name of the filesystem, having this set to None will mount all filesystems. (this is the default)

  overlayboolean

    perform an overlay mount.

  optionsstring

    optional comma-separated list of mount options to use temporarily for the duration of the mount.

  Added in version 2016.3.0.

  Changed in version 2018.3.1.

  Warning

  Passing '-a' as name is deprecated and will be removed in 3001.

  CLI Example:

      salt '*' zfs.mount
      salt '*' zfs.mount myzpool/mydataset
      salt '*' zfs.mount myzpool/mydataset options=ro

salt.modules.zfs.promote(name)

  Promotes a clone file system to no longer be dependent on its "origin" snapshot.

  Note

  This makes it possible to destroy the file system that the clone was created from. The clone parent-child dependency relationship is reversed, so that the origin file system becomes a clone of the specified file system.

  The snapshot that was cloned, and any snapshots previous to this snapshot, are now owned by the promoted clone. The space they use moves from the origin file system to the promoted clone, so enough space must be available to accommodate these snapshots. No new space is consumed by this operation, but the space accounting is adjusted. The promoted clone must not have any conflicting snapshot names of its own. The rename subcommand can be used to rename any conflicting snapshots.

  namestring

    name of clone-filesystem

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.promote myzpool/myclone

salt.modules.zfs.release(tag, *snapshot, **kwargs)

  Removes a single reference, named with the tag argument, from the specified snapshot or snapshots.

  Note

  The tag must already exist for each snapshot. If a hold exists on a snapshot, attempts to destroy that snapshot by using the zfs destroy command return EBUSY.

  tagstring

    name of tag

  snapshotstring

    name of snapshot(s)

  recursiveboolean

    recursively releases a hold with the given tag on the snapshots of all descendent file systems.

  Added in version 2016.3.0.

  Changed in version 2018.3.1.

  Warning

  As of 2018.3.1 the tag parameter no longer accepts a comma-separated value. It's is now possible to create a tag that contains a comma, this was impossible before.

  CLI Example:

      salt '*' zfs.release mytag myzpool/mydataset@mysnapshot [recursive=True]
      salt '*' zfs.release mytag myzpool/mydataset@mysnapshot myzpool/mydataset@myothersnapshot

salt.modules.zfs.rename(name, new_name, **kwargs)

  Rename or Relocate a ZFS File System.

  namestring

    name of dataset, volume, or snapshot

  new_namestring

    new name of dataset, volume, or snapshot

  forceboolean

    force unmount any filesystems that need to be unmounted in the process.

  create_parentboolean

    creates all the nonexistent parent datasets. Datasets created in this manner are automatically mounted according to the mountpoint property inherited from their parent.

  recursiveboolean

    recursively rename the snapshots of all descendent datasets. snapshots are the only dataset that can be renamed recursively.

  Added in version 2015.5.0.

  CLI Example:

      salt '*' zfs.rename myzpool/mydataset myzpool/renameddataset

salt.modules.zfs.rollback(name, **kwargs)

  Roll back the given dataset to a previous snapshot.

  namestring

    name of snapshot

  recursiveboolean

    destroy any snapshots and bookmarks more recent than the one specified.

  recursive_allboolean

    destroy any more recent snapshots and bookmarks, as well as any clones of those snapshots.

  forceboolean

    used with the -R option to force an unmount of any clone file systems that are to be destroyed.

  Warning

  When a dataset is rolled back, all data that has changed since the snapshot is discarded, and the dataset reverts to the state at the time of the snapshot. By default, the command refuses to roll back to a snapshot other than the most recent one.

  In order to do so, all intermediate snapshots and bookmarks must be destroyed by specifying the -r option.

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.rollback myzpool/mydataset@yesterday

salt.modules.zfs.set(*dataset, **kwargs)

  Sets the property or list of properties to the given value(s) for each dataset.

  datasetstring

    name of snapshot(s), filesystem(s), or volume(s)

  propertiesstring

    additional zfs properties pairs

  Note

  properties are passed as key-value pairs. e.g.

  > compression=off

  Note

  Only some properties can be edited.

  See the Properties section for more information on what properties can be set and acceptable values.

  Numeric values can be specified as exact values, or in a human-readable form with a suffix of B, K, M, G, T, P, E (for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, or exabytes respectively).

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.set myzpool/mydataset compression=off
      salt '*' zfs.set myzpool/mydataset myzpool/myotherdataset compression=off
      salt '*' zfs.set myzpool/mydataset myzpool/myotherdataset compression=lz4 canmount=off

salt.modules.zfs.snapshot(*snapshot, **kwargs)

  Creates snapshots with the given names.

  snapshotstring

    name of snapshot(s)

  recursiveboolean

    recursively create snapshots of all descendent datasets.

  propertiesdict

    additional zfs properties (-o)

  Note

  ZFS properties can be specified at the time of creation of the filesystem by passing an additional argument called "properties" and specifying the properties with their respective values in the form of a python dictionary:

      properties="{'property1': 'value1', 'property2': 'value2'}"

  Added in version 2016.3.0.

  CLI Example:

      salt '*' zfs.snapshot myzpool/mydataset@yesterday [recursive=True]
      salt '*' zfs.snapshot myzpool/mydataset@yesterday myzpool/myotherdataset@yesterday [recursive=True]

salt.modules.zfs.unmount(name, **kwargs)

  Unmounts ZFS file systems

  namestring

    name of the filesystem, you can use None to unmount all mounted filesystems.

  forceboolean

    forcefully unmount the file system, even if it is currently in use.

  Warning

  Using `-a` for the name parameter will probably break your system, unless your rootfs is not on zfs.

  Added in version 2016.3.0.

  Changed in version 2018.3.1.

  Warning

  Passing '-a' as name is deprecated and will be removed in 3001.

  CLI Example:

      salt '*' zfs.unmount myzpool/mydataset [force=True|False]