Playbooks

pb_iocage_ansible_clients

Synopsis

This playbook creates jails from the templates.

Examples

clones

Use the dictionary clones. For example,

clones:
  test_111:
    clone_from: ansible_client
    properties:
      ip4_addr: 'em0|10.1.0.111/24'
  test_112:
    clone_from: ansible_client
    properties:
      ip4_addr: 'em0|10.1.0.112/24'
  test_113:
    clone_from: ansible_client
    properties:
      ip4_addr: 'em0|10.1.0.113/24'

Use the playbook tag clone to execute selected tasks

(env) > ansible-playbook pb_iocage_ansible_clients.yml -t clone -e clone=true

creates the clones

shell> iocage list -l
+-----+----------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
| JID |   NAME   | BOOT | STATE | TYPE |     RELEASE     |        IP4        | IP6 |    TEMPLATE    | BASEJAIL |
+=====+==========+======+=======+======+=================+===================+=====+================+==========+
| 170 | test_111 | off  | up    | jail | 14.1-RELEASE-p6 | em0|10.1.0.111/24 | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
| 171 | test_112 | off  | up    | jail | 14.1-RELEASE-p6 | em0|10.1.0.112/24 | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
| 172 | test_113 | off  | up    | jail | 14.1-RELEASE-p6 | em0|10.1.0.113/24 | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+-------------------+-----+----------------+----------+

swarms

Use the dictionary swarms. For example,

swarms:
  sw_01:
    count: 3
    template: ansible_client

Use the playbook tag swarm to execute selected tasks

(env) > ansible-playbook pb_iocage_ansible_clients.yml -t swarm -e swarm=true

creates 3 jails from the template ansible_client. The names are generated automatically

shell> iocage list -l
+-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
| JID |   NAME   | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+=====+==========+======+=======+======+=================+====================+=====+================+==========+
| 64  | 08daa493 | off  | up    | jail | 14.1-RELEASE-p6 | epair0b|10.1.0.114 | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
| 65  | 2746353a | off  | up    | jail | 14.1-RELEASE-p6 | epair0b|10.1.0.187 | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
| 66  | 83707231 | off  | up    | jail | 14.1-RELEASE-p6 | epair0b|10.1.0.233 | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+

clone_host_hostname

Use the dictionary clone_host_hostname. The keys are used to create hostnames. Create fstab entries. See the iocage property host_hostname. For example,

clones_host_hostname:
  www-5:
    template: ansible_client_apache
    fstab:
      - spec: /usr/local/poudriere
        file: /usr/local/poudriere
        type: nullfs
        options: ro 0 0

Use the playbook tag clone_host_hostname to execute selected tasks

(env) > ansible-playbook pb_iocage_ansible_clients.yml \
                         -t clone_host_hostname -e clone_host_hostname=true

default properties

The dictionary properties keeps the default properties. For example,

properties:
  notes: "vmm={{ inventory_hostname }}"
  vnet: 1
  defaultrouter: 10.1.0.10

, get the DHCP address

properties:
  notes: "vmm={{ inventory_hostname }}"
  bpf: 1
  dhcp: 1
  vnet: 1

, or mount datasets

properties:
  notes: "vmm={{ inventory_hostname }}"
  bpf: 1
  dhcp: 1
  vnet: 1
  allow_mount: 1
  allow_mount_zfs: 1
  jail_zfs: 1

See also

iocage tags

Hint

Look at the Index and search the playbook pb_iocage_ansible_client.yml to see what examples are available.

Workflow

TBD

pb_iocage_template

Synopsis

This playbook creates iocage templates from the dictionary templates. For example,

templates:
  ansible_client:
    release: 14.3-RELEASE
    properties:
      bpf: 'on'
      dhcp: 'on'
      vnet: 'on'
    dhclient: "{{ act_dhclient | dict2items }}"
    rcconf: "{{ act_rcconf | dict2items }}"
    pkglist: /tmp/ansible/ansible_client/pkgs.json

creates the template ansible_client

shell> iocage list -lt
+------+----------------+------+-------+----------+-----------------+--------------------+-----+----------+----------+
| JID  |      NAME      | BOOT | STATE |   TYPE   |     RELEASE     |        IP4         | IP6 | TEMPLATE | BASEJAIL |
+======+================+======+=======+==========+=================+====================+=====+==========+==========+
| None | ansible_client | off  | down  | template | 14.3-RELEASE-p1 | DHCP (not running) | -   | -        | no       |
+------+----------------+------+-------+----------+-----------------+--------------------+-----+----------+----------+

Note

• The attributes release and properties are mandatory.

• The lists dhclient and rcconf can be empty.

• The attribute pkglist is optional.

Hint

Look at the Index and search the playbook pb_iocage_template.yml what examples are available.

Ansible Client Template variables

A few variables are required to configure a template for Ansible clients. See the playbook tasks to learn details.

act_pkg: []
act_pkg_install: false
act_user: ''
act_pk: ''
act_sudo: false
act_rcconf: {}
act_dhclient: {}

See also

• Setting the Python interpreter

• Understanding privilege escalation

act_pkg

Install a list of packages. Put the list into the template attribute act_pkg. For example,

templates:
  ansible_client:
    act_pkg:
      - security/sudo
      - lang/python311
    ...

If this attribute is missing, the variable act_pkg is used. Below is the minimal list for an ansible client. Set the Python version to your needs

act_pkg:
  - security/sudo
  - lang/python311

Fit the list to your needs. Usually, you want to add gtar and other archivers. See the module ansible.builtin.unarchive. If you want to use the collection community.crypto add py-openssl

act_pkg:
  - lang/python311
  - security/sudo
  - archivers/gtar
  - security/py-openssl

Enable the installation by setting act_pkg_install=true (default=false).

Notes:

• As a first choice, use pkglist. Use act_pkg to install additional packages in an already created jail.

• The module community.general.pkgng is jail-aware. Quoting:

  jail: Pkg will execute in the given jail name or ID.
  

• It seems that a short UUID doesn’t work as a name. Use the ID instead

  jail: "{{ iocage_jails[item.key]['jid'] }}"
  

See also

• Setting the Python interpreter

• Understanding privilege escalation

act_user

Create a user in the jail. Usually, this user is used as the remote_user to connect to the jail.

act_user: admin

See also

• Setting a remote user

act_pk

A path to a file comprising the public keys allowed to connect to the act_user in the jail.

act_pk: pk_admins.txt

Warning

The module ansible.posix.authorized_key, used in this task, is not jail-aware. The user act_user must exist on the iocage host. Otherwise, the module ansible.posix.authorized_key will crash.

act_sudo

Add act_user to <dataset>/root/usr/local/etc/sudoers

act_sudo: true

The below passwordless entry will be created

line: "{{ _act_user }} ALL=(ALL) NOPASSWD: ALL"

Note

See Understanding privilege escalation

act_rcconf

Configure <dataset>/root/etc/rc.conf

act_rcconf:
  iocage_enable: "YES"
  sshd_enable: "YES"

act_dhclient

Create dhclient hooks in <dataset>/root/etc/

act_dhclient:
  dhclient-exit-hooks: |
    case "$reason" in
        "BOUND"|"REBIND"|"REBOOT"|"RENEW")
        echo $new_ip_address > /var/db/dhclient-hook.address.$interface
        ;;
    esac

Note

• These hooks are needed to configure hooks_results in inventory plugin vbotka.freebsd.iocage

• See man dhclient-script

pkglist

pkglist is an optional attribute of the dictionary templates. The value is a path on the iocage host where the file pkgs.json will be copied to. See the option --pkglist in man iocage

templates:
  ansible_client:
    pkglist: /tmp/ansible/ansible_client/pkgs.json
    ...

Create the file files/pkgs.json. For example,

{
    "pkgs": [
        "python311",
        "sudo"
        ]
}

The playbook tasks pkglist.yml expects the path files/pkgs.json to be relative to the inventory

- name: Copy pkglist files.
  ansible.builtin.copy:
    src: "{{ inventory_dir }}/files/{{ item.value.pkglist | basename }}"
    dest: "{{ item.value.pkglist }}"
  loop: "{{ _templates }}"
  vars:
    _templates: "{{ templates | dict2items
                              | selectattr('value.pkglist', 'defined') }}"

Fit the list to your needs. Usually, you want to add gtar and other archivers. See the module ansible.builtin.unarchive. Add py-openssl if you want to use the collection community.crypto

{
    "pkgs": [
        "python311",
        "sudo",
        "gtar",
        "py-openssl"
        ]
}

Note

iocage tests DNS on installing the packages:

Testing Host DNS response to pkg.freebsd.org
2025/08/06 01:18:12 (INFO) Testing ansible_client's SRV response to pkg.freebsd.org
2025/08/06 01:18:12 (INFO) Testing ansible_client's DNSSEC response to pkg.freebsd.org

See also

Install package inside jail vs install package from outside

Workflow

The last tasks template.yml convert the jails to templates. If you start the play again the first tasks setup.yml ends the host(s) if all templates have already been created. If you want to reconfigure already created template set template=0 manually. For example,

shell> iocage set template=0 ansible_client

If a running jail is needed start it

shell> iocage start ansible_client

Then, use the playbook tags to execute selected tasks. For example, to install additional packages, create the list of the packages act_pkg and run the play

(env) > ansible-playbook pb_iocage_template.yml -t pkg -e act_pkg_install=true

After the reconfiguration stop the jail and convert it to the template manually

shell> iocage stop ansible_client
shell> iocage set template=1 ansible_client

, or by the play

(env) > ansible-playbook pb_iocage_template.yml -t stop,template

pb_iocage_project_create

Synopsis

This playbook creates jails in a project.

Hint

Look at the Index and search the playbook pb_iocage_project_create.yml what examples are available.

Example

project:
  logserv_1:
    class: [logserv]
    vmm: iocage_01
  http_1:
    class: [http, logclient]
    vmm: iocage_02
  db_1:
    class: [db, logclient]
    vmm: iocage_02
  http_2:
    class: [http, logclient]
    vmm: iocage_04
  db_2:
    class: [db, logclient]
    vmm: iocage_04

pb_iocage_project_create_from_plugins

Synopsis

This playbook creates jails in a project.

Hint

Look at the Index and search the playbook pb_iocage_project_create_from_plugins.yml what examples are available.

Example

project:
  logserv:
    class: [logserv]
    plugin: syslog-ng
    vmm: iocage_05
  foo:
    class: [logclient]
    plugin: syslog-ng
    vmm: iocage_05
  bar:
    class: [logclient]
    plugin: syslog-ng
    vmm: iocage_05

pb_iocage_project_destroy

Synopsis

This playbook destroys a project.

Hint

Look at the Index and search the playbook pb_iocage_project_destroy.yml what examples are available.

pb_iocage_plugins

Synopsis

This playbook fetches iocage plugins.

Examples

enabled_plugins

Use the tag enabled_plugins to fetch the enabled iocage plugins. For example,

enabled_plugins:
  - ansible-pull-syslogng-client
  - ansible-pull-syslogng-server

project_plugins

Use the tag project_plugins to fetch the iocage plugins required by a project. For example,

project:
  logserv:
    class: [logserv]
    plugin: ansible-syslogng
    vmm: iocage_05
  foo:
    class: [logclient]
    plugin: ansible-syslogng
    vmm: iocage_05
  bar:
    class: [logclient]
    plugin: ansible-syslogng
    vmm: iocage_05

swarm_plugins

Use the tag swarm_plugins to fetch the iocage plugins required by a swarm. For example,

swarms:
  sw_01:
    count: 3
    plugin: ansible-zero

plugins

Declare the plugins in a dictionary. For example,

plugins:
  ansible-pull-syslogng-client:
    git: https://github.com/vbotka/iocage-plugins
    branch: main
    properties:
      bpf: 1
      dhcp: 1
      vnet: 1
  ansible-pull-syslogng-server:
    git: https://github.com/vbotka/iocage-plugins
    branch: main
    properties:
      bpf: 1
      dhcp: 1
      vnet: 1

Hint

To find the examples, search in the Index:

• pb_iocage_plugins.yml

• tag enabled_plugins

• tag project_plugins

• tag swarm_plugins

See also

• man iocage

Other iocage playbooks

• pb_iocage_destroy_all_jails.yml

• pb_iocage_start_all_jails.yml

• pb_iocage_update_repos.yml

• pb_iocage_update_vmm_repos.yml

Other playbooks

• pb_freebsd_custom_img.yml

• pb_install_repos_from_git.yml

• pb_preamble.yml

• pb_synchronize_csv.yml