iocage

Installation and configuration of iocage hosts and jails on FreeBSD. (Note: This may not work as intended on FreeNAS; contributions are welcome!)

Uses the iocage Ansible module from https://github.com/fractalcells/ansible-iocage (This is included in the role's library.)

It adds created hosts to the inventory (add_host) with a iocage_host variable containing the host's name and an iojails group.

Role Variables

(Found in defaults/main.yml)

• iocage_zpool (zroot): ZFS pool for iocage.

• iocage_fetch_args ({}): Arguments to pass to iocage fetch Example: "-s ftp.local -d pub/FreeBSD/releases".

• jail_list ([]): A list of jail definitions to be created on the host (details below).

• myjail (''): If specified, runs only this jail from jail_list (skips if not found).

• myjails ([]): Similar to myjail, but for multiple jails.

• iocage_components (none): If specified, only these components will be installed.

• iocage_enable_ssh (True): Enables SSH in new jails.

• iocage_release (uname -r): The FreeBSD release version you need.

• jail_init_role (): Specifies a role to initialize new jails.

• iocage_use_pkg (True): Indicates whether to install iocage from system packages (True) or from git (False).

Per-Jail Variables

(Found in vars/jail.yml)

• name (no default, mandatory): A unique human-readable identifier for the jail.

• hostname (''): Generated UUID if left empty.

• ip4 (''): IPv4 address(es) in the format required by iocage, e.g., [ifaceN|]192.0.2.1[/24][,[ifaceN|]192.0.2.1[/24][,…]]

  • If prefixed with 'iface|', the IP is assigned to the interface at jail boot.
  • If no mask is given, default is /32.

• ip6 (''): IPv6 similar to the IPv4 format (defaults to /128).

• resolver ('auto'): Content for resolv.conf in the jail, using ';' instead of newlines. (i.e., iocage will copy the host's settings if this is empty.)

• properties ({}): A dictionary for any iocage jail properties.

• authkeys (/root/.ssh/authorized_keys): The file to copy as /root/.ssh/authorized_keys in the jail.

Logic for resolver=auto

The resolver variable is automatically populated based on search_domains and resolvers defined in group_vars/all.yml. This setup selects the appropriate domain and resolver based on the jail's IP.

# If the IP is in the 'network', the corresponding 'domain' is added.
search_domains:
  - { network: '192.0.2.0/24', domain: 'our.example.net' }
  - { network: '198.51.100.0/24', domain: 'ryd.example.org' }
  - { network: '2001:0DB8:fe43::/32', domain: 'ipv6.example.org' }
  - { network: '0.0.0.0/0', domain: 'example.com' }

# If the IP is in the 'network', the corresponding 'ip' is added to the resolvers.
resolvers:
  - { network: '192.0.2.0/24', ip: 192.0.2.1 }
  - { network: '198.51.100.0/24', ip: 192.0.2.1 }
  - { network: '2001:0DB8:fe43::/56', ip: 2001:0DB8::1 }
  - { network: '0.0.0.0/0', ip: 8.8.8.8 }
  - { network: '::/0', ip: 2620:0:ccc::2 }

Example Playbooks:

A Jail Host with Two Jails:

- hosts: realmachine
  roles:
    - criecm.iocage
  vars:
    jail_list:
      - { name: myfirstjail, hostname: myfirstjail.example.org, ip4_addr: 'bge0|198.51.100.0' }
      - { name: mysecjail, hostname: mysecjail.example.org, ip4_addr: 'bge0|198.51.100.8' }

A Playbook Snippet to Create/Register the Jail Before Working on It:

- hosts: realmachine
  roles:
    - criecm.iocage
  vars:
    # jail_list can also be specified in inventory/host_vars/realmachine.yml
    myjail: myfirstjail

- hosts: myfirstjail
  roles:
    - criecm.apache
  […]

Updating the ansible-iocage Module from Source:

git subtree pull -P roles/criecm.iocage/library/src/iocage https://github.com/criecm/ansible-iocage.git master