salt.modules.zpool

Module for running ZFS zpool command

codeauthor:	Nitin Madhok <nmadhok@clemson.edu>, Jorge Schrauwen <sjorge@blackdot.be>
maintainer:	Jorge Schrauwen <sjorge@blackdot.be>
maturity:	new
depends:	salt.utils.zfs
platform:	illumos,freebsd,linux

salt.modules.zpool.add(zpool, *vdevs, **kwargs)

Add the specified vdev's to the given storage pool

zpool : string

Name of storage pool

vdevs : string

One or more devices

force : boolean

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

zpool : string

Name of storage pool

device : string

Existing device name too

new_device : string

New device name (to be attached to device)

force : boolean

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.

zpool : string

name of storage pool

device : string

(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

zpool : string

Name of storage pool

vdevs : string

One or move devices

force : boolean

Forces use of vdevs, even if they appear in use or specify a conflicting replication level.

mountpoint : string

Sets the mount point for the root dataset

altroot : string

Equivalent to "-o cachefile=none,altroot=root"

properties : dict

Additional pool properties

filesystem_properties : dict

Additional filesystem properties

createboot : boolean

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

zpool : string

Name of storage pool

force : boolean

Force destroy of pool

CLI Example:

salt '*' zpool.destroy myzpool

salt.modules.zpool.detach(zpool, device)

Detach specified device to zpool

zpool : string

Name of storage pool

device : string

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

zpool : string

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

pools : string

One or more storage pools to export

force : boolean

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

zpool : string

Name of storage pool

prop : string

Optional name of property to retrieve

show_source : boolean

Show source of property

parsable : boolean

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

zpool : string

Optional storage pool

internal : boolean

Toggle display of internally logged ZFS events

verbose : boolean

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

zpool : string

Optional name of storage pool

new_name : string

Optional new name for the storage pool

mntopts : string

Comma-separated list of mount options to use when mounting datasets within the pool.

force : boolean

Forces import, even if the pool appears to be potentially active.

altroot : string

Equivalent to "-o cachefile=none,altroot=root"

dir : string

Searches for devices or files in dir, multiple dirs can be specified as follows: dir="dir1,dir2"

no_mount : boolean

Import the pool without mounting any file systems.

only_destroyed : boolean

Imports destroyed pools only. This also sets force=True.

recovery : bool|str

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.

properties : dict

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

zpool : string

optional name of storage pool

sample_time : int

seconds to capture data before output default a sample of 5 seconds is used

parsable : boolean

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

Device name; must not be part of an active pool configuration.

force : boolean

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

zpool : string

optional name of storage pool

properties : string

comma-separated list of properties to list

parsable : boolean

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

zpool : string

optional zpool

Note

Multiple storage pool can be provded 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.

zpool : string

name of storage pool

vdevs : string

One or more devices

temporary : boolean

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

zpool : string

name of storage pool

vdevs : string

one or more devices

expand : boolean

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.

zpool : string

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

zpool : string

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.

zpool : string

Name of storage pool

old_device : string

Old device to replace

new_device : string

Optional new device

force : boolean

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

zpool : string

Name of storage pool

stop : boolean

If True, cancel ongoing scrub

pause : boolean

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

zpool : string

Name of storage pool

prop : string

Name of property to set

value : string

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!

zpool : string

Name of storage pool

newzpool : string

Name of new storage pool

mountpoint : string

Sets the mount point for the root dataset

altroot : string

Sets altroot for newzpool

properties : dict

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

zpool : string

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

zpool : string

Optional storage pool, applies to all otherwize

version : int

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