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.

You may use ALL as a target jail name for these commands if you want to target all jails at once.

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.

iocage snapshot [UUID|NAME] -n [SNAPSHOT NAME]

This creates a snapshot with the given name.

Delete a snapshot:

iocage snapremove [UUID|NAME] -n [SNAPSHOT NAME]

Delete all snapshots from a jail (requires -f / –force):

iocage snapremove [UUID|NAME] -n ALL -f

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]

List Applied Limits

List applied limits:

iocage limits [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]

Apply limits

Apply limits to a running jail with:

iocage cap [UUID | TAG]

Check Limits

Check the currently active limits on a jail with:

iocage limits [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.