salt.modules.zfs¶

Salt interface to ZFS commands

codeauthor:	Nitin Madhok <nmadhok@clemson.edu>

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

2016.3.0 新版功能.

Creates a bookmark of the given snapshot

注解

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.

snapshot : string: name of snapshot to bookmark
bookmark : string: name of bookmark

CLI Example:

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

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

2016.3.0 新版功能.

Creates a clone of the given snapshot.

name_a : string: name of snapshot
name_b : string: name of filesystem or volume
create_parent : boolean: creates all the non-existing parent datasets. any property specified on the command line using the -o option is ignored.
properties : dict: additional zfs properties (-o)

注解

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'}"

CLI Example:

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

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

2015.5.0 新版功能.

在 2016.3.0 版更改.

Create a ZFS File System.

name : string: name of dataset or volume
volume_size : string: if specified, a zvol will be created instead of a dataset
sparse : boolean: create sparse volume
create_parent : boolean: creates all the non-existing parent datasets. any property specified on the command line using the -o option is ignored.
properties : dict: additional zfs properties (-o)

注解

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

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)¶

2015.5.0 新版功能.

Destroy a ZFS File System.

name : string: name of dataset, volume, or snapshot
force : boolean: force an unmount of any file systems using the unmount -f command.
recursive : boolean: recursively destroy all children. (-r)
recursive_all : boolean: recursively destroy all dependents, including cloned file systems outside the target hierarchy. (-R)

警告

watch out when using recursive and recursive_all

CLI Example:

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

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

2016.3.0 新版功能.

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_a : string: name of snapshot
name_b : string: name of snapshot or filesystem
show_changetime : boolean: display the path's inode change time as the first column of output. (default = False)
show_indication : boolean: display an indication of the type of file. (default = True)

CLI Example:

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

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

2015.5.0 新版功能.

Check if a ZFS filesystem or volume or snapshot exists.

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

CLI Example:

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

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

2016.3.0 新版功能.

Displays properties for the given datasets.

*dataset : string: name of snapshot(s), filesystem(s), or volume(s)
properties : string: comma-separated list of properties to list, defaults to all
recursive : boolean: recursively list children
depth : int: recursively list children to depth
fields : string: comma-seperated list of fields to include, the name and property field will always be added
type : string: comma-separated list of types to display, where type is one of filesystem, snapshot, volume, bookmark, or all.
source : string: 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.

注解

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

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)¶

2016.3.0 新版功能.

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

注解

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.

tag : string: name of tag
*snapshot : string: name of snapshot(s)
recursive : boolean: specifies that a hold with the given tag is applied recursively to the snapshots of all descendent file systems.

注解

A comma-seperated list can be provided for the tag parameter to hold multiple tags.

CLI Example:

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

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

2016.3.0 新版功能.

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

snapshot : string: name of snapshot
recursive : boolean: lists the holds that are set on the named descendent snapshots also.

CLI Example:

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

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

2016.3.0 新版功能.

Clears the specified property

prop : string: name of property
name : string: name of the filesystem, volume, or snapshot
recursive : boolean: recursively inherit the given property for all children.
revert : boolean: revert the property to the received value if one exists; otherwise operate as if the -S option was not specified.

CLI Example:

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

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

2015.5.0 新版功能.

在 2016.3.0 版更改.

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

name : string: name of dataset, volume, or snapshot
recursive : boolean: recursively list children
depth : int: limit recursion to depth
properties : string: comma-seperated list of properties to list, the name property will always be added
type : string: comma-separated list of types to display, where type is one of filesystem, snapshot, volume, bookmark, or all.
sort : string: property to sort on (default = name)
order : string [ascending|descending]: sort order (default = ascending)

CLI Example:

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

salt.modules.zfs.mount(name='-a', **kwargs)¶

2016.3.0 新版功能.

Mounts ZFS file systems

name : string: name of the filesystem, you can use '-a' to mount all unmounted filesystems. (this is the default)
overlay : boolean: perform an overlay mount.
options : string: optional comma-separated list of mount options to use temporarily for the duration of the mount.

CLI Example:

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

salt.modules.zfs.promote(name)¶

2016.3.0 新版功能.

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

注解

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.

name : string: name of clone-filesystem

CLI Example:

salt '*' zfs.promote myzpool/myclone

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

2016.3.0 新版功能.

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

注解

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.

tag : string: name of tag
*snapshot : string: name of snapshot(s)
recursive : boolean: recursively releases a hold with the given tag on the snapshots of all descendent file systems.

注解

A comma-seperated list can be provided for the tag parameter to release multiple tags.

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)¶

2015.5.0 新版功能.

在 2016.3.0 版更改.

Rename or Relocate a ZFS File System.

name : string: name of dataset, volume, or snapshot
new_name : string: new name of dataset, volume, or snapshot
force : boolean: force unmount any filesystems that need to be unmounted in the process.
create_parent : boolean: creates all the nonexistent parent datasets. Datasets created in this manner are automatically mounted according to the mountpoint property inherited from their parent.
recursive : boolean: recursively rename the snapshots of all descendent datasets. snapshots are the only dataset that can be renamed recursively.

CLI Example:

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

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

2016.3.0 新版功能.

Roll back the given dataset to a previous snapshot.

警告

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.

name : string: name of snapshot
recursive : boolean: destroy any snapshots and bookmarks more recent than the one specified.
recursive_all : boolean: destroy any more recent snapshots and bookmarks, as well as any clones of those snapshots.
force : boolean: used with the -R option to force an unmount of any clone file systems that are to be destroyed.

CLI Example:

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

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

2016.3.0 新版功能.

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

*dataset : string: name of snapshot(s), filesystem(s), or volume(s)
*properties : string: additional zfs properties pairs

注解

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

compression=off

注解

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, Z (for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, or zettabytes, respectively).

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)¶

2016.3.0 新版功能.

Creates snapshots with the given names.

*snapshot : string: name of snapshot(s)
recursive : boolean: recursively create snapshots of all descendent datasets.
properties : dict: additional zfs properties (-o)

注解

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

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)¶

2016.3.0 新版功能.

Unmounts ZFS file systems

name : string: name of the filesystem, you can use '-a' to unmount all mounted filesystems.
force : boolean: forcefully unmount the file system, even if it is currently in use.

警告

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

CLI Example:

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