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