Thursday 11 October 2018

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

Links and Resources




No comments: