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¶
Updates are handled with the freebsd-update(8) utility. Jails can be updated while they are stopped or running.
Note
The command iocage update [UUID | NAME] automatically creates a backup snapshot of the jail given.
To create a backup snapshot manually, run:
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.
Note
It is recommended to keep the iocage host and jails RELEASE synchronized.
To upgrade a 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. This method also applies to basejails.
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
Note
Setting boot=on during jail creation starts the jail after the jail is created.
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.
Depends Property¶
Use the depends property to require other jails to start
before this one. It is space delimited. Jails listed as dependents
also wait to start if those jails have listed depends.
Example: iocage set depends=“foo bar” baz
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.