Advanced Usage¶
Clones¶
When a jail is cloned, iocage creates a ZFS clone filesystem. Essentially, clones are cheap, lightweight, and writable snapshots.
A clone depends on its source snapshot and filesystem. To destroy the source jail and preserve its clones, the clone must be promoted first.
Create a Clone¶
To clone www01 to www02, run:
# iocage clone www01 --name www02
Clone a jail from an existing snapshot with:
# iocage clone www01@snapshotname --name www03
Promoting a Clone¶
Warning
This functionality isn’t fully added to iocage, and may not function as expected.
To promote a cloned jail, run:
iocage promote [UUID | NAME]
This reverses the clone and source jail relationship. The clone becomes the source and the source jail is demoted to a clone.
The demoted jail can now be removed:
iocage destroy [UUID | NAME]
Updating Jails¶
Warning
Updating a basejail is currently not implemented in iocage. Refer to iocage GitHub issue #50 for more information.
Updates are handled with the freebsd-update(8) utility. Jails can be updated while they are stopped or running. While updating can seem routine, it is always recommended to use ZFS snapshot functionality to create a backup of the jail before updating.
Create a backup snapshot of the jail:
iocage snapshot -n [snapshotname] [UUID | NAME]
To update a jail to latest patch level, run:
iocage update [UUID | NAME]
When updates are finished and the jail appears to function properly, remove the snapshot:
iocage snapremove [UUID|NAME]@[snapshotname]
To test updating without affecting a jail, create a clone and update the clone the same way as outlined above.
To clone a jail, run:
iocage clone [UUID|NAME] --name [testupdate]
Note
The [-n | –name] flag is optional. iocage assigns an UUID to the jail if [-n | –name] is not used.
Upgrading Jails¶
Upgrades are handled with the freebsd-update(8) utility. By default, the user must supply the new RELEASE for the jail’s upgrade. For example:
# iocage upgrade examplejail -r 11.0-RELEASE
Tells jail examplejail to upgrade its RELEASE to 11.0-RELEASE.
Upgrades are handled differently for basejails and the other types of jails, as a basejail is treated differently in iocage.
Upgrade a Standard Jail¶
To upgrade a Standard (non-basejail) jail to the host’s RELEASE, run:
iocage upgrade -r [11.1-RELEASE] [UUID | NAME]
This upgrades the jail to the same RELEASE as the host.
Upgrade basejail (Legacy ONLY)¶
Warning
This section only applies to legacy versions of iocage. Basejail upgrade functionality is not yet re-implemented in the current version.
Ugrading a basejail has a few steps. Always start by verifying the jail type, as this process only works with basejails. Running:
iocage get type [UUID|TAG]
needs to return basejail, for the desired jail.
Upgrading can be forced while the jail is online by executing:
iocage upgrade [UUID|TAG]
This forcibly re-clones the basejail filesystems while the jail is
running (no downtime) and update the jail’s /etc with the
changes from the new RELEASE.
To upgrade the jail while it is stopped, run:
iocage set release=[11.0-RELEASE] [UUID|TAG]
This causes the jail to re-clone its filesystems from the 11.0-RELEASE
on next jail start. This does not update the jail’s /etc files
with changes from the next RELEASE.
Auto-boot¶
Make sure iocage_enable="YES" is set in /etc/rc.conf.
To enable a jail to auto-boot during a system boot, simply run:
# iocage set boot=on UUID|NAME
Boot Priority¶
Boot order can be specified by setting the priority value:
iocage set priority=[20] [UUID|NAME]
Lower values are higher in the boot priority.
Snapshot Management¶
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:
iocage snaplist [UUID|NAME]
Create a new snapshot:
iocage snapshot [UUID|NAME]
This creates a snapshot based on the current time.
Resource Limits (Legacy ONLY)¶
Warning
This functionality is only available for legacy versions of iocage. It is not yet implemented in the current version. This applies to all subsections of Resource Limits.
iocage can enable optional resource limits for a jail. The outlined procedure here is meant to provide a starting point for the user.
Limit Cores or Threads¶
Limit a jail to a single thread or core #1:
iocage set cpuset=1 [UUID|TAG] iocage start [UUID|TAG]
Limit DRAM use¶
This example limits a jail to using 4 Gb DRAM memory (limiting RSS memory use can be done on-the-fly):
# iocage set memoryuse=4G:deny examplejail
Turn on Resource Limits¶
Turn on resource limiting for a jail with:
iocage set rlimits=on [UUID|TAG]
Limit CPU Usage by %¶
In this example, iocage limits testjail CPU execution to 20%, then applies the limitation to the active jail:
# iocage set pcpu=20:deny testjail
# iocage cap testjail
Double check the jail’s current limits to confirm the functionality:
# iocage limits testjail
Automatic Package Installation¶
Packages can be installed automatically at creation time!
Use the [-p | –pkglist] option at creation time, which needs to point to a JSON file containing one package name per line.
Note
An Internet connection is required for automatic package installations, as pkg install obtains packages from online repositories.
Create a pkgs.json file and add package names to it.
pkgs.json:
{
"pkgs": [
"nginx",
"tmux"
]
}
Now, create a jail and supply pkgs.json:
iocage create -r [RELEASE] -p [path-to/pkgs.json] -n [NAME]
Note
The [-n | –name] flag is optional. iocage assigns an UUID to the jail if [-n | –name] is not used.
This installs nginx and tmux in the newly created jail.