community.general.zfs module – Manage ZFS

Note

This module is part of the community.general collection (version 14.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.zfs.

Synopsis

  • Manages ZFS file systems, volumes, clones and snapshots.

Parameters

Parameter

Comments

create_only_mismatch

string

added in community.general 14.0.0

What to do when the dataset already exists and the current value of a property that can only be set at creation time differs from the one requested in extra_zfs_properties.

Choices:

  • "fail" (default): Make the module fail.

  • "ignore": Silently leave the property unchanged.

  • "warn": Issue a warning and leave the property unchanged.

extra_zfs_properties

dictionary

A dictionary of zfs properties to be set.

See the zfs(8) man page for more information.

Properties that can only be set when the dataset is created (casesensitivity, encryption, keyformat, normalization, pbkdf2iters, utf8only, volblocksize) are not changed if the dataset already exists. See create_only_mismatch for what happens if their current value differs from the requested one.

Values of size properties (quota, recordsize, refquota, refreservation, reservation, special_small_blocks, volblocksize, volsize) written in human-readable notation, such as 4k or 1.5G, are compared to the current value as byte counts.

Default: {}

name

string / required

File system, snapshot or volume name, for example rpool/myfs.

origin

string

Snapshot from which to create a clone.

state

string / required

Whether to create (present), or remove (absent) a file system, snapshot or volume. All parents/children are created/destroyed as needed to reach the desired state.

Choices:

  • "absent"

  • "present"

Attributes

Attribute

Support

Description

check_mode

Support: partial

In certain situations it may report a task as changed that is not reported as changed when check_mode is disabled.

For example, this might occur when the zpool altroot option is set.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: full

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Create a new file system called myfs in pool rpool with the setuid property turned off
  community.general.zfs:
    name: rpool/myfs
    state: present
    extra_zfs_properties:
      setuid: 'off'

- name: Create a new volume called myvol in pool rpool.
  community.general.zfs:
    name: rpool/myvol
    state: present
    extra_zfs_properties:
      volsize: 10M

- name: Create a snapshot of rpool/myfs file system.
  community.general.zfs:
    name: rpool/myfs@mysnapshot
    state: present

- name: Create a new file system called myfs2 with snapdir enabled
  community.general.zfs:
    name: rpool/myfs2
    state: present
    extra_zfs_properties:
      snapdir: enabled

- name: Create a new file system by cloning a snapshot
  community.general.zfs:
    name: rpool/cloned_fs
    state: present
    origin: rpool/myfs@mysnapshot

- name: Destroy a filesystem
  community.general.zfs:
    name: rpool/myfs
    state: absent

Authors

  • Johan Wiren (@johanwiren)