- Blog
- Ansible community forum
- Documentation

Ansible Collections Documentation

# vbotka.freebsd.iocage module – FreeBSD iocage jail handling

Note

This module is part of the vbotka.freebsd collection (version 0.2.7).

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 vbotka.freebsd`. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: `vbotka.freebsd.iocage`.

## Synopsis

- The vbotka.freebsd.iocage module is wrapper to iocage command.

## Requirements

The below requirements are needed on the host that executes this module.

- lang/python >= 3.6

- sysutils/iocage

## Parameters

Parameter | Comments
--- | ---
args string | Additional arguments of vbotka.freebsd.iocage applied to the `state`. They will be applied to the sub-command create if the `state` is `basejail, thickjail, template, present`. If the same Ansible task also fetches a release as apart of the creation the arguments will not be applied to the sub-command fetch. Use separate task state=fetched and set `args` there if needed. Default: `""`
bupdate boolean | Update the fetch to the latest patch level when state=fetched. Fetch and install binary updates when `name` is defined. This will start the jail. Choices: `false` ← (default) `true`
clone_from string | Clone the jail `clone_from` to `name`. Use `properties` to configure the clone.
cmd string | Execute the command `cmd` inside the specified jail `name`.
components aliases: files, component list / elements=path | Uses a local file directory for the root directory instead of HTTP to downloads and/or updates releases.
name string | `name` of the jail. States `started, stopped, restarted` accept `ALL` to start, stop, or restart all jails. States `present, cloned, template, basejail, thickjail` will return `uuid` and `uuid_short` if `name` is `None` or empty.
pkglist path | Path to a JSON file containing packages to install. Only applicable when creating a jail.
plugin string | Specify which plugin to fetch or update.
properties dictionary | `properties` of the jail. The jail will restart if any of the properties ip4_addr, ip6_addr, template, interfaces, vnet, host_hostname changes.
release string | Specify which RELEASE to fetch, update, or create a jail from. `release` defaults to the release of the remote host if `state` is one of `basejail, thickjail, template, fetched, present`. `release` also defaults to the release of the remote host if `bupdate=True`.
state string | `state` of the desired result. State `absent` by default force the destruction `iocage destroy --force name`. Choices: `"absent"` `"basejail"` `"cloned"` `"exec"` `"facts"` ← (default) `"fetched"` `"get"` `"pkg"` `"present"` `"restarted"` `"set"` `"started"` `"stopped"` `"template"` `"thickjail"`
user string | `user` who runs the command `cmd`. Default: `"root"`

## Notes

Note

- Supports `check_mode`.

- There is no mandatory option.

- The module always creates facts iocage_releases, iocage_templates, and iocage_jails

- Returns module_args when debugging is set `ANSIBLE_DEBUG=true`

## See Also

See also

iocage - A FreeBSD Jail Manager

  iocage 1.2 documentation

iocage - jail manager using ZFS and VNET

  FreeBSD System Manager’s Manual

## Examples

    - name: Create Ansible facts iocage_*. This is the default state.
      vbotka.freebsd.iocage:
        state: facts

    - name: Display lists of bases, plugins, templates, and jails
      debug:
        msg: |-
          {{ iocage_releases }}
          {{ iocage_plugins.keys()|list }}
          {{ iocage_templates.keys()|list }}
          {{ iocage_jails.keys()|list }}

    - name: Fetch the remote host's version of base
      vbotka.freebsd.iocage:
        state: fetched

    - name: Fetch base 13.0-RELEASE
      vbotka.freebsd.iocage:
        state: fetched
        release: 13.0-RELEASE

    - name: Fetch only components base.txz and doc.txz of the base 13.0-RELEASE
      vbotka.freebsd.iocage:
        state: fetched
        release: 13.0-RELEASE
        components: 'base.txz,doc.txz'

    - name: Fetch plugin Tarsnap. Keep jails on failure.
      vbotka.freebsd.iocage:
        state: fetched
        plugin: Tarsnap
        args: -k

    - name: Update or fetch components base.txz and doc.txz of the remote host's release.
            Fetch plugin Tarsnap. Keep jails on failure.
      vbotka.freebsd.iocage:
        state: fetched
        bupdate: true
        components: 'base.txz,doc.txz'
        plugin: Tarsnap
        args: -k

    - name: Update the jail. This will start the jail.
      vbotka.freebsd.iocage:
        state: present
        bupdate: true
        name: foo

    - name: Start jail
      vbotka.freebsd.iocage:
        state: started
        name: foo

    - name: Start all jails
      vbotka.freebsd.iocage:
        state: started
        name: ALL

    - name: Start all jails with boot=on
      vbotka.freebsd.iocage:
        state: started
        args: '--rc'

    - name: Stop jail
      vbotka.freebsd.iocage:
        state: stopped
        name: foo

    - name: Stop all jails
      vbotka.freebsd.iocage:
        state: stopped
        name: ALL

    - name: Stop all jails with boot=on
      vbotka.freebsd.iocage:
        state: stopped
        args: '--rc'

    - name: Restart jail
      vbotka.freebsd.iocage:
        state: restarted
        name: foo

    - name: Restart all jails
      vbotka.freebsd.iocage:
        state: restarted
        name: ALL

    - name: Set IP address of the jail
      vbotka.freebsd.iocage:
        state: set
        name: foo
        properties:
          vnet: 'on'
          defaultrouter: 10.1.0.10
          ip4_addr: 'vnet0|10.1.0.199/24'

    - name: Create jail without cloning, install packages, and set properties.
            Use release of the remote host.
      vbotka.freebsd.iocage:
        state: present
        name: foo
        pkglist: /path/to/pkglist.json
        properties:
          ip4_addr: 'vnet0|10.1.0.199/24'
          boot: true
          allow_sysvipc: true
          defaultrouter: '10.1.0.1'

    - name: Create template, install packages, and set properties.
            Use release of the remote host.
      vbotka.freebsd.iocage:
        state: template
        name: tplfoo
        pkglist: /path/to/pkglist.json
        properties:
          ip4_addr: 'lo1|10.1.0.5'
          boot: true
          allow_sysvipc: true
          defaultrouter: '10.1.0.1'

    - name: Create a cloned jail. Creates basejail if needed.
      vbotka.freebsd.iocage:
        state: present
        name: foo
        clone_from: tplfoo
        pkglist: /path/to/pkglist.json
        properties:
          ip4_addr: 'lo1|10.1.0.5'
          boot: true
          allow_sysvipc: true
          defaultrouter: '10.1.0.1'

    - name: Create a cloned jail. Name is automatically generated.
      vbotka.freebsd.iocage:
        state: present
        clone_from: tplfoo
      register: result
    - name: Set variable contains the name of the created jail.
      set_fact:
        jname: "{{ result.uuid_short }}"

    - name: Execute command in running jail
      vbotka.freebsd.iocage:
        state: exec
        name: foo
        cmd: service sshd start

    - name: Execute pkg command in running jail
      vbotka.freebsd.iocage:
        state: pkg
        name: foo
        cmd: info

    - name: Destroy jail
      vbotka.freebsd.iocage:
        state: absent
        name: foo

## Returned Facts

Facts returned by this module are added/updated in the `hostvars` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.

Key | Description
--- | ---
iocage_jails dictionary | Dictionary of all jails. Returned: always Sample: `{}`
iocage_plugins dictionary | Dictionary of all plugins. Returned: always Sample: `{}`
iocage_releases list / elements=string | List of all bases. Returned: always Sample: `["13.3-RELEASE", "13.4-RELEASE"]`
iocage_templates dictionary | Dictionary of all templates. Returned: always Sample: `{}`

## Return Values

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

Key | Description
--- | ---
module_args dictionary | Information on how the module was invoked. Returned: debug
uuid string | Automatically generated unique ID of a jail. Returned: States present, cloned, template, basejail, thickjail if name is `None` or empty.
uuid_short string | First 8 characters of uuid. Set as a name of the jail. Returned: States present, cloned, template, basejail, thickjail if name is `None` or empty.

### Authors

- Johannes Meixner (@xmj)

- Vladimir Botka (@vbotka)

- dgeo (@dgeo)

- Berend de Boer (@berenddeboer)

- Dr Josef Karthauser (@Infiniverse)

- Kevin P. Fleming (@kpfleming)

- Ross Williams (@overhacked)

- david8001 (@david8001)

- luto (@luto)

- Keve Müller (@kevemueller)

- Mårten Lindblad (@martenlindblad)

### Collection links

- Issue Tracker
- Homepage
- Repository (Sources)