vbotka.freebsd.iocage module – FreeBSD iocage jail handling

Note

This module is part of the vbotka.freebsd collection (version 0.2.7).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install vbotka.freebsd. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: vbotka.freebsd.iocage.

Synopsis

• The vbotka.freebsd.iocage module is wrapper to iocage command.

Requirements

The below requirements are needed on the host that executes this module.

• lang/python >= 3.6

• sysutils/iocage

Parameters

Parameter	Comments
args string	Additional arguments of vbotka.freebsd.iocage applied to the state. They will be applied to the sub-command create if the state is basejail, thickjail, template, present. If the same Ansible task also fetches a release as apart of the creation the arguments will not be applied to the sub-command fetch. Use separate task state=fetched and set args there if needed. Default: ""
bupdate boolean	Update the fetch to the latest patch level when state=fetched. Fetch and install binary updates when name is defined. This will start the jail. Choices: false ← (default) true
clone_from string	Clone the jail clone_from to name. Use properties to configure the clone.
cmd string	Execute the command cmd inside the specified jail name.
components aliases: files, component list / elements=path	Uses a local file directory for the root directory instead of HTTP to downloads and/or updates releases.
name string	name of the jail. States started, stopped, restarted accept ALL to start, stop, or restart all jails. States present, cloned, template, basejail, thickjail will return uuid and uuid_short if name is None or empty.
pkglist path	Path to a JSON file containing packages to install. Only applicable when creating a jail.
plugin string	Specify which plugin to fetch or update.
properties dictionary	properties of the jail. The jail will restart if any of the properties ip4_addr, ip6_addr, template, interfaces, vnet, host_hostname changes.
release string	Specify which RELEASE to fetch, update, or create a jail from. release defaults to the release of the remote host if state is one of basejail, thickjail, template, fetched, present. release also defaults to the release of the remote host if bupdate=True.
state string	state of the desired result. State absent by default force the destruction iocage destroy --force name. Choices: "absent" "basejail" "cloned" "exec" "facts" ← (default) "fetched" "get" "pkg" "present" "restarted" "set" "started" "stopped" "template" "thickjail"
user string	user who runs the command cmd. Default: "root"

Notes

Note

• Supports check_mode.

• There is no mandatory option.

• The module always creates facts iocage_releases, iocage_templates, and iocage_jails

• Returns module_args when debugging is set ANSIBLE_DEBUG=true

See Also

See also

iocage - A FreeBSD Jail Manager

iocage 1.2 documentation

iocage - jail manager using ZFS and VNET

FreeBSD System Manager’s Manual

Examples

- name: Create Ansible facts iocage_*. This is the default state.
  vbotka.freebsd.iocage:
    state: facts

- name: Display lists of bases, plugins, templates, and jails
  debug:
    msg: |-
      {{ iocage_releases }}
      {{ iocage_plugins.keys()|list }}
      {{ iocage_templates.keys()|list }}
      {{ iocage_jails.keys()|list }}

- name: Fetch the remote host's version of base
  vbotka.freebsd.iocage:
    state: fetched

- name: Fetch base 13.0-RELEASE
  vbotka.freebsd.iocage:
    state: fetched
    release: 13.0-RELEASE

- name: Fetch only components base.txz and doc.txz of the base 13.0-RELEASE
  vbotka.freebsd.iocage:
    state: fetched
    release: 13.0-RELEASE
    components: 'base.txz,doc.txz'

- name: Fetch plugin Tarsnap. Keep jails on failure.
  vbotka.freebsd.iocage:
    state: fetched
    plugin: Tarsnap
    args: -k

- name: Update or fetch components base.txz and doc.txz of the remote host's release.
        Fetch plugin Tarsnap. Keep jails on failure.
  vbotka.freebsd.iocage:
    state: fetched
    bupdate: true
    components: 'base.txz,doc.txz'
    plugin: Tarsnap
    args: -k

- name: Update the jail. This will start the jail.
  vbotka.freebsd.iocage:
    state: present
    bupdate: true
    name: foo

- name: Start jail
  vbotka.freebsd.iocage:
    state: started
    name: foo

- name: Start all jails
  vbotka.freebsd.iocage:
    state: started
    name: ALL

- name: Start all jails with boot=on
  vbotka.freebsd.iocage:
    state: started
    args: '--rc'

- name: Stop jail
  vbotka.freebsd.iocage:
    state: stopped
    name: foo

- name: Stop all jails
  vbotka.freebsd.iocage:
    state: stopped
    name: ALL

- name: Stop all jails with boot=on
  vbotka.freebsd.iocage:
    state: stopped
    args: '--rc'

- name: Restart jail
  vbotka.freebsd.iocage:
    state: restarted
    name: foo

- name: Restart all jails
  vbotka.freebsd.iocage:
    state: restarted
    name: ALL

- name: Set IP address of the jail
  vbotka.freebsd.iocage:
    state: set
    name: foo
    properties:
      vnet: 'on'
      defaultrouter: 10.1.0.10
      ip4_addr: 'vnet0|10.1.0.199/24'

- name: Create jail without cloning, install packages, and set properties.
        Use release of the remote host.
  vbotka.freebsd.iocage:
    state: present
    name: foo
    pkglist: /path/to/pkglist.json
    properties:
      ip4_addr: 'vnet0|10.1.0.199/24'
      boot: true
      allow_sysvipc: true
      defaultrouter: '10.1.0.1'

- name: Create template, install packages, and set properties.
        Use release of the remote host.
  vbotka.freebsd.iocage:
    state: template
    name: tplfoo
    pkglist: /path/to/pkglist.json
    properties:
      ip4_addr: 'lo1|10.1.0.5'
      boot: true
      allow_sysvipc: true
      defaultrouter: '10.1.0.1'

- name: Create a cloned jail. Creates basejail if needed.
  vbotka.freebsd.iocage:
    state: present
    name: foo
    clone_from: tplfoo
    pkglist: /path/to/pkglist.json
    properties:
      ip4_addr: 'lo1|10.1.0.5'
      boot: true
      allow_sysvipc: true
      defaultrouter: '10.1.0.1'

- name: Create a cloned jail. Name is automatically generated.
  vbotka.freebsd.iocage:
    state: present
    clone_from: tplfoo
  register: result
- name: Set variable contains the name of the created jail.
  set_fact:
    jname: "{{ result.uuid_short }}"

- name: Execute command in running jail
  vbotka.freebsd.iocage:
    state: exec
    name: foo
    cmd: service sshd start

- name: Execute pkg command in running jail
  vbotka.freebsd.iocage:
    state: pkg
    name: foo
    cmd: info

- name: Destroy jail
  vbotka.freebsd.iocage:
    state: absent
    name: foo

Returned Facts

Facts returned by this module are added/updated in the hostvars host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.

Key	Description
iocage_jails dictionary	Dictionary of all jails. Returned: always Sample: {}
iocage_plugins dictionary	Dictionary of all plugins. Returned: always Sample: {}
iocage_releases list / elements=string	List of all bases. Returned: always Sample: ["13.3-RELEASE", "13.4-RELEASE"]
iocage_templates dictionary	Dictionary of all templates. Returned: always Sample: {}

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
module_args dictionary	Information on how the module was invoked. Returned: debug
uuid string	Automatically generated unique ID of a jail. Returned: States present, cloned, template, basejail, thickjail if name is None or empty.
uuid_short string	First 8 characters of uuid. Set as a name of the jail. Returned: States present, cloned, template, basejail, thickjail if name is None or empty.

Authors

• Johannes Meixner (@xmj)

• Vladimir Botka (@vbotka)

• dgeo (@dgeo)

• Berend de Boer (@berenddeboer)

• Dr Josef Karthauser (@Infiniverse)

• Kevin P. Fleming (@kpfleming)

• Ross Williams (@overhacked)

• david8001 (@david8001)

• luto (@luto)

• Keve Müller (@kevemueller)

• Mårten Lindblad (@martenlindblad)

Collection links

• Issue Tracker
• Homepage
• Repository (Sources)