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

OPTIONS (red indicates it is required):

   args    Additional arguments of vbotka.freebsd.iocage applied to the
           `state'. They will be applied to the sub-command
           1mcreate0m 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 1mfetch0m. Use separate
           task 1mstate=fetched0m and set `args' there if needed.
        default: ''
        type: str

   bupdate  Update the fetch to the latest patch level when
            1mstate=fetched0m. Fetch and install binary updates
            when `name' is defined. This will start the jail.
        default: false
        type: bool

   clone_from  Clone the jail `clone_from' to `name'. Use `properties' to configure
               the clone.
        default: null
        type: str

   cmd     Execute the command `cmd' inside the specified jail `name'.
        default: null
        type: str

   components  Uses a local file directory for the root directory instead of HTTP
               to downloads and/or updates releases.
        aliases: [files, component]
        default: null
        elements: path
        type: list

   name    `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.
        default: null
        type: str

   pkglist  Path to a JSON file containing packages to install. Only applicable
            when creating a jail.
        default: null
        type: path

   plugin  Specify which plugin to fetch or update.
        default: null
        type: str

   properties  `properties' of the jail. The jail will restart if any of the
               properties 1mip4_addr, ip6_addr, template,
               interfaces, vnet, host_hostname0m changes.
        default: null
        type: dict

   release  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'.
        default: null
        type: str

   state   `state' of the desired result.
           State `absent' by default force the destruction `iocage
           destroy --force name'.
        choices: [absent, basejail, cloned, exec, facts, fetched, get, pkg, present, restarted, set,
          started, stopped, template, thickjail]
        default: facts
        type: str

   user    `user' who runs the command `cmd'.
        default: root
        type: str

NOTES:
      * Supports `check_mode'.
      * There is no mandatory option.
      * The module always creates facts 1miocage_releases0m,
        1miocage_templates0m, and 1miocage_jails0m
      * Returns 1mmodule_args0m when debugging is set
        `ANSIBLE_DEBUG=true'

SEE ALSO:
      * iocage - A FreeBSD Jail Manager
           iocage 1.2 documentation
           https://iocage.readthedocs.io/en/latest/
      * iocage - jail manager using ZFS and VNET
           FreeBSD System Manager's Manual
           https://www.freebsd.org/cgi/man.cgi?query=iocage

REQUIREMENTS:  lang/python >= 3.6, sysutils/iocage


AUTHOR: 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)

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

RETURN VALUES:

   ansible_facts  Facts to add to ansible_facts.
        returned: always
        type: dict
        contains:

           iocage_jails          Dictionary of all jails.
          returned: always
          sample: {}
          type: dict

           iocage_plugins          Dictionary of all plugins.
          returned: always
          sample: {}
          type: dict

           iocage_releases          List of all bases.
          elements: str
          returned: always
          sample: [13.3-RELEASE, 13.4-RELEASE]
          type: list

           iocage_templates          Dictionary of all templates.
          returned: always
          sample: {}
          type: dict

   module_args  Information on how the module was invoked.
        returned: debug
        type: dict

   uuid    Automatically generated unique ID of a jail.
        returned: States 4mpresent, cloned, template, basejail, thickjail0m if 4mname0m is `None'
          or empty.
        type: str

   uuid_short  First 8 characters of 4muuid0m. Set as a name of the jail.
        returned: States 4mpresent, cloned, template, basejail, thickjail0m if 4mname0m is `None'
          or empty.
        type: str

