Added docs Inventory Guide. (#10239)

* Added docs Inventory Guide.

* Errata docs Inventory Guide.

* Fix docs Inventory Guide error: use ASCII quotes.

* Fix docs Inventory Guide various lint errors.

* Added docs Inventory Guide BOTMETA entries.

* Fix docs Inventory Guide lint errors: trailing whitespace

* Fix docs Inventory Guide lint errors: force yaml pygment

* Fix docs Inventory Guide lint errors: No way to force yaml pygment in code-block

* Update docs/docsite/rst/inventory_guide_iocage.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/inventory_guide_iocage_aliases.rst

Thank you for the explanation!

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/inventory_guide_iocage_aliases.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Updated docs Inventory Guide.

* Problematic pygments changed to 'console'.

* Update docs/docsite/rst/inventory_guide_iocage_hooks.rst
  Update docs/docsite/rst/inventory_guide_iocage_properties.rst
  Update docs/docsite/rst/inventory_guide_iocage_hooks.rst

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* Put dhclient-exit-hooks into the sh code-block.

* Fix the code-block.

* Update docs/docsite/rst/inventory_guide_iocage.rst
  Update docs/docsite/rst/inventory_guide_iocage_aliases.rst
  Update docs/docsite/rst/inventory_guide_iocage_basics.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Remove tabs.

* Update docs/docsite/rst/inventory_guide_iocage_basics.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Indent the note block.

* Update docs/docsite/rst/inventory_guide_iocage_hooks.rst
  Update docs/docsite/rst/inventory_guide_iocage_dhcp.rst
  Update docs/docsite/rst/inventory_guide_iocage_hooks.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Fix ansval.

* Add guide_iocage.rst and inventory_guide_iocage*.rst

* Fix 'disallowed language sh found'.

* Remove note block.

* Remove include which triggers a bug in rstcheck.

* Update docs/docsite/extra-docs.yml
  Update docs/docsite/rst/iocage_inventory_guide_basics.rst
  Update docs/docsite/rst/iocage_inventory_guide_dhcp.rst
  Update docs/docsite/rst/iocage_inventory_guide_hooks.rst
  Update docs/docsite/rst/iocage_inventory_guide_properties.rst
  Update docs/docsite/rst/iocage_inventory_guide_tags.rst
  Update docs/docsite/rst/iocage_inventory_guide_hooks.rst
  Update docs/docsite/rst/iocage_inventory_guide_properties.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Put man iocage quotation into the text code block.

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

.github/BOTMETA.yml

@@ -1529,6 +1529,22 @@ files:
     maintainers: russoz
   docs/docsite/rst/guide_vardict.rst:
     maintainers: russoz
+  docs/docsite/rst/guide_iocage.rst:
+    maintainers: russoz felixfontein
+  docs/docsite/rst/iocage_inventory_guide.rst:
+    maintainers: vbotka
+  docs/docsite/rst/iocage_inventory_guide_aliases.rst:
+    maintainers: vbotka
+  docs/docsite/rst/iocage_inventory_guide_basics.rst:
+    maintainers: vbotka
+  docs/docsite/rst/iocage_inventory_guide_dhcp.rst:
+    maintainers: vbotka
+  docs/docsite/rst/iocage_inventory_guide_hooks.rst:
+    maintainers: vbotka
+  docs/docsite/rst/iocage_inventory_guide_properties.rst:
+    maintainers: vbotka
+  docs/docsite/rst/iocage_inventory_guide_tags.rst:
+    maintainers: vbotka
   docs/docsite/rst/test_guide.rst:
     maintainers: felixfontein
 #########################

docs/docsite/extra-docs.yml

@@ -8,9 +8,10 @@ sections:
     toctree:
       - filter_guide
       - test_guide
-  - title: Cloud Guides
+  - title: Technology Guides
     toctree:
       - guide_alicloud
+      - guide_iocage
       - guide_online
       - guide_packet
       - guide_scaleway

docs/docsite/rst/guide_iocage.rst

@@ -0,0 +1,15 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_iocage:
+
+************
+Iocage Guide
+************
+
+.. toctree::
+   :maxdepth: 1
+
+   iocage_inventory_guide

docs/docsite/rst/iocage_inventory_guide.rst

@@ -0,0 +1,31 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_iocage.iocage_inventory_guide:
+
+community.general.iocage inventory plugin
+=========================================
+
+The inventory plugin :ansplugin:`community.general.iocage#inventory` gets the inventory hosts from the iocage jail manager.
+
+See:
+
+* `iocage - A FreeBSD Jail Manager <https://iocage.readthedocs.io/en/latest>`_
+* `man iocage <https://man.freebsd.org/cgi/man.cgi?query=iocage>`_
+* `Jails and Containers <https://docs.freebsd.org/en/books/handbook/jails>`_
+
+.. note::
+  The output of the examples is YAML formatted. See the option :ansopt:`ansible.bulitin.default#callback:result_format`.
+
+.. toctree::
+   :caption: Table of Contents
+   :maxdepth: 1
+
+   inventory_guide_iocage_basics
+   inventory_guide_iocage_dhcp
+   inventory_guide_iocage_hooks
+   inventory_guide_iocage_properties
+   inventory_guide_iocage_tags
+   inventory_guide_iocage_aliases

docs/docsite/rst/iocage_inventory_guide_aliases.rst

@@ -0,0 +1,200 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_iocage.iocage_inventory_guide.iocage_inventory_guide_aliases:
+
+Aliases
+-------
+
+Quoting :ref:`inventory_aliases`:
+
+   The ``inventory_hostname`` is the unique identifier for a host in Ansible, this can be an IP or a hostname, but also just an 'alias' or short name for the host.
+
+As root at the iocage host, stop and destroy all jails:
+
+.. code-block:: console
+
+   shell> iocage stop ALL
+   * Stopping srv_1
+     + Executing prestop OK
+     + Stopping services OK
+     + Tearing down VNET OK
+     + Removing devfs_ruleset: 1000 OK
+     + Removing jail process OK
+     + Executing poststop OK
+   * Stopping srv_2
+     + Executing prestop OK
+     + Stopping services OK
+     + Tearing down VNET OK
+     + Removing devfs_ruleset: 1001 OK
+     + Removing jail process OK
+     + Executing poststop OK
+   * Stopping srv_3
+     + Executing prestop OK
+     + Stopping services OK
+     + Tearing down VNET OK
+     + Removing devfs_ruleset: 1002 OK
+     + Removing jail process OK
+     + Executing poststop OK
+   ansible_client is not running!
+
+   shell> iocage destroy -f srv_1 srv_2 srv_3
+   Destroying srv_1
+   Destroying srv_2
+   Destroying srv_3
+
+Create three VNET jails with a DHCP interface from the template *ansible_client*. Use the option ``--count``:
+
+.. code-block:: console
+
+   shell> iocage create --short --template ansible_client --count 3 bpf=1 dhcp=1 vnet=1
+   1c11de2d successfully created!
+   9d94cc9e successfully created!
+   052b9557 successfully created!
+
+The names are random. Start the jails:
+
+.. code-block:: console
+
+   shell> iocage start ALL
+   No default gateway found for ipv6.
+   * Starting 052b9557
+     + Started OK
+     + Using devfs_ruleset: 1000 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.137/24
+   No default gateway found for ipv6.
+   * Starting 1c11de2d
+     + Started OK
+     + Using devfs_ruleset: 1001 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.146/24
+   No default gateway found for ipv6.
+   * Starting 9d94cc9e
+     + Started OK
+     + Using devfs_ruleset: 1002 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.115/24
+   Please convert back to a jail before trying to start ansible_client
+
+List the jails:
+
+.. code-block:: console
+
+   shell> iocage list -l
+   +-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | JID |   NAME   | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+   +=====+==========+======+=======+======+=================+====================+=====+================+==========+
+   | 207 | 052b9557 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.137 | -   | ansible_client | no       |
+   +-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 208 | 1c11de2d | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.146 | -   | ansible_client | no       |
+   +-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 209 | 9d94cc9e | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.115 | -   | ansible_client | no       |
+   +-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+
+Set notes. The tag *alias* will be used to create inventory aliases:
+
+.. code-block:: console
+
+   shell> iocage set notes="vmm=iocage_02 project=foo alias=srv_1" 052b9557
+   notes: none -> vmm=iocage_02 project=foo alias=srv_1
+   shell> iocage set notes="vmm=iocage_02 project=foo alias=srv_2" 1c11de2d
+   notes: none -> vmm=iocage_02 project=foo alias=srv_2
+   shell> iocage set notes="vmm=iocage_02 project=bar alias=srv_3" 9d94cc9e
+   notes: none -> vmm=iocage_02 project=bar alias=srv_3
+
+Update the inventory configuration. Set the option
+:ansopt:`community.general.iocage#inventory:inventory_hostname_tag` to :ansval:`alias`. This tag keeps the
+value of the alias. The option :ansopt:`community.general.iocage#inventory:get_properties` must be
+enabled. For example, ``hosts/02_iocage.yml`` contains:
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   get_properties: true
+   inventory_hostname_tag: alias
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+   compose:
+     ansible_host: (iocage_hooks.0 == '-') | ternary(iocage_ip4, iocage_hooks.0)
+     iocage_tags: dict(iocage_properties.notes | split | map('split', '='))
+   keyed_groups:
+     - prefix: vmm
+       key: iocage_tags.vmm
+     - prefix: project
+       key: iocage_tags.project
+
+Display tags and groups. Create a playbook ``pb-test-groups.yml`` with the following content:
+
+.. code-block:: yaml+jinja
+
+   - hosts: all
+     remote_user: admin
+
+     vars:
+
+       ansible_python_interpreter: auto_silent
+
+     tasks:
+
+       - debug:
+           var: iocage_tags
+
+       - debug:
+           msg: |
+             {% for group in groups %}
+             {{ group }}: {{ groups[group] }}
+             {% endfor %}
+         run_once: true
+
+Run the playbook:
+
+.. code-block:: console
+
+   shell> ansible-playbook -i hosts/02_iocage.yml pb-test-groups.yml
+
+   PLAY [all] **********************************************************************************************************
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       iocage_tags:
+           alias: srv_1
+           project: foo
+           vmm: iocage_02
+   ok: [srv_2] =>
+       iocage_tags:
+           alias: srv_2
+           project: foo
+           vmm: iocage_02
+   ok: [srv_3] =>
+       iocage_tags:
+           alias: srv_3
+           project: bar
+           vmm: iocage_02
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       msg: |-
+           all: ['srv_1', 'srv_2', 'srv_3']
+           ungrouped: []
+           vmm_iocage_02: ['srv_1', 'srv_2', 'srv_3']
+           project_foo: ['srv_1', 'srv_2']
+           project_bar: ['srv_3']
+
+   PLAY RECAP **********************************************************************************************************
+   srv_1                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_2                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_3                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

docs/docsite/rst/iocage_inventory_guide_basics.rst

@@ -0,0 +1,128 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_iocage.iocage_inventory_guide.iocage_inventory_guide_basics:
+
+Basics
+------
+
+As root at the iocage host, create three VNET jails with a DHCP interface from the template
+*ansible_client*:
+
+.. code-block:: console
+
+   shell> iocage create --template ansible_client --name srv_1 bpf=1 dhcp=1 vnet=1
+   srv_1 successfully created!
+   shell> iocage create --template ansible_client --name srv_2 bpf=1 dhcp=1 vnet=1
+   srv_2 successfully created!
+   shell> iocage create --template ansible_client --name srv_3 bpf=1 dhcp=1 vnet=1
+   srv_3 successfully created!
+
+See: `Configuring a VNET Jail <https://iocage.readthedocs.io/en/latest/networking.html#configuring-a-vnet-jail>`_.
+
+As admin at the controller, list the jails:
+
+.. code-block:: console
+
+   shell> ssh admin@10.1.0.73 iocage list -l
+   +------+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | JID  | NAME  | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+   +======+=======+======+=======+======+=================+====================+=====+================+==========+
+   | None | srv_1 | off  | down  | jail | 14.2-RELEASE-p3 | DHCP (not running) | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | None | srv_2 | off  | down  | jail | 14.2-RELEASE-p3 | DHCP (not running) | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | None | srv_3 | off  | down  | jail | 14.2-RELEASE-p3 | DHCP (not running) | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+
+Create the inventory file ``hosts/02_iocage.yml``
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+
+Display the inventory:
+
+.. code-block:: console
+
+   shell> ansible-inventory -i hosts/02_iocage.yml --list --yaml
+   all:
+     children:
+       ungrouped:
+         hosts:
+           srv_1:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (not running)
+             iocage_ip6: '-'
+             iocage_jid: None
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: down
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_2:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (not running)
+             iocage_ip6: '-'
+             iocage_jid: None
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: down
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_3:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (not running)
+             iocage_ip6: '-'
+             iocage_jid: None
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: down
+             iocage_template: ansible_client
+             iocage_type: jail
+
+Optionally, create shared IP jails:
+
+.. code-block:: console
+
+   shell> iocage create --template ansible_client --name srv_1 ip4_addr="em0|10.1.0.101/24"
+   srv_1 successfully created!
+   shell> iocage create --template ansible_client --name srv_2 ip4_addr="em0|10.1.0.102/24"
+   srv_2 successfully created!
+   shell> iocage create --template ansible_client --name srv_3 ip4_addr="em0|10.1.0.103/24"
+   srv_3 successfully created!
+   shell> iocage list -l
+   +------+-------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
+   | JID  | NAME  | BOOT | STATE | TYPE |     RELEASE     |        IP4        | IP6 |    TEMPLATE    | BASEJAIL |
+   +======+=======+======+=======+======+=================+===================+=====+================+==========+
+   | None | srv_1 | off  | down  | jail | 14.2-RELEASE-p3 | em0|10.1.0.101/24 | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
+   | None | srv_2 | off  | down  | jail | 14.2-RELEASE-p3 | em0|10.1.0.102/24 | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
+   | None | srv_3 | off  | down  | jail | 14.2-RELEASE-p3 | em0|10.1.0.103/24 | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
+
+See: `Configuring a Shared IP Jail <https://iocage.readthedocs.io/en/latest/networking.html#configuring-a-shared-ip-jail>`_
+
+If iocage needs environment variable(s), use the option :ansopt:`community.general.iocage#inventory:env`. For example,
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   env:
+     CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1

docs/docsite/rst/iocage_inventory_guide_dhcp.rst

@@ -0,0 +1,175 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_iocage.iocage_inventory_guide.iocage_inventory_guide_dhcp:
+
+DHCP
+----
+
+As root at the iocage host, start the jails:
+
+.. code-block:: console
+
+   shell> iocage start ALL
+   No default gateway found for ipv6.
+   * Starting srv_1
+     + Started OK
+     + Using devfs_ruleset: 1000 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.183/24
+   No default gateway found for ipv6.
+   * Starting srv_2
+     + Started OK
+     + Using devfs_ruleset: 1001 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.204/24
+   No default gateway found for ipv6.
+   * Starting srv_3
+     + Started OK
+     + Using devfs_ruleset: 1002 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.169/24
+   Please convert back to a jail before trying to start ansible_client
+
+List the jails:
+
+.. code-block:: console
+
+   shell> iocage list -l
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | JID | NAME  | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+   +=====+=======+======+=======+======+=================+====================+=====+================+==========+
+   | 204 | srv_1 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.183 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 205 | srv_2 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.204 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 206 | srv_3 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.169 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+
+As admin at the controller, list the jails. The IP4 tab says "... address requires root":
+
+.. code-block:: console
+
+   shell> ssh admin@10.1.0.73 iocage list -l
+   +-----+-------+------+-------+------+-----------------+-----------------------------------------+-----+----------------+----------+
+   | JID | NAME  | BOOT | STATE | TYPE |     RELEASE     |                   IP4                   | IP6 |    TEMPLATE    | BASEJAIL |
+   +=====+=======+======+=======+======+=================+=========================================+=====+================+==========+
+   | 204 | srv_1 | off  | up    | jail | 14.2-RELEASE-p3 | DHCP (running -- address requires root) | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+-----------------------------------------+-----+----------------+----------+
+   | 205 | srv_2 | off  | up    | jail | 14.2-RELEASE-p3 | DHCP (running -- address requires root) | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+-----------------------------------------+-----+----------------+----------+
+   | 206 | srv_3 | off  | up    | jail | 14.2-RELEASE-p3 | DHCP (running -- address requires root) | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+-----------------------------------------+-----+----------------+----------+
+
+Use sudo if enabled:
+
+.. code-block:: console
+
+   shell> ssh admin@10.1.0.73 sudo iocage list -l
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | JID | NAME  | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+   +=====+=======+======+=======+======+=================+====================+=====+================+==========+
+   | 204 | srv_1 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.183 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 205 | srv_2 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.204 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 206 | srv_3 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.169 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+
+Create the inventory file ``hosts/02_iocage.yml``. Use the option
+:ansopt:`community.general.iocage#inventory:sudo`:
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   sudo: true
+
+Display the inventory:
+
+.. code-block:: console
+
+   shell> ansible-inventory -i hosts/02_iocage.yml --list --yaml
+   all:
+     children:
+       ungrouped:
+         hosts:
+           srv_1:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: 10.1.0.183
+             iocage_ip4_dict:
+               ip4:
+               - ifc: epair0b
+                 ip: 10.1.0.183
+                 mask: '-'
+               msg: ''
+             iocage_ip6: '-'
+             iocage_jid: '204'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_2:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: 10.1.0.204
+             iocage_ip4_dict:
+               ip4:
+               - ifc: epair0b
+                 ip: 10.1.0.204
+                 mask: '-'
+               msg: ''
+             iocage_ip6: '-'
+             iocage_jid: '205'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_3:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: 10.1.0.169
+             iocage_ip4_dict:
+               ip4:
+               - ifc: epair0b
+                 ip: 10.1.0.169
+                 mask: '-'
+               msg: ''
+             iocage_ip6: '-'
+             iocage_jid: '206'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+
+Note: If the option :ansopt:`community.general.iocage#inventory:env` is used and :ansopt:`community.general.iocage#inventory:sudo` is enabled, enable also :ansopt:`community.general.iocage#inventory:sudo_preserve_env`. For example,
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   env:
+     CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1
+   sudo: true
+   sudo_preserve_env: true
+
+In this case, make sure the sudo tag ``SETENV`` is used:
+
+.. code-block:: console
+
+   shell> ssh admin@10.1.0.73 sudo cat /usr/local/etc/sudoers | grep admin
+   admin ALL=(ALL) NOPASSWD:SETENV: ALL

docs/docsite/rst/iocage_inventory_guide_hooks.rst

@@ -0,0 +1,187 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_iocage.iocage_inventory_guide.iocage_inventory_guide_hooks:
+
+Hooks
+-----
+
+The iocage utility internally opens a console to a jail to get the jail's DHCP address. This
+requires root. If you run the command ``iocage list -l`` as unprivileged user, you'll see the
+message ``DHCP (running -- address requires root)``. If you are not granted the root privilege, use
+``/etc/dhclient-exit-hooks``. For example, in the jail *srv_1*, create the file
+``/zroot/iocage/jails/srv_1/root/etc/dhclient-exit-hooks``
+
+.. code-block:: shell
+
+   case "$reason" in
+       "BOUND"|"REBIND"|"REBOOT"|"RENEW")
+       echo $new_ip_address > /var/db/dhclient-hook.address.$interface
+       ;;
+   esac
+
+where ``/zroot/iocage`` is the activated pool.
+
+.. code-block:: console
+
+   shell> zfs list | grep /zroot/iocage
+   zroot/iocage                                4.69G   446G  5.08M  /zroot/iocage
+   zroot/iocage/download                        927M   446G   384K  /zroot/iocage/download
+   zroot/iocage/download/14.1-RELEASE           465M   446G   465M  /zroot/iocage/download/14.1-RELEASE
+   zroot/iocage/download/14.2-RELEASE           462M   446G   462M  /zroot/iocage/download/14.2-RELEASE
+   zroot/iocage/images                          384K   446G   384K  /zroot/iocage/images
+   zroot/iocage/jails                           189M   446G   480K  /zroot/iocage/jails
+   zroot/iocage/jails/srv_1                    62.9M   446G   464K  /zroot/iocage/jails/srv_1
+   zroot/iocage/jails/srv_1/root               62.4M   446G  3.53G  /zroot/iocage/jails/srv_1/root
+   zroot/iocage/jails/srv_2                    62.8M   446G   464K  /zroot/iocage/jails/srv_2
+   zroot/iocage/jails/srv_2/root               62.3M   446G  3.53G  /zroot/iocage/jails/srv_2/root
+   zroot/iocage/jails/srv_3                    62.8M   446G   464K  /zroot/iocage/jails/srv_3
+   zroot/iocage/jails/srv_3/root               62.3M   446G  3.53G  /zroot/iocage/jails/srv_3/root
+   zroot/iocage/log                             688K   446G   688K  /zroot/iocage/log
+   zroot/iocage/releases                       2.93G   446G   384K  /zroot/iocage/releases
+   zroot/iocage/releases/14.2-RELEASE          2.93G   446G   384K  /zroot/iocage/releases/14.2-RELEASE
+   zroot/iocage/releases/14.2-RELEASE/root     2.93G   446G  2.88G  /zroot/iocage/releases/14.2-RELEASE/root
+   zroot/iocage/templates                       682M   446G   416K  /zroot/iocage/templates
+   zroot/iocage/templates/ansible_client        681M   446G   432K  /zroot/iocage/templates/ansible_client
+   zroot/iocage/templates/ansible_client/root   681M   446G  3.53G  /zroot/iocage/templates/ansible_client/root
+
+See: `man dhclient-script <https://man.freebsd.org/cgi/man.cgi?dhclient-script>`_
+
+Create the inventory configuration. Use the option :ansopt:`community.general.iocage#inventory:hooks_results` instead of :ansopt:`community.general.iocage#inventory:sudo`:
+
+.. code-block:: console
+
+   shell> cat hosts/02_iocage.yml
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+
+.. note::
+
+   The option :ansopt:`community.general.iocage#inventory:hooks_results` expects the poolname to be mounted to ``/poolname``. For example, if you
+   activate the pool iocage, this plugin expects to find the :ansopt:`community.general.iocage#inventory: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.
+
+As admin at the controller, display the inventory:
+
+.. code-block:: console
+
+   shell> ansible-inventory -i hosts/02_iocage.yml --list --yaml
+   all:
+     children:
+       ungrouped:
+         hosts:
+           srv_1:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_hooks:
+             - 10.1.0.183
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (running -- address requires root)
+             iocage_ip6: '-'
+             iocage_jid: '204'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_2:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_hooks:
+             - 10.1.0.204
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (running -- address requires root)
+             iocage_ip6: '-'
+             iocage_jid: '205'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_3:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_hooks:
+             - 10.1.0.169
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (running -- address requires root)
+             iocage_ip6: '-'
+             iocage_jid: '206'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+
+Compose the variable ``ansible_host``. For example, ``hosts/02_iocage.yml`` could look like:
+
+.. code-block:: yaml+jinja
+
+   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 == '-') | ternary(iocage_ip4, iocage_hooks.0)
+
+Test the jails. Create a playbook ``pb-test-uname.yml``:
+
+.. code-block:: yaml
+
+   - hosts: all
+     remote_user: admin
+
+     vars:
+
+       ansible_python_interpreter: auto_silent
+
+     tasks:
+
+       - command: uname -a
+         register: out
+
+       - debug:
+           var: out.stdout
+
+See: :ref:`working_with_bsd`
+
+Run the playbook:
+
+.. code-block:: console
+
+   shell> ansible-playbook -i hosts/02_iocage.yml pb-test-uname.yml
+
+   PLAY [all] **********************************************************************************************************
+
+   TASK [command] ******************************************************************************************************
+   changed: [srv_3]
+   changed: [srv_1]
+   changed: [srv_2]
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       out.stdout: FreeBSD srv-1 14.2-RELEASE-p1 FreeBSD 14.2-RELEASE-p1 GENERIC amd64
+   ok: [srv_3] =>
+       out.stdout: FreeBSD srv-3 14.2-RELEASE-p1 FreeBSD 14.2-RELEASE-p1 GENERIC amd64
+   ok: [srv_2] =>
+       out.stdout: FreeBSD srv-2 14.2-RELEASE-p1 FreeBSD 14.2-RELEASE-p1 GENERIC amd64
+
+   PLAY RECAP **********************************************************************************************************
+   srv_1                      : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_2                      : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_3                      : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+
+Note: This playbook and the inventory configuration works also for the *Shared IP Jails*.

docs/docsite/rst/iocage_inventory_guide_properties.rst

@@ -0,0 +1,201 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_iocage.iocage_inventory_guide.iocage_inventory_guide_properties:
+
+Properties
+----------
+
+Optionally, in the inventory file ``hosts/02_iocage.yml``, get the iocage properties. Enable
+:ansopt:`community.general.iocage#inventory:get_properties`:
+
+.. code-block:: yaml+jinja
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   get_properties: true
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+   compose:
+     ansible_host: (iocage_hooks.0 == '-') | ternary(iocage_ip4, iocage_hooks.0)
+
+Display the properties. Create the playbook ``pb-test-properties.yml``:
+
+.. code-block:: yaml
+
+   - hosts: all
+     remote_user: admin
+
+     vars:
+
+       ansible_python_interpreter: auto_silent
+
+     tasks:
+
+       - debug:
+           var: iocage_properties
+
+Run the playbook. Limit the inventory to *srv_3*:
+
+.. code-block:: console
+
+   shell> ansible-playbook -i hosts/02_iocage.yml -l srv_3 pb-test-properties.yml
+
+   PLAY [all] **********************************************************************************************************
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_3] =>
+       iocage_properties:
+           CONFIG_VERSION: '33'
+           allow_chflags: '0'
+           allow_mlock: '0'
+           allow_mount: '1'
+           allow_mount_devfs: '0'
+           allow_mount_fdescfs: '0'
+           allow_mount_fusefs: '0'
+           allow_mount_linprocfs: '0'
+           allow_mount_linsysfs: '0'
+           allow_mount_nullfs: '0'
+           allow_mount_procfs: '0'
+           allow_mount_tmpfs: '0'
+           allow_mount_zfs: '0'
+           allow_nfsd: '0'
+           allow_quotas: '0'
+           allow_raw_sockets: '0'
+           allow_set_hostname: '1'
+           allow_socket_af: '0'
+           allow_sysvipc: '0'
+           allow_tun: '0'
+           allow_vmm: '0'
+           assign_localhost: '0'
+           available: readonly
+           basejail: '0'
+           boot: '0'
+           bpf: '1'
+           children_max: '0'
+           cloned_release: 14.2-RELEASE
+           comment: none
+           compression: 'on'
+           compressratio: readonly
+           coredumpsize: 'off'
+           count: '1'
+           cpuset: 'off'
+           cputime: 'off'
+           datasize: 'off'
+           dedup: 'off'
+           defaultrouter: auto
+           defaultrouter6: auto
+           depends: none
+           devfs_ruleset: '4'
+           dhcp: '1'
+           enforce_statfs: '2'
+           exec_clean: '1'
+           exec_created: /usr/bin/true
+           exec_fib: '0'
+           exec_jail_user: root
+           exec_poststart: /usr/bin/true
+           exec_poststop: /usr/bin/true
+           exec_prestart: /usr/bin/true
+           exec_prestop: /usr/bin/true
+           exec_start: /bin/sh /etc/rc
+           exec_stop: /bin/sh /etc/rc.shutdown
+           exec_system_jail_user: '0'
+           exec_system_user: root
+           exec_timeout: '60'
+           host_domainname: none
+           host_hostname: srv-3
+           host_hostuuid: srv_3
+           host_time: '1'
+           hostid: ea2ba7d1-4fcd-f13f-82e4-8b32c0a03403
+           hostid_strict_check: '0'
+           interfaces: vnet0:bridge0
+           ip4: new
+           ip4_addr: none
+           ip4_saddrsel: '1'
+           ip6: new
+           ip6_addr: none
+           ip6_saddrsel: '1'
+           ip_hostname: '0'
+           jail_zfs: '0'
+           jail_zfs_dataset: iocage/jails/srv_3/data
+           jail_zfs_mountpoint: none
+           last_started: '2025-06-11 04:29:23'
+           localhost_ip: none
+           login_flags: -f root
+           mac_prefix: 02a098
+           maxproc: 'off'
+           memorylocked: 'off'
+           memoryuse: 'off'
+           min_dyn_devfs_ruleset: '1000'
+           mount_devfs: '1'
+           mount_fdescfs: '1'
+           mount_linprocfs: '0'
+           mount_procfs: '0'
+           mountpoint: readonly
+           msgqqueued: 'off'
+           msgqsize: 'off'
+           nat: '0'
+           nat_backend: ipfw
+           nat_forwards: none
+           nat_interface: none
+           nat_prefix: '172.16'
+           nmsgq: 'off'
+           notes: none
+           nsem: 'off'
+           nsemop: 'off'
+           nshm: 'off'
+           nthr: 'off'
+           openfiles: 'off'
+           origin: readonly
+           owner: root
+           pcpu: 'off'
+           plugin_name: none
+           plugin_repository: none
+           priority: '99'
+           pseudoterminals: 'off'
+           quota: none
+           readbps: 'off'
+           readiops: 'off'
+           release: 14.2-RELEASE-p3
+           reservation: none
+           resolver: /etc/resolv.conf
+           rlimits: 'off'
+           rtsold: '0'
+           securelevel: '2'
+           shmsize: 'off'
+           source_template: ansible_client
+           stacksize: 'off'
+           state: up
+           stop_timeout: '30'
+           swapuse: 'off'
+           sync_state: none
+           sync_target: none
+           sync_tgt_zpool: none
+           sysvmsg: new
+           sysvsem: new
+           sysvshm: new
+           template: '0'
+           type: jail
+           used: readonly
+           vmemoryuse: 'off'
+           vnet: '1'
+           vnet0_mac: 02a0983da05d 02a0983da05e
+           vnet0_mtu: auto
+           vnet1_mac: none
+           vnet1_mtu: auto
+           vnet2_mac: none
+           vnet2_mtu: auto
+           vnet3_mac: none
+           vnet3_mtu: auto
+           vnet_default_interface: auto
+           vnet_default_mtu: '1500'
+           vnet_interfaces: none
+           wallclock: 'off'
+           writebps: 'off'
+           writeiops: 'off'
+
+   PLAY RECAP **********************************************************************************************************
+   srv_3                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

docs/docsite/rst/iocage_inventory_guide_tags.rst

@@ -0,0 +1,117 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_iocage.iocage_inventory_guide.iocage_inventory_guide_tags:
+
+Tags
+----
+
+Quoting `man iocage <https://man.freebsd.org/cgi/man.cgi?query=iocage>`_
+
+.. code-block:: text
+
+   PROPERTIES
+   ...
+   notes="any string"
+         Custom notes for miscellaneous tagging.
+         Default: none
+         Source: local
+
+We will use the format `notes="tag1=value1 tag2=value2 ..."`.
+
+.. note::
+
+    The iocage tags have nothing to do with the :ref:`tags`.
+
+As root at the iocage host, set notes. For example,
+
+.. code-block:: console
+
+   shell> iocage set notes="vmm=iocage_02 project=foo" srv_1
+   notes: none -> vmm=iocage_02 project=foo
+   shell> iocage set notes="vmm=iocage_02 project=foo" srv_2
+   notes: none -> vmm=iocage_02 project=foo
+   shell> iocage set notes="vmm=iocage_02 project=bar" srv_3
+   notes: none -> vmm=iocage_02 project=bar
+
+Update the inventory configuration. Compose a dictionary *iocage_tags* and create groups. The option
+:ansopt:`community.general.iocage#inventory:get_properties` must be enabled.
+For example, ``hosts/02_iocage.yml`` could look like:
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   get_properties: true
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+   compose:
+     ansible_host: (iocage_hooks.0 == '-') | ternary(iocage_ip4, iocage_hooks.0)
+     iocage_tags: dict(iocage_properties.notes | split | map('split', '='))
+   keyed_groups:
+     - prefix: vmm
+       key: iocage_tags.vmm
+     - prefix: project
+       key: iocage_tags.project
+
+Display tags and groups. Create a playbook ``pb-test-groups.yml``:
+
+.. code-block:: yaml+jinja
+
+   - hosts: all
+     remote_user: admin
+
+     vars:
+
+       ansible_python_interpreter: auto_silent
+
+     tasks:
+
+       - debug:
+           var: iocage_tags
+
+       - debug:
+           msg: |
+             {% for group in groups %}
+             {{ group }}: {{ groups[group] }}
+             {% endfor %}
+         run_once: true
+
+Run the playbook:
+
+.. code-block:: console
+
+   shell> ansible-playbook -i hosts/02_iocage.yml pb-test-groups.yml
+
+   PLAY [all] **********************************************************************************************************
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       iocage_tags:
+           project: foo
+           vmm: iocage_02
+   ok: [srv_2] =>
+       iocage_tags:
+           project: foo
+           vmm: iocage_02
+   ok: [srv_3] =>
+       iocage_tags:
+           project: bar
+           vmm: iocage_02
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       msg: |-
+           all: ['srv_1', 'srv_2', 'srv_3']
+           ungrouped: []
+           vmm_iocage_02: ['srv_1', 'srv_2', 'srv_3']
+           project_foo: ['srv_1', 'srv_2']
+           project_bar: ['srv_3']
+
+   PLAY RECAP **********************************************************************************************************
+   srv_1                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_2                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_3                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0