Repository files navigation

iocage is a jail/container manager amalgamating some of the best features andtechnologies the FreeBSD operating system has to offer. It is geared for easeof 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 py38-iocage

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

• pkg install python38 git-lite py38-cython py38-libzfs py38-pip
• git clone https://github.com/iocage/iocage
• make install as root

To install subsequent updates: runmake 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 py38-iocage

This repository replacesiocage_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 oldiocage package if it is installed (pkg delete iocage)
4. Installiocage using one of the methods above
5. Migrate the jails. This can be done by runningiocage list as root
6. Start the jails (service iocage onestart)

• iocage Project Website
• Documentation
• Mailing list

• 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!

Welike issues! If you are having trouble withiocage please open a GitHubissue and we willrun 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 likeuname -ro
• It would also be helpful if you gave us the output ofiocage --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 theMarkdown Basics GitHub page for more information on how to paste lines of code and terminal output.

Please be detailed on the exact use case of your change and a short demo ofit. Make sure it conforms with PEP-8 and that you supply a test with it ifrelevant. 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. Usezpool list and substitute it for thezpool you wish to use.

Fetch a release:

iocage fetch

Create a jail:

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

NOTE: em0 and 11.0-RELEASE are placeholders. Please replace them with yourreal interface (ifconfig) and RELEASE chosen duringiocage 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 usefulspot to begin configuration of your jail.

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

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

me:\        :charset=UTF-8:\        :lang=en_US.UTF-8:\        :setenv=LC_COLLATE=C:

• Kernel compiled with:

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

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

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

• Useiocage set to modify properties andiocage get to retrieve propertyvalues

• Typeiocage 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? Mountfdescfs:

    mount -t fdescfs null /dev/fd