(408) 943-4100               V   Commercial Support Toggle between Light and Dark mode
TrueNAS.com Software Systems Company Community Security iX Portal Download
  1. Documentation Hub
  2. /
  3. TrueNAS CORE and Enterprise
  4. /
  5. Applications
  6. /
  7. Jails
  8. /
  9. Create
Edit this page

Create

  14 minute read.

Last Modified 2021-07-30 09:08 EDT
This feature is only supported by the TrueNAS CORE community.

Jails are a lightweight, operating-system-level virtualization. One or multiple services can run in a jail, isolating those services from the host TrueNAS system. TrueNAS uses iocage for jail and plugin management. The main differences between a user-created jail and a plugin are that plugins are preconfigured and usually provide only a single service.

By default, jails run the FreeBSD operating system. These jails are independent instances of FreeBSD. The jail uses the host hardware and runs on the host kernel, avoiding most of the overhead usually associated with virtualization. The jail installs FreeBSD software management utilities so FreeBSD packages or ports can be installed from the jail command line. This allows for FreeBSD ports to be compiled and FreeBSD packages to be installed from the command line of the jail.

It is important to understand that users, groups, installed software, and configurations within a jail are isolated from both the TrueNAS host operating system and any other jails running on that system.

The ability to create multiple jails offers flexibility regarding software management. For example, an administrator can choose to provide application separation by installing different applications in each jail, to create one jail for all installed applications, or to mix and match how software is installed into each jail.

Jail Storage

A data storage pool must be created before using jails. Make sure the pool has enough storage for all the intended jails. The Jails screen displays a message and button to CREATE POOL if no pools exist on the TrueNAS system.

If pools exist, but none have been chosen for use with jails or plugins, a dialog appears to choose a pool. Select a pool and click CHOOSE.

To select a different pool for jail and plugin storage, click . A dialog shows the active pool. A different pool can be selected from the drop-down.

Jails and downloaded FreeBSD release files are stored in a dataset named iocage/.

  • At least 10 GiB of free space is recommended.
  • Cannot be located on a Share.
  • iocage automatically uses the first pool that is not a root pool for the TrueNAS system.
  • A defaults.json file contains default settings used when a new jail is created. The file is created automatically when not already present. When the file is present but corrupted, iocage shows a warning and uses default settings from memory.
  • Each new jail installs into a new child dataset of iocage/. For example, with the iocage/jails dataset in pool1, a new jail called jail1 installs into a new dataset named pool1/iocage/jails/jail1.
  • FreeBSD releases are fetched as a child dataset into the /iocage/download dataset. This datset is then extracted into the /iocage/releases dataset to be used in jail creation. The dataset in /iocage/download can then be removed without affecting the availability of fetched releases or an existing jail.
  • iocage/ datasets on activated pools are independent of each other and do not share any data.

iocage jail configs are stored in /mnt/poolname/iocage/jails/jailname. When iocage is updated, the config.json configuration file is backed up as /mnt/poolname/iocage/jails/jailname/config_backup.json. The backup file can be renamed to config.json to restore previous jail settings.

Creating Jails

TrueNAS has two options to create a jail. The Jail Wizard makes it easy to quickly create a jail. ADVANCED JAIL CREATION is an alternate method, where every possible jail option is configurable. There are numerous options spread across four different primary sections. This form is recommended for advanced users with very specific requirements for a jail.

Jail Networking

If you have installed TrueNAS in VMware, you will need functional networking to create a jail.

For the jail to have functional networking, you have to change the VMware settings to allow Promiscuous, MAC address changes, and Forged Transmits.

SettingDescription
Promiscuous ModeWhen enabled at the virtual switch level, objects defined within all portgroups can receive all incoming traffic on the vSwitch.
MAC Address ChangesWhen set to Accept, ESXi accepts requests to change the effective MAC address to a different address than the initial MAC address.
Forged TransmitsWhen set to Accept, ESXi does not compare source and effective MAC addresses.

New jails can be created quickly by going to Jails > ADD.

JailsAddName

The wizard provides the simplest process to create and configure a new jail.

Enter a Jail Name. Names can contain letters, numbers, periods (.), dashes (-), and underscores (_).

Choose a Jail Type: Default (Clone Jail) or Basejail. Clone jails are clones of the specified FreeBSD RELEASE. They are linked to that RELEASE, even if they are upgraded. Basejails mount the specified RELEASE directories as nullfs mounts over the jail directories. Basejails are not linked to the original RELEASE when upgraded.

Jails can run FreeBSD versions up to the same version as the host TrueNAS system. Newer releases are not shown.

Versions of FreeBSD are downloaded the first time they are used in a jail. Additional jails created with the same version of FreeBSD are created faster because the download has already been completed.

Click NEXT to see a simplified list of networking options.

Jails support several different networking solutions:

  • VNET adds a virtual network interface to the jail. This interface can set NAT, DHCP, or static jail network configurations. Since VNET provides the jail with an independent networking stack, it can broadcast an IP address, which is required by some applications.

  • Network Address Translation (NAT), which uses the TrueNAS IP address and sets a unique port for the jail to use. VNET is required when NAT is selected.

  • Set DHCP Autoconfigure IPv4 for the jail to receive its IP address from a DHCP server.

  • Manually configure networking by entering values for the IPv4 Address or IPv6 Address fields. Any combination of these fields can be configured. Multiple interfaces are supported for IPv4 and IPv6 addresses. To add more interfaces and addresses, click ADD.

    Setting the IPv4 Default Router and IPv6 Default Router fields to auto automatically configures these values. VNET must be set to enable the IPv4 Default Router field. When no interface is selected when manually configuring IP addresses, TrueNAS automatically assigns the given jail IP address to the current active interface of the host system.

  • Leaving all checkboxes unset and fields empty initializes the jail without any networking abilities. Networking is added to the jail after creation by going to Jails, clicking for a jail, then > Basic Properties.

Setting a proxy in the TrueNAS network settings also configures new jails to use the proxy settings, except when performing DNS lookups. Make sure a firewall is properly configured to maximize system security.

When pairing the jail with a physical interface, edit the network interface and set Disable Hardware Offloading. This prevents a network interface reset when the jail starts.

JailsAddNetworking

Click NEXT to view a summary screen of the chosen jail options. Click SUBMIT to create the new jail. After a few moments, the new jail is added to the primary jails list.

The advanced jail creation form is opened by clicking Jails > ADD, then ADVANCED JAIL CREATION.

JailsAddAdvanced

Options

A usable jail without any networking can be quickly created by setting only the required Jail Name and Release. Configure the remaining Basic Properties when the jail needs to communicate over the local network or out to the internet.

Basic Properties

NameDescription
NameRequired. Can contain letters, numbers, periods (.), dashes (-), and underscores (_).
Jail TypeDefault (Clone Jail) or Basejail. Clone jails are clones of the specified RELEASE. They are linked to that RELEASE, even if they are upgraded. Basejails mount the specified RELEASE directories as nullfs mounts over the jail directories. Basejails are not linked to the original RELEASE when upgraded.
ReleaseFreeBSD release to use as the jail operating system. Jails can run FreeBSD versions up to the same version as the host system. Newer releases are not shown.
DHCP Autoconfigure IPv4Set to autoconfigure jail networking with the Dynamic Host Configuration Protocol. VNET and Berkeley Packet Filter must also be enabled.
NATNetwork Address Translation (NAT). Transforms local network IP addresses into a single IP address. Set when the jail will share a single connection to the Internet with other systems on the network.
VNETSet to use VNET(9) to emulate network devices for the jail. A fully virtualized per-jail network stack will be installed.
Berkeley Packet FilterSet to use the Berkeley Packet Filter (BPF(4)) to data link layers in a protocol independent fashion.
vnet_default_interfaceSet the default VNET interface. Only takes effect when VNET is set. Choose a specific interface or set to auto to use the interface that has the default route. Choose none to not set a default VNET interface.
IPv4 InterfaceIPv4 interface for the jail.
IPv4 AddressEnter the IPv4 address for VNET(9) and shared IP jails.
IPv4 NetmaskIPv4 netmask for the jail.
IPv4 Default RouterA valid IPv4 address to use as the default route. Enter none to configure the jail with no IPv4 default route. A jail without a default route will not be able to access any networks.
AutoConfigure IPv6Set to use SLAAC (Stateless Address Auto Configuration) to autoconfigure IPv6 in the jail.
IPv6 InterfaceIPv6 interface for the jail.
IPv6 AddressEnter the IPv6 address for VNET(9) and shared IP jails.
IPv6 NetmaskIPv6 prefix for the jail.
IPv6 Default RouterA valid IPv6 address to use as the default route. Enter none to configure the jail without an IPv6 default route. A jail without a default route will not be able to access any networks.
Auto StartSet to auto-start the jail at system boot time. Jails are started and stopped based on iocage priority. Set in the priority field under Custom Properties.

Additional settings are in the Jail Properties, Network Properties, and Custom Properties sections.

Jail Properties

NameDescription
devfs_rulesetThe devfs(8) ruleset number to enforce when mounting devfs in the jail. The default 0 means no ruleset is enforced. Mounting devfs inside a jail is only possible when the allow_mount and allow_mount_devfs permissions are enabled and enforce_statfs is set to a value lower than 2.
exec_startCommands to run in the jail environment when the jail is created. Example: sh /etc/rc. The pseudo-parameters section of JAIL(8) describes exec.start usage.
exec_stopCommands to run in the jail environment before the jail is removed and after exec.prestop commands are complete. Example: sh /etc/rc.shutdown.
exec_prestartCommands to run in the system environment before a jail is started.
exec_poststartCommands to run in the system environment after a jail is started and after any exec_start commands are finished.
exec_prestopCommands to run in the system environment before a jail is stopped.
exec_poststopCommands to run in the system environment after a jail is stopped.
exec_jail_userEnter either root or another valid username. Inside the jail, commands run as this user.
exec_system_userRun commands in the jail as this user. By default, commands are run as the current user.
securelevelThe value of the jail securelevel sysctl. A jail never has a lower securelevel than the host system. Setting this parameter allows a higher securelevel. If the host system securelevel is changed, the jail securelevel will be at least as secure.
sysvmsgAllow or deny access to SYSV IPC message primitives. Inherit: All IPC objects on the system are visible to the jail. New: Only objects the jail creates using the private key namespace are visible. The system and parent jails have access to the jail objects but not private keys. Disable: The jail cannot perform any sysvmsg related system calls.
sysvsemAllow or deny access to SYSV IPC semaphore primitives. Inherit: All IPC objects on the system are visible to the jail. New: Only objects the jail creates using the private key namespace are visible. The system and parent jails have access to the jail objects but not private keys. Disable: The jail cannot perform any sysvmem related system calls.
sysvshmAllow or deny access to SYSV IPC shared memory primitives. Inherit: All IPC objects on the system are visible to the jail. New: Only objects the jail creates using the private key namespace are visible. The system and parent jails have access to the jail objects but not private keys.
vnet_interfacesA space-delimited list of network interfaces attached to a VNET enabled jail after it is created. Interfaces are automatically released when the jail is removed.
allow_set_hostnameAllow the jail hostname to be changed with hostname(1) or sethostname(3).
allow_sysvipcChoose whether a process in the jail has access to System V IPC primitives. Equivalent to setting sysvmsg, sysvsem, and sysvshm to Inherit. Deprecated in FreeBSD 11.0 and newer! Use sysvmsg, sysvsem, and sysvshm instead.
allow_raw_socketsSet to allow raw sockets. Utilities like ping(8) and traceroute(8) require raw sockets. When set, source IP addresses are enforced to comply with the IP addresses bound to the jail, ignoring the IP_HDRINCL flag on the socket.
allow_chflagsSet to treat jail users as privileged and allow the manipulation of system file flags. securelevel constraints are still enforced.
allow_mlockEnable running services that require mlock(2) in a jail.
allow_vmmAllow the jail to access the bhyve virtual machine monitor (VMM). The jail must have FreeBSD 12.0 or newer installed with the vmm(4) kernel module loaded.
allow_quotasSet to allow the jail root to administer quotas on jail filesystems. This includes filesystems the jail shares with other jails or with non-jailed parts of the system.
allow_socket_afSet to allow access to other protocol stacks beyond IPv4, IPv6, local (UNIX), and route. Warning: jail functionality does not exist for all protocol stacks.
allow_mountSet to allow privileged users inside the jail to mount and unmount filesystem types marked as jail-friendly.

Network Properties

NameDescription
InterfacesEnter up to four interface configurations in the format interface:bridge, separated by a comma (,). The left value is the virtual VNET interface name and the right value is the bridge name where the virtual interface should be attached.
host_domainnameEnter a NIS Domain name for the jail.
host_hostnameSet the jail hostname. Defaults to the jail UUID.
resolverAdd lines to the jail resolv.conf. Example: nameserver IP;search domain.local. Fields must be delimited with a semicolon (;), This is translated as new lines in resolv.conf. Enter none to inherit resolv.conf from the host.
ip4.saddrselDisable IPv4 source address selection for the jail in favor of the primary IPv4 address of the jail. Only available when the jail is not configured to use VNET.
ip6.saddrselDisable IPv6 source address selection for the jail in favor of the primary IPv6 address of the jail. Only available when the jail is not configured to use VNET.
ip4Control the availability of IPv4 addresses. Inherit: Allow unrestricted access to all system addresses. New: Restrict addresses with ip4_addr. Disable: Stop the jail from using IPv4 entirely.
ip6Control the availability of IPv6 addresses. Inherit: Allow unrestricted access to all system addresses. New: Restrict addresses with ip6_addr. Disable: Stop the jail from using IPv6 entirely.
mac_prefixEnter a valid MAC address vendor prefix. Example: E4F4C6
vnet0_macLeave this field empty to generate random MAC addresses for the host and jail. To assign fixed MAC addresses, enter the MAC address to be assigned to the host, a space, then the MAC address to be assigned to the jail.

Custom Properties

NameDescription
priorityNumeric start priority for the jail at boot time. Valid priorities are between 1 and 99. Smaller values are higher priority. At system shutdown the priority is reversed. Example: 99
hostidA new jail hostid, if desired. Example hostid: 1a2bc345-678d-90e1-23fa-4b56c78901de.
commentEnter comments about the jail.
templateSet to set this jail as a template.
host_timeSystem host time to synchronize the time between jail and host.
jail_zfsSet to enable automatic ZFS jailing inside the jail. The assigned ZFS dataset is fully controlled by the jail.
jail_zfs_datasetDefine the dataset to be jailed and fully handed over to a jail. Enter a ZFS filesystem name without a pool name. jail_zfs must be set for this option to work.
jail_zfs_mountpointEnter the mountpoint for the jail_zfs_dataset. Example: /data example-dataset-name
allow_tunReveal tun devices for the jail with an individual devfs ruleset. Allow the creation of tun devices in the jail
Autoconfigure IPv6 with rtsoldUse rtsold(8) as part of IPv6 autoconfiguration. Send ICMPv6 Router Solicitation messages to interfaces to discover new routers.
ip_hostnameSet to use DNS records during jail IP configuration to search the resolver and apply the first open IPv4 and IPv6 addresses. See jail(8).
assign_localhostSet to add network interface lo0 to the jail and assign it the first available localhost address, starting with 127.0.0.2. VNET must be unset. Jails using VNET configure a localhost as part of their virtualized network stack.

Creating Template Jails

Template jails are basejails that can efficiently create jails with the same configuration. These steps create a template jail:

  • Go to Jails > ADD > ADVANCED JAIL CREATION.
  • Select Basejail as the Jail Type. Configure the jail with desired options.
  • Set template in the Custom Properties section.
  • Click SAVE.
  • Click ADD.
  • Enter a name for the template jail. Leave Jail Type as Default (Clone Jail). Set Release to basejailname(template), where basejailname is the name of the base jail created earlier.
  • Complete the jail creation wizard.