Ansible Pot

I am a role to manage your Pot jails on FreeBSD. My source is located in the pot.org file.

Requirements

None.

Role Variables

Pot Server

Variable	Type	Choices	Required?	Default	Info
enabled	bool			False	Triggers pot init
vnet_enabled	bool			False	Triggers pot vnet-start
zfs_root	str			‘tank/pot’	Is written to pot.conf
fs_root	str			‘/opt/pot’	Is written to pot.conf
cache	str			‘/var/cache/pot’	Is written to pot.conf
tmp	str			‘/tmp’	Is written to pot.conf
mktemp_suffix	str			‘.XXXXXXXX’	Is written to pot.conf
hostname_max_length	int			64	Is written to pot.conf
network	str			‘10.192.0.0/10’	Is written to pot.conf
netmask	str			‘255.192.0.0’	Is written to pot.conf
gateway	str			‘10.192.0.1’	Is written to pot.conf
extif	str			‘em0’	Is written to pot.conf

---
pot:
  enabled: False
  vnet_enabled: False
  zfs_root: 'tank/pot'
  fs_root: '/opt/pot'
  cache: '/var/cache/pot'
  tmp: '/tmp'
  mktemp_suffix: '.XXXXXXXX'
  hostname_max_length: 64
  network: '10.192.0.0/10'
  netmask: '255.192.0.0'
  gateway: '10.192.0.1'
  extif: 'em0'

Collected Variables

Variable	Default	Info
initialized		If pot init has been run already.
vnet_initialized		If pot vnet-start has been run already.
version		The pot version.
fscomps	[]
bridges	[]
bases	[]
jails	{}	A JSON list of the data returned by pot info -p; keys are the jail names.

---
potintel:
  initialized: '{{ ansible_local.pot.initialized|default("") }}'
  vnet_initialized: '{{ ansible_local.pot.vnet_initialized|default("") }}'
  version: '{{ ansible_local.pot.version|default("") }}'
  fscomps: '{{ ansible_local.pot.fscomps|default("[]") }}'
  bridges: '{{ ansible_local.pot.bridges|default("[]") }}'
  bases: '{{ ansible_local.pot.bases|default("[]") }}'
  jails: '{{ ansible_local.pot.jails|default("{}") }}'

Pot Configuration Template

# {{ ansible_managed }}
# pot configuration file

# All datasets related to pot use the some zfs dataset as parent
# With this variable, you can choose which dataset has to be used
POT_ZFS_ROOT={{ pot.zfs_root|default("zroot/pot") }}

# It is also important to know where the root dataset is mounted
POT_FS_ROOT={{ pot.fs_root|default("/opt/pot") }}

# This is the cache used to import/export pots
POT_CACHE={{ pot.cache|default("/var/cache/pot") }}

# This is where pot is going to store temporary files
POT_TMP={{ pot.tmp|default("/tmp") }}

# This is the suffix added to temporary files created using mktemp,
# X is a placeholder for a random character, see mktemp(1)
POT_MKTEMP_SUFFIX={{ pot.mktemp_suffix|default(".XXXXXXXX") }}

# Define the max length of the hostname inside the pot
POT_HOSTNAME_MAX_LENGTH={{ pot.hostname_max_length|default(64) }}

# Internal Virtual Network configuration

# IPv4 Internal Virtual network
POT_NETWORK={{ pot.network|default("10.192.0.0/10") }}

# Internal Virtual Network netmask
POT_NETMASK={{ pot.netmask|default("255.192.0.0") }}

# The default gateway of the Internal Virtual Network
POT_GATEWAY={{ pot.gateway|default("10.192.0.1") }}

# The name of the network physical interface, to be used as default gateway
POT_EXTIF={{ pot.extif|default("em0") }}

{% if "extra_extif" in pot %}
# The list of extra network interface, to make other network segments accessible
POT_EXTRA_EXTIF={%- for item in pot.extra_extif %}{{ item.name }} {%- endfor %}

# for each extra interface, a variable is used to sepcify its network segment
{% for item in pot.extra_extif %}
POT_NETWORK_{{ item.name }}={{ item.netmask }}
{% endfor %}
{% else %}
# POT_EXTRA_EXTIF=expl0
# POT_NETWORK_expl0=
{% endif %}

# DNS on the Internal Virtual Network

# name of the pot running the DNS
POT_DNS_NAME={{ pot.dns_name|default() }}

# IP of the DNS
POT_DNS_IP={{ pot.dns_ip|default() }}

# VPN support

# name of the tunnel network interface
POT_VPN_EXTIF={{ pot.vpn_extif|default() }}

{% if "vpn_networks" in pot %}
POT_VPN_NETWORKS={%- for item in pot.vpn_networks %}{{ item }} {%- endfor %}
{% else %}
# POT_VPN_NETWORKS=
{% endif %}

# EOF

Plugins

Bridges Module

Pot bridges created with pot create-private-bridge.

Variable	Type	Choices	Required?	Default	Info
name	str		#t	None	The bridge name
size	int		#f	None	expected number of hosts
state	str	‘present’, ‘absent’	#f	‘present’
ignore	bool		#f	False

Examples

- name: Create private bridge
  pot_bridge:
    name: mybridge
    size: 5
- name: Check if creation was successful
  shell:
    cmd: if [ -f /opt/pot/bridges/mybridge ]; then exit 0; else exit 1; fi
  register: bridgetest
- name: Assert test result
  assert:
    that:
      - bridgetest.rc == 0

FS Components Module

The ones created with pot create-fscomp.

Variable	Type	Choices	Required?	Default	Info
name	str		#t	None	The fscomp name
state	str	‘present’, ‘absent’	#f	‘present’
ignore	bool		#f	False	Ignore this task?

Examples

Bases Module

The ones created with pot create-base.

Variable	Type	Choices	Required?	Default	Info
name	str		#t	None	The base name
release	str		#t	None	The FreeBSD release to use
state	str	‘present’, ‘absent’	#f	‘present’
ignore	bool		#f	False	Ignore this task?

Examples

Jails Module

For each jail, you can supply a number of arguments.

Variable	Type	Choices	Required?	Default	Info
name	str		#t	None	The jail name
state	str	‘present’, ‘absent’, ‘started’, ‘stopped’, ‘restarted’	#f	‘present’
ignore	bool		#f	False	Ignore this task?
ip	list	str	#f	[]	Defaults to auto
network_stack	str	‘ipv4’, ‘ipv6’, ‘dual’	#f	‘dual’
network_type	str	‘inherit’, ‘alias’, ‘public-bridge’, ‘private-bridge’	#f	‘inherit’
bridge_name	str		#f	None
base	str		#t	None
pot	str		#f	None
type	str	‘single’, ‘multi’	#f	‘multi’
level	int		#f	None
flavour	list	str	#f	[‘ansible-managed’]
mounts	list	dict	#f	[]	Things to mount
ports	list	dict	#f	[]	Ports to map
attributes	dict		#f	{}	Attributes

Options for mounts:

Variable	Type	Choices	Required?	Default	Info
target	path		#t	None	Mount point
dir	path		#f	None	Directory on the host to mount
fscomp	str		#f	None	fscomp to mount
dataset	str		#f	None	ZFS dataset to mount
direct	bool		#f	False	change the ZFS mount point instead of using nullfs
mode	str	‘ro’, ‘rw’	#f	‘rw’	Mount as read-only or read-write?

Options for ports:

Variable	Type	Choices	Required?	Default	Info
protocol	str	‘tcp’, ‘udp’	#f	‘tcp’
port	int		#t	None	The port to export
pot_port	int		#f	None	dynamically allocated by default

Return values:

Variable	Type	Info
ip	str	The assigned IP address

Examples

ansible-managed Flavour

A freshly created pot is somewhat useless if you want to manage it with Ansible, because there is no Python installation, and no sudo.

pkg install -y python3 sudo
pkg clean -ayq

- name: Install ansible-managed Flavour
  copy:
    dest: '/usr/local/etc/pot/flavours/ansible-managed.sh'
    src: 'ansible-managed.sh'
    mode: '0755'
  become: yes

Inventory

Pot Connection

This collection also provides a connection plugin to execute commands inside a Pot. Two variants are provided: one for local pots, and one for remote pots.

Local Pots

Variable	Type	Choices	Required?	Default	Info
ansible_host	str		#f	inventory_hostname	Name of the jail
ansible_user	str		#f		User inside the jail to run as

Examples

Remote Pots

Connecting to remote pots works almost like the SSH connection plugin - it is an extension of it. The difference is that you have to specify the name of the pot, and of course tell Ansible to use the zilti.pot.pot_remote connection plugin. Here’s an example inventory file:

[jails]
[email protected] ansible_connection=zilti.pot.pot_remote

Be aware that the connection plugin will need to use a become plugin to copy files into and out of the pot.

Lookup Plugin

This lookup plugin is currently in a testing phase.

Dependencies

Needs the community.general collection.

Example Playbook

- hosts: all
  become: yes
  remote_user: root
  roles:
  - role: zilti.pot.pot
    vars:
      pot:
	enabled: true
	vnet_enabled: true
	zfs_root: tank/pot
	extif: vtnet0
  tasks:
  - zilti.pot.pot_base:
      name: 13.1
      release: 13.1

  - zilti.pot.pot_fscomp:
      name: testfs

  - zilti.pot.pot_jail:
      name: testpot1
      base: 13.1
      type: single
      state: started
      mounts:
      - target: /opt
	fscomp: testfs

License

GPL3.0

Author Information

Daniel Ziltener, Code & Magic UG

Ansible Galaxy Metadata

requires_ansible: ">=2.9"

namespace: zilti
name: pot
version: 0.5.34

authors:
  - Daniel Ziltener <[email protected]>

dependencies:
  community.general: "*"

tags:
  - freebsd
  - jails
  - pot

readme: README.md
license: GPL-3.0-or-later
description: Roles and modules for installing and using Pot

repository: https://github.com/zilti/ansible-pot
issues: https://github.com/zilti/ansible-pot/issues
documentation: https://github.com/zilti/ansible-pot
homepage: https://github.com/zilti/ansible-pot

galaxy_info:
  author: Daniel Ziltener
  description: A role to manage Pot jails
  company: Code & Magic UG

  # If the issue tracker for your role is not on github, uncomment the
  # next line and provide a value
  # issue_tracker_url: http://example.com/issue/tracker

  # Choose a valid license ID from https://spdx.org - some suggested licenses:
  # - BSD-3-Clause (default)
  # - MIT
  # - GPL-2.0-or-later
  # - GPL-3.0-only
  # - Apache-2.0
  # - CC-BY-4.0
  license: GPL-3.0-or-later

  min_ansible_version: 2.9

  # If this a Container Enabled role, provide the minimum Ansible Container version.
  # min_ansible_container_version:

  #
  # Provide a list of supported platforms, and for each platform a list of versions.
  # If you don't wish to enumerate all versions for a particular platform, use 'all'.
  # To view available platforms and versions (or releases), visit:
  # https://galaxy.ansible.com/api/v1/platforms/

  platforms:
  - name: FreeBSD
    versions:
    - all

  galaxy_tags:
  - freebsd
  - jails
    # List tags for your role here, one per line. A tag is a keyword that describes
    # and categorizes the role. Users find roles by searching for tags. Be sure to
    # remove the '[]' above, if you add tags to this list.
    #
    # NOTE: A tag is limited to a single word comprised of alphanumeric characters.
    #       Maximum 20 tags per role.

dependencies: []
  # List your role dependencies here, one per line. Be sure to remove the '[]' above,
  # if you add dependencies to this list.