Skip to content
A Python library to manage jails with ioc{age,ell}
Python Other
  1. Python 99.7%
  2. Other 0.3%
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github rename Python module ioc to libioc Jan 12, 2019
.travis correct libzfs.SendFlag typing Apr 24, 2018
docs fix sphinx-apidoc import in doc builder Aug 8, 2019
libioc check Fstab automount destination directory Nov 2, 2019
tests test hostuuid configuration Nov 2, 2019
.cirrus.yml install git dependency to Cirrus Ci May 11, 2019
.gitignore gitignore sphinx makefile Jan 5, 2019
.travis.yml use bmake on travis Feb 21, 2019 fork python module name iocage to ioc Jan 4, 2019 fork python module name iocage to ioc Jan 4, 2019
LICENSE.txt update license to 2019 Jan 4, 2019 rename iocage to libioc in Feb 4, 2019
Makefile suppress MyPy tracebacks in flake8 output Nov 1, 2019 link to gitter chat in readme Feb 24, 2019
requirements-dev.txt pin Python developer requirement bandit to version 1.5.1 May 9, 2019
requirements.txt sysctl NODE type can have int values May 9, 2019
setup.cfg do not print coverage report when tests have failed Mar 16, 2019


Python Library to manage FreeBSD jails with ioc{age,ell}.

iocage is a jail/container manager fusioning some of the best features and technologies the FreeBSD operating system has to offer. It is geared for ease of use with a simple and easy to understand command syntax.

This library provides programmatic access to iocage features and jails, while aiming to be compatible with iocage_legacy, iocell and the Python 3 version of iocage (< 1.0).


git clone
cd libioc
make install

At the current time libiocage is not packaged or available in FreeBSD ports.



Active ZFS pool

libiocage iterates over existing ZFS pools and stops at the first one with ZFS property org.freebsd.ioc:active set to yes. This behavior is the default used by other iocage variants and is restricted to one pool managed by iocage

Root Datasets configured in /etc/rc.conf

When iocage datasets are specified in the jail hosts /etc/rc.conf, libiocage prefers them over activated pool lookups. Every ZFS filesystem that iocage should use as root dataset has a distinct name and is configured as ioc_dataset_<NAME>="zroot/some-dataset/iocage", for example:

$ cat /etc/rc.conf | grep ^ioc_dataset

iocage commands default to the first root data source specified in the file. Operations can be pointed to an alternative root by prefixing the subject with the source name followed by a slash.

import ioc
release = libioc.Release("12.0-RELEASE")

jail_a = libioc.Jail(new=True, {})
ioc create othersource/myjail
ioc rename othersource/myjail myjail2

When othersource is the only datasource with a jail named myjail the above operation would have worked without explicitly stating the dataset name.

Legacy Support

With upcoming releases existing and future legacy / compatibility features will be disabled by default. Setting the sysrc ioc_legacy_support="YES" these compatibility features:

  • ZFS Basejail Support (iocage_legacy)

On initialization libioc detects the hosts sysrc setting ioc_legacy_support that can be enabled to unlock features liste above.

sysrc ioc_legacy_support="YES"



import ioc

jail = libioc.Jail()


libioc has a CLI tool called ioc that is no longer bundled with the library, but can be installed individually. It is inspired by the command line interface of iocage but meant to be developed along with the library and to spike on new features.


The API Reference (html) documenting all public interfaces of libioc is updated with every release. The information found in the reference is compiled from Python docstrings and MyPy typings using Sphinx.


Unit Tests

Unit tests may run on FreeBSD or HardenedBSD and require an activated ioc pool.

ZPOOL=zroot make test

Static Code Analysis

The project enforces PEP-8 code style and MyPy strong typing via flake8, that is required to pass before merging any changes. Together with Bandit checks for common security issues the static code analysis can be ran on Linux and BSD as both do not require py-libzfs or code execution.

make install-dev
make check

Project Status (Archive)


Progress towards the transition of python-iocage using libiocage has been made. Recent changes to both projects ensure compatibility running on the same host, so that it is now possible to partially utilize libiocage in iocage until a full migration is performed. Because some changes to the command line arguments and the script output will occur, @skarekrow will continue to maintain the current implementation until users had time to follow the deprecation warnings and suggestions.

In terms of the "Advanced container management with libiocage" tutorial at EuroBSDCon 2018 the Handbook was published.


libiocage is making small but continuous steps to stabilize the interfaces and become used in iocage/iocage. The project was first presented in the talk "Imprisoning software with libiocage" at BSDCan 2018 (Video Recording on YouTube). There will be a Tutorial about Advanced container management with libiocage on September 20th, 2018 at EuroBSDCon in Bucharest.

Ongoing preparations at this repository and iocage ensure that the transition to using libiocage under the hood of iocage go as smooth as possible for users. Features that exist in iocage will be further improved and tested or announced to be replaced or deprecated shortly. iXsystems let one imagine that libiocage once finds its way into FreeNAS where it can play its full strength behind a Web GUI.


As of November 2017 this project is working towards an alpha release. This means stabilization of command-line and library interfaces, so that proper integration tests can be built. This phase requires manual verification and testing until reaching feature-completion and compatibility with Python iocage and prior iocage_legacy versions with ZFS property and UCL file config storage.

You can’t perform that action at this time.