Skip to content

Iocage

Alternatives:

mini howto:

https://www.truenas.com/community/threads/iocage-helper-thread.59988/

Setup

Vimage / VNET support

The shared IP variant is considered more mature. However, when working with many different VLANs it seems more sensible to me to work with bridges and VLANs while simultaneously utilizing VNET in FreeBSD.

As of FreeBSD 12, Vimage / VNET support is already an integral part of the kernel and no longer needs to be compiled in manually.

FreeBSD 11 and older

Shared IP operation may be more proven, but VNET definitely seems like the better solution to me. To use it, you need to compile the kernel with different options.

FreeBSD recently switched to using git for versioning the kernel and ports. For older systems, please refer to the history of this article to check out the kernel via SVN.

This part is also described here: https://forums.freebsd.org/threads/installing-and-updating-the-src-tree-with-git.78367/

pkg install git
cd /usr/src
git clonehttps://git.freebsd.org/src.gitssh://anongit@git.freebsd.org/src.git

Use the vnet config file for kernel compilation

cp -v /usr/src/share/examples/jails/VIMAGE /usr/src/sys/amd64/conf/VIMAGE

Compile kernel

cd /usr/src make KERNCONF=VIMAGE kernel

Alternatively, compile with 8 cores

make -j 8 KERNCONF=VIMAGE kernel

Place parameters in /etc/sysctl.conf:

net.inet.ip.forwarding=1 # Enable IP forwarding between interfaces
net.link.bridge.pfil_onlyip=0 # Only pass IP packets when pfil is enabled
net.link.bridge.pfil_bridge=0 # Packet filter on the bridge interface
net.link.bridge.pfil_member=0 # Packet filter on the member interface

Installing iocage

pkg install py38-iocage

Activate Usage

A ZFS volume must exist, in this example it is called zroot

iocage activate zroot

Fetch Available OS Images

iocage fetch

Specific version

iocage fetch -r 12.2-RELEASE

Managing Jails

Creating a Guest

iocage create -n test -r 12.2-RELEASE

static IPs and using a template

iocage create -n syncthing -r 11.2-RELEASE boot=on vnet=on dhcp=off ip4_addr="vnet0|10.10.101.62/24" defaultrouter="10.10.101.199" ip6_addr="vnet0|2001:1234:1234:1b:5679:a79:752d:2265/64" defaultrouter6="2001:1234:1234:1b:5054:ff:fe44:1062"
In this exampel the host is completely on autoconf, as well as IPv4 and IPv6
iocage create -n syncthing -r 12.2-RELEASE vnet=on dhcp=on bpf=1 ip6_addr="vnet0|accept_rtadv"

Unfortunately this alone is not enough; adjustments are also needed inside the guest in /etc/rc.conf

ipv6_activate_all_interfaces="YES"
rtsold_enable="YES"
ifconfig_epair0b="SYNCDHCP"
ifconfig_epair0b_ipv6="inet6 auto_linklocal accept_rtadv autoconf"

Connecting to a Guest

iocage console <<jailname>>

To disconnect, either type exit or press CTRL + D

Update Jail to Latest RELEASE

iocage update <<jailname>>

Stop Jail

iocage stop <<jailname>>

Start Jail

iocage start <<jailname>>

Listing Jails

List jails in short form

iocage list

List jails in more detail

iocage list -l

List existing templates in short form

iocage list -t

List existing templates in more detail

iocage list -l -t

List plugin jails

iocage list -P

Mount ZFS Volume

iocage fstab -a <<jailname>> <<path>>

Unmount ZFS Volume

iocage fstab -r <<jailname>> <<path>>

iocage Plugins

Index of available standard plugins:

https://raw.githubusercontent.com/freenas/iocage-ix-plugins/master/INDEX

Github repo with the *.json files

https://github.com/freenas/iocage-ix-plugins

List available plugins

iocage list -PR

List installed plugins

iocage list -P

Fetch a plugin and start it with DHCP

iocage fetch -P syncthing ip4_addr="igb0|dhcp"

Fetch a plugin and start it with a static IP

iocage fetch -P syncthing ip4_addr="igb0|192.168.2.10"

iocage Templates

You can also work with templates in iocage. This helps when provisioning new jails. NOTE: Templates do not help keeping many existing jails at a consistent version level. For that purpose you should use tools like Ansible. Otherwise, note the following when working with templates:

  • To modify a template, you must first convert it back to a jail with:
    iocage set template=0 syncthing
  • You should not rename a template if there are jails derived from it