- Blog
- Ansible community forum
- Documentation

Ansible Collections Documentation

# vbotka.freebsd.iocage inventory – iocage inventory source

Note

This inventory plugin 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 inventory plugin, see Requirements for details.

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

New in vbotka.freebsd 10.2.0

## Synopsis

- Get inventory hosts from the iocage jail manager.

- Uses a configuration file as an inventory source, it must end in `.iocage.yml` or `.iocage.yaml`.

## Requirements

The below requirements are needed on the local controller node that executes this inventory.

- iocage >= 1.8

## Parameters

Parameter | Comments
--- | ---
- cache boolean | Toggle to enable/disable the caching of the inventory’s source data, requires a cache plugin setup to work. Choices: `false` ← (default) `true` Configuration: INI entry:
      [inventory]
      cache = false
Environment variable: `ANSIBLE_INVENTORY_CACHE`
- cache_connection string | Cache connection data or path, read cache plugin documentation for specifics. Configuration: INI entries:
      [defaults]
      fact_caching_connection = VALUE
      [inventory]
      cache_connection = VALUE
Environment variable: `ANSIBLE_CACHE_PLUGIN_CONNECTION` Environment variable: `ANSIBLE_INVENTORY_CACHE_CONNECTION`
- cache_plugin string | Cache plugin to use for the inventory’s source data. Default: `"memory"` Configuration: INI entries:
      [defaults]
      fact_caching = memory
      [inventory]
      cache_plugin = memory
Environment variable: `ANSIBLE_CACHE_PLUGIN` Environment variable: `ANSIBLE_INVENTORY_CACHE_PLUGIN`
- cache_prefix string | Prefix to use for cache plugin files/tables. Default: `"ansible_inventory_"` Configuration: INI entries:
      [defaults]
      fact_caching_prefix = ansible_inventory_
      [inventory]
      cache_prefix = ansible_inventory_
Environment variable: `ANSIBLE_CACHE_PLUGIN_PREFIX` Environment variable: `ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX`
- cache_timeout integer | Cache duration in seconds. Default: `3600` Configuration: INI entries:
      [defaults]
      fact_caching_timeout = 3600
      [inventory]
      cache_timeout = 3600
Environment variable: `ANSIBLE_CACHE_PLUGIN_TIMEOUT` Environment variable: `ANSIBLE_INVENTORY_CACHE_TIMEOUT`
compose dictionary | Create vars from jinja2 expressions. Default: `{}`
env list / elements=string | `user`‘s environment on `host`. Default: `[]`
get_properties boolean | Get jails’ properties. Creates dictionary `iocage_properties` for each added host. Choices: `false` ← (default) `true`
groups dictionary | Add hosts to group based on Jinja2 conditionals. Default: `{}`
host string / required | The ip/name of the `iocage` host.
keyed_groups list / elements=dictionary | Add hosts to group based on the values of a variable. Default: `[]`
default_value string added in ansible-core 2.12 | The default value when the host variable’s value is an empty string. This option is mutually exclusive with `keyed_groups[].trailing_separator`.
key string | The key from input dictionary used to generate groups.
parent_group string | parent group for keyed group.
prefix string | A keyed group name will start with this prefix. Default: `""`
separator string | separator used to build the keyed group name. Default: `"_"`
trailing_separator boolean added in ansible-core 2.12 | Set this option to `false` to omit the `keyed_groups[].separator` after the host variable when the value is an empty string. This option is mutually exclusive with `keyed_groups[].default_value`. Choices: `false` `true` ← (default)
leading_separator boolean added in ansible-core 2.11 | Use in conjunction with `keyed_groups`. By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore. This is because the default prefix is `""` and the default separator is `"_"`. Set this option to `false` to omit the leading underscore (or other separator) if no prefix is given. If the group name is derived from a mapping the separator is still used to concatenate the items. To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead. Choices: `false` `true` ← (default)
plugin string / required | The name of this plugin, it should always be set to `vbotka.freebsd.iocage` for this plugin to recognize it as its own. Choices: `"vbotka.freebsd.iocage"`
strict boolean | If `yes` make invalid entries a fatal error, otherwise skip and continue. Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default. Choices: `false` ← (default) `true`
- use_extra_vars boolean added in ansible-core 2.11 | Merge extra vars into the available variables for composition (highest precedence). Choices: `false` ← (default) `true` Configuration: INI entry:
      [inventory_plugins]
      use_extra_vars = false
Environment variable: `ANSIBLE_INVENTORY_USE_EXTRA_VARS`
user string | `iocage` user. It is expected that the `user` is able to connect to the `host` and execute the command `iocage list`. This option is not required if `host` is `localhost`.

## Notes

Note

- You might want to test the command `ssh user@host iocage list -l` on the controller before using this inventory plugin.

- If you run this inventory plugin on `localhost` `ssh` is not used. In this case, test the command `iocage list -l`.

- This inventory plugin creates variables `iocage_*` for each added host.

- The values of these variables are collected from the output of the command `iocage list -l`

- The names of these variables correspond to the output columns.

- The column `NAME` is used to name the added host.

## Examples

    # file name must end with iocage.yaml or iocage.yml
    plugin: vbotka.freebsd.iocage
    host: 10.1.0.73
    user: admin

    # user is not required if iocage is running on localhost
    plugin: vbotka.freebsd.iocage
    host: localhost

    # run cryptography without legacy algorithms
    plugin: vbotka.freebsd.iocage
    host: 10.1.0.73
    user: admin
    env:
      - CRYPTOGRAPHY_OPENSSL_NO_LEGACY=1

    # enable cache
    plugin: vbotka.freebsd.iocage
    host: 10.1.0.73
    user: admin
    env:
      - CRYPTOGRAPHY_OPENSSL_NO_LEGACY=1
    cache: true

    # see inventory plugin ansible.builtin.constructed
    plugin: vbotka.freebsd.iocage
    host: 10.1.0.73
    user: admin
    env:
      - CRYPTOGRAPHY_OPENSSL_NO_LEGACY=1
    cache: true
    strict: false
    compose:
      ansible_host: iocage_ip4
      release: iocage_release | split('-') | first
    groups:
      test: inventory_hostname.startswith('test')
    keyed_groups:
      - prefix: distro
        key: iocage_release
      - prefix: state
        key: iocage_state

### Authors

- Vladimir Botka (@vbotka)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

### Collection links

- Issue Tracker
- Homepage
- Repository (Sources)