NAME

SYNOPSIS

DESCRIPTION

Both shared IP jails and VNET jails are supported.

Each jail has a unique ID (UUID) which is automatically generated at creation time. Using the UUID as a jail identifier is more flexible when replicating a jail in a distributed environment. This also eliminates potential naming clashes on large scale deployments and helps reduce operator error.

Partial UUID calling is supported with every operation. For example, adae47cb-01a8-11e4-aa78-3c970ea3222f can be used in the form of adae47cb or just adae. In addition to partial UUID calling, jail NAMEs can also be used.

Jails can be easily moved with ZFS send and receive, preserving all of their properties automatically.

iocage relies on ZFS and at least one ZFS pool must be present on the host system. Bridge interfaces like bridge0 or bridge1 are required for VNET and can be enabled by adding this line to /etc/rc.conf:

cloned_interfaces="bridge0 bridge1"

To enable all the features iocage supports, consider building a kernel with these options:

options         VIMAGE
options         RACCT
options         RCTL

SUBCOMMANDS

-D | --debug

Log iocage debug output to the console.

--help

Display iocage help text. Including --help after a specific subcommand displays help text for that command.

--version

Display the iocage version number.

activate

Intended for use by automation tools. The pool can be activated for iocage jails without requiring user input. By default, all other pools are deactivated.

Example:

# iocage activate examplezpool

chroot

Chroot into a jail without actually starting the jail itself. Useful for initial setup like setting a root password or configuring networking. A command can be specified as with the normal system, see chroot(8).

Example:

# iocage chroot 6ffe99a9 ls

Run ls in the jail identified by the shortened UUID.

clean

Destroy ZFS datasets.

Options:

[-a | --all | dataset_type]

Destroys all created iocage data.

[-b | -r | --base | dataset_type]

Destroys all fetched RELEASE jails.

[-f | --force]

Runs the command without any further user interaction.

[-j | --jails | dataset_type]

Destroys all created jails.

[-t | --template | dataset_type]

Destroys all templates.

Example:

# iocage clean -j

Destroys all created jails on the system, after a prompt ensures this is the desired action.

clone

Clone a jail. Properties can be configured for the clone by listing them after the UUID | NAME.

Options:

[-c | --count TEXT]

Designate the number of jails to create, all cloned from the desired jail.

Examples:

# iocage clone 38114a58 --name cloneexample1

Clone jail 38114a58 and add the name cloneexample1 to the new jail.

# iocage clone exampjail -c 3

Creates three jail clones of exampjail.

console

Execute login to open a shell inside the jail.

Options:

[-f | --force]

Start the jail if it is not running.

Examples:

# iocage console cloneexample1

# iocage console -f jail1

create

Deploy a new jail based on the host operating system's RELEASE. The default can be overridden by specifying the RELEASE option. A fully independent jail set is created by default.

Options:

[-b | --basejail]

Create a new "basejail". Basejails copy the RELEASE and mount the designated RELEASE directories as nullfs mounts over the jail directories.

[-c | --count TEXT]

Designate the number of jails to create, all cloned from the desired [-r RELEASE].

[-e | --empty]

Create an empty jail for unsupported or custom jails.

[-f | --force]

Skip prompts, auto-confirming them with yes.

[-n | --name TEXT]

Provide a NAME instead of a UUID for the new jail.

[-p | --pkglist TEXT]

Specify a JSON file which manages the installation of each package in the newly created jail.

[-r | --release TEXT]

Specify which RELEASE to use for the new jail.

[-r | --release latest | LATEST]

Creat a new jail with the latest release available.

[-s | --short]

Use a short UUID of 8 characters instead of the default 36.

[-t | --template TEXT]

Create a jail from the specified template.

[-B | --clone_basejail]

Create a new "clone basejail". Clone basejails clone the RELEASE with ZFS and mount the designated RELEASE directories as nullfs mounts over the jail directories.

[-T | --thickjail]

Thick jails are copies of the release, not clones.

[-u | --uuid TEXT]

Specify a desired UUID for the new jail.

Examples:

# iocage create -s -r 11.0-RELEASE

Create a FreeBSD 11.0 jail with a shortened UUID.

# iocage create -r 11.0-RELEASE -u 12345678

Create a FreeBSD 11.0 jail with the custom UUID 12345678.

# iocage create -c 3 -r 11.0-RELEASE -n examplejail

This command creates three identical jails based off the FreeBSD 11.0 RELEASE. These jails are sequentially numbered based on the custom NAME.

destroy

Destroy the specified jail. Caution, this subcommand is irreversible. destroy only works with a stopped jail.

Options:

[-R | --recursive]

Skip the destroy children prompt. This is best used with the [-f | --force] option.

[-d | --download]

Also destroy the specified RELEASE download.

[-f | --force]

Destroy the jail with no further warnings or user input.

[-r | --release]

Destroy a specified RELEASE dataset.

Examples:

# iocage destroy 12345678 -f

Destroy the identified jail with no further input.

# iocage destroy -r 10.1-RELEASE

Destroy the downloaded FreeBSD 10.1 release.

df

Show resource usage of all jails. Invoking df displays a table with several fields:

UUID

unique jail ID

CRT

compression ratio

RES

reserved space

QTA

disk quota

USE

used space

AVA

available space

NAME

jail name

Options:

[-H | -h | --header]

Use when scripting, using tabs for separators.

[-l | --long]

Shows the full UUID.

[-s | --sort TEXT]

Sorts the list by the named type.

Example:

# iocage df -l

Displays the usage table with the full UUID of each jail.

exec

Execute a command inside the specified jail. This is an iocage UUID/NAME wrapper for jexec(8). After invoking exec, specify the jail, any commands to run inside that jail, and any arguments for those commands. jexec also runs commands similar to iocage. When using jexec use the JID instead of the jail name. For more info see the manual page for jexec. Use -- in front of the specified command to prevent iocage from parsing them.

Options:

[-f | --force]

Start the jail if it is not running.

[-U | --jail_user NAME]

Specifies which jail user runs the command.

[-u | --host_user NAME]

Specify which host user runs the command.

Examples:

# iocage exec -f examplejail_1 ls /tmp

Starts examplejail_1 and lists the contents of the /tmp directory.

# iocage exec examplejail_1 cat COPYRIGHT | less

In this example, examplejail_1 executes cat COPYRIGHT, while the output is run with less outside the jail on the primary system.

export

Exports the specified jail. An archive file is created in /iocage/images with an SHA256 checksum. The jail must be stopped before exporting.

Example:

# iocage export examplejail_2

fetch

Downloads and/or updates releases.

fetch must be executed as the first command on a pristine system. The host node's RELEASE is downloaded for deployment. If other releases are required, this can be changed by supplying the required release property or selecting the appropriate RELEASE from the menu list.

Options:

[--accept]

Accept the plugin's LICENSE agreement.

[--noaccept]

Do not accept the plugin's LICENSE agreement.

[--plugins OPTIONS]

Fetch and create a plugin.

[--plugins --official OPTIONS]

Fetch and create an official FreeNAS plugin.

[-E | --eol]

Enable End Of Life (EOL) checking upstream.

[-F | --files TEXT]

Uses a local file directory for the root directory instead of HTTP.

[-NE | --noeol]

Disable EOL checking upstream.

[-NU | --noupdate]

Disable updating the fetch item to the latest patch level.

[-NV | --noverify]

Disable verifying the SSL cert for HTTP fetching.

[-P | --plugin-file TEXT]

Specify which plugin file to use.

[-U | --update]

Update the fetch to the latest patch level.

[-V | --verify]

Enable verifying the SSL cert for HTTP fetching.

[-a | --auth TEXT]

Specifies the authentication method for HTTP fetching. Current values are basic and digest.

[-c | --count TEXT]

Used when fetching a plugin. This option creates the designated number of plugin type jails.

[-d | --root-dir TEXT]

Specify the root directory containing all RELEASE files.

[-f | --file]

Use a local file directory for the root directory instead of HTTP.

[-h | --http]

No-op flag for backwords compatibility. Previous versions of iocage used this to adjust [-s | --server] to define an HTTP server.

[-p | --password TEXT]

Add a password, if required.

[-r | --release TEXT]

Define the FreeBSD release to fetch.

[-r latest | LATEST]

Fetches the latest release.

[-s | --server TEXT]

Define the server from which to fetch the RELEASE.

[-u | --user TEXT]

Define the user.

Examples:

# iocage fetch

iocage lists available FreeBSD releases and asks which to download. Enter the numeric option for the desired release, or type EXIT to quit without downloading.

# iocage fetch --release 10.3-RELEASE

This tells iocage to download and automatically update the FreeBSD 10.3 RELEASE. This can also be used to apply the latest patches to an already downloaded release. Newly created jails or basejails are automatically updated.

# iocage fetch -NE -r 11.0-RELEASE

This disables the end of life check, then fetches the FreeBSD 11.0 release and updates with the latest patches.

# iocage fetch -r LATEST

This fetches the latest release available.

fstab

Manipulates the fstab settings of a specific jail. Name any options, then the jail, and finally all needed fstab strings.

Options:

[-H | -h | --header]

For scripting. Use tabs for separators.

[-R | --replace]

Replace an entry by index number.

[-a | --add | action]

Adds an entry to the specific jail's fstab and mounts it.

[-e | --edit | action]

Opens the fstab file in the default editor.

[-l | --list]

List the jail's fstab.

[-r | --remove | action]

Remove an entry from a specific jail's fstab and unmounts it.

Example:

# iocage fstab -a example_jail_1 /usr/home /usr/home nullfs rw 0 0

get

Display the specified property. List the property, then the UUID or NAME of the jail to search.

Options:

[-H | -h | --header]

Used in scripting. Use tabs for separators.

[-P | --plugin [-f | --force]]

Get the specified key for a plugin jail. The -f | --force option starts the jail if it is not already running. -f | --force only works with -P | --plugin.

[-a | --all]

Get all properties for the specified jail. If accessing a nested key, use "." as a separator.

[-p | --pool]

Get the currently activated zpool.

[-r | --recursive]

Get the specified property for all jails.

[-s | state]

Return the state of the jail.

[-j | JID]

Return the JID.

Examples:

# iocage get -p

Outputs the name of the activated zpool.

# iocage get -a examplejail_1 | less

List all properties of examplejail_1 and send the output through less.

# iocage get -r dhcp

Displays a table with each jail's UUID or NAME and the status of the requested property.

# iocage get -s examplejail_1

Return whether the state of the jail is up or down.

import

Import a specific jail image. Short UUIDs can be used, but do not specify the full filename, only the UUID.

Example:

# iocage import 064c247

list

List the specified dataset type. By default, all jails are listed.

Options:

[--http]

Changes [-R | --remote] to use HTTP.

[-H | -h | --header]

Used in scripting. Use tabs for separators.

[-P | --plugins]

Shows plugins installed on the system.

[-PRO]

Lists official plugins available for download.

[-R | --remote]

Shows available RELEASE options for remote.

[-b | -r | --base | --release | dataset_type]

List all bases.

[-l | --long]

Shows JID, NAME, BOOT, STATE, TYPE, RELEASE, IP4, IP6, and TEMPLATE information.

[-q | --quick]

Lists all jails with less processing and fields.

[-s | --sort TEXT]

Sorts the list by the given type.

[-t | --template | dataset_type]

Lists all templates.

Example:

# iocage list

Displays a table containing several elements for each installed jail:

JID

Jail identifier

UUID

Unique identifcation number.

STATE

Displays the active state of the jail. Can be up or down.

NAME

The user assigned NAME.

RELEASE

The jail's FreeBSD RELEASE.

IP4

Shows the availability of IP4 addresses.

migrate

Migrate from the development version of iocage-legacy to the current jail format.

Options:

[-d | --delete]

Destroy the old dataset after migration.

[-f | --force]

Bypass any further warning or required user interaction.

Example:

# iocage migrate -d -f

Migrates to the new jail format and deletes the old dataset with no further user interaction.

pkg

Run desired pkg commands in the specified jail. List the jail's UUID or NAME, then any desired commands.

rename

Rename the specified jail.

Examples:

# iocage rename jail1 NEWNAME

Jail: jail1 renamed to NEWNAME

restart

Restart the specified jail, OR use ALL to restart all jails.

Options:

[-s | --soft]

Restart the jail, but do not tear down the network stack.

Examples:

# iocage restart ALL

# iocage restart --soft examplejail1

rollback

Roll back a jail to an existing snapshot. Any intermediate snapshots are destroyed in the process. For more information on this functionality, please see zfs(8).

Options:

[-f | --force]

Run the command, skipping any warnings or further user interaction.

-n | --name TEXT

[Required] Used to specify the snapshot name.

Example:

# iocage rollback -n snapshottest2 examplejail1

set

Set the specified properties in the desired jail. Type the desired properties separated by a space, then the jail UUID or NAME to apply the changes.

Options:

[-P | --plugin KEY]

Set the specified key for a plugin jail. If accessing a nested key, use "." as a separator.

Examples:

# iocage set boot=1 notes="Example note." testjail -P foo.bar.baz=VALUE PLUGIN

snaplist

List snapshots of a jail. A number of different fields are displayed:

NAME

snapshot name

CREATED

creation time

RSIZE

referenced size

USED

used space

Options:

[-H | -h | --header]

Used for scripting. Tabs are used as separators.

[-l | --long]

Show the full dataset path for the snapshot.

[-s | --sort TYPE]

Sort the returned list by the named TYPE.

Example:

# iocage snaplist examplejail1

# iocage snaplist FOO -s name

snapremove

Delete snapshots of the specified jail. If the keyword [ALL] is used, all snapshots the specified jail are deleted.

Options:

[-n | --name TEXT]

[Required] The snapshot name.

Example:

# iocage snapremove -n snapshottest1 examplejail1

snapshot

Create a ZFS snapshot of the specified jail. If a snapshot name is not specified, a name based on the current date and time is generated.

Options:

[-n | --name TEXT]

The user created snapshot name.

Example:

# iocage snapshot examplejail1 -n snapshottest1

start

Start a jail identified by UUID or NAME. Use [ALL] to start all installed jails instead.

Options:

[--rc]

Start all jails with boot=1 in a specific order. Jails with lower priority start first.

Example:

# iocage start examplejail1

stop

Stop a jail identified by UUID or NAME. Use [ALL] to stop all active jails instead.

Options:

[--rc]

Stop all jails with boot=1 in a specific order. Jails with higher priority values stop first.

Example:

# iocage stop 6ffe99a9

Stop the jail identified by the shortened UUID.

update

Runs freebsd-update to update the specified jail to the latest patch level.

Example:

# iocage update examplejail1

upgrade

Runs freebsd-update to upgrade a jail RELEASE to the specified RELEASE. A backup snapshot is automatically created to provide a rollback option.

Options:

[-r | --release RELEASE]

[Required] RELEASE the jail uses for upgrading.

Example:

# iocage upgrade examplejail2 -r 11.0-RELEASE

To upgrade, the release must be locally available.

PROPERTIES

assign_localhost=[1 | 0]

Boolean option to add interface lo0 and assign it the first available localhost address, starting with ‘127.0.0.2’. Only used when ‘vnet=0’. Jails using VNET configure a localhost as part of their virtualized network stack.

Default: ‘0’

Source: local

localhost_ip=“123.456.7.8”

Only applies when ‘vnet=0’ and ‘assign_localhost=1’. Assign the jail localhost IP address to a custom IP address instead of the first available “127.0.0.#” address. iocage checks for active jail IP addresses and warns when another jail is using the requested IP address.

Source: local

bpf=[1 | 0]

Toggle starting the jail with Berkely Packet Filter devices enabled.

Default: 0

Source: local

depends=“none | foo bar”

Require another jail to start before starting this jail. Space delimited. The option nests, resulting in dependent jails waiting in turn for their dependents, if specified, to start.

Default: “none”

Source: local

dhcp=[1 | 0]

This controls starting the jail with the Dynamic Host Configuration Protocol enabled. To enable dhcp, vnet and bpf must also be enabled.

Default: 0

Source: local

pkglist=[none | path-to-file]

A json file listing one package per entry. Packages are automatically installed when a jail is created. Works only in combination with the create subcommand.

Default: none

Source: local

vnet=[1 | 0]

Controls whether the jail is started with a VNET or a shared IP configuration. Set to on if a fully virtualized per-jail network stack is required.

Default: 0

Source: local

ip_hostname=[1 | 0]

A boolean option for using DNS records during jail IP configuration. jail(8) pulls the first IPv4 or IPv6 addresses from the resolver and applies them to the jail.

Default: 0

Source: jail(8)

ip4_addr="interface|ip-address/netmask"

The IPv4 address for VNET and shared IP jails.

Single interface format:

interface|ip-address/netmask

Multiple interface format:

interface|ip-address/netmask,interface|ip-address/netmask

On shared IP jails, an interface name given before the IP address adds an alias to that interface.

A netmask in either dotted-quad or CIDR form given after the IP address is used when adding the IP alias.

In VNET jails, the interface is configured with the IP addresses listed.

Example:

"vnet0|192.168.0.10/24,vnet1|10.1.1.10/24"
    

Interfaces vnet0 and vnet1 are configured in a VNET jail. In this case, no network configuration is necessary in the jail's rc.conf file.

Default: none

Source: jail(8)

ip4_saddrsel=[1 | 0]

Only applies when vnet=0. A boolean option to change the formerly mentioned behavior and disable IPv4 source address selection for the prison in favor of the primary IPv4 address of the jail. Source address selection is enabled by default for all jails and the ip4_nosaddrsel settting of a parent jail is not inherited for any child jails.

Default: 1

Source: jail(8)

ip4=[new | disable | inherit]

Only applies when vnet=0. Control the availability of IPv4 addresses. Possible values are "inherit" to allow unrestricted access to all system addresses, "new" to restrict addresses via ip4_addr above, and "disable" to stop the jail from using IPv4 entirely. Setting the ip4_addr parameter implies a value of "new".

Default: new

Source: jail(8)

defaultrouter=[none | ipaddress]

Setting this property to anything other than none configures a default route inside a VNET jail.

defaultrouter6=[none | ip6address]

Setting this property to anything other than none configures a default IPv6 route inside a VNET jail.

resolver=[none | nameserver IP;nameserver IP;search domain.local]

Set the jail's resolver (resolv.conf). Fields must be delimited with a semicolon. Semicolons are translated to newlines in resolv.conf.

If the resolver is set to none (default) the jail inherits the resolv.conf file from the host.

ip6_addr, ip6_saddrsel, ip6

A set of IPv6 options for the prison, the counterparts to ip4_addr, ip4_saddrsel and ip4 above.

interfaces=[vnet0:bridge0,vnet1:bridge1 | vnet0:bridge0]

By default, there are two interfaces specified with their bridge association. Up to four interfaces are supported. Interface configurations are separated by commas. The format is interface:bridge, where the left value is the virtual VNET interface name and the right value is the bridge name where the virtual interface should be attached.

Default: vnet0:bridge0,vnet1:bridge1

Source: local

host_domainname=

The NIS domain name of the jail.

Default: none

Source: jail(8)

host_hostname=UUID

The hostname of the jail.

Default: UUID

Source: jail(8)

host_time=[1 |0]

When active, copies the host /etc/localtime into the jail when the jail boots.

Default: 1

Source: local

exec_fib=[0 | 1 ..]

The FIB (routing table) to set when running commands inside the jail.

Default: 0

Source: jail(8)

devfs_ruleset=[4 | 0 ..]

The number of the devfs ruleset that is enforced for mounting devfs in this jail. A value of zero (default) means no ruleset is enforced. Descendent jails inherit the parent jail's devfs ruleset enforcement. Mounting devfs inside a jail is possible only if the allow_mount and allow_mount_devfs permissions are effective and enforce_statfs is set to a value lower than 2. Devfs rules and rulesets cannot be viewed or modified from inside a jail.

NOTE: It is important that only appropriate device nodes in devfs be exposed to a jail. Access to disk devices in the jail may permit processes in the jail to bypass the jail sandboxing by modifying files outside of the jail. See devfs(8) for information on how to use devfs rules to limit access to entries in the per-jail devfs. A simple devfs ruleset for jails is available as ruleset 4 in /etc/defaults/devfs.rules

Default: 4

Source: jail(8)

mount_devfs=[1 | 0]

Mount a devfs(5) filesystem on the chrooted /dev directory, and apply the ruleset in the devfs_ruleset parameter (or a default of ruleset 4: devfsrules_jail) to restrict the devices visible inside the jail.

Default: 1

Source: jail(8)

exec_created="/usr/bin/true"

Commands to run in the system environment after creating a jail but before commands or services run inside that jail.

Default: /usr/bin/true

Source: jail(8)

exec_start="/bin/sh /etc/rc"

Commands to run in the prison environment when a jail is created. A typical command to run is sh /etc/rc

Default: /bin/sh /etc/rc

Source: jail(8)

exec_stop="/bin/sh /etc/rc.shutdown"

Commands to run in the prison environment before a jail is removed and after any exec_prestop commands have completed. A typical command to run is sh /etc/rc.shutdown

Default: /bin/sh /etc/rc.shutdown

Source: jail(8)

exec_prestart="/usr/bin/true"

Commands to run in the system environment before a jail is started.

Default: /usr/bin/true

Source: jail(8)

exec_prestop="/usr/bin/true"

Commands to run in the system environment before a jail is stopped.

Default: /usr/bin/true

Source: jail(8)

exec_poststop="/usr/bin/true"

Commands to run in the system environment after a jail is stopped.

Default: /usr/bin/true

Source: jail(8)

exec_poststart="/usr/bin/true"

Commands to run in the system environment after a jail is started, and after any exec_start commands have completed.

Default: /usr/bin/true

Source: jail(8)

exec_clean=[1 | 0]

Run commands in a clean environment. The environment is discarded except for HOME, SHELL, TERM and USER. HOME and SHELL are set to the target login's default values. USER is set to the target login. TERM is imported from the current environment. The environment variables from the login class capability database for the target login are also set.

Default: 1

Source: jail(8)

exec_timeout=[60 | 30 ..]

The maximum amount of time to wait for a command to complete. If a command is still running after this many seconds have passed, the jail will be terminated.

Default: 60

Source: jail(8)

stop_timeout=[30 | 60 ..]

The maximum amount of time to wait for a jail's processes to exit after sending them a SIGTERM signal. This happens after the exec_stop commands have completed. After this many seconds have passed, the jail is removed, killing any remaining processes. If this is set to zero, no SIGTERM is sent and the prison is immediately removed.

Default: 30

Source: jail(8)

exec_jail_user=[root | username]

In the jail environment, commands are run as this user.

Default: root

Source: jail(8)

exec_system_jail_user=[1 | 0]

This boolean option looks for the exec_jail_user in the system passwd(5) file rather than the jail's file.

Default: 0

Source: jail(8)

exec_system_user=[root | username]

Run commands as this user in the system environment. The default is to run commands as the current user.

Default: root

Source: jail(8)

mount_fdescfs=[1 | 0]

Mount a fdescfs(5) filesystem in the jail's /dev/fd directory. Note: This is not supported on FreeBSD 9.3.

Default: 1

Source: jail(8)

mount_procfs=[1 | 0]

Mount a procfs(5) filesystem in the jail's /dev/proc directory.

Default: 0

Source: local

enforce_statfs=[2 | 1 | 0]

Determine which information processes in a jail are able to obtain about mount points. The behavior of these syscalls is affected: statfs(2), fstatfs(2), getfsstat(2), and fhstatfs(2) as well as similar compatibility syscalls. When set to 0, all mount points are available without any restrictions. When set to 1, only mount points below the jail's chroot directory are visible. Additionaly, the path to the jail's chroot directory is removed from the front of their pathnames. When set to 2 (default), the syscalls above can operate only on a mountpoint where the jail's chroot directory is located.

Default: 2

Source: jail(8)

children_max=[0 | ..]

The number of child jails allowed to be created by this jail (or by other jails under this jail). This limit is zero by default, indicating the jail is not allowed to create child jails. See the Hierarchical Jails section for more information in jail(8).

Default: 0

Source: jail(8)

login_flags="-f root"

These flags are passed to login(1) when logging in to jails with the console function.

Default: -f root

Source: login(1)

jail_zfs=[1 | 0]

Enable automatic ZFS jailing inside the jail. The assigned ZFS dataset is fully controlled by the jail.

NOTE: Setting this to 1 automatically sets ‘allow_mount=1’, ‘enforce_statfs=1’, and ‘allow_mount_zfs=1’! These are dependent options required for ZFS management inside a jail.

Default: 0

Source: local

jail_zfs_dataset=[iocage/jails/UUID/root/data | zfs_filesystem]

The dataset(s) to be jailed and fully handed over to a jail. Takes the ZFS filesystem name without the pool name. Multiple datasets may be specified, separated by whitespace.

NOTE: only valid when ‘jail_zfs=1.’ By default, the mountpoint is set to none. To mount this dataset, set its mountpoint inside the jail. For example,

zfs set mountpoint=/data full-dataset-name
mount -a
    

Default: iocage/jails/UUID/root/data

Source: local

securelevel=[3 | 2 | 1 | 0 | -1]

The value of the jail's kern.securelevel sysctl. A jail never has a lower securelevel than the default system, but by setting this parameter it is allowed to have a higher one. If the system securelevel is changed, any jail securelevels will be at least as secure.

Default: 2

Source: jail(8)

allow_set_hostname=[1 | 0]

Allow the jail's hostname to be changed with hostname(1) or sethostname(3).

Default: 1

Source: jail(8)

allow_sysvipc=[1 | 0]

Set whether a process in the jail has access to System V IPC primitives. Prior to FreeBSD 11.0, System V primitives share a single namespace across the host and jail environments, meaning that processes within a jail would be able to communicate with, and potentially interfere with, processes outside of the jail, or in other jails. In FreeBSD 11.0 and later, this setting is deprecated. Use sysvmsg, sysvsem, and sysvshm instead.

Default: 0

Source: jail(8)

sysvmsg=[disable | inherit | new]

Allow access to SYSV IPC message primitives. When set to inherit, all IPC objects on the system are visible to this jail, whether they were created by the jail itself, the base system, or other jails. When set to new, the jail has its own key namespace, and can only see the objects that it has created. The system or parent jail has access to the jail's objects, but not to its keys. When set to disable, the jail cannot perform any sysvmsg-related system calls. Ignored in FreeBSD 10.3 and earlier.

Default: new

Source: jail(8)

sysvsem=[disable | inherit | new]

Allow access to SYSV IPC semaphore primitives in the same manner as sysvmsg. Ignored in FreeBSD 10.3 and earlier.

Default: new

Source: jail(8)

sysvshm=[disable | inherit | new]

Allow access to SYSV IPC shared memory primitives in the same manner as sysvmsg. Ignored in FreeBSD 10.3 and earlier.

Default: new

Source: jail(8)

allow_raw_sockets=[1 | 0]

The prison root is allowed to create raw sockets. Setting this parameter allows utilities like ping(8) and traceroute(8) to operate inside the prison. If set, the source IP addresses are enforced to comply with the IP address bound to the jail, regardless of whether the IP_HDRINCL flag has been set on the socket. Since raw sockets can be used to configure and interact with various network subsystems, extra caution should be used where privileged access to jails is given out to untrusted parties.

Default: 0

Source: jail(8)

allow_chflags=[1 | 0]

Normally, privileged users inside a jail are treated as unprivileged by chflags(2). When this parameter is set, such users are treated as privileged, and can manipulate system file flags subject to the usual constraints on kern.securelevel.

Default: 0

Source: jail(8)

allow_mount=[1 | 0]

Allow privileged users inside the jail to mount and unmount filesystem types marked as jail-friendly. The lsvfs(1) command can be used to find filesystem types available for mount from within a jail. This permission is effective only if enforce_statfs is set to a value lower than 2.

Default: 0

Source: jail(8)

allow_mount_devfs=[1 | 0]

Allow privileged users inside the jail to mount and unmount the devfs file system. This permission is effective only together with allow.mount and if enforce_statfs is set to a value lower than 2. Please consider restricting the devfs ruleset with the devfs_ruleset option.

Default: 0

Source: jail(8)

allow_mount_fusefs=[1 | 0]

Allow privileged users inside the jail to mount and unmount fusefs file systems. This permission is effective only together with allow_mount and if enforce_statfs is set to a value lower than 2.

Note: This requires FreeBSD 12.0 or later.

Default: 0

Source: jail(8)

allow_mount_nullfs=[1 | 0]

Allow privileged users inside the jail to mount and unmount the nullfs file system. This permission is effective only together with allow_mount and if enforce_statfs is set to a value lower than 2.

Default: 0

Source: jail(8)

allow_mount_procfs=[1 | 0]

Allow privileged users inside the jail to mount and unmount the procfs file system. This permission is effective only together with allow.mount and if enforce_statfs is set to a value lower than 2.

Default: 0

Source: jail(8)

allow_mount_tmpfs=[1 | 0]

Allow privileged users inside the jail to mount and unmount the tmpfs file system. This permission is effective only together with allow.mount and if enforce_statfs is set to a value lower than 2.

Note: This is not supported on FreeBSD 9.3.

Default: 0

Source: jail(8)

allow_mount_zfs=[1 | 0]

Allow privileged users inside the jail to mount and unmount the ZFS filesystem. This permission is effective only together with allow.mount and if enforce_statfs is set to a value lower than 2. See zfs(8) for information on how to configure the ZFS filesystem to operate from within a jail.

Default: 0

Source: jail(8)

allow_quotas=[1 | 0]

The jail root can administer quotas on the jail's filesystems. This includes filesystems that the jail might share with other jails or with non-jailed parts of the system.

Default: 0

Source: jail(8)

allow_socket_af=[1 | 0]

Sockets within a jail are normally restricted to IPv4, IPv6, local (UNIX), and route. This setting allows access to other protocol stacks that have not had jail functionality added to them.

Default: 0

Source: jail(8)

allow_tun=[1 | 0]

Unhides tun devices for the jail with an individual devfsruleset. Allows the creation of tuns in the jail.

Default: 0

allow_mlock=[1 | 0]

Enables running services that require mlock in a jail.

Default: 0

Source: mlock(2)

allow_vmm=[1 | 0]

Allow access to vmm(4) inside the jail. The vmm(4) kernel module must be loaded for this to take effect.

Note: This requires FreeBSD 12.0 or later.

Default: 0

Source: jail(8)

host_hostuuid=UUID

Default: UUID

Source: jail(8)

name="any string"

Custom string for aliasing jails.

Default: UUID

Source: local

template=[1 | 0]

This property controls whether the jail is a template. Templates are not started by iocage. Set to 1 if this jail will be converted into a template. See the EXAMPLES section below.

Default: 0

Source: local

boot=[1 | 0]

If set to 1, the jail is auto-started at boot time with start --rc and stopped at shutdown time with stop --rc. Jails are started and stopped based on their priority value. If boot=1 is added to the create command, the jail is started after creation

Default: 0

Source: local

notes="any string"

Custom notes for miscellaneous tagging.

Default: none

Source: local

owner=root

The owner of the jail. Can be any string.

Default: root

Source: local

priority=[99 | 50 ..]

Start priority at boot time. Smaller values mean higher priority. For shutdown, the order is reversed.

Default: 99.

Source: local

last_started

Last successful start time. Automatically set every time the jail starts.

Default: timestamp

Source: local

type=[basejail | empty | normal]

Set the jail type to basejail, empty or normal.

Default: normal

Source: local

release=[11.0-RELEASE | 10.3-RELEASE]

The release used at creation time. Can be set to any string if needed.

Default: the host's release

Source: local

compression=[on | off [lzjb | gzip | gzip-N | zle | lz4]]

Controls the compression algorithm used for this dataset. The lzjb compression algorithm is optimized for performance while providing decent data compression. Setting compression to on uses the lzjb compression algorithm. The gzip algorithm uses the same compression as the gzip(1) command. The compression level can be specified by using the value gzip-N, where N is an integer from 1 (fastest) to 9 (best compression ratio). Currently, gzip is equivalent to gzip-6, which is also the default for gzip(1).

The zle algorithm compresses runs of zeros.

The lz4 algorithm is a high-performance replacement for the lzjb algorithm. It features significantly faster compression and decompression and a moderately higher compression ratio than lzjb, but can only be used on pools with the lz4_compress feature enabled. See zpool-features(7) for details on ZFS feature flags and the lz4_compress feature.

This property can also be referred to by its shortened column name of "compress".

Changing this property affects only newly-written data.

Default: lz4

Source: zfs(8)

origin

This is only set for clones and is read-only. For cloned file systems or volumes, the snapshot from which the clone was created. See the clones property.

Default: -

Source: zfs(8)

quota=[15G | 50G | ..]

Quota for the jail. Limit the amount of space a dataset and its descendants can consume. This property enforces a hard limit on the amount of space used. This includes all space consumed by descendants, including file systems and snapshots. Setting a quota on a descendent of a dataset that already has a quota does not override the ancestor's quota, but rather imposes an additional limit.

Default: none

Source: zfs(8)

mountpoint

Path for the jail's root filesystem. Do not tweak this or the jail will not start!

Default: set to jail's root

Source: zfs(8)

compressratio

Compression ratio. Read-only. For non-snapshots, the compression ratio achieved for the used space of this dataset, expressed as a multiplier. The used property includes descendant datasets, and, for clones, does not include the space shared with the origin snapshot.

Source: zfs(8)

available

Available space in the jail's dataset. The amount of space available to the dataset and all its children, assuming that there is no other activity in the pool. Because space is shared within a pool, availability can be limited by any number of factors, including physical pool size, quotas, reservations, or other datasets within the pool.

Source: zfs(8)

used

Space used by jail. Read-only.

Source: zfs(8)

dedup=[on | off [verify | sha256[,verify]]]

Deduplication for jail.

Default: off

Source: zfs(8)

reservation=[size | none]

Reserved space for jail.

Default: none

Source: zfs(8)

sync_target

This is for future use, currently not supported.

sync_tgt_zpool

For future use, currently not supported.

cpuset=[1 | 1,2,3,4 | 1-2 | off]

Control the jail's CPU affinity.

Default: off

Source: cpuset(1)

vnet_interfaces

A space delimited list of network interfaces to give to a VNET-enabled jail after it is created. Interfaces are automatically released when the jail is removed.

Default: none

Source: jail(8)

vnet_default_interface=[none | INTERFACE]

Default network interface used for the VNET bridge interface in the jail. Only takes effect when VNET is set.

Default: none

hostid_strict_check [1 | 0]

Check the hostid property of the jail. If not the same as the host, do not start the jail.

Default: 0

EXAMPLES

iocage fetch

Create first jail:

iocage create -r 11.0-RELEASE -n myjail

List jails:

iocage list

Start jail:

iocage start UUID

Convert jail into template:

iocage set template=yes UUID

List templates:

iocage list -t

Import package on another host:

iocage import UUID

HINTS

When using VNET and an outside connection is needed, add the node's physical NIC into one of the bridges. Also see bridge(4) for how traffic is handled. Basically, bridges behave like a network switch.

IPFW and PF are fully supported inside a VNET jail.

The actual jail name in the jls(8) output is set to ioc-UUID. This is a required workaround as jails refuse to start with jail(8) when the jail name starts with a "0".

dmesg(8) information leakage inside jails can be prevented with this sysctl:

security.bsd.unprivileged_read_msgbuf=0

When using VNET, consider applying these sysctls as well:

net.inet.ip.forwarding=1
net.link.bridge.pfil_onlyip=0
net.link.bridge.pfil_bridge=0
net.link.bridge.pfil_member=0

See https://github.com/iocage/iocage for more information.

SEE ALSO

BUGS

AUTHORS

This manual page was written by Warren Block, Tim Moore, Peter Toth, and Brandon Schneider.

SPECIAL THANKS