Basic Usage¶
This section is about basic iocage usage and is meant as a “how-to” reference for new users.
Tip
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.
Tip
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:
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 [ftp.hostname.org]
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.
Tip
Partial entries can also be supplied for any other iocage operation or subcommand.
Start¶
Use iocage start to start jails.
Examples:
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
Stop¶
iocage stop uses the same syntax as iocage start.
Examples:
# iocage stop www01
# iocage stop 26e8e027-f00c-11e4-8f7f-3c970e80eb61
# iocage stop 26e8
Restart¶
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
Warning
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