freebsd_zfs

This role is included in the collection vbotka.freebsd as vbotka.freebsd.zfs

Ansible role. FreeBSD. Configure ZFS.

Feel free to share your feedback and report issues.

Contributions are welcome.

Requirements

Collections

• community.general
• vbotka.freebsd

Roles

• vbotka.freebsd.postinstall

This role, included in the collection vbotka.freebsd, is needed to run tasks from sysctl.yml. Instead of the collection vbotka.freebsd, you can install and use the role vbotka.freebsd_postinstall. Edit the tasks sysctl.yml:

  ansible.builtin.include_role:
    name: vbotka.freebsd_postinstall

If you install and use vbotka.freebsd_postinstall, remove vbotka.freebsd from the collections in meta/main.yml. Then, the role can be used without the collection vbotka.freebsd.

Variables

See defaults and examples in vars.

Workflow

1. Change the shell on the remote host to /bin/sh if necessary

shell> ansible host -e ansible_shell_type=csh -e ansible_shell_executable=/bin/csh -a 'sudo pw usermod user -s /bin/sh'

2. Install the roles and collections

shell> ansible-galaxy role install vbotka.freebsd_zfs
shell> ansible-galaxy role install vbotka.freebsd_postinstall

If necessary install the collection

shell> ansible-galaxy collection install community.general

3. Fit variables to your needs.

4. Create the playbook

shell> cat freebsd-zfs.yml
- hosts: host
  roles:
    - vbotka.freebsd_zfs

5. Configure the system

shell> ansible-playbook freebsd-zfs.yml

Ansible lint

Use the configuration file .ansible-lint.local when running ansible-lint. Some rules might be disabled and some warnings might be ignored. See the notes in the configuration file.

shell> ansible-lint -c .ansible-lint.local

Known issues

community.general.zpool

The module community.general.zpool can't create correct diff. For example,

(Pdb) p vdev_layout_diff
{'before': {'vdevs': [{'type': 'stripe', 'disks': ['/dev/ada2']}, {'type': 'stripe', 'disks': ['/dev/ada3']}]},
 'after': {'vdevs': [{'type': 'stripe', 'disks': ['/dev/ada2', '/dev/ada3']}]}}

This makes the module not idempotent. It crashes when running repeatedly. For example,

failed: [srv.example.org] (item=iocage) =>
    ansible_loop_var: item
    changed: false
    cmd: /sbin/zpool add iocage /dev/ada2 /dev/ada3
    item:
        key: iocage
        value:
            vdevs:
            -   disks:
                - /dev/ada2
                - /dev/ada3
    msg: |-
        invalid vdev specification
        use '-f' to override the following errors:
        /dev/ada2 is part of active pool 'iocage'
        /dev/ada3 is part of active pool 'iocage'
    rc: 1
    ...

Setting force: true doesn't help. At the moment, the only workaround is to skip the module if the pool already exists. You'll see a warning. For example,

TASK [vbotka.freebsd_zfs : Pools: WARNING | community.general.zpool skipped.] ****
ok: [srv.example.org] =>
    msg: |-
        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        # WARNING:
        #
        # The module community.general.zpool is not idempotent. It crashes
        # when running repeatedly. Because of the poor quality, the module
        # community.general.zpool will be skipped for pools:
        # ['iocage']
        #
        # Configure the skipped pools manually, if necessary.
        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

References

• FreeBSD handbook: The Z File System (ZFS)
• FreeBSD wiki: ZFS
• FreeBSD wiki: ZFS Quick Start Guide
• FreeBSD wiki: ZFS Tuning Guide
• FreeBSD wiki: Category ZFS

License

Author Information

Vladimir Botka