FreeBSD Manual Pages
IOCAGE(8) 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 management 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 po- tential 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 sub- command 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 config- uring 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 RE- LEASE 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 tem- plate. [-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 directo- ries. [-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 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 separa- tors. [-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 spec- ified 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 com- mand. [-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 system. The host node's RELEASE is downloaded for deployment. If other releases are required, this can be changed by supplying the re- quired release property or selecting the appropriate RELEASE from the menu list. Options: [--accept] Accept the plugin's LICENSE agree- ment. [--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 num- ber of plugin type jails. [-d | --root-dir TEXT] Specify the root directory contain- ing 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 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 op- tions, 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 ed- itor. [-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 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 down- load. [-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, RE- LEASE, 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 cur- rent jail format. Options: [-d | --delete] Destroy the old dataset after migration. [-f | --force] Bypass any further warning or required user in- teraction. 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 snap- shots 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 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 ac- cessing 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 dis- played: NAME snapshot name CREATED creation time RSIZE referenced size USED used space Options: [-H | -h | --header] Used for scripting. Tabs are used as sepa- rators. [-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 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 Config- uration 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 au- tomatically 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 config- uration. 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 ad- dress 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 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 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 parameter im- plies 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 delim- ited 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 rule- set 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 per- missions 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 de- vfs(8) for information on how to use devfs rules to limit ac- cess to entries in the per-jail devfs. A simple devfs rule- set 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 cre- ated. 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 dis- carded 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 environ- ment. The environment variables from the login class capa- bility 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 sec- onds 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 sys- tem 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 de- fault 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 fh- statfs(2) as well as similar compatibility syscalls. When set to 0, all mount points are available without any restric- tions. When set to 1, only mount points below the jail's ch- root 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 direc- tory 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 informa- tion 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(s) to be jailed and fully handed over to a jail. Takes the ZFS filesystem name without the pool name. Multi- ple datasets may be specified, separated by whitespace. NOTE: only valid when `jail_zfs=1.' By default, the mount- point is set to none. To mount this dataset, set its mount- point 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 commu- nicate with, and potentially interfere with, processes out- side 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 in- herit, 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 tracer- oute(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 config- ure and interact with various network subsystems, extra cau- tion 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 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) com- mand can be used to find filesystem types available for mount from within a jail. This permission is effective only if en- force_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 to- gether 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 to- gether 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 functionality 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. Tem- plates are not started by iocage. Set to 1 if this jail will be converted into a template. See the EXAMPLES section be- low. 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 pri- ority. 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 algo- rithm 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_com- press 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 snap- shots. Setting a quota on a descendent of a dataset that al- ready 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 num- ber of factors, including physical pool size, quotas, reser- vations, 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 auto- matically 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 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 vari- able IOCAGE_COLOR=TRUE to enable this experimental feature. When using VNET and an outside connection is needed, add the node's physi- cal 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 ports 15.quarterly September 12, 2020 IOCAGE(8)
NAME | SYNOPSIS | DESCRIPTION | SUBCOMMANDS | PROPERTIES | EXAMPLES | HINTS | SEE ALSO | BUGS | AUTHORS | SPECIAL THANKS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=iocage&sektion=8&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>