iocage

by iocage

iocage /iocage

A FreeBSD jail manager written in Python 3

453 Stars 121 Forks Last release: 12 months ago (1.2) Other 1.9K Commits 42 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

iocage

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

Installation

GitHub:

The FreeBSD source tree must be located at

$SRC_BASE
(
/usr/src
by default) to build from git.
  • pkg install python36 git-lite 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.

Ports:

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

Pkg:

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

Links

WARNING:

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

FEATURES

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

QUICK HOWTO

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|192.168.1.10/24" -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.

REQUIREMENTS

  • FreeBSD 9.3-RELEASE amd64 and higher or HardenedBSD/TrueOS
  • ZFS file system
  • Python 3.6+
  • UTF-8 locale (place into your ~/.login_conf):
me:\
        :charset=UTF-8:\
        :lang=en_US.UTF-8:\
        :setenv=LC_COLLATE=C:

Optional

  • 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
    

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.