13. Jails — FreeNAS®11.2-BETA1 User Guide Table of Contents

# 13. Jails

Jails are a very light-weight, operating system-level virtualization, and the basis for the FreeNAS® plugin system. Jails can also be created by the user. While plugins generally are preconfigured and use a GUI for configuration, jails are often managed from the command line. Plugins provide a single application or service, while jails can provide multiple services.

By default, a FreeBSD jail is created. A jail is an independent instance of FreeBSD, using the host kernel, running on the same hardware without all of the overhead usually associated with virtualization. The jail installs FreeBSD software management utilities so FreeBSD ports can be compiled and FreeBSD packages can 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 FreeNAS® host operating system and any other jails running on that system. During creation, the VNET option can be checked to provide the jail with an independent networking stack. The jail can then do its own IP broadcasting, which is required by some applications.

Advanced users can also create custom templates to automate the creation of pre-installed and customized operating systems.

The ability to create multiple jails offers great 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.

This section will discuss:

- Jail Storage
- Creating Jails
- Managing Jails
- Using iocage

## 13.1. Jail Storage

Jails and FreeBSD releases are stored in a single dataset named `iocage`.

Note

Notes on the `iocage` dataset:

- 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 FreeNAS® system.
- 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`.

## 13.2. Creating Jails

FreeNAS® has two options to create a jail. The Jail Wizard makes it easy to quickly create a jail. Advanced Jail Creation is the second method, where every possible jail option is configurable. There are numerous configurables spread across four different primary sections. This form is recommended for advanced users with very specific requirements for a jail.

### 13.2.1. Jail Wizard

To quickly create a new jail, navigate to Jails and click ＋ (Add/Create). This opens the wizard screen seen in Figure 13.2.1.

Fig. 13.2.1 Jail Creation Wizard

The wizard demonstrates the simplest process to create and configure networking for a new jail. Enter a Jail Name. Jail names can only contain alphanumeric characters (`Aa-Zz`, `123`), dashes (`-`), and underscores (`_`). Choose the version of FreeBSD to install for this jail. Previously downloaded versions display `(fetched)` next to their entry in the list. These are the minimum required settings for a new jail but it is also recommended to configure networking for the jail.

Click Next to see a simplified list of networking options. The jail can be set to automatically configure IPv4 with DHCP and VNET or IPv4 and IPv6 can be configured manually. Multiple interfaces are supported in the IPv4 Address and IPv6 Address fields by entering a comma delimited list of interfaces, addresses, and netmask in the format `interface|ipaddress/netmask`.

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.

Tip

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.

### 13.2.2. Advanced Jail Creation

To open the full jail creation form, navigate Jails ‣ Add Jail and click Advanced Jail Creation to access the screen shown in Figure 13.2.2.

Fig. 13.2.2 Creating a Jail

Table 13.2.1 summarizes the available options of the Basic Properties of a new jail. By default, the only required values to create a jail are the Jail Name and Release. It is recommended to configure these basic properties as a simple method to quickly create an immediately usable jail. Many more advanced settings are available in the Jail Properties, Network Properties, and Custom Properties sections.

Table 13.2.1 Basic Properties
Setting | Value | Description
--- | --- | ---
Jail Name | string | Required. Jail names can only contain alphanumeric characters (`Aa-Zz`, `123`), dashes (`-`), and underscores (`_`).
Release | drop-down menu | Required. Choose the version of FreeBSD to download and install for the jail. Previously downloaded versions of FreeBSD display `(fetched)` next to the entry in the list and do not need to be fetched again.
DHCP autoconfigure IPv4 | checkbox | Set to automatically configure IPv4 networking with an independent VNET stack. VNET and guilabel:Berkeley Packet Filter must also be checked. If not set, ensure the defined address in IPv4 Address does not conflict with an existing address.
VNET network subsystem virtualization infrastructure | checkbox | Set to use 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 Filter | checkbox | Set to use the Berkeley Packet Filter to data link layers in a protocol independent fashion See BPF(4) for more details.
IPv4 address | string | This and the other IPv4 settings are grayed out if DHCP autoconfigure IPv4 is set. Configures the interface to use for network or internet access for the jail. Type 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. Example: vnet0|192.168.0.10/24
Default IPv4 Router | string | Type `none` or a valid IP address. Setting this property to anything other than none configures a default route inside a VNET jail.
IPv6 address | string | Configures network or internet access for the jail. Type the IPv6 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. Example: re0|2001:0db8:85a3:0000:0000:8a2e:0370:7334/24.
Default IPv6 Router | string | Type `none` or a valid IP address. Setting this property to anything other than none configures a default route inside a VNET jail.
Note | string | Enter any notes or comments about the jail.
Auto-start | checkbox | Check to start the jail at system startup.

Similar to the Jail Wizard, configuring the basic properties then clicking Save is often all that is needed to quickly create and begin using a new jail. To continue configuring more settings, click Next to proceed to the Jail Properties section of the form. Table 13.2.2 describes each of these options.

Table 13.2.2 Jail Properties
Setting | Value | Description
--- | --- | ---
devfs_ruleset | integer | The number 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.start | string | Commands to run in the jail environment when a jail is created. Example: `sh /etc/rc`. See jail(8) for more details.
exec.stop | string | Commands 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_prestart | string | Commands to run in the system environment before a jail is started.
exec_poststart | string | Commands to run in the system environment after a jail is started and after any exec_start commands are finished.
exec_prestop | string | Commands to run in the system environment before a jail is stopped.
exec_poststop | string | Commands to run in the system environment after a jail is started and after any exec_start commands are finished.
exec.clean | checkbox | Run 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_timeout | integer | The 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_timeout | integer | The 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 immeadility removed.
exec_jail_user | string | Enter either `root` or a valid username. Inside the jail, commands run as this user.
exec.system_jail_user | string | Set this boolean option to True to look for the exec.jail_user in the system passwd(5) file instead of the jail passwd.
exec.system_user | string | Run comands in the jail as this user. By default, commands are run as the current user.
mount.devfs | checkbox | Mount 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.fdescfs | checkbox | Mount an fdescfs(5) filesystem in the jail `/dev/fd` directory.
enforce_statfs | drop-down | Determine which information processes in a jail are able to obtain about mount points. The behavior of multiple syscalls is affected: statfs(2), fstatfs(2), getfsstat(2), fhstatfs(2), and other similar compatibility syscalls. Set to 0, all mount points are available without any restriction. Set to 1, only mount points below the jail chroot directory are available. Set to 2, the default option only mount points where the jail chroot directory is located are available.
children.max | integer | The number 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_flags | string | The flags to pass to LOGIN(1) when logging in to the jail using the console function.
securelevel | integer | The 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, jail securelevel will be at least as secure. Securelevel options are 3, 2, 1, 0, and -1.
sysvmsg | drop-down | Allow 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.
sysvsem | drop-down | Allow 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.
sysvshm | drop-down | Allow 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_hostname | checkbox | Allow the jail hostname to be changed with hostname(1) or sethostname(3).
*allow.sysvipc | checkbox | Choose 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_sockets | checkbox | Set to allow raw sockets. Utilities like ping(8) and traceroute(8) require raw sockets to operate inside a jail. When set, the source IP addresses are enforced to comply with the IP address bound to the jail, ignoring the the IP_HDRINCL flag on the socket.
allow.chflags | checkbox | Set to treat jail users as privileged and allow the manipulation of system file flags. securelevel constraints are still enforced.
allow.mount | checkbox | Set to allow privileged users inside the jail to mount and unmount filesystem types marked as jail-friendly.
allow.mount.devfs | checkbox | Set to allow 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.
allow.mount.nullfs | checkbox | Set to allow 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.procfs | checkbox | Set to allow 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.tmpfs | checkbox | Set to allow 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.zfs | checkbox | Set to allow 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) man page has information on how to configure the ZFS filesystem to operate from within a jail.
allow.quotas | checkbox | Set to allow 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_af | checkbox | Check to allow access to other protocol stacks beyond IPv4, IPv6, local (UNIX), and route. Warning: jail functionality does not exist for all protocal stacks.

Click Next to view all jail Network Properties. These are shown in Table 13.2.3:

Table 13.2.3 Network Properties
Setting | Value | Description
--- | --- | ---
interfaces | string | Enter 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_domainname | string | Enter an NIS Domain name for the jail.
host.hostname | string | Enter a hostname for the jail. By default, the system uses the jail UUID.
exec.fib | integer | Enter a number to define the routing table (FIB) to set when running commands inside the jail.
ip4.saddrsel | checkbox | Only available when the jail is not configured to use VNET. Disables IPv4 source address selection for the jail in favor of the primary IPv4 address of the jail.
ip4 | drop-down | Control 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.saddrsel | string | Only available when the jail is not configured to use VNET. Disables IPv6 source address selection for the jail in favor of the primary IPv6 address of the jail.
ip6 | drop-down | Control 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.
resolver | string | Add lines to `resolv.conf` in 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_prefix | string | Optional. Enter a valid MAC address vendor prefix. Example: E4F4C6
vnet0_mac | string | Optional. Enter a valid MAC address for the VNET0 interface.
vnet1_mac | string | Optional. Enter a valid MAC address for the VNET1 interface.
vnet2_mac | string | Optional. Enter a valid MAC address for the VNET2 interface.
vnet3_mac | string | Optional. Enter a valid MAC address for the VNET3 interface.

The final set of jail properties are contained in the Custom Properties section. Table 13.2.4 describes these options.

Table 13.2.4 Custom Properties
Setting | Value | Description
--- | --- | ---
owner | string | The owner of the jail. Can be any string.
priority | integer | The numeric start priority for the jail at boot time. Smaller values mean a higher priority. At system shutdown, the priority is reversed. Example: 99
hostid | string | A new a jail hostid, if necessary. Example hostid: 1a2bc345-678d-90e1-23fa-4b56c78901de.
comment | string | Comments about the jail.
depends | string | Specify any jails the jail depends on. Child jails must already exist before the parent jail can be created.
mount.procfs | checkbox | Set to allow mounting of a procfs(5) filesystems in the jail `/dev/proc` directory.
mount_linprocfs | checkbox | Set to allow mounting of a linprocfs(5) filesystem in the jail.
host_time | checkbox | Set to synchronize the time between jail and host.
jail_zfs | checkbox | Set to enable 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_dataset | string | Define 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_mountpoint | string | The mountpoint for the jail_zfs_dataset. Example: /data/example-dataset-name

Click Save when satisfied with all the different jail properties. New jails are added to the primary list in the Jails menu.

## 13.3. Managing Jails

Click Jails to see an overview of installed jails as shown in Figure 13.3.1.

Fig. 13.3.1 Jail Overview Section

Table 13.3.1 describes each column.

Table 13.3.1 Jail Overview Information
Column Name | Description
--- | ---
Jail Name | The name of the jail.
IPv4 addresses | Each of the configured IPv4 addresses.
IPv6 addresses | Each of the configured IPv6 addresses.
Status | up: jail is running
down: jail is stopped.
Type | Currently 2 supported jail types
jail: A jail for general use.
pluginv2: A jail installed by or used for a plugin. A plugin jail contains and isolates a plugin from the FreeNAS® system limiting exposure in the event of an issue and allows resources to be easily managed.
Release | The FreeBSD version the jail is based on.
⫶ (Options) | Click to open the jail options menu as shown in Figure 13.3.2.

Fig. 13.3.2 Jail Option Menu

Note

The ⫶ (Options) menu is jail state sensitive meaning menu entries change depending on the jail state. For example, a stopped jail does not have a Stop option and cannot be accessed via Shell; these options are not available when a jail is stopped.

Table 13.3.2 describes the option menu entries available for a jail.

Table 13.3.2 Jail Option Menu Entry Descriptions
Menu Options | Description
--- | ---
Edit | Open the Jails ‣ Edit section to edit the jail. Jail Edit has the same configurables as the Add Jail section. A jail name cannot be changed after creation, so the UUID/Jail Name field will be grayed out.
Mount points | Open the Mount Points list. Select an existing mount point or click ＋ (Add/Create) to open the Add New Mount Point section to create a new mount point to add. Adding a mount point gives a jail access to storage located elsewhere on the FreeNAS® system. See f:ref:Add Storage or more details.
Start | Start a jail. Running jails are indicated as up.
Stop | Stop a jail. Stopped jails are indicated as down.
Update | Updates any packages installed in the jail to the latest version available in the installed FreeBSD RELEASE.
Shell | Access a root command prompt to interact with a jail directly from the command line. Type exit to close the shell and return to the Jails Overview section.
Delete | Delete the jail and any periodic snapshots. The contents of the jail are entirely removed.

Note

To modify the IP address information for a jail, use ⫶ (Options) Edit instead of issuing the networking commands directly from the command line of the jail. This ensures the changes will survive a jail or FreeNAS® reboot.

Warning

Back up data and programs in a jail before clicking delete. There is no way to recover the contents of a jail after deletion.

### 13.3.1. Accessing a Jail Using SSH

Accessing a jail is not limited to using Jail Add, the Jail Wizard, or using one of the Shells that are built in to the UI. Enable the ssh daemon sshd(8) in a jail, create a user account to log in with, and ssh access to the jail via any computer that has network access to the FreeNAS® server is now possible.

Log in to a shell to get cli access to the jail to enable SSH on. To use the Jails Shell click ⫶ (Options) –> Shell on the desired jail. A root shell will open as shown in this example:

    [root@freenas ~]# iocage console jailexamp
    Last login: Fri Apr 6 07:57:04 on pts/12
    FreeBSD 11.1-STABLE (FreeNAS.amd64) #0 0ale9f753(freenas/11-stable): FriApr 6 04:46:31 UTC 2018

    Welcome to FreeBSD!

    Release Notes, Errata: https://www.FreeBSD.org/releases/
    Security Advisories:   https://www.FreeBSD.org/security/
    FreeBSD Handbook:      https://www.FreeBSD.org/handbook/
    FreeBSD FAQ:           https://www.FreeBSD.org/faq/
    Questions List: https://lists.FreeBSD.org/mailman/listinfo/freebsd-questions/
    FreeBSD Forums:        https://forums.FreeBSD.org/

    Documents installed with the system are in the /usr/local/share/doc/freebsd/
    directory, or can be installed later with: pkg install en-freebsd-doc
    For other languages, replace "en" with a language code like de or fr.

    Show the version of FreeBSD installed: freebsd-version ; uname -a
    Please include that output and any error messages when posting questions.
    Introduction to manual pages: man man
    FreeBSD directory layout:     man hier

    Edit /etc/motd to change this login announcement.
    root@jailexamp:~ #

Tip

A root shell can also be opened for a jail using Shell. Open the Shell, then type `iocage console Jail Name`. Note: Jail Name and UUID are the same thing.

Enable sshd:

    sysrc sshd_enable="YES"

    No existing entry or already set to NO:
    sshd_enable: NO -> YES

    Existing entry set to YES
    sshd_enable: YES -> YES

Tip

Using sysrc to enable sshd will verify sshd gets enabled even if there is an existing entry.

Start the SSH daemon: `service sshd start`

The first time the service runs, the jail RSA key pair is generated and the key fingerprint is displayed.

Add a user account with adduser. Follow the prompts, `Enter` will accept the default value offered. Users that require root access must also be a member of the wheel group. Enter wheel when prompted to invite user into other groups? []:

    root@jailexamp:~ # adduser
    Username: jailuser
    Full name: Jail User
    Uid (Leave empty for default):
    Login group [jailuser]:
    Login group is jailuser. Invite jailuser into other groups? []: wheel
    Login class [default]:
    Shell (sh csh tcsh git-shell zsh rzsh nologin) [sh]: csh
    Home directory [/home/jailuser]:
    Home directory permissions (Leave empty for default):
    Use password-based authentication? [yes]:
    Use an empty password? (yes/no) [no]:
    Use a random password? (yes/no) [no]:
    Enter password:
    Enter password again:
    Lock out the account after creation? [no]:
    Username   : jailuser
    Password   : *****
    Full Name  : Jail User
    Uid        : 1002
    Class      :
    Groups     : jailuser wheel
    Home       : /home/jailuser
    Home Mode  :
    Shell      : /bin/csh
    Locked     : no
    OK? (yes/no): yes
    adduser: INFO: Successfully added (jailuser) to the user database.
    Add another user? (yes/no): no
    Goodbye!
    root@jailexamp:~

After creating the user, set the jail root password to allow users to use su to gain superuser privileges. To set the jail root password, use passwd. Nothing is echoed back when using passwd

    root@jailexamp:~ # passwd
    Changing local password for root
    New Password:
    Retype New Password:
    root@jailexamp:~ #

Finally, test from another system that the user can successfully ssh in to the jail and gain superuser priviledges. In the example, a user named jailuser uses ssh to access the jail at 192.168.2.3. The host RSA key fingerprint must be verified the first time a user logs in.

    ssh jailuser@192.168.2.3
    The authenticity of host '192.168.2.3 (192.168.2.3)' can't be established.
    RSA key fingerprint is 6f:93:e5:36:4f:54:ed:4b:9c:c8:c2:71:89:c1:58:f0.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added '192.168.2.3' (RSA) to the list of known hosts.
    Password:

Note

Every jail has its own user accounts and service configuration. These steps must be repeated for each jail that requires SSH access.

### 13.3.2. Additional Storage

Jails can be given access to an area of storage outside of the jail that is configured on the FreeNAS® system.

It is possible to give a FreeBSD jail access to an area of storage on the FreeNAS® system. This is useful for applications or plugins that store large amount of data or if an application in a jail needs access to data stored on the FreeNAS® system. One example is transmission, a plugin that stores data using BitTorrent. The storage is added using the mount_nullfs(8) mechanism, which links data that resides outside of the jail as a storage area within a jail.

The Mount Points section of a jail shows the all additional storage currently added and allows new additional storage to be added.

Navigate Jails, click ⫶ (Options) on the desired jail, then Mount points. In the Mount points section is a list of all of the currently defined mount points.

To add storage, navigate to Mount points and click ＋ (Add/Create). This opens the screen shown in Figure 13.3.3.

Fig. 13.3.3 Adding Storage to a Jail

Browse to the Source and Destination, where:

- Source: is the directory or dataset on the FreeNAS® system which will be accessed by the jail. This directory must reside outside of the pool or dataset being used by the jail. This is why it is recommended to create a separate dataset to store jails, so the dataset holding the jails is always separate from any datasets used for storage on the FreeNAS® system.
- Destination: select an existing, empty directory within the jail to link to the Source storage area. If that directory does not exist yet, enter the desired directory name and enable the Create directory option.

Storage is typically added because the user and group account associated with an application installed inside of a jail needs to access data stored on the FreeNAS® system. Before selecting the Source, it is important to first ensure that the permissions of the selected directory or dataset grant permission to the user/group account inside of the jail. This is not the default, as the users and groups created inside of a jail are totally separate from the users and groups of the FreeNAS® system.

The workflow for adding storage usually goes like this:

1. Determine the name of the user and group account used by the application. For example, the installation of the transmission application automatically creates a user account named transmission and a group account also named transmission. When in doubt, check the files `/etc/passwd` (to find the user account) and `/etc/group` (to find the group account) inside the jail. Typically, the user and group names are similar to the application name. Also, the UID and GID are usually the same as the port number used by the service.

   A media user and group (GID 8675309) are part of the base system. Having applications run as this group or user makes it possible to share storage between multiple applications in a single jail, between multiple jails, or even between the host and jails.

2. On the FreeNAS® system, create a user account and group account that match the user and group names used by the application in the jail.

3. Decide if the jail will have access to existing data or if a new area of storage will be set aside for the jail to use.

4. If the jail will access existing data, edit the permissions of the pool or dataset so the user and group accounts have the desired read and write access. If multiple applications or jails are to have access to the same data, create a new group and add each needed user account to that group.

5. If an area of storage is being set aside for that jail or individual application, create a dataset. Edit the permissions of that dataset so the user and group account has the desired read and write access.

6. Use the Mount points ‣ Add Mount Point options of the jail and select the configured pool or dataset as the Source.

To prevent writes to the storage, check Read-Only.

After storage has been added or created, it appears in the Mount points for that jail. In the example shown in Figure 13.3.4, a dataset named `pool1/data` has been chosen as the Source as it contains the files stored on the FreeNAS® system. When the storage was created, the user browsed to the existing `pool1/jails/freebsd1/usr/local/test` directory in the Destination field. The storage was added to the freenas1 entry in the tree as `/usr/local/test`. The user has clicked this `/usr/local/test` entry to access the Edit screen.

Fig. 13.3.4 Example Storage

Storage is automatically mounted as it is created.

Note

A mounted dataset will not automatically mount any of its child datasets. While the child datasets may appear to be browsable inside the jail, any changes will not be visible. Since each dataset is considered to be its own filesystem, each child dataset must have its own mount point, so separate storage must be created for any child datasets which need to be mounted.

To delete the storage, click its Delete button.

Warning

It is important to realize that added storage is really just a pointer to the selected storage directory on the FreeNAS® system. It does not copy that data to the jail. Files that are deleted from the Destination directory in the jail are really deleted from the Source directory on the FreeNAS® system. However, removing the jail storage entry only removes the pointer, leaving the data intact but not accessible from the jail.

## 13.4. Jail Software

A jail is created with no software aside from the core packages installed as part of the selected version of FreeBSD. Software in a jail is managed by navigating to the Shell and logging into the jail with iocage console. In this example, the user has logged into testjail01:

    [root@freenas ~]# iocage console testjail01
    FreeBSD 11.1-STABLE (FreeNAS.amd64) #0 35e0ef284(freenas/11-stable): Mon Apr  9 17:44:36 UTC 2018

    Welcome to FreeBSD!

    Release Notes, Errata: https://www.FreeBSD.org/releases/
    Security Advisories:   https://www.FreeBSD.org/security/
    FreeBSD Handbook:      https://www.FreeBSD.org/handbook/
    FreeBSD FAQ:           https://www.FreeBSD.org/faq/
    Questions List: https://lists.FreeBSD.org/mailman/listinfo/freebsd-questions/
    FreeBSD Forums:        https://forums.FreeBSD.org/

    Documents installed with the system are in the /usr/local/share/doc/freebsd/
    directory, or can be installed later with:  pkg install en-freebsd-doc
    For other languages, replace "en" with a language code like de or fr.

    Show the version of FreeBSD installed:  freebsd-version ; uname -a
    Please include that output and any error messages when posting questions.
    Introduction to manual pages:  man man
    FreeBSD directory layout:      man hier

    Edit /etc/motd to change this login announcement.
    root@testjail01:~ #

Tip

See Using iocage for more details about different iocage commands simple jail manipulation.

The next sections detail two different options to install software inside a jail using pkg or compiling the port directly. There are also instructions for starting and using installed software.

### 13.4.1. Installing FreeBSD Packages

The quickest and easiest way to install software inside the jail is to install a FreeBSD package. FreeBSD packages are pre-compiled. They contains all the binaries and a list of dependencies required for the software to run on a FreeBSD system.

A huge amount of software has been ported to FreeBSD, currently over 24,000 applications, and most of that software is available as a package. One way to find FreeBSD software is to use the search bar at FreshPorts.org.

After finding the name of the desired package, use the pkg install command to install it. For example, to install the audiotag package, use this command:

    pkg install audiotag

When prompted, type y to complete the installation. The installation messages will indicate if the package and its dependencies successfully download and install.

Warning

Some older versions of FreeBSD used package systems which are now obsolete. Do not use commands from those obsolete package systems in a FreeNAS® jail, as they will cause inconsistencies in the jail’s package management database. Use the current FreeBSD package system as shown in these examples.

A successful installation can be confirmed by querying the package database:

    pkg info -f audiotag
    audiotag-0.19_1
    Name:           audiotag
    Version:        0.19_1
    Installed on:   Fri Nov 21 10:10:34 PST 2014
    Origin:         audio/audiotag
    Architecture:   freebsd:9:x86:64
    Prefix:         /usr/local
    Categories:     multimedia audio
    Licenses:       GPLv2
    Maintainer:     ports@FreeBSD.org
    WWW:            http://github.com/Daenyth/audiotag
    Comment:        Command-line tool for mass tagging/renaming of audio files
    Options:
      DOCS:         on
      FLAC:         on
      ID3:          on
      MP4:          on
      VORBIS:       on
    Annotations:
      repo_type:    binary
      repository:   FreeBSD
    Flat size:      62.8KiB
    Description:   Audiotag is a command-line tool for mass tagging/renaming of audio files
                   it supports the vorbis comment, id3 tags, and MP4 tags.
    WWW:           http://github.com/Daenyth/audiotag

To show what was installed by the package:

    pkg info -l audiotag
    audiotag-0.19_1:
    /usr/local/bin/audiotag
    /usr/local/share/doc/audiotag/COPYING
    /usr/local/share/doc/audiotag/ChangeLog
    /usr/local/share/doc/audiotag/README
    /usr/local/share/licenses/audiotag-0.19_1/GPLv2
    /usr/local/share/licenses/audiotag-0.19_1/LICENSE
    /usr/local/share/licenses/audiotag-0.19_1/catalog.mk

In FreeBSD, third-party software is always stored in `/usr/local` to differentiate it from the software that came with the operating system. Binaries are almost always located in a subdirectory called `bin` or `sbin` and configuration files in a subdirectory called `etc`.

### 13.4.2. Compiling FreeBSD Ports

Software is typically installed into FreeBSD jails using packages. But sometimes there are good reasons to compile a port instead. Compiling ports offers these advantages:

- Not every port has an available package. This is usually due to licensing restrictions or known, unaddressed security vulnerabilities.
- Sometimes the package is out-of-date and a feature is needed that only became available in the newer version.
- Some ports provide compile options that are not available in the pre-compiled package. These options are used to add or remove features or options.

Compiling a port has these disadvantages:

- It takes time. Depending upon the size of the application, the amount of dependencies, the speed of the CPU, the amount of RAM available, and the current load on the FreeNAS® system, the time needed can range from a few minutes to a few hours or even to a few days.

Note

If the port does not provide any compile options, it saves time and preserves the FreeNAS® system’s resources to just use the pkg install command instead.

The FreshPorts.org listing shows whether a port has any configurable compile options. Figure 13.4.1 shows the Configuration Options for audiotag.

Fig. 13.4.1 Configuration Options for Audiotag

This port has five configurable options (DOCS, FLAC, ID3, MP4, and VORBIS) and each option is enabled (on) by default.

FreeBSD packages are always built using the default options. When compiling a port, those options are presented in a menu, allowing the default values to be changed.

The Ports Collection must be installed in a jail before ports can be compiled. Inside the jail, use the portsnap utility. This command downloads the ports collection and extracts it to the jail’s `/usr/ports/` directory:

    portsnap fetch extract

Note

To install additional software at a later date, make sure the ports collection is updated with portsnap fetch update.

To compile a port, cd into a subdirectory of `/usr/ports/`. The entry for the port at FreshPorts provides the location to cd into and the make command to run. This example compiles and installs the audiotag port:

    cd /usr/ports/audio/audiotag
    make install clean

Since this port has configurable options, the first time this command is run, the configure screen shown in Figure 13.4.2 is displayed:

Fig. 13.4.2 Configuration Options for Audiotag Port

Use the arrow keys to select an option and press `spacebar` to toggle the value. When all the values are as desired, press `Enter`. The port will begin to compile and install.

Note

The configuration screen will not be shown again, even if the build is stopped and restarted. It can be redisplayed by typing make config. Change the settings, then rebuild with make clean install clean.

Many ports depend on other ports. Those other ports can also have configuration screens that will be shown before compiling begins. It is a good idea to keep an eye on the compile until it finishes and the command prompt returns.

When the port is installed, it is registered in the same package database that manages packages. The same pkg info command can be used to determine what was installed, as described in the previous section.

### 13.4.3. Starting Installed Software

After packages or ports are installed, they must be configured and started. If familiar with the software, look for the configuration file in `/usr/local/etc` or a subdirectory of it. Many FreeBSD packages contain a sample configuration file as a reference. If unfamiliar with the software, spend some time reading the software documentation to learn which configuration options are available and which configuration files require editing.

Most FreeBSD packages that contain a startable service include a startup script which is automatically installed to `/usr/local/etc/rc.d/`. After the configuration is complete, the starting of the service can be tested by running the script with the onestart option. As an example, if openvpn is installed into the jail, these commands run its startup script and verify that the service started:

    /usr/local/etc/rc.d/openvpn onestart
    Starting openvpn.

    /usr/local/etc/rc.d/openvpn onestatus
    openvpn is running as pid 45560.

    sockstat -4
    USER COMMAND         PID     FD      PROTO   LOCAL ADDRESS   FOREIGN ADDRESS
    root openvpn         48386   4       udp4    *:54789         *:*

If it produces an error:

    /usr/local/etc/rc.d/openvpn onestart
    Starting openvpn.
    /usr/local/etc/rc.d/openvpn: WARNING: failed to start openvpn

Run tail /var/log/messages to see if any error messages hint at the problem. Most startup failures are related to a misconfiguration: either a typo or a missing option in a configuration file.

After verifying that the service starts and is working as intended, add a line to `/etc/rc.conf` to start the service automatically when the jail is started. The line to start a service always ends in _enable=”YES” and typically starts with the name of the software. For example, this is the entry for the openvpn service:

    openvpn_enable="YES"

When in doubt, the startup script shows the line to put in `/etc/rc.conf`. This is the description in `/usr/local/etc/rc.d/openvpn`:

    # This script supports running multiple instances of openvpn.
    # To run additional instances link this script to something like
    # % ln -s openvpn openvpn_foo

    # and define additional openvpn_foo_* variables in one of
    # /etc/rc.conf, /etc/rc.conf.local or /etc/rc.conf.d /openvpn_foo

    #
    # Below NAME should be substituted with the name of this script. By default
    # it is openvpn, so read as openvpn_enable. If you linked the script to
    # openvpn_foo, then read as openvpn_foo_enable etc.
    #
    # The following variables are supported (defaults are shown).
    # You can place them in any of
    # /etc/rc.conf, /etc/rc.conf.local or /etc/rc.conf.d/NAME
    #
    # NAME_enable="NO"
    # set to YES to enable openvpn

The startup script also indicates if any additional parameters are available:

    # NAME_if=
    # driver(s) to load, set to "tun", "tap" or "tun tap"
    #
    # it is OK to specify the if_ prefix.
    #
    # # optional:
    # NAME_flags=
    # additional command line arguments
    # NAME_configfile="/usr/local/etc/openvpn/NAME.conf"
    # --config file
    # NAME_dir="/usr/local/etc/openvpn"
    # --cd directory

## 13.5. Using iocage

Beginning with FreeNAS® 9.10.1, the iocage command line utility is included for creating and managing jails. Click the Shell option to open the command line and begin using iocage.

iocage has several options to help users:

- There is built-in help displayed by entering `iocage --help | less`. Each subcommand also has help, displayed by giving the subcommand name followed by the `--help` flag. For example, help for the activate subcommand displays with `iocage activate --help`.
- The iocage manual page is accessed by typing `man iocage | less`.
- The iocage project also has documentation available on readthedocs.io.

### 13.5.1. Managing iocage Jails

Creating a jail automatically starts the iocage configuration process for the FreeNAS® system. Jail properties can also be specified with the iocage create command.

In this example a new jail named examplejail is created. Additional properties are a manually designated IP address of 192.168.1.10, a netmask of /24 on the em0 interface, and using the FreeBSD 11.1-RELEASE:

    [root@freenas ~]# iocage create -n examplejail ip4_addr="em0|192.168.1.10/24" -r
    11.1-RELEASE
    ...
    examplejail successfully created!

Jail creation may take a few moments. After completion, start the new jail with iocage start:

    [root@freenas ~]# iocage start examplejail
    * Starting examplejail
    + Started OK
    + Starting services OK

To open the console in the started jail, use iocage console

    [root@freenas ~]# iocage console examplejail
    FreeBSD 11.1-STABLE (FreeNAS.amd64) #0 35e0ef284(freenas/11-stable): Wed Oct 18
    17:44:36 UTC 2017

    Welcome to FreeBSD!

    Release Notes, Errata: https://www.FreeBSD.org/releases/
    Security Advisories:   https://www.FreeBSD.org/security/
    FreeBSD Handbook:      https://www.FreeBSD.org/handbook/
    FreeBSD FAQ:           https://www.FreeBSD.org/faq/
    Questions List: https://lists.FreeBSD.org/mailman/listinfo/freebsd-questions/
    FreeBSD Forums:        https://forums.FreeBSD.org/

    Documents installed with the system are in the /usr/local/share/doc/freebsd/
    directory, or can be installed later with:  pkg install en-freebsd-doc
    For other languages, replace "en" with a language code like de or fr.

    Show the version of FreeBSD installed:  freebsd-version ; uname -a
    Please include that output and any error messages when posting questions.
    Introduction to manual pages:  man man
    FreeBSD directory layout:      man hier

    Edit /etc/motd to change this login announcement.
    root@examplejail:~ #

Jails can be shut down with iocage stop:

    [root@freenas ~]# iocage stop examplejail
    * Stopping examplejail
      + Running prestop OK
      + Stopping services OK
      + Removing jail process OK
      + Running poststop OK

Jails are deleted with iocage destroy:

    [root@freenas ~]# iocage destroy examplejail

    This will destroy jail examplejail

    Are you sure? [y/N]: y
    Destroying examplejail

To adjust the properties of a jail, use iocage set and iocage get. All properties of a jail are viewed with iocage get all:

Tip

This example shows an abbreviated list of the properties for examplejail. The iocage manual page (man iocage) describes even more configurable properties for jails.

    [root@freenas ~]# iocage get all examplejail | less
    allow_mount:0
    allow_mount_devfs:0
    allow_sysvipc:0
    available:readonly
    basejail:no
    boot:off
    bpf:no
    children_max:0
    cloned_release:11.1-RELEASE
    comment:none
    compression:lz4
    compressratio:readonly
    coredumpsize:off
    count:1
    cpuset:off
    cputime:off
    datasize:off
    dedup:off
    defaultrouter:none
    defaultrouter6:none
    ...

To adjust a jail property, use iocage set:

    [root@freenas ~]# iocage set notes="This is a testing jail." examplejail
    Property: notes has been updated to This is a testing jail.