Basic usage

Use an existing dedicated jail pool. These examples call it jailpool and use www01 as a tag; replace pool/release names, interfaces and addresses. See Known limitations for command restrictions and storage boundaries.

Activate a pool and fetch a release

Activate the dedicated pool first, not the host’s boot pool:

iocell activate jailpool

Then request an available release explicitly:

iocell fetch release=15.1-RELEASE

If the default mirror/path is unavailable, specify both, for example:

iocell fetch release=15.1-RELEASE ftphost=download.freebsd.org ftpdir=/releases/amd64/amd64/15.1-RELEASE

The architecture and directory must match the host and distribution server. The downloader also supports ftplocaldir=/path/to/distributions for local release archives. Use trusted distribution files and verify their provenance; do not assume every download/import path verifies a checksum.

Fetched releases include the base files and etcupdate data needed to create basejails. The fetch/update paths can apply patches with freebsd-update(8). Inspect their output and the resulting release before deploying it. Legacy -p/-P ports options rely on obsolete tooling; use current FreeBSD package or ports management instead.

Processing an existing release (including a repeated fetch to patch it) requires every iocell jail on the host to be stopped, including thick jails and jails on other releases or pools. This conservative guard is host-wide, not a check of which jails share this release. A first fetch of a new release has no such guard.

Recover an incomplete fetch

A failed fetch retains its datasets and cache. A retry refuses an incomplete release rather than re-extracting over potentially valuable data. Inspect and back up that data before deciding to discard it. Stop all iocell jails and check the exact pool, release, mounts, snapshots and clone dependencies. For an unneeded incomplete 15.1-RELEASE in the example jailpool only:

zfs list -r jailpool/iocell/releases/15.1-RELEASE
zfs list -r jailpool/iocell/download/15.1-RELEASE
zfs destroy -r jailpool/iocell/releases/15.1-RELEASE
zfs destroy -r jailpool/iocell/download/15.1-RELEASE
iocell fetch release=15.1-RELEASE

This deletes the partial release and its cached archives; substitute your actual pool/release, omit commands for absent datasets and never discard a needed release. Keep valid archives separately if you want to reuse them. Do not add -R or -f to overcome a dependent clone or busy mount, and do not recursively remove host directories after a failed ZFS command. clean -r removes all releases, not a single incomplete release.

Create a jail

iocell create creates a basejail using the host’s release and a generated timestamp tag. Fetch that release first. Its base directories are mounted read-only from the shared release when the jail starts; they are not an independent copy of the complete OS.

Prefer a meaningful tag and explicit networking mode:

iocell create release=15.1-RELEASE tag=www01 vnet=off ip4_addr="em0|192.168.1.10/24"

Replace em0 with your actual host interface and choose an unused address. VNET is enabled automatically on capable hosts unless overridden; its bridge and network configuration differ from this shared-IP example.

iocell create -e tag=empty-test creates an empty jail filesystem. It is not a lightweight clone and cannot boot a FreeBSD userland until that filesystem has been populated appropriately. Use iocell clone SOURCE tag=copy for a clone of an existing jail or template. Legacy create -b, -c, -t and base=... recipes were already unsupported in 2.2.0 despite older docs; these are not newly removed creation modes. See Jail types and Changelog for supported workflows and compatibility changes.

Installing packages during creation

Create a readable text file containing one package name per line, for example pkgconf. Blank lines and lines beginning with # are ignored:

iocell create tag=www01 vnet=off pkglist=/path/to/packages.txt

Relative list paths are resolved from the invocation directory. The selected release or template is mounted for installation and unmounted afterwards. An empty list is allowed; a missing or unreadable list is rejected before creating a jail.

Creation stops on the first package or mount error. The failed jail is retained for inspection, but is not started or reported as successfully created. With count, remaining jails are not created. Packages installed before an error are not rolled back. Failed unmounts are also errors: inspect reported mounts before retrying or deleting the failed jail.

Listing and lifecycle

iocell list lists jails, iocell list -r lists fetched releases and iocell list -t lists templates. The -s option selects a sort field; see iocell help for the supported fields.

Start and stop by tag or full UUID:

iocell start www01

iocell stop www01

A normal restart stops and recreates the jail:

iocell restart www01

For a soft restart, retaining the kernel jail and networking, specify -s:

iocell restart -s www01

This runs the configured stop/start commands and signals remaining processes; it does not guarantee graceful shutdown or recovery of every application.

Console and commands

iocell console www01 opens a shell in an already running jail. iocell console -f www01 starts it first if stopped, then opens the console. A failed startup returns an error without attempting login. To run a command without an interactive console:

iocell exec www01 /bin/sh -c 'echo ready'

For a stopped template, convert it back to a jail before normal start/console operations; see How to create and use templates.

Properties and defaults

Set and inspect a per-jail property:

iocell set tag=www02 www01

iocell get tag www02

iocell get all www02

Per-jail configuration writes retain one config.old last-write backup beside config. Later writes overwrite it; tag recovery may consume it. It is not a jail backup or a backup of an entire multi-property command.

iocell defaults displays configured defaults. Set defaults for subsequent create commands with iocell set vnet=off default, and inspect one with iocell get vnet default. Explicit creation properties override saved defaults; existing jails and cloned/imported configurations are unchanged. iocell get all default still does not dump all defaults.

Defaults are stored in the selected pool’s .default UCL file. Generated identity/runtime fields, active-pool selection, template selection/conversion and read-only ZFS properties cannot be set as creation defaults; see iocell help for the exact list. Writable native defaults such as compression affect new jail datasets, not existing datasets or their parent. Invalid names, empty values, invalid on/off switches and failed UCL writes leave the setting unchanged. Other value validation is incomplete; a stored string is not proof that every kernel combination will work. Multiple settings are independent updates, not a batch transaction.

Malformed syntax fails before pool/filesystem setup. Valid multi-target commands are not transactional: a runtime failure can follow earlier successful changes. Some property values are only partially validated. Quote values for the invoking shell; spaces, apostrophes and equals signs are preserved literally.

Destroy a jail

iocell destroy www02 asks for confirmation and refuses a running jail. Stop the jail first for a deliberate teardown. iocell destroy -f www02 bypasses confirmation and may stop a running jail before destroying it.

Warning

Destruction is irreversible. Verify identity, dependent clones and backups. Explicit template force-cleanup can also destroy clones outside its tree.