When a jail is cloned, iocage creates a ZFS clone filesystem. In a nutshell clones are cheap lightweight writable snapshots.
A clone depends on its source snapshot and filesystem. If you’d like to destroy the source jail and preserve its clones you need to promote the clone first, otherwise the source jail cannot be destroyed.
To promote a cloned jail, simply run:
iocage promote UUID | TAG
The above step will reverse the clone and source jail relationship. Basically the clone will become the source and the source jail will be demoted to a clone.
Now you can remove the demoted jail with:
iocage destroy UUID | TAG
Updates are handled with the freebsd-update(8) utility. Jails can be updated while they are stopped or running.
To update a jail to latest patch level run:
iocage update UUID | TAG
This will create a back-out snapshot of the jail automatically.
When finished with updating and the jail is working OK, simply remove the snapshot:
iocage snapremove UUID|TAG@snapshotname
In case the update breaks the jail, simply revert back to the snapshot:
iocage rollback UUID|TAG@snapshotname
If you’d like to test updating without affecting a jail, create a clone and update the clone the same way as outlined above.
To clone run:
iocage clone UUID|TAG tag=testupdate
Upgrades are handled with the freebsd-update(8) utility. By default the upgrade command will try to upgrade the jail to the hosts RELEASE version (uname -r).
Based on the jail “type” property, upgrades are handled differently for basejails and non basejails.
To upgrade a normal jail (non basejail) to the hosts RELEASE run:
iocage upgrade UUID | TAG
This will upgrade the jail to the same RELEASE as the host.
To upgrade to a specific release run:
iocage upgrade UUID|TAG release=10.1-RELEASE
To upgrade a basejail:
Verify whether the jail is a basejail:
iocage get type UUID|TAG
Should return type “basejail”.
iocage set release=10.1-RELEASE UUID|TAG
This will cause the jail to re-clone its filesystems from 10.1-RELEASE on next jail start. This will not update the jails /etc files with changes from the next RELEASE.
Also the upgrade can be forced while the jail is online with executing:
iocage upgrade UUID|TAG
This will forcibly re-clone the basejail filesystems while the jail is running (no downtime) and update the jails /etc with the changes from the new RELEASE.
Make sure iocage_enable="YES" is set in /etc/rc.conf.
To enable a jail to auto-boot during a boot, simply run:
iocage set boot=on UUID|TAG
Boot order can be specified by setting the priority value:
iocage set priority=20 UUID|TAG
Lower value means higher boot priority.
iocage supports transparent ZFS snapshot management out of the box. Snapshots are point-in-time copies of data, a safety point to which a jail can be reverted at any time. Initially snapshots take up almost no space as only changing data is recorded.
List snapshots for a jail with:
iocage snaplist UUID|TAG
To create a new snapshot run:
iocage snapshot UUID|TAG
This will create a snapshot based on current time.
If you’d like to create a snapshot with custom naming run:
iocage snapshot UUID|TAG@mysnapshotname
iocage can enable optional resource limits for a jail. The outlined procedure should provide enough for a decent starting point.
Limit a jail to a single thread or core number 1:
iocage set cpuset=1 UUID|TAG iocage start UUID|TAG
Limit a jail to 4G DRAM memory use (limit RSS memory use can be done on-the-fly):
iocage set memoryuse=4G:deny UUID|TAG
Limit CPU execution to 20%:
iocage set pcpu=20:deny UUID|TAG iocage cap UUID|TAG
Check limits:
iocage limits UUID | TAG