# salt.modules.zpool

Module for running ZFS zpool 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.zpool.add(zpool, *vdevs, **kwargs)

  Add the specified vdev's to the given storage pool

  zpoolstring

    Name of storage pool

  vdevsstring

    One or more devices

  forceboolean

    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

  zpoolstring

    Name of storage pool

  devicestring

    Existing device name too

  new_devicestring

    New device name (to be attached to `device`)

  forceboolean

    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.

  zpoolstring

    name of storage pool

  devicestring

    (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

  zpoolstring

    Name of storage pool

  vdevsstring

    One or move devices

  forceboolean

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

  mountpointstring

    Sets the mount point for the root dataset

  altrootstring

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

  propertiesdict

    Additional pool properties

  filesystem_propertiesdict

    Additional filesystem properties

  createbootboolean

    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

  zpoolstring

    Name of storage pool

  forceboolean

    Force destroy of pool

  CLI Example:

      salt '*' zpool.destroy myzpool

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

  Detach specified device to zpool

  zpoolstring

    Name of storage pool

  devicestring

    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

  zpoolstring

    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

  poolsstring

    One or more storage pools to export

  forceboolean

    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

  zpoolstring

    Name of storage pool

  propstring

    Optional name of property to retrieve

  show_sourceboolean

    Show source of property

  parsableboolean

    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

  zpoolstring

    Optional storage pool

  internalboolean

    Toggle display of internally logged ZFS events

  verboseboolean

    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

  zpoolstring

    Optional name of storage pool

  new_namestring

    Optional new name for the storage pool

  mntoptsstring

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

  forceboolean

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

  altrootstring

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

  dirstring

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

  no_mountboolean

    Import the pool without mounting any file systems.

  only_destroyedboolean

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

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

  propertiesdict

    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

  zpoolstring

    optional name of storage pool

  sample_timeint

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

  parsableboolean

    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

  devicestring

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

  forceboolean

    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

  zpoolstring

    optional name of storage pool

  propertiesstring

    comma-separated list of properties to list

  parsableboolean

    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

  zpoolstring

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

  zpoolstring

    name of storage pool

  vdevsstring

    One or more devices

  temporaryboolean

    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

  zpoolstring

    name of storage pool

  vdevsstring

    one or more devices

  expandboolean

    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.

  zpoolstring

    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

  zpoolstring

    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.

  zpoolstring

    Name of storage pool

  old_devicestring

    Old device to replace

  new_devicestring

    Optional new device

  forceboolean

    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

  zpoolstring

    Name of storage pool

  stopboolean

    If `True`, cancel ongoing scrub

  pauseboolean

    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

  zpoolstring

    Name of storage pool

  propstring

    Name of property to set

  valuestring

    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!

  zpoolstring

    Name of storage pool

  newzpoolstring

    Name of new storage pool

  mountpointstring

    Sets the mount point for the root dataset

  altrootstring

    Sets altroot for newzpool

  propertiesdict

    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

  zpoolstring

    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

  zpoolstring

    Optional storage pool, applies to all otherwize

  versionint

    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