ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-23 05:10:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Added docs Inventory Guide. (#10239)
Some checks are pending
EOL CI / EOL Sanity (Ⓐ2.16) (push) Waiting to run
Details
EOL CI / EOL Units (Ⓐ2.16+py2.7) (push) Waiting to run
Details
EOL CI / EOL Units (Ⓐ2.16+py3.11) (push) Waiting to run
Details
EOL CI / EOL Units (Ⓐ2.16+py3.6) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+alpine3+py:azp/posix/1/) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+alpine3+py:azp/posix/2/) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+alpine3+py:azp/posix/3/) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+fedora38+py:azp/posix/1/) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+fedora38+py:azp/posix/2/) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+fedora38+py:azp/posix/3/) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+opensuse15+py:azp/posix/1/) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+opensuse15+py:azp/posix/2/) (push) Waiting to run
Details
EOL CI / EOL I (Ⓐ2.16+opensuse15+py:azp/posix/3/) (push) Waiting to run
Details
nox / Run extra sanity tests (push) Waiting to run
Details

Browse source 
* 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>
This commit is contained in:
Vladimir Botka 2025-07-12 20:43:07 +02:00 • committed by GitHub
commit 563b29e12a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 1072 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

16
.github/BOTMETA.yml vendored
View file

@ -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
#########################

3
docs/docsite/extra-docs.yml
View file

@ -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

15
docs/docsite/rst/guide_iocage.rst Normal file
View file

@ -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

31
docs/docsite/rst/iocage_inventory_guide.rst Normal file
View file

@ -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

200
docs/docsite/rst/iocage_inventory_guide_aliases.rst Normal file
View file

@ -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

128
docs/docsite/rst/iocage_inventory_guide_basics.rst Normal file
View file

@ -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

175
docs/docsite/rst/iocage_inventory_guide_dhcp.rst Normal file
View file

@ -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

187
docs/docsite/rst/iocage_inventory_guide_hooks.rst Normal file
View file

@ -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*.

201
docs/docsite/rst/iocage_inventory_guide_properties.rst Normal file
View file

@ -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

117
docs/docsite/rst/iocage_inventory_guide_tags.rst Normal file
View file

@ -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