How to Create and Configure an iocage Jail on FreeNAS 11.1

بسم الله الرحمن الرحيم

Abstract

Tutorial on how to create and configure an iocage jail on FreeNAS 11.1.

Assumptions and Prerequisites

OS: FreeNAS 11.1-U6
FreeNAS Host: fn
FreeNAS Network Interface: igb0
FreeNAS IP: 10.0.0.2
FreeNAS Subnet Mask: 24
Jail Container: iocage
iocage Version: 1.0 Alpha
Jail Release: 11.1-RELEASE
Jail Name: test
Jail Network Interface: vnet0
Jail Network Config: DHCP | STATIC
Jail IP: 10.0.0.3
Jail Default Route: 10.0.0.1
IP Version: IPv4
Bridge Network Interface: bridge0
DNS 1: 10.0.0.1
Domain: example.com
ZPool Volume: tank
Dataset: /mnt/tank/share

Instructions

List iocage Commands

root@fn:~ # iocage

Activate iocage zpool volume

Set iocage to use the default volume, use the following command.
root@fn:~ # iocage activate
or
Set iocage to use a zpool volume if more than one exist on the FreeNAS
iocage activate [zpool]
root@fn:~ # iocage activate tank

Fetch/Download a Release Image

Fetch a release which will be used to create a jail.

Fetch a release from a list
root@fn:~ # iocage fetch

Fetch a release by name
iocage fetch -r [RELEASE IMAGE NAME]
root@fn:~ # iocage fetch -r 11.1-RELEASE

Create a Jail with VNET/VIMAGE (Virtual Network Interface Stack) and DHCP

Command Example: iocage create -n "[Name]" -r [Release] vnet="on" bpf="yes" dhcp="on" allow_raw_sockets="1" boot="on" interfaces="vnet[N]:bridge[N]" resolver="search [DOMAIN];domain [DOMAIN];nameserver [DNS1 IP]

The following command creates a jail "test" from the "11.1-RELEASE" image with the following jail properties enabled, vnet/vimage network stack, Start on boot, and dhcp.

root@fn:~ # iocage create -n "test" -r 11.1-RELEASE vnet="on" bpf="yes" dhcp="on" allow_raw_sockets="1" boot="on" interfaces="vnet0:bridge0" resolver="search example.com;domain example.com;nameserver 10.0.0.1"

Create a Jail with VNET/VIMAGE (Virtual Network Interface Stack) and Static IP Configuration

Command Example: iocage create -n "[Name]" -r [Release] ip4_addr="vnet[N]|[IP]/[Mask]" defaultrouter="[IP]" vnet="on" allow_raw_sockets="1" boot="on" interfaces="vnet[N]:bridge[N]" resolver="search [DOMAIN];domain [DOMAIN];nameserver [DNS1 IP]"

root@fn:~ # iocage create -n "test" -r 11.1-RELEASE vnet="on" ip4_addr="vnet0|10.0.0.3/24" defaultrouter="10.0.0.1" vnet="on" allow_raw_sockets="1" boot="on" interfaces="vnet0:bridge0" resolver="search example.com;domain example.com;nameserver 10.0.0.1"

Create a Jail with a Shared IP

Command Example: iocage create -n "[Name]" -r [Release] ip4_addr="[IF]|[IP]/[MASK]" defaultrouter="[IP]" vnet="off" allow_raw_sockets="1" boot="on" resolver="search [DOMAIN];domain [DOMAIN];nameserver [DNS1 IP]"

root@fn:~ # iocage create -n "test" -r 11.1-RELEASE ip4_addr="igb0|10.0.0.100/24" defaultrouter="10.0.0.1" vnet="off" allow_raw_sockets="1" boot="on" resolver="search example.com;domain example.com;nameserver 10.0.0.1"

List Jails, Releases, and Plugins

List all Jails
root@fn:~ # iocage list

List all downloaded Releases
root@fn:~ # iocage list -r

List all available Templates
root@fn:~ # iocage list -t

List Remote Plugins
iocage list -PR
or
iocage list --plugins --remote

List Installed Plugins
iocage list -P
or
iocage list --plugins

Start, Stop, or Restart a Jail

Start a Jail

iocage start [JAIL NAME]

root@fn:~ # iocage start test

Stop a Jail

iocage stop [JAIL NAME]

root@fn:~ # iocage stop test

Restart a Jail

iocage restart [JAIL NAME]

root@fn:~ # iocage restart test

Configure a Jail

Set Jail Property

iocage set [PROPERTY]="[ARG]" [JAIL NAME]

root@fn:~ # iocage set notes="This is a test jail." test

Get Jail Property

iocage get [PROPERTY] [JAIL NAME]

root@fn:~ # iocage get notes test

Get All Properties of a Jail

iocage get all [JAIL NAME]

root@fn:~ # iocage get all test

Delete/Destroy a Jail

iocage destroy [JAIL NAME]

root@fn:~ # iocage destroy test

Rename a Jail

iocage rename [OLD JAIL NAME] [NEW JAIL NAME]

root@fn:~ # iocage rename test test2

Log in to a Jail

iocage console [JAIL NAME]

root@fn:~ # iocage console test

Run a command inside a Jail

iocage exec [JAIL NAME] "[COMMAND]"

root@fn:~ # iocage exec test "ls -lfa /etc"

Mount Dataset inside a Jail as Read Only

iocage fstab -a [JAIL NAME] /source/folder /destination/folder/in/jail nullfs ro 0 0

root@fn:~ # iocage fstab -a test /mnt/tank/share /mnt/share nullfs ro 0 0

Mount Dataset inside a Jail as Read and Write

iocage fstab -a [JAIL NAME] /source/folder /destination/folder/in/jail nullfs rw 0 0

root@fn:~ # iocage fstab -a test /mnt/tank/share /mnt/share nullfs rw 0 0

List Jail Mount Entries

iocage fstab -l [JAIL NAME]

root@fn:~ # iocage fstab -l test

Edit Jail Mount Entries

iocage fstab -e [JAIL NAME]

root@fn:~ # iocage fstab -e test

Remove a Jail Mount Entry

iocage fstab -r [JAIL NAME] [INDEX]

root@fn:~ # iocage fstab -r test 0

Create Jail Snapshot

iocage snapshot -n "[SNAPSHOT NAME]" [JAIL]
root@fn:~ # iocage snapshot -n "Recent Upgrade" test

List Jail Snapshots

iocage snaplist [JAIL]
root@fn:~ # iocage snaplist test

Remove/Delete Jail Snapshot

iocage snapremove -n "[SNAPSHOT NAME]" [JAIL]
root@fn:~ # iocage snapremove -n "Recent Upgrade" test

Rollback Jail to a Snapshot

iocage rollback -n "[SNAPSHOT NAME]" [JAIL]
root@fn:~ # iocage rollback -n "Recent Upgrade" test

Observations

DNS Resolver

When you create a Jail in iocage and skip to define the 'resolver' property, the iocage uses the host system's (in this case the FreeNAS host) default DNS settings defined in the '/etc/resolv.conf'.

If your FreeNAS has been configured as a Domain Controller, it resets the DNS setting in the '/etc/resolv.conf' to point to itself. Example: "nameserver 127.0.0.1". Incidentally, the iocage jail DNS is also set to 127.0.0.1. As a result, all the DNS queries within the jail fail because the jail points to itself as a nameserver where a name service does not exits. So, in order for the jail's DNS to work, we will need to manually define the resolver property for the jail.

And if you have a complicated network setup, like a switch with multiple VLANs. You will also need to define the 'defaultrouter' and 'interfaces' property so that the vnet interface is linked to the correct bridge interface and the bridge interface is link to the correct VLAN interface.

Helpful Commands

Check iocage version
root@fn:~ # iocage -v

iocage Help command
root@fn:~ # iocage --help

List all zpools on the FreeNAS
root@fn:~ # zpool list

Delete Release
iocage destroy -r [RELEASE NAME]
root@fn:~ # iocage destroy -r 11.0-RELEASE

Mujahid Jaleel - My Life, My Blog

Thursday, 11 October 2018