TrueNAS Jail Options Reference

Descriptions and example usage for each web interface field related to Jails.

  13 minute read

Jail Creation Wizard

SettingValueDescription
NamestringRequired. Can contain letters, numbers, periods (.), dashes (-), and underscores (_).
Jail Typedrop-downDefault (Clone Jail) are clones of the specified RELEASE. They are linked to that RELEASE, even if they are upgraded. Basejail mount the specified RELEASE directories as nullfs mounts over the jail directories. Basejails are not linked to the original RELEASE when upgraded.
Releasedrop-down menuRequired. Jails can run FreeBSD versions up to the same version as the host TrueNAS system. Newer releases are not shown.
DHCP Autoconfigure IPv4checkboxAutomatically configure IPv4 networking with an independent VNET stack. VNET and Berkeley Packet Filter must also be checked. If not set, ensure the defined address in IPv4 Address does not conflict with an existing address.
NATcheckboxNetwork Address Translation (NAT). When set, the jail is given an internal IP address and connections are forwarded from the host to the jail. When NAT is set, Berkeley Packet Filter cannot be set. Adds the NAT Port Forwarding options to the jail Network Properties.
VNETcheckboxUse VNET to emulate network devices for this jail and a create a fully virtualized per-jail network stack. See VNET(9) for more details.
Berkeley Packet FiltercheckboxUse the Berkeley Packet Filter to data link layers in a protocol independent fashion. Unset by default to avoid security vulnerabilities. See BPF(4) for more details. Cannot be set when NAT is set.
vnet_default_interfacedrop-downSet 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 Interfacedrop-down menuChoose a network interface to use for this IPv4 connection. See the note below this table about adding interfaces.
IPv4 AddressstringThis and the other IPv4 settings are grayed out when DHCP autoconfigure IPv4 is set. Configures the interface to use for network or internet access for the jail. Enter an IPv4 address for this IP jail. Example: 192.168.0.10.
IPv4 Netmaskdrop-down menuChoose a subnet mask for this IPv4 Address.
IPv4 Default RouterstringEnter none or a valid IP address. Setting this property to anything other than none configures a default route inside a VNET jail.
Auto Configure IPv6checkboxSet to use SLAAC (Stateless Address Auto Configuration) to auto-configure IPv6 in the jail.
IPv6 Interfacedrop-down menuChoose a network interface to use for this IPv6 connection. See the note below this table about adding interfaces.
IPv6 AddressstringConfigures network or internet access for the jail. Type the IPv6 address for VNET and shared IP jails. Example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334.
IPv6 Prefixdrop-down menuChoose a prefix for this IPv6 Address.
IPv6 Default RouterstringEnter none or a valid IP address. Setting this property to anything other than none configures a default route inside a VNET jail.
NotesstringEnter any notes or comments about the jail.
Auto-startcheckboxStart the jail at system startup.

For static configurations not using DHCP or NAT, multiple IPv4 and IPv6 addresses and interfaces can be added to the jail by clicking ADD.

Jail Properties

SettingValueDescription
devfs_rulesetintegerNumber of the devfs(8) ruleset to enforce when mounting devfs in the jail. The default value of 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.startstringCommands to run in the jail environment when a jail is created. Example: sh /etc/rc. See jail(8) for more details.
exec.stopstringCommands to run in the jail environment before a jail is removed and after any exec_prestop commands are complete. Example: sh /etc/rc.shutdown.
exec_prestartstringCommands to run in the system environment before a jail is started.
exec_poststartstringCommands to run in the system environment after a jail is started and after any exec_start commands are finished.
exec_prestopstringCommands to run in the system environment before a jail is stopped.
exec_poststopstringCommands to run in the system environment after a jail is started and after any exec_start commands are finished.
exec_cleancheckboxRun commands in a clean environment. The current environment is discarded except for $HOME, $SHELL, $TERM and $USER. $HOME and $SHELL are set to the target login. $USER is set to the target login. $TERM is imported from the current environment. The environment variables from the login class capability database for the target login are also set.
exec_timeoutintegerThe maximum amount of time in seconds to wait for a command to complete. If a command is still running after the allotted time, the jail is terminated.
stop_timeoutintegerThe maximum amount of time in seconds to wait for the jail processes to exit after sending a SIGTERM signal. This happens after any exec_stop commands are complete. After the specified time, the jail is removed, killing any remaining processes. If set to 0, no SIGTERM is sent and the jail is immediately removed.
exec_jail_userstringEnter either root or a valid user name. Inside the jail, commands run as this user.
exec_system_jail_userstringSet to True to look for the exec.jail_user in the system passwd(5) file instead of the jail passwd.
exec_system_userstringRun commands in the jail as this user. By default, commands are run as the current user.
mount_devfscheckboxMount a devfs(5) filesystem on the chrooted /dev directory and apply the ruleset in the devfs_ruleset parameter to restrict the devices visible inside the jail.
mount_fdescfscheckboxMount an fdescfs(5) filesystem in the jail /dev/fd directory.
enforce_statfsdrop-downDetermine which information processes in a jail are able to obtain about mount points. The behavior of multiple syscalls is affected: [statfs(2)}(https://www.freebsd.org/cgi/man.cgi?query=statfs, fstatfs(2), getfsstat(2), fhstatfs(2), and other similar compatibility syscalls. All mount points are available without any restrictions if this is set to 0. Only mount points below the jail chroot directory are available if this is set to 1. Set to 2, the default option only mount points where the jail chroot directory is located are available.
children_maxintegerNumber of child jails allowed to be created by the jail or other jails under this jail. A limit of 0 restricts the jail from creating child jails. Hierarchical Jails in the jail(8) man page explains the finer details.
login_flagsstringFlags to pass to [login(1)}(https://www.freebsd.org/cgi/man.cgi?query=login) when logging in to the jail using the console function.
securelevelintegerValue 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, jail securelevel will be at least as secure. Securelevel options are: 3, 2 (default), 1, 0, and -1.
sysvmsgdrop-downAllow or deny access to SYSV IPC message primitives. Set to Inherit: All IPC objects on the system are visible to the jail. Set to New: Only objects the jail created using the private key namespace are visible. The system and parent jails have access to the jail objects but not private keys. Set to Disable: The jail cannot perform any sysvmsg related system calls.
sysvsemdrop-downAllow or deny access to SYSV IPC semaphore primitives. Set to Inherit: All IPC objects on the system are visible to the jail. Set to 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. Set to Disable: The jail cannot perform any sysvmem related system calls.
sysvshmdrop-downAllow or deny access to SYSV IPC shared memory primitives. Set to Inherit: All IPC objects on the system are visible to the jail. Set to 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. Set to Disable: The jail cannot perform any sysvshm related system calls.
allow_set_hostnamecheckboxAllow the jail hostname to be changed with hostname(1) or [sethostname(3)}(https://www.freebsd.org/cgi/man.cgi?query=sethostname).
allow_sysvipccheckboxChoose 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 later! Use sysvmsg, sysvsem,and sysvshm instead.
allow_raw_socketscheckboxAllow the jail to use raw sockets. When set, the jail has access to lower-level network layers. This allows utilities like ping(8) and traceroute(8) to work in the jail, but has security implications and should only be used on jails running trusted software.
allow_chflagscheckboxTreat jail users as privileged and allow the manipulation of system file flags. securelevel constraints are still enforced.
allow_mlockcheckboxAllow jail to run services that use mlock(2) to lock physical pages in memory.
allow_mountcheckboxAllow privileged users inside the jail to mount and unmount filesystem types marked as jail-friendly.
allow_mount_devfscheckboxAllow privileged users inside the jail to mount and unmount the devfs(5) device filesystem. This permission is only effective when allow_mount is set and enforce_statfs is set to a value lower than 2.
allout_mount_fusefscheckboxAllow privileged users inside the jail to mount and unmount fusefs. The jail must have FreeBSD 12.0 or newer installed. This permission is only effective when allow_mount is set and enforce_statfs is set to a value lower than 2.
allow_mount_nullfscheckboxAllow privileged users inside the jail to mount and unmount the nullfs(5) file system. This permission is only effective when allow_mount is set and enforce_statfs is set to a value lower than 2.
allow_mount_procfscheckboxAllow privileged users inside the jail to mount and unmount the procfs(5) file system. This permission is only effective when allow_mount is set and enforce_statfs is set to a value lower than 2.
allow_mount_tmpfscheckboxAllow privileged users inside the jail to mount and unmount the tmpfs(5) file system. This permission is only effective when allow_mount is set and enforce_statfs is set to a value lower than 2.
allow_mount_zfscheckboxAllow privileged users inside the jail to mount and unmount the ZFS file system. This permission is only effective when allow_mount is set and enforce_statfs is set to a value lower than 2. The [ZFS(8)(https://www.freebsd.org/cgi/man.cgi?query=zfs) manual page has information on how to configure the ZFS filesystem to operate from within a jail.
allow_vmmcheckboxGrants the jail access to the Bhyve Virtual Machine Monitor (VMM). The jail must have FreeBSD 12.0 or newer installed with the vmm(4) kernel module loaded.
allow_quotascheckboxAllow the jail root to administer quotas on the jail filesystems. This includes filesystems the jail shares with other jails or with non-jailed parts of the system.
allow_socket_afcheckboxAllow access to other protocol stacks beyond IPv4, IPv6, local (UNIX), and route. Warning: jail functionality does not exist for all protocol stacks.
vnet_interfacesstringSpace-delimited list of network interfaces to attach to a VNET-enabled jail after it is created. Interfaces are automatically released when the jail is removed.

Networking Properties

SettingValueDescription
interfacesstringEnter 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 is attached.
host_domainnamestringEnter a NIS Domain name for the jail.
host_hostnamestringEnter a hostname for the jail. By default, the system uses the jail NAME/UUID.
exec_fibintegerEnter a number to define the routing table (FIB) to set when running commands inside the jail.
ip4.saddrselcheckboxDisables 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.
ip4drop-downControl the availability of IPv4 addresses. Set to Inherit: allow unrestricted access to all system addresses. Set to New: restrict addresses with ip4_addr. Set to Disable: stop the jail from using IPv4 entirely.
ip6.saddrselstringDisable 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.
ip6drop-downControl the availability of IPv6 addresses. Set to Inherit: allow unrestricted access to all system addresses. Set to New: restrict addresses with ip6_addr. Set to Disable: stop the jail from using IPv6 entirely.
resolverstringAdd lines to the resolv.conf file. 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.
mac_prefixstringOptional. Enter a valid MAC address vendor prefix. Example: E4F4C6
vnet0_macstringLeave this blank to generate random MAC addresses for the host and jail. To assign fixed MAC addresses, enter the host MAC address and the jail MAC address separated by a space.
vnet1_macstringLeave this blank to generate random MAC addresses for the host and jail. To assign fixed MAC addresses, enter the host MAC address and the jail MAC address separated by a space.
vnet2_macstringLeave this blank to generate random MAC addresses for the host and jail. To assign fixed MAC addresses, enter the host MAC address and the jail MAC address separated by a space.
vnet3_macstringLeave this blank to generate random MAC addresses for the host and jail. To assign fixed MAC addresses, enter the host MAC address and the jail MAC address separated by a space.

Custom Properties

SettingValueDescription
ownerstringThe owner of the jail. Can be any string.
priorityintegerThe numeric start priority for the jail at boot time. Smaller values mean a higher priority. At system shutdown, the priority is reversed. Example: 99
hostidstringA new a jail hostid, if necessary. Example hostid: 1a2bc345-678d-90e1-23fa-4b56c78901de.
hostid_strict_checkcheckboxCheck the jail hostid property. Prevents the jail from starting if the hostid does not match the host.
commentstringComments about the jail.
dependsstringSpecify any jails the jail depends on. Child jails must already exist before the parent jail can be created.
mount_procfscheckboxAllow mounting of a procfs(5) filesystems in the jail /dev/proc directory.
mount_linprocfscheckboxAllow mounting of a linprocfs(5) filesystem in the jail.
templatecheckboxConvert the jail into a template. Template jails can be used to quickly create jails with the same configuration.
host_timecheckboxSynchronize the time between jail and host.
jail_zfscheckboxEnable automatic ZFS jailing inside the jail. The assigned ZFS dataset is fully controlled by the jail. Note: allow_mount, enforce_statfs, and allow_mount_zfs must all be set for ZFS management inside the jail to work correctly.
jail_zfs_datasetstringDefine 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_mountpointstringThe mountpoint for the jail_zfs_dataset. Example: /data/example-dataset-name
allow_tuncheckboxExpose host tun(4) devices in the jail. Allow the jail to create tun devices.
Autoconfigure IPv6 with rtsoldcheckboxUse rtsold(8) as part of IPv6 autoconfiguration. Send ICMPv6 Router Solicitation messages to interfaces to discover new routers.
ip_hostnamecheckboxUse DNS records during jail IP configuration to search the resolver and apply the first open IPv4 and IPv6 addresses. See jail(8).
assign_localhostcheckboxAdd network interface lo0 to the jail and assign it the first available localhost address, starting with 127.0.0.2. VNET cannot be set. Jails using VNET configure a localhost as part of their virtualized network stack.