Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IOCAGE(8)		FreeBSD	System Manager's Manual		     IOCAGE(8)

NAME
     iocage -- jail manager using ZFS and VNET

SYNOPSIS
     iocage [-D	| --debug]
     iocage [--help | SUBCOMMAND --help]
     iocage [-v	| --version]

     iocage activate ZPOOL
     iocage chroot UUID	| NAME [COMMAND]
     iocage clean [-a |	--all |	dataset_type]
	    [-b	| -r | --base |	dataset_type] [-f | --force]
	    [-j	| --jails | dataset_type] [-t |	--template | dataset_type]
     iocage clone UUID | NAME [PROPERTIES] [-c | --count TEXT]
     iocage console [-f	| --force] UUID	| NAME
     iocage create [-b | --basejail] [-c | --count TEXT] [-e | --empty]
	    [-f	| --force] [-n | --name	TEXT] [-p | --pkglist TEXT]
	    [-r	| --release TEXT] [-r |	--release latest | LATEST]
	    [-s	| --short] [-t | --template TEXT] [-B |	--clone_basejail]
	    [-T	| --thickjail] [-u | --uuid | TEXT] [PROPERTIES]
     iocage destroy [-R	| --recursive] [-d | --download] [-f | --force]
	    [-r	| --release] UUID | NAME
     iocage df [-H | -h	| --header] [-l	| --long] [-s |	--sort TEXT]
     iocage exec [-f | --force]	[-U | --jail_user NAME]
	    [-u	| --host_user NAME] UUID | NAME	-- COMMAND [ARGS]
     iocage export UUID	| NAME
     iocage fetch [--accept] [--noaccept] [--plugins OPTIONS]
	    [--plugins --official OPTIONS] [-E | --eol]	[-F | --files]
	    [-NE | --noeol] [-NU | --noupdate] [-NV | --noverify]
	    [-P	| --plugin-file] [-U | --update] [-V | --verify] [-a | --auth]
	    [-c	| --count] [-d | --root-dir] [-f | --file] [-h | --http]
	    [-n	| --name -TEXT]	[-p | --password]
	    [-r	| --release | latest | LATEST] [-s | --server] [-u | --user]
     iocage fstab JAIL FSTAB_STRING [-H	| -h | --header] [-R | --replace]
	    [-a	| --add	| action] [-e |	--edit | action] [-l | --list]
	    [-r	| --remove | action]
     iocage get	PROPERTY UUID |	NAME [-H | -h |	--header]
	    [-P	| --plugin [-f | --force]] [-a | --all]	[-p | --pool]
	    [-r	| --recursive] [-s | state] [-j	| JID]
     iocage import UUID	| NAME
     iocage list [--http] [-H |	-h | --header] [-P | --plugins]
	    [-R	| --remote] [-b	| -r | --base |	--release | dataset_type]
	    [-l	| --long] [-q |	--quick] [-s | --sort]
	    [-t	| --template | dataset_type] [-PRO]
     iocage migrate [-d	| --delete] [-f	| --force]
     iocage pkg	UUID | NAME COMMAND
     iocage rename UUID	| NAME NEW_NAME
     iocage restart [-s	| --soft] UUID | NAME
     iocage rollback [-f | --force] -n | --name	TEXT UUID | NAME
     iocage set	PROPERTY [...] UUID | NAME [-P | --plugin KEY]
     iocage snaplist UUID | NAME [-H | -h | --header] [-l | --long]
	    [-s	| --sort TYPE]
     iocage snapremove [-n | --name TEXT] UUID | NAME |	ALL
     iocage snapshot [-n | --name TEXT]	UUID | NAME
     iocage start [--rc] [UUID | NAME |	ALL]
     iocage stop [--rc]	[UUID |	NAME | ALL]
     iocage update UUID	| NAME
     iocage upgrade UUID | NAME	-r | --release RELEASE

DESCRIPTION
     iocage is a system	administration tool designed to	simplify jail manage-
     ment tasks.  It abstracts out the management of ZFS-backed	jails running
     VNET or shared IP networking.

     Both shared IP jails and VNET jails are supported.

     Each jail has a unique ID (UUID) which is automatically generated at cre-
     ation 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 op-
     erator 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 acti-
	       vated for iocage	jails without requiring	user input.  By	de-
	       fault, 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	con-
	       figuring	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	en-
	       sures 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 desig-
					nated RELEASE directories as nullfs
					mounts over the	jail directories.

	       [-c | --count TEXT]	Designate the number of	jails to cre-
					ate, 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 re-
					lease available.

	       [-s | --short]		Use a short UUID of 8 characters in-
					stead of the default 36.

	       [-t | --template	TEXT]	Create a jail from the specified tem-
					plate.

	       [-B | --clone_basejail]	Create a new "clone basejail".	Clone
					basejails clone	the RELEASE with ZFS
					and mount the designated RELEASE di-
					rectories 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	Free-
	       BSD 11.0	RELEASE.  These	jails are sequentially numbered	 based
	       on the custom NAME.

     destroy   Destroy the specified jail.  Caution, this subcommand is	irre-
	       versible.  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	sepa-
				     rators.

	       [-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 argu-
	       ments 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 com-
					mand.

	       Examples:

		     # iocage exec -f examplejail_1 ls /tmp

	       Starts examplejail_1 and	lists the contents of the /tmp direc-
	       tory.

		     # 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 sys-
	       tem.  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 RE-
	       LEASE from the menu list.

	       Options:

	       [--accept]		     Accept the	plugin's LICENSE
					     agreement.

	       [--noaccept]		     Do	not accept the plugin's	LI-
					     CENSE 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.	Cur-
					     rent values are basic and digest.

	       [-c | --count TEXT]	     Used when fetching	a plugin.
					     This option creates the desig-
					     nated number of plugin type
					     jails.

	       [-d | --root-dir	TEXT]	     Specify the root directory	con-
					     taining all RELEASE files.

	       [-f | --file]		     Use a local file directory	for
					     the root directory	instead	of
					     HTTP.

	       [-h | --http]		     No-op flag	for backwords compati-
					     bility.  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 down-
	       load.  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 lat-
	       est 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 separa-
					 tors.

	       [-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 -e examplejail_1

     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 separa-
				     tors.

	       [-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 separa-
				     tors.

	       [-P | --plugins]	     Shows plugins installed on	the system.

	       [-PRO]		     Lists official plugins available for
				     download.

	       [-R | --remote]	     Shows available RELEASE options for re-
				     mote.

	       [-b | -r	| --base | --release | dataset_type]
				     List all bases.

	       [-l | --long]	     Shows JID,	NAME, BOOT, STATE, TYPE, RE-
				     LEASE, IP4, IP6, and TEMPLATE informa-
				     tion.

	       [-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 net-
			      work 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 fur-
			       ther 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 de-
	       sired 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 separa-
				tor.

	       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	snap-
				     shot.

	       [-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
     The Source	listed with each property shows	whether	it is a	local iocage
     property or where more information	can be located.	 Boolean properties
     are listed	with [1	| 0] as	the options, but iocage	also accepts [yes |
     no], [true	| false], or [on | off].

     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 lo-
		   calhost 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'.	 As-
		   sign	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 Con-
		   figuration 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 con-
		   figuration.	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 ad-
		   dresses 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 ad-
		   dress 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 unre-
		   stricted 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	param-
		   eter	implies	a value	of "new".

		   Default: new

		   Source: jail(8)

     defaultrouter=[none | ipaddress]
		   Setting this	property to anything other than	none config-
		   ures	a default route	inside a VNET jail.

     defaultrouter6=[none | ip6address]
		   Setting this	property to anything other than	none config-
		   ures	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 de-
		   limited 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 for-
		   mat is interface:bridge, where the left value is the	vir-
		   tual	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	mount-
		   ing 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	al-
		   low_mount_devfs permissions are effective and en-
		   force_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 de-
		   vices 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 cur-
		   rent	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 com-
		   plete.  If a	command	is still running after this many sec-
		   onds	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 direc-
		   tory.  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	direc-
		   tory.

		   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 ch-
		   root	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 cre-
		   ate 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 de-
		   pendent options required for	ZFS management inside a	jail.

		   Default: 0

		   Source: local

     jail_zfs_dataset=[iocage/jails/UUID/root/data | zfs_filesystem]
		   The dataset to be jailed and	fully handed over to a jail.
		   Takes the ZFS filesystem name without pool name.

		   NOTE: only valid when `jail_zfs=1.' By default, the mount-
		   point 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	se-
		   curelevels 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 environ-
		   ments, meaning that processes within	a jail would be	able
		   to communicate with,	and potentially	interfere with,	pro-
		   cesses 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: disable

		   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: disable

		   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	ear-
		   lier.

		   Default: disable

		   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 ad-
		   dress 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	par-
		   ties.

		   Default: 0

		   Source: jail(8)

     allow_chflags=[1 |	0]
		   Normally, privileged	users inside a jail are	treated	as un-
		   privileged 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.se-
		   curelevel.

		   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 to-
		   gether 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 to-
		   gether 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 filesys-
		   tems.  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 functional-
		   ity added to	them.

		   Default: 0

		   Source: jail(8)

     allow_tun=[1 | 0]
		   Unhides tun devices for the jail with an individual devfs-
		   ruleset.  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	sec-
		   tion	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.

		   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 compres-
		   sion	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 compres-
		   sion	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 col-
		   umn 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 com-
		   pression ratio achieved for the used	space of this dataset,
		   expressed as	a multiplier.  The used	property includes de-
		   scendant 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 au-
		   tomatically released	when the jail is removed.

		   Default: none

		   Source: jail(8)

     vnet_default_interface=[none | INTERFACE]
		   Default network interface used for the VNET bridge inter-
		   face	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
     Set up iocage from	scratch:

	   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
     By	default, iocage	doesn't	have colors enabled.  Set the environment
     variable IOCAGE_COLOR=TRUE	to enable this experimental feature.

     When using	VNET and an outside connection is needed, add the node's phys-
     ical 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
     cpuset(1),	bridge(4), epair(4), freebsd-update(8),	ifconfig(8), jail(8),
     jexec(8), rctl(8),	sysctl(8), zfs(8), zpool(8), VNET(9)

BUGS
     Please report bugs, issues, and feature requests to
     https://github.com/iocage/iocage/issues

AUTHORS
     iocage was	developed by Peter Toth, Brandon Schneider, and	Stefan Gronke.

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

SPECIAL	THANKS
     Sichendra Bista - for his ever willing attitude and ideas.

FreeBSD	13.0			March 14, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | SUBCOMMANDS | PROPERTIES | EXAMPLES | HINTS | SEE ALSO | BUGS | AUTHORS | SPECIAL THANKS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=iocage&sektion=8&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help