Basic Usage

This section is about basic iocage usage and is meant as a “how-to” reference for new users.


Remember, command line help is always available by typing iocage --help or iocage [subcommand] --help.

iocage has a basic “flow” when first used. As a new user interacts with iocage for the first time, this flow guides them through initializing iocage, then interacting with newly created jails.


iocage has an experimental “color” mode enabled by setting the environment variable IOCAGE_COLOR to TRUE.

Setting Environment Variables

iocage currently has four environment variables:

iocage Environment Variables
Name Accepted Values Description
IOCAGE_LOGFILE FILE File location to have iocage log into.
IOCAGE_COLOR TRUE|FALSE Turns on a colored CLI output.
IOCAGE_FORCE TRUE|FALSE Required for any automatic migrations
IOCAGE_PLUGIN_IP IP_ADDR This environment variable is set in a plugin jail. Use it to quickly query it with another program/script

The process for setting these variables depends on the shell being used. The default FreeBSD shell csh/tcsh and the bash/sh shell are different from one another and require a slightly different process for setting environment variables. For example:

In the FreeBSD shell csh/tcsh , setenv IOCAGE_COLOR TRUE sets the environment variable IOCAGE_COLOR to true.

In the bash/sh shell, export IOCAGE_COLOR=TRUE sets the environment variable IOCAGE_COLOR to true.

Activate iocage

Before iocage is functional, it needs to activate. Essentially, iocage needs to link with a usable zpool. In most cases, activation is automatic to the primary system zpool, but more advanced users can use iocage activate to designate a different zpool for iocage usage.

Once iocage is ready with an active zpool, users are able to immediately begin downloading FreeBSD releases for jail creation.

Fetch a Release

iocage now needs to fetch a RELEASE, which is used to create jails. By default, typing iocage fetch opens a menu for the user to choose which release to download, as seen in this example:

# iocage fetch
[0] 9.3-RELEASE (EOL)
[1] 10.1-RELEASE (EOL)
[2] 10.2-RELEASE (EOL)
[3] 10.3-RELEASE
[4] 11.0-RELEASE

Type the number of the desired RELEASE
Press [Enter] to fetch the default selection: (11.0-RELEASE)
Type EXIT to quit: 4

Once the desired RELEASE is downloaded, the most recent patches are also applied to it.

iocage fetch also has a number of options and properties for users to fine-tune the functionality of the command.

To fetch the latest RELEASE,

iocage fetch -r LATEST

If a specific RELEASE is required, use the -r option:

iocage fetch -r [11.0-RELEASE]

If a specific download mirror is required, use the -s option:

iocage fetch -s []

fetch can also pull from a specific ftp directory, using the -d option:

iocage fetch -d [dir/]

Create a Jail

With a release downloaded, iocage is now able to create jails. There are two types of jails: normal and base. More details about these jail types can be found in the Jail Types section of this documentation.

Depending on the user’s requirements, the create subcommand can be adjusted to create either jail type. By default, iocage create creates a normal jail, but invoking the -b option changes the creation to the basejail type. iocage is able to create a jail with the latest release by adding LATEST to the create command.

Here is an example of creating a normal jail from the latest available release:

# iocage create -r LATEST -n [JAIL]

This creates a normal jail that is a clone of the latest release.

Here is an example of creating a normal jail from the 11.0-RELEASE:

# iocage create -r 11.0-RELEASE

This normal jail is a clone of the specified RELEASE.

To create multiple jails, use the -c option:

# iocage create -r 11.0-RELEASE -c 2

This example shows the numeric value after the -c flag is used to designate the number of jails to create. In the above example, two jails are created.

A simple basejail is created with the -b option:

iocage create -b -r [RELEASE]

After designating the type and number of jails to create with the option flags, specific jail properties can also be set. For example:

# iocage create -r 11.0-RELEASE --name myjail boot=on

Creates a FreeBSD 11.0-RELEASE jail with the custom name myjail and sets the jail to start at system boot time.

More information about jail properties is available in the iocage(8) FreeBSD manual page, accessible on a FreeBSD system by typing man iocage.

Listing Jails

To list all jails, use iocage list

To see all downloaded RELEASEs, use iocage list -r

View available templates with iocage list -t

Start, Stop, or Restart a Jail

Jails can be started, stopped, or restarted at any time. By default, new jails are in a down (stopped) state. To see the status of all jails, use iocage list and read the STATE column.

Use each jail’s UUID or custom NAME to start, stop, or restart it. Partial entries are acceptable, as long as the given characters are enough to identify the desired jail. Alternately, use ALL to apply the command to all created jails.


Partial entries can also be supplied for any other iocage operation or subcommand.


Use iocage start to start jails.


Start a jail with the custom name www01:

iocage start www01.

If no custom NAME or UUID is provided by the user, iocage automatically assigns a complex UUID to a new jail. This UUID is always usable when doing iocage operations like starting a jail:

# iocage start 26e8e027-f00c-11e4-8f7f-3c970e80eb61

Partial entries are also acceptable:

# iocaget start www

# iocage start 26e8


iocage stop uses the same syntax as iocage start.


# iocage stop www01

# iocage stop 26e8e027-f00c-11e4-8f7f-3c970e80eb61

# iocage stop 26e8


iocage restart also uses the same syntax as start and stop:

# iocage restart www01

# iocage restart 26e8e027-f00c-11e4-8f7f-3c970e80eb61

# iocage restart 26e8

Configure a Jail

Configuring the properties of an already created jail is best done with the set and get subcommands. Be sure to provide the NAME or UUID of the desired jail when using these subcommands.

Set Jail Property

iocage uses the set subcommand to configure jail properties.

To assign a custom note to a jail with the notes property:

# iocage set notes="This is a test jail." 26e8e027

The full list of jail properties is available in the iocage(8) manual page PROPERTIES section.

Get Jail Property

To view a specific jail property, use the get subcommand:

# iocage get notes 26e8e027

Get all properties:

Display the full list of a jail’s properties:

# iocage get all 26e8e027 | more

Destroy a Jail

Destroy a specific jail using the destroy subcommand:

# iocage destroy www02


This irreversibly destroys the jail!

Rename a Jail

iocage allows jails to be renamed after creation and/or migration. The iocage rename subcommand is used to alter an existing jail’s UUID or NAME. Type the command, then the UUID or name of the jail to be altered, then the desired name. This example shows using the rename subcommand:

# iocage rename jail1 TESTINGJAIL