community.general.beadm module – Manage ZFS boot environments on FreeBSD/Solaris/illumos systems

Note

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

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

Synopsis

  • Create, delete or activate ZFS boot environments.

  • Mount and unmount ZFS boot environments.

Parameters

Parameter

Comments

description

string

Associate a description with a new boot environment. This option is available only on Solarish platforms.

force

boolean

Specifies if the unmount should be forced.

Choices:

  • false ← (default)

  • true

mountpoint

path

Path where to mount the ZFS boot environment.

name

aliases: be

string / required

ZFS boot environment name.

options

string

Create the datasets for new BE with specific ZFS properties.

Multiple options can be specified.

This option is available only on Solarish platforms.

snapshot

string

If specified, the new boot environment will be cloned from the given snapshot or inactive boot environment.

state

string

Create or delete ZFS boot environment.

Choices:

  • "absent"

  • "activated"

  • "mounted"

  • "present" ← (default)

  • "unmounted"

Attributes

Attribute

Support

Description

check_mode

Support: full

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

diff_mode

Support: none

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

Examples

- name: Create ZFS boot environment
  community.general.beadm:
    name: upgrade-be
    state: present

- name: Create ZFS boot environment from existing inactive boot environment
  community.general.beadm:
    name: upgrade-be
    snapshot: be@old
    state: present

- name: Create ZFS boot environment with compression enabled and description "upgrade"
  community.general.beadm:
    name: upgrade-be
    options: "compression=on"
    description: upgrade
    state: present

- name: Delete ZFS boot environment
  community.general.beadm:
    name: old-be
    state: absent

- name: Mount ZFS boot environment on /tmp/be
  community.general.beadm:
    name: BE
    mountpoint: /tmp/be
    state: mounted

- name: Unmount ZFS boot environment
  community.general.beadm:
    name: BE
    state: unmounted

- name: Activate ZFS boot environment
  community.general.beadm:
    name: upgrade-be
    state: activated

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

description

string

BE description

Returned: always

Sample: "Upgrade from 9.0 to 10.0"

force

boolean

If forced action is wanted

Returned: always

Sample: false

mountpoint

string

BE mountpoint

Returned: always

Sample: "/mnt/be"

name

string

BE name

Returned: always

Sample: "pre-upgrade"

options

string

BE additional options

Returned: always

Sample: "compression=on"

snapshot

string

ZFS snapshot to create BE from

Returned: always

Sample: "rpool/ROOT/oi-hipster@fresh"

state

string

state of the target

Returned: always

Sample: "present"

Authors

  • Adam Števko (@xen0l)