iocell

A FreeBSD jail manager using ZFS, VNET and resource limits.

Project website · Documentation

iocell continues the classic shell-based iocage interface. Jails can use shared-IP networking or a separate VNET stack, shared read-only base files, ZFS clones, templates, snapshots, quotas and optional kernel resource limits. Configuration is stored in UCL files alongside the ZFS datasets; native ZFS properties still control storage settings.

Status

Use a FreeBSD release receiving security updates and a compatible jail userland. See known limitations for command restrictions and storage behavior. See the 2.3.0 release notes for compatibility and recovery changes since 2.2.0.

Requirements and installation

• FreeBSD with ZFS and jail support, and at least one usable ZFS pool.
• uclcmd (the devel/uclcmd port/package); this is not a zero-dependency tool.
• Root for mutating commands; supported read-only commands can run unprivileged.
• VNET/VIMAGE kernel support only for VNET jails; shared-IP jails do not need it.
• RACCT/RCTL support and kern.racct.enable=1 at boot only for resource limits.
• Git for Git-backed workflows; SSH keys for remote operations. mbuffer is optional and must be available at both ends when selected by remote send.

The FreeBSD port is sysutils/iocell:

pkg install iocell

A packaged release may not include fixes in this checkout. To exercise the checkout directly on FreeBSD, install its dependencies and use sh ./iocell from the repository root in place of the installed iocell command.

Quick start

The example assumes an existing dedicated jail pool named jailpool, not the host's boot pool. Provision that pool separately and substitute its name.

iocell activate jailpool
iocell fetch release=15.1-RELEASE
iocell create release=15.1-RELEASE tag=myjail vnet=off \
    ip4_addr="em0|192.168.1.10/24"
iocell start myjail
iocell console myjail

Choose an available release compatible with your host. Specify it explicitly or use the interactive release prompt. Use an appropriate distribution mirror if its default location is no longer available; see basic usage, including recovery from a partial fetch.

Replace em0 with the host interface shown by ifconfig(8) and select an unused address on your own network. vnet=off is explicit because VNET-capable hosts otherwise enable VNET automatically. This creates a basejail, not a complete independent OS copy. Basejails depend on their fetched shared release.

For VNET, configure an appropriate bridge and routing/firewall policy first; see networking. Do not bridge jail interfaces onto a provider's public link if additional MAC addresses are prohibited. An isolated private bridge with host routing/NAT avoids exposing those MACs externally.

Commands and workflows

Use the canonical command reference rather than old command lists:

iocell help

The reference is maintained in lib/ioc-help; iocell.8 and iocell.8.txt are generated from that text. Full UUIDs and tags are supported; do not rely on short UUID prefixes except for image selection during import.

• Basic usage and package installation
• Jail types
• Templates
• Snapshots, rollback, updates and resource limits
• Operational guidance

Useful distinctions:

• create creates a basejail; create -e creates an empty filesystem, not a clone. Legacy create -b, -c, -t and base= recipes were already unsupported in 2.2.0 despite older docs; these are not newly removed modes.
• clone TAG@snapshot tag=newtag uses the requested snapshot. Existing delegated data requires its matching snapshot too; use recursive snapshots for that tree.
• restart TAG is a hard stop/start. restart -s TAG runs the configured stop/start commands and signals remaining processes, retaining the kernel jail/network.
• Template names must be valid safe ZFS components. Retag generated timestamp names before conversion. Invalid names fail before metadata/alias changes.
• Full sends take fresh unique snapshots. send -m removes only the original source after successful receive and activation. Existing replicas generally need incremental streams, not a forced full replacement.
• clean -t removes the templates tree, including its internal clones. Outside clones block cleanup unless -f explicitly permits their destruction. All cleanup operations are destructive.
• Historical chroot, record, package and show subcommands were already undispatched in 2.2.0. Use the documented current workflows instead.
• Experimental push and the portsnap fetch/update -p|-P forms are disabled or rejected in 2.3.0. See the release notes for the reasons, replacement workflows and stricter argument/error handling.

Reporting issues and contributing

Open issues at https://github.com/bartekrutkowski/iocell/issues with the command, complete output, uname -ro, jail type, relevant properties, and expected versus observed state. Include iocell version and the checkout's git rev-parse HEAD or installed package version.

Please open upstream pull requests against develop and follow CONTRIBUTING.md. Update lib/ioc-help before regenerating the manuals. The test guide distinguishes portable tests from opt-in FreeBSD/ZFS tests; never run the latter against production data.