بسم الله الرحمن الرحيم
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
iocage snapshot -n "[SNAPSHOT NAME]" [JAIL]
root@fn:~ # iocage snapshot -n "Recent Upgrade" test
iocage snaplist [JAIL]
root@fn:~ # iocage snaplist test
iocage snapremove -n "[SNAPSHOT NAME]" [JAIL]
root@fn:~ # iocage snapremove -n "Recent Upgrade" test
iocage rollback -n "[SNAPSHOT NAME]" [JAIL]
root@fn:~ # iocage rollback -n "Recent Upgrade" test
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.
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
Links and Resources
- http://iocage.readthedocs.io/en/latest/index.html
- https://forums.freenas.org/index.php?threads/iocage-helper-thread.59988/
