Advanced usage

Clones

When a jail is cloned, iocell 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.

Create a clone

To clone www01 to www02 run:

iocell clone www01 tag=www02

To clone a jail from an existing snapshot:

iocell clone www01@snapshotname tag=www03

Promoting a clone

To promote a cloned jail, simply run:

iocell 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:

iocell destroy UUID | TAG

Updating jails

Updates use freebsd-update(8) where supported by the selected userland. Use a maintenance window and stop affected services/jails for predictable results. A basejail update changes its shared release and can affect every jail using that release; it is not isolated to the named jail.

To update a jail to latest patch level run:

iocell update UUID | TAG

Non-basejail updates create a jail-root back-out snapshot. That snapshot does not back up a shared basejail release. Back up the shared release and application data separately before updating basejails.

When finished with updating and the jail is working OK, simply remove the snapshot:

iocell snapremove UUID|TAG@snapshotname

If a suitable jail snapshot exists, stop the jail before restoring it:

iocell rollback UUID|TAG@snapshotname

A clone is useful for testing writable jail data, but it can still use the same shared release as its source. Do not assume updating a basejail clone isolates shared base updates; use a separate test release/host when necessary.

To clone run:

iocell clone UUID|TAG tag=testupdate

Upgrading jails

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.

Upgrade non-basejail

To upgrade a normal jail (non basejail) to the hosts RELEASE run:

iocell upgrade UUID | TAG

This will upgrade the jail to the same RELEASE as the host.

To upgrade to a specific release run:

iocell upgrade UUID|TAG release=15.1-RELEASE

Upgrade basejail

To upgrade a basejail:

Verify whether the jail is a basejail:

iocell get type UUID|TAG

Should return type “basejail”.

Fetch the target release, stop the jail, and run:

iocell upgrade UUID|TAG release=15.1-RELEASE

This selects the new shared base and merges /etc using etcupdate. Inspect merge output and test the jail before returning it to service. There is no application-level zero-downtime guarantee. Independent full-userland upgrades may require interactive confirmations and several installation passes.

Setting release=15.1-RELEASE alone changes the selected base on the next start, but does not merge /etc. It is not equivalent to completing an upgrade.

Auto boot

Make sure iocell_enable="YES" is set in /etc/rc.conf.

To enable a jail to auto-boot during a boot, simply run:

iocell set boot=on UUID|TAG

Boot priority

Boot order can be specified by setting the priority value:

iocell set priority=20 UUID|TAG

Lower value means higher boot priority.

Snapshot management

iocell 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:

iocell snaplist UUID|TAG

To create a new snapshot run:

iocell snapshot UUID|TAG

This will create a snapshot based on current time.

If you’d like to create a snapshot with custom naming run:

iocell snapshot UUID|TAG@mysnapshotname

A normal snapshot covers only the jail’s root dataset. To include the jail’s configuration and all descendant datasets, take a recursive snapshot:

iocell snapshot -r UUID|TAG@mysnapshotname

Stop the jail before restoring a snapshot:

iocell stop UUID|TAG

iocell rollback UUID|TAG@mysnapshotname

Rollback restores only the root dataset for a normal snapshot, or the jail configuration and descendant datasets for a recursive snapshot. All targets must have the requested snapshot before rollback starts. A descendant created after a recursive snapshot therefore prevents rollback; iocell will not delete it automatically. Native ZFS properties and tag symlinks are not restored; a saved tag property can differ from the current alias namespace. Review that namespace before explicitly retagging a jail. Shared basejail release datasets are not restored.

Warning

Rollback discards changes and newer snapshots on the affected datasets. Multi-dataset rollback is not atomic. If ZFS reports an error, iocell stops immediately, but earlier datasets may already have been restored.

Resource limits

Resource limits require kernel RACCT/RCTL support and RACCT enabled at boot (kern.racct.enable=1 in the loader configuration). Check sysctl kern.racct.enable before using these examples. Verify actual kernel rules, not just stored property values.

Limit core or thread

Limit a jail to a single thread or core number 1:

iocell set cpuset=1 UUID|TAG iocell start UUID|TAG

List applied rules

List applied limits:

iocell limits UUID|TAG

Limit DRAM use

Limit a jail to 4G DRAM memory use (limit RSS memory use can be done on-the-fly):

iocell set memoryuse=4G:deny UUID|TAG

Turn on resource limits

Turn on resource limiting for jail:

iocell set rlimits=on UUID|TAG

Apply limits

Apply limit on-the-fly:

iocell cap UUID | TAG

Check limits

Check active limits:

iocell limits UUID | TAG

Limit CPU use by %

Limit CPU execution to 20%:

iocell set pcpu=20:deny UUID|TAG iocell cap UUID|TAG

Check limits:

iocell limits UUID | TAG

Resetting a jail’s properties

Record custom properties before requesting a reset:

iocell reset UUID | TAG

You can also reset every jail to the default properties:

iocell reset ALL

Reset carries forward the jail’s UUID, tag, generated VNET MAC addresses and selected networking/type fields. It uses built-in values for other properties; it does not reload defaults saved by set PROPERTY=value default. Those saved values apply to later create commands. Use explicit set commands when changing an existing jail to your chosen settings.

Replication and moves

iocell send backup-pool creates a fresh unique recursive snapshot of the active pool’s iocell tree and sends it to the destination. Existing snapshot-bearing replicas may need incremental streams rather than another full receive:

iocell send -i source-pool/iocell@before -i source-pool/iocell@after backup-pool

Use -I on both endpoints to include intermediate snapshots. Remote mode requires -r -u USER -h HOST and public-key SSH. The destination pool is validated on the receiver; no same-named local pool is needed.

iocell send -m new-pool is local only and requires stopped jails. The original source is removed only after successful transfer, destination activation and mounting. Snapshot, sender, receiver and optional buffer failures are errors. A failed activation retains data but may have relocated the source mountpoint; inspect state and explicitly reactivate the source before resuming operations.

After a successful transfer, -c removes older reserved ioc-send-* snapshots under the iocell tree, keeping the new common replication point. Failed transfers retain earlier bases. Cleanup does not delete dependent clones. Local transfers clean both ends; remote transfers clean only the sender, leaving receiver retention to the operator. A failed full transfer reports and retains its source snapshot for recovery.

Automatic package installation

Packages can be installed automatically at creation time!

Specify the pkglist property at creation time, which should point to a text file containing one package name per line. Please note you need to have Internet connection for this to work as pkg install will try to get the packages from online repositories.

Example:

Create a pkgs.txt file and add package names to it.

pkgs.txt:

nginx
tmux

Now simply create a jail and supply the pkgs.txt file:

iocell create pkglist=/path-to/pkgs.txt tag=myjail

This will install nginx and tmux in the newly created jail.