Module for running ZFS zpool command
Nitin Madhok <nmadhok@clemson.edu>, Jorge Schrauwen <sjorge@blackdot.be>
Jorge Schrauwen <sjorge@blackdot.be>
new
salt.utils.zfs
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.zpool.
add
(zpool, *vdevs, **kwargs)¶Add the specified vdev's to the given storage pool
Name of storage pool
One or more devices
Forces use of device
CLI Example:
salt '*' zpool.add myzpool /path/to/vdev1 /path/to/vdev2 [...]
salt.modules.zpool.
attach
(zpool, device, new_device, force=False)¶Attach specified device to zpool
Name of storage pool
Existing device name too
New device name (to be attached to device
)
Forces use of device
CLI Example:
salt '*' zpool.attach myzpool /path/to/vdev1 /path/to/vdev2 [...]
salt.modules.zpool.
clear
(zpool, device=None)¶Clears device errors in a pool.
Warning
The device must not be part of an active pool configuration.
name of storage pool
(optional) specific device to clear
New in version 2018.3.1.
CLI Example:
salt '*' zpool.clear mypool
salt '*' zpool.clear mypool /path/to/dev
salt.modules.zpool.
create
(zpool, *vdevs, **kwargs)¶New in version 2015.5.0.
Create a simple zpool, a mirrored zpool, a zpool having nested VDEVs, a hybrid zpool with cache, spare and log drives or a zpool with RAIDZ-1, RAIDZ-2 or RAIDZ-3
Name of storage pool
One or move devices
Forces use of vdevs, even if they appear in use or specify a conflicting replication level.
Sets the mount point for the root dataset
Equivalent to "-o cachefile=none,altroot=root"
Additional pool properties
Additional filesystem properties
create a boot partition
New in version 2018.3.0.
CLI Examples:
salt '*' zpool.create myzpool /path/to/vdev1 [...] [force=True|False]
salt '*' zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False]
salt '*' zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False]
salt '*' zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False]
salt '*' zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False]
Note
Zpool properties can be specified at the time of creation of the pool 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'}"
Filesystem properties can be specified at the time of creation of the pool by passing an additional argument called "filesystem_properties" and specifying the properties with their respective values in the form of a python dictionary:
filesystem_properties="{'property1': 'value1', 'property2': 'value2'}"
Example:
salt '*' zpool.create myzpool /path/to/vdev1 [...] properties="{'property1': 'value1', 'property2': 'value2'}"
CLI Example:
salt '*' zpool.create myzpool /path/to/vdev1 [...] [force=True|False]
salt '*' zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False]
salt '*' zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False]
salt '*' zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False]
salt '*' zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False]
salt.modules.zpool.
create_file_vdev
(size, *vdevs)¶Creates file based virtual devices for a zpool
CLI Example:
salt '*' zpool.create_file_vdev 7G /path/to/vdev1 [/path/to/vdev2] [...]
Note
Depending on file size, the above command may take a while to return.
salt.modules.zpool.
destroy
(zpool, force=False)¶Destroys a storage pool
Name of storage pool
Force destroy of pool
CLI Example:
salt '*' zpool.destroy myzpool
salt.modules.zpool.
detach
(zpool, device)¶Detach specified device to zpool
Name of storage pool
Device to detach
CLI Example:
salt '*' zpool.detach myzpool /path/to/vdev1
salt.modules.zpool.
exists
(zpool)¶Check if a ZFS storage pool is active
Name of storage pool
CLI Example:
salt '*' zpool.exists myzpool
salt.modules.zpool.
export
(*pools, **kwargs)¶New in version 2015.5.0.
Export storage pools
One or more storage pools to export
Force export of storage pools
CLI Example:
salt '*' zpool.export myzpool ... [force=True|False]
salt '*' zpool.export myzpool2 myzpool2 ... [force=True|False]
salt.modules.zpool.
get
(zpool, prop=None, show_source=False, parsable=True)¶New in version 2016.3.0.
Retrieves the given list of properties
Name of storage pool
Optional name of property to retrieve
Show source of property
Display numbers in parsable (exact) values
New in version 2018.3.0.
CLI Example:
salt '*' zpool.get myzpool
salt.modules.zpool.
healthy
()¶Check if all zpools are healthy
New in version 2016.3.0.
CLI Example:
salt '*' zpool.healthy
salt.modules.zpool.
history
(zpool=None, internal=False, verbose=False)¶New in version 2016.3.0.
Displays the command history of the specified pools, or all pools if no pool is specified
Optional storage pool
Toggle display of internally logged ZFS events
Toggle display of the user name, the hostname, and the zone in which the operation was performed
CLI Example:
salt '*' zpool.upgrade myzpool
salt.modules.zpool.
import_
(zpool=None, new_name=None, **kwargs)¶New in version 2015.5.0.
Import storage pools or list pools available for import
Optional name of storage pool
Optional new name for the storage pool
Comma-separated list of mount options to use when mounting datasets within the pool.
Forces import, even if the pool appears to be potentially active.
Equivalent to "-o cachefile=none,altroot=root"
Searches for devices or files in dir, multiple dirs can be specified as
follows: dir="dir1,dir2"
Import the pool without mounting any file systems.
Imports destroyed pools only. This also sets force=True
.
false: do not try to recovery broken pools true: try to recovery the pool by rolling back the latest transactions test: check if a pool can be recovered, but don't import it nolog: allow import without log device, recent transactions might be lost
Note
If feature flags are not support this forced to the default of 'false'
Warning
When recovery is set to 'test' the result will be have imported set to True if the pool can be imported. The pool might also be imported if the pool was not broken to begin with.
Additional pool properties
Note
Zpool properties can be specified at the time of creation of the pool 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 '*' zpool.import [force=True|False]
salt '*' zpool.import myzpool [mynewzpool] [force=True|False]
salt '*' zpool.import myzpool dir='/tmp'
salt.modules.zpool.
iostat
(zpool=None, sample_time=5, parsable=True)¶Display I/O statistics for the given pools
optional name of storage pool
seconds to capture data before output default a sample of 5 seconds is used
display data in pythonc values (True, False, Bytes,...)
New in version 2016.3.0.
Changed in version 2018.3.1: Added `parsable`
parameter that defaults to True
CLI Example:
salt '*' zpool.iostat myzpool
salt.modules.zpool.
labelclear
(device, force=False)¶New in version 2018.3.0.
Removes ZFS label information from the specified device
Device name; must not be part of an active pool configuration.
Treat exported or foreign devices as inactive
CLI Example:
salt '*' zpool.labelclear /path/to/dev
salt.modules.zpool.
list_
(properties='size, alloc, free, cap, frag, health', zpool=None, parsable=True)¶New in version 2015.5.0.
Return information about (all) storage pools
optional name of storage pool
comma-separated list of properties to list
display numbers in parsable (exact) values
New in version 2018.3.0.
Note
The name
property will always be included, while the frag
property will get removed if not available
optional zpool
Note
Multiple storage pool can be provided as a space separated list
CLI Example:
salt '*' zpool.list
salt '*' zpool.list zpool=tank
salt '*' zpool.list 'size,free'
salt '*' zpool.list 'size,free' tank
salt.modules.zpool.
offline
(zpool, *vdevs, **kwargs)¶New in version 2015.5.0.
Ensure that the specified devices are offline
Warning
By default, the OFFLINE
state is persistent. The device remains
offline when the system is rebooted. To temporarily take a device
offline, use temporary=True
.
name of storage pool
One or more devices
Enable temporarily offline
CLI Example:
salt '*' zpool.offline myzpool /path/to/vdev1 [...] [temporary=True|False]
salt.modules.zpool.
online
(zpool, *vdevs, **kwargs)¶New in version 2015.5.0.
Ensure that the specified devices are online
name of storage pool
one or more devices
Expand the device to use all available space.
Note
If the device is part of a mirror or raidz then all devices must be expanded before the new space will become available to the pool.
CLI Example:
salt '*' zpool.online myzpool /path/to/vdev1 [...]
salt.modules.zpool.
reguid
(zpool)¶Generates a new unique identifier for the pool
Warning
You must ensure that all devices in this pool are online and healthy before performing this action.
name of storage pool
New in version 2016.3.0.
CLI Example:
salt '*' zpool.reguid myzpool
salt.modules.zpool.
reopen
(zpool)¶Reopen all the vdevs associated with the pool
name of storage pool
New in version 2016.3.0.
CLI Example:
salt '*' zpool.reopen myzpool
salt.modules.zpool.
replace
(zpool, old_device, new_device=None, force=False)¶Replaces old_device
with new_device
Note
This is equivalent to attaching new_device
,
waiting for it to resilver, and then detaching old_device
.
The size of new_device
must be greater than or equal to the minimum
size of all the devices in a mirror or raidz configuration.
Name of storage pool
Old device to replace
Optional new device
Forces use of new_device, even if its appears to be in use.
CLI Example:
salt '*' zpool.replace myzpool /path/to/vdev1 /path/to/vdev2
salt.modules.zpool.
scrub
(zpool, stop=False, pause=False)¶Scrub a storage pool
Name of storage pool
If True
, cancel ongoing scrub
If True
, pause ongoing scrub
New in version 2018.3.0.
Note
Pause is only available on recent versions of ZFS.
If both pause
and stop
are True
, then stop
will
win.
CLI Example:
salt '*' zpool.scrub myzpool
salt.modules.zpool.
set
(zpool, prop, value)¶Sets the given property on the specified pool
Name of storage pool
Name of property to set
Value to set for the specified property
New in version 2016.3.0.
CLI Example:
salt '*' zpool.set myzpool readonly yes
salt.modules.zpool.
split
(zpool, newzpool, **kwargs)¶New in version 2018.3.0.
Splits devices off pool creating newpool.
Note
All vdevs in pool must be mirrors. At the time of the split,
newzpool
will be a replica of zpool
.
After splitting, do not forget to import the new pool!
Name of storage pool
Name of new storage pool
Sets the mount point for the root dataset
Sets altroot for newzpool
Additional pool properties for newzpool
CLI Examples:
salt '*' zpool.split datamirror databackup
salt '*' zpool.split datamirror databackup altroot=/backup
Note
Zpool properties can be specified at the time of creation of the pool 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'}"
Example:
salt '*' zpool.split datamirror databackup properties="{'readonly': 'on'}"
CLI Example:
salt '*' zpool.split datamirror databackup
salt '*' zpool.split datamirror databackup altroot=/backup
salt.modules.zpool.
status
(zpool=None)¶Return the status of the named zpool
optional name of storage pool
New in version 2016.3.0.
CLI Example:
salt '*' zpool.status myzpool
salt.modules.zpool.
upgrade
(zpool=None, version=None)¶New in version 2016.3.0.
Enables all supported features on the given pool
Optional storage pool, applies to all otherwize
Version to upgrade to, if unspecified upgrade to the highest possible
Warning
Once this is done, the pool will no longer be accessible on systems that do not support feature flags. See zpool-features(5) for details on compatibility with systems that support feature flags, but do not support all features enabled on the pool.
CLI Example:
salt '*' zpool.upgrade myzpool