W3cubDocs

/Ansible

community.general.iocage inventory – iocage inventory source

Note

This inventory plugin is part of the community.general collection (version 10.7.3).

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. You need further requirements to be able to use this inventory plugin, see Requirements for details.

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

New in community.general 10.2.0

Synopsis
Requirements
Parameters
Notes
Examples

Synopsis

Get inventory hosts from the iocage jail manager running on host.
By default, host is localhost. If host is not localhost it is expected that the user running Ansible on the controller can connect to the host account user with SSH non-interactively and execute the command iocage list.
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 dictionary	`user`‘s environment on `host`. Enable `sudo_preserve_env` if `sudo` is enabled. 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: `{}`
hooks_results list / elements=path added in community.general 10.4.0	List of paths to the files in a jail. Content of the files is stored in the items of the list `iocage_hooks`. If a file is not available the item keeps the dash character `-`. The variable `iocage_hooks` is not created if `hooks_results` is empty.
host string	The IP/hostname of the `iocage` host. Default: `"localhost"`
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 `community.general.iocage` for this plugin to recognize it as its own. Choices: `"community.general.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`
sudo boolean added in community.general 10.3.0	Enable execution as root. This requires passwordless sudo of the command `iocage list`. Choices:* `false` ← (default) `true`
sudo_preserve_env boolean added in community.general 10.3.0	Preserve environment if `sudo` is enabled. This requires `SETENV` sudoers tag. 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` with SSH and execute the command `iocage list`. This option is not required if `host` is `localhost`.

Note

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) 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. The entry types are also ordered by precedence from low to high priority order. For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).

Notes

Note

You might want to test the command ssh user@host iocage list -l on the controller before using this inventory plugin with user specified and with host other than localhost.
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.
The option hooks_results expects the poolname of a jail is mounted to /poolname. For example, if you activate the pool iocage this plugin expects to find the hooks_results items in the path /iocage/iocage/jails/<name>/root. If you mount the poolname to a different path the easiest remedy is to create a symlink.

Examples

---
# file name must end with iocage.yaml or iocage.yml
plugin: community.general.iocage
host: 10.1.0.73
user: admin

---
# user is not required if iocage is running on localhost (default)
plugin: community.general.iocage

---
# run cryptography without legacy algorithms
plugin: community.general.iocage
host: 10.1.0.73
user: admin
env:
  CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1

---
# execute as root
# sudoers example 'admin ALL=(ALL) NOPASSWD:SETENV: /usr/local/bin/iocage list*'
plugin: community.general.iocage
host: 10.1.0.73
user: admin
sudo: true
sudo_preserve_env: true
env:
  CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1

---
# enable cache
plugin: community.general.iocage
host: 10.1.0.73
user: admin
env:
  CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1
cache: true

---
# see inventory plugin ansible.builtin.constructed
plugin: community.general.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

---
# Read the file /var/db/dhclient-hook.address.epair0b in the jails and use it as ansible_host
plugin: community.general.iocage
host: 10.1.0.73
user: admin
hooks_results:
  - /var/db/dhclient-hook.address.epair0b
compose:
  ansible_host: iocage_hooks.0
groups:
  test: inventory_hostname.startswith('test')

Authors

Vladimir Botka (@vbotka)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/iocage_inventory.html