A FreeBSD jail manager written in Python 3
Clone or download
skarekrow tkt-69267: Add --debug(-d) and --images(-i) flag to clean (#797)
* Add --debug(-d) and --images(-i) flag to clean

Also switch over to subprocess zfs as occasionally the base dataset would not be destroyed properly by py-libzfs.

FreeNAS Ticket: #69267

* Add new property to template created jails

- This allows us to destroy jails faster that are from templates.
- Destroy leftovers properly now
- Add iocroot_datasets property
- Remove context manager for zfs_get_property as it's not functioning, Waqar will have a PR for this and the other usages.

* Clarify message on debug cleaning

* Fix clean breaking from destroy behavior change

* Remove debug

* Fix thickjails key

* Use stdout, stderr instead of capture_output for python3.6

* Handle jails named 'root' and fix a string typo

* More fixes

- Use ioc_exceptions to suppress
- Properly handle jails named 'root' for templates
- Destroy leftover parent datasets of jails when a template is destroyed
- Reverse dataset direction to destroy in the correct order
- Add mountpoint special handling to zfs_get_property
- Use zfs_get_property for the hack88 portion to avoid superfluous messages about non-existent datasets during cleaning.

* Travis

* Add callback to IOCZFS

* Travis
Latest commit 679b567 Jan 17, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis Change travis over to new flatten modules for before Dec 22, 2018
doc Bump copyrights to 2019 Jan 3, 2019
iocage_cli tkt-69267: Add --debug(-d) and --images(-i) flag to clean (#797) Jan 16, 2019
iocage_lib tkt-69267: Add --debug(-d) and --images(-i) flag to clean (#797) Jan 16, 2019
rc.d Update rc.d script Jan 5, 2018
tests tkt-69267: Add --debug(-d) and --images(-i) flag to clean (#797) Jan 16, 2019
zsh-completion adds zsh completion to iocage (#394) Oct 16, 2017
.cirrus.yml Bug fix for jail ips (#804) Jan 14, 2019
.coveragerc Improve testing (#54) Feb 28, 2017
.gitignore Leverage jail(8) for shared IP networking behaviour (#770) Jan 2, 2019
.travis.yml remove manual checkout from Travis CI configuration May 16, 2017
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Jun 22, 2017
CONTRIBUTING.md run markdownlint-cli on *.md (#355) Sep 3, 2017
ISSUE_TEMPLATE.md Fix typo May 18, 2017
LICENSE Bump copyrights to 2019 Jan 3, 2019
Makefile Update Makefile (#751) Dec 22, 2018
README.md The dragons have gone back into their caves Jan 14, 2019
_config.yml Set theme jekyll-theme-tactile Jan 26, 2017
fastentrypoints.py use fast returns for less indentation and easier readability (#293) Aug 1, 2017
iocage Avoid false positive with EOL notice on jail updates Oct 10, 2018
iocage.8 Updated man page with hostid_strict_check option. (#798) Jan 11, 2019
iocage.8.gz Updated man page with hostid_strict_check option. (#798) Jan 11, 2019
requirements-dev.txt Flatten Python module names (#592) Aug 5, 2018
requirements.txt Catch a missing location, bump netifaces dep Jan 3, 2019
setup.cfg Add More tests (#740) Dec 20, 2018
setup.py Bump copyrights to 2019 Jan 3, 2019



Average time to resolve an issue Percentage of issues still open Python Version GitHub issues GitHub forks GitHub stars Twitter

A FreeBSD jail manager

iocage is a jail/container manager amalgamating 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.

iocage is in the FreeBSD ports tree as sysutils/py-iocage. To install using binary packages, simply run: pkg install py36-iocage



The FreeBSD source tree must be located at $SRC_BASE (/usr/src by default) to build from git.

  • pkg install python36 git-lite libgit2 py36-cython py36-pip
  • git clone --recursive https://github.com/iocage/iocage
  • make install as root

To install subsequent updates: run make install as root.


  • Build the port as follows: cd /usr/ports/sysutils/iocage/ ; make install clean


  • It is possible to install pre-built packages using pkg(8) if you are using FreeBSD 10 or above: pkg install py36-iocage

Upgrading from iocage_legacy:

This repository replaces iocage_legacy. To upgrade to the current version:

  1. Stop the jails (service iocage stop; iocage stop ALL)
  2. Back up your data
  3. Remove the old iocage package if it is installed (pkg delete iocage)
  4. Install iocage using one of the methods above
  5. Migrate the jails. This can be done by running iocage list as root
  6. Start the jails (service iocage onestart)



  • Some features of the previous iocage_legacy are either being dropped or simply not ported yet, feel free to open an issue asking about your favorite feature. But please search before opening a new one. PR's welcome for any feature you want!

Raising an issue:

We like issues! If you are having trouble with iocage please open a GitHub issue and we will run around with our hair on fire look into it. Before doing so, please give us some information about the situation:

  • Tell us what version of FreeBSD you are using with something like uname -ro
  • It would also be helpful if you gave us the output of iocage --version
  • Most importantly, try to be detailed. Simply stating "I tried consoling into a jail and it broke" will not help us very much.
  • Use the Markdown Basics GitHub page for more information on how to paste lines of code and terminal output.

Submitting a pull request:

Please be detailed on the exact use case of your change and a short demo of it. Make sure it conforms with PEP-8 and that you supply a test with it if relevant. Lines may not be longer then 80 characters.


  • Ease of use
  • Rapid jail creation within seconds
  • Automatic package installation
  • Virtual networking stacks (vnet)
  • Shared IP based jails (non vnet)
  • Transparent ZFS snapshot management
  • Export and import
  • And many more!


Activate a zpool:

iocage activate ZPOOL

NOTE: ZPOOL is a placeholder. Use zpool list and substitute it for the zpool you wish to use.

Fetch a release:

iocage fetch

Create a jail:

iocage create -n myjail ip4_addr="em0|" -r 11.0-RELEASE

NOTE: em0 and 11.0-RELEASE are placeholders. Please replace them with your real interface (ifconfig) and RELEASE chosen during iocage fetch.

Start the jail:

iocage start myjail

Congratulations, you have created your first jail with iocage! You can now use it like you would a real system. Since SSH won't be available by default, iocage console myjail is a useful spot to begin configuration of your jail.

To see a list of commands available to you now, type iocage outside the jail.


  • FreeBSD 9.3-RELEASE amd64 and higher or HardenedBSD/TrueOS
  • ZFS file system
  • Python 3.6+
  • UTF-8 locale (place into your ~/.login_conf):


  • Kernel compiled with:

      # This is optional and only needed if you need VNET
      options         VIMAGE # VNET/Vimage support

Helpful Considerations

  • For the explanations on jail properties read jail(8)

  • Create bridge0 and bridge1 interfaces for VNET jails to attach to.

  • Use iocage set to modify properties and iocage get to retrieve property values

  • Type iocage COMMAND --help to see any flags the command supports and their help, for example:

      iocage create --help
      iocage fetch --help
      iocage list --help
  • If using VNET consider adding the following to /etc/sysctl.conf on the host:

      net.inet.ip.forwarding=1       # Enable IP forwarding between interfaces
      net.link.bridge.pfil_onlyip=0  # Only pass IP packets when pfil is enabled
      net.link.bridge.pfil_bridge=0  # Packet filter on the bridge interface
      net.link.bridge.pfil_member=0  # Packet filter on the member interface
  • Lots of jails or a big server? Mount fdescfs:

      mount -t fdescfs null /dev/fd