# Module vbotka.freebsd.iocage

    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

See also

module > iocage