13. Jails — FreeNAS® User Guide 9.10.1 Table of Contents

# 13. Jails

The previous section described how to find, install, and configure software using Plugins.

This section describes how to use Jails, which allow users who are comfortable with the command line to have more control over software installation and management. Any software installed using Jails must be managed from the command line of the jail. If you prefer to use a GUI to manage software, use Plugins instead.

FreeNAS® automatically creates a jail whenever a plugin is installed, but does not let the user install multiple plugins into the same jail. In contrast, using Jails allows users to create as many jails as needed and to customize the operating system and installed software within each jail.

In FreeNAS® 9.x, two types of jails are supported:

1. By default, a FreeBSD jail is created. This provides a very light-weight, operating system-level virtualization. Consider it as another independent instance of FreeBSD running on the same hardware, without all of the overhead usually associated with virtualization. The jail will install the FreeBSD software management utilities so FreeBSD ports can be compiled and FreeBSD packages can be installed from the command line of the jail.
2. A Virtualbox template is also provided. This template installs an instance of phpVirtualBox, a web-based front-end to VirtualBox This can then be used to install any operating system and to use the software management tools provided by that operating system.

It is important to understand that any users, groups, installed software, and configurations within a jail are isolated from both the FreeNAS® operating system and any other jails running on that system. During creation, the VIMAGE option can be selected which will also provide that jail with its own, independent networking stack. This allows that jail to 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 running different operating systems offers great flexibility regarding software management. For example, the administrator can choose to provide application separation by installing different applications in each jail, or to create one jail for all installed applications, or to mix and match how software is installed into each jail.

The rest of this section describes:

- Jails Configuration
- Adding Jails
- Using the phpVirtualBox Template
- Managing Jail Templates

## 13.1. Jails Configuration

Jails are stored in a volume or dataset. Using a separate dataset for the Jail Root is strongly recommended. The volume or dataset to be used must already exist or can be created with Volume Manager.

Note

The Jail Root volume or dataset cannot be created on a Share.

Begin global jail configuration by choosing `Jails → Configuration` to open the screen shown in Figure 13.1.1. Jails are automatically installed into their own dataset under the specified path as they are created. For example, if the Jail Root is set to `/mnt/volume1/dataset1` and a jail named jail1 is created, it is installed into its own dataset named `/mnt/volume1/dataset1/jail1`.

Fig. 13.1.1 Global Jail Configuration

Warning

If any Plugins have already been installed, the Jail Root, IPv4 Network, IPv4 Network Start Address, and IPv4 Network End Address are automatically filled. Double-check that the pre-configured IP address values are appropriate for the jails and do not conflict with addresses used by other systems on the network.

Table 13.1.1 summarizes the fields in this configuration screen. Refer to the text below the table for more details on how to properly configure the Jail Root and network settings. Some settings are only available in Advanced Mode. To see these settings, either click the Advanced Mode button or configure the system to always display these settings by checking the box Show advanced fields by default in `System → Advanced`.

Table 13.1.1 Jail Configuration Options
Setting | Value | Description
--- | --- | ---
Jail Root | browse button | mandatory; jails cannot be added until this is set
IPv4 DHCP | checkbox | check this box if the network has a DHCP server
IPv4 Network | string | only available in Advanced Mode; format is IP address of network/CIDR mask
IPv4 Network Start Address | string | only available in Advanced Mode; enter the first IP address in the reserved range in the format host/CIDR mask
IPv4 Network End Address | string | only available in Advanced Mode; enter the last IP address in the reserved range in the format host/CIDR mask
IPv6 Autoconfigure | checkbox | check this box if the network has a DHCPv6 server and IPv6 will be used to access jails
IPv6 Network | string | only available in Advanced Mode; enter the network address for a properly configured IPv6 network
IPv6 Network Start Address | string | only available in Advanced Mode; enter the first IP address in the reserved range for a properly configured IPv6 network
IPv6 Network End Address | string | only available in Advanced Mode; enter the last IP address in the reserved range for a properly configured IPv6 network
Collection URL | string | only available in Advanced Mode; changing the default may break the ability to install jails

When selecting the Jail Root, ensure that the size of the selected volume or dataset is sufficient to hold the number of jails to be installed as well as any software, log files, and data to be stored within each jail. At a bare minimum, budget at least 2 GB per jail and do not select a dataset that is less than 2 GB in size.

Note

If you plan to add storage to a jail, be aware that the path size is limited to 88 characters. Make sure that the length of the volume name plus the dataset name plus the jail name does not exceed this limit.

If the network contains a DHCP server, it is recommended to check the box IPv4 DHCP (or IPv6 Autoconfigure, for a properly configured IPv6 network). This will prevent IP address conflicts on the network as the DHCP server will automatically assign the jail the next available lease and record the lease as in use.

If a static IP address is needed so that users always know the IP address of the jail, enter the start and end address for the IPv4 and/or IPv6 network. The range defined by the start and end addresses will be automatically assigned as jails are created. For example, if you plan to create 5 jails on the 192.168.1.0 network, enter a IPv4 Network Start Address of 192.168.1.100 and a IPv4 Network End Address of 192.168.1.104.

If you create a start and end range on a network that contains a DHCP server, it is very important that you also reserve those addresses on the DHCP server. Otherwise, the DHCP server will not be aware that those addresses are being used by jails and there will be IP address conflicts and weird networking errors on the network. When troubleshooting jails that do not install or which are unavailable, double-check that the IP address being used by the jail is not also being used by another jail or system in the network.

FreeNAS® will automatically detect and display the IPv4 Network to which the administrative interface is connected. This setting is important. The IP addresses used by the jails must be pingable from the FreeNAS® system for the jails and any installed software to be accessible. If the network topology requires changing the default value, a default gateway and possibly a static route need to be added to the specified network. After changing this value, ensure that the subnet mask value is correct, as an incorrect mask can make the IP network unreachable. When in doubt, keep the default setting for IPv4 Network. With VMware, make sure that the vswitch is set to “promiscuous mode”.

After clicking the Save button to save the configuration, the system is ready to create and manage jails as described in the rest of this chapter.

## 13.2. Adding Jails

To create a jail, click `Jails → Add Jail` to access the screen shown in Figure 13.2.1.

Note

the Add Jail menu item will not appear until after you configure `Jails → Configuration`.

Fig. 13.2.1 Creating a Jail

By default, the only required value to create a jail is a name. FreeBSD jails are created by default.

Table 13.2.1 summarizes the available options. Most settings are only available in Advanced Mode and are not needed if the intent is to create a FreeBSD jail. To see these settings, either click the Advanced Mode button or configure the system to always display these settings by checking the box Show advanced fields by default in `System → Advanced`.

Table 13.2.1 Jail Configuration Options
Setting | Value | Description
--- | --- | ---
Jail Name | string | mandatory; can only contain letters, numbers, dashes, or the underscore character
Template | drop-down menu | only available in Advanced Mode; contains the VirtualBox template for creating an instance of phpVirtualBox; advanced users can create and install custom templates as described in Managing Jail Templates
IPv4 DHCP | checkbox | only available in Advanced Mode; if unchecked, make sure that the defined address does not conflict with the DHCP server’s pool of available addresses
IPv4 address | integer | only available in Advanced Mode; this and the other IPv4 settings will be grayed out if IPv4 DHCP is checked; input IP address that is reachable within the local network and is not in use by any other host in the network
IPv4 netmask | drop-down menu | only available in Advanced Mode; select the subnet mask associated with IPv4 address
IPv4 bridge address | integer | only available in Advanced Mode and will be grayed out if VIMAGE is unchecked; see NOTE below
IPv4 bridge netmask | drop-down menu | only available in Advanced Mode; select the subnet mask associated with IPv4 bridge address; will begrayed out if VIMAGE is unchecked
IPv4 default gateway | string | only available in Advanced Mode; will be grayed out if VIMAGE is unchecked
IPv6 Autoconfigure | checkbox | only available in Advanced Mode; if unchecked, make sure that the defined address does not conflict with the DHCP server’s pool of available addresses
IPv6 address | integer | only available in Advanced Mode; this and the other IPv6 settings will be grayed out if IPv6 Autoconfigure is checked; input IPv6 address that is reachable within the local network and is not in use by any other host in the network
IPv6 prefix length | drop-down menu | only available in Advanced Mode; select the prefix length associated with IPv6 address
IPv6 bridge address | integer | only available in Advanced Mode and will be grayed out if VIMAGE is unchecked; see NOTE below
IPv6 bridge prefix length | drop-down menu | only available in Advanced Mode and will be grayed out if VIMAGE is unchecked; select the prefix length associated with IPv6 address
IPv6 default gateway | string | only available in Advanced Mode and will be grayed out if VIMAGE is unchecked; used to set the jail’s default gateway IPv6 address
MAC | string | only available in Advanced Mode and will be grayed out if VIMAGE is unchecked; if a static MAC address is entered, unique static MAC addresses must be entered for every jail created
NIC | drop-down menu | only available in Advanced Mode and will be grayed out if VIMAGE is checked; can be used to specify the interface to use for jail connections
Sysctls | string | only available in Advanced Mode; comma-delimited list of sysctls to set inside jail (e.g. allow.sysvipc=1,allow.raw_sockets=1)
Autostart | checkbox | only available in Advanced Mode; uncheck if the jail will be started manually
VIMAGE | checkbox | only available in Advanced Mode; gives a jail its own virtualized network stack; requires promiscuous mode to be enabled on the interface
NAT | checkbox | only available in Advanced Mode and will be grayed out for Linux jails or if VIMAGE is unchecked; enables Network Address Translation for the jail

Note

The IPv4 and IPv6 bridge interface is used to bridge the epair(4) device, which is automatically created for each started jail, to a physical network device. The default network device is the one that is configured with a default gateway. So, if em0 is the FreeBSD name of the physical interface and three jails are running, these virtual interfaces are automatically created: bridge0, epair0a, epair1a, and epair2a. The physical interface em0 will be added to the bridge, as well as each epair device. The other half of the epair will be placed inside the jail and will be assigned the IP address specified for that jail. The bridge interface will be assigned an alias of the default gateway for that jail, if configured, or the bridge IP, if configured; either is correct.

The only time an IP address and mask are required for the bridge is when the jail will be on a different network than the FreeNAS® system. For example, if the FreeNAS® system is on the 10.0.0.0/24 network and the jail will be on the 192.168.0.0/24 network, set the IPv4 bridge address and IPv4 bridge netmask fields for the jail.

If both the VIMAGE and NAT boxes are unchecked, the jail must be configured with an IP address within the same network as the interface it is bound to, and that address will be assigned as an alias on that interface. To use a VIMAGE jail on the same subnet, uncheck NAT and configure an IP address within the same network. In both of these cases, configure only an IP address and do not configure a bridge or a gateway address.

After making selections, click the OK button. The jail is created and added to the Jails tab as well as in the tree menu under Jails. Jails start automatically. To prevent this, uncheck the Autostart box.

The first time a jail is added or used as a template, the GUI automatically downloads the necessary components from the internet. A progress bar indicates the status of the download and provides an estimated time for the process to complete. If it is unable to connect to the internet, jail creation fails.

Warning

Failure to download is often caused by the default gateway not being set, preventing internet access. See the Network Global Configuration section for information on setting the default gateway.

After the first jail is created or a template has been used, subsequent jails will be added very quickly because the downloaded base for creating the jail has been saved to the Jail Root.

### 13.2.1. Managing Jails

Click Jails to view and configure the added jails. In the example shown in Figure 13.2.2, the list entry for the jail named xdm_1 has been clicked to enable that jail’s configuration options. The entry indicates the jail name, IP address, whether it will start automatically at system boot, if it is currently running, and jail type: standard for a FreeBSD jail, or pluginjail if it was installed using Plugins.

Fig. 13.2.2 Viewing Jails

From left to right, these configuration icons are available:

Edit Jail: edit the jail settings which were described in Table 13.2.1.

After a jail has been created, the jail name and type cannot be changed, so these fields will be grayed out.

Note

To modify the IP address information for a jail, use the Edit Jail button instead of the associated networking commands from the command line of the jail.

Add Storage: configure the jail to access an area of storage as described in Add Storage.

Upload Plugin: manually upload a plugin previously downloaded from the plugins repository.

Start/Stop: this icon changes appearance depending on the current Status of the jail. When the jail is not running, the icon is green and clicking it starts the jail. When the jail is already running, the icon is red and clicking it stops the jail. A stopped jail and its applications are inaccessible until it is restarted.

Restart: restart the jail.

Shell: access a root command prompt to configure the selected jail from the command line. When finished, type exit to close the shell.

Delete: delete the jail and any periodic snapshots of it. The contents of the jail are entirely removed.

> Warning

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

#### 13.2.1.1. Accessing a Jail Using SSH

ssh can be used to access a jail instead of the jail’s Shell icon. This requires starting the ssh service and creating a user account for ssh access. Start by clicking the Shell icon for the desired jail.

To start the SSH service, look for this line in the jail’s `/etc/rc.conf`:

    sshd_enable="NO"

Change the NO to YES and save the file. Then start the SSH daemon:

    service sshd start

The jail’s RSA key pair will be generated and the key fingerprint and random art image displayed.

Add a user account by typing adduser and following the prompts. If the user needs superuser privileges, they must be added to the wheel group. For those users, enter wheel at this prompt:

> Login group is user1. Invite user1 into other groups? []: wheel

After creating the user, set the root password so that the new user will be able to use the su command to gain superuser privilege. To set the password, type passwd then enter and confirm the desired password.

Finally, test from another system that the user can successfully ssh in and become the superuser. In this example, a user named user1 uses ssh to access the jail at 192.168.2.3. The first time the user logs in, they will be asked to verify the fingerprint of the host:

    ssh user1@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: type_password_here

Note

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

#### 13.2.1.2. Add Storage

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

To add storage, click the Add Storage button for a highlighted jail’s entry to open the screen shown in Figure 13.2.3. This screen can also be accessed by expanding the jail name in the tree view and clicking `Storage → Add Storage`.

Fig. 13.2.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 volume 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 check the Create directory box.

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.

So 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.
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 whether the jail should 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 volume 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 Add Storage button of the jail and select the configured volume/dataset as the Source.

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

By default, the Create directory box is checked. This means that the directory will automatically be created under the specified Destination path if the directory does not already exist.

After storage has been added or created, it appears in the tree under the specified jail. In the example shown in Figure 13.2.4, a dataset named `volume1/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 `volume1/jails/freebsd1/usr/local` in the Destination field, then entered test as the directory. Since this directory did not already exist, it was created, because the Create directory box was left checked. The resulting 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.2.4 Example Storage

Storage is normally mounted as it is created. To unmount the storage, uncheck the Mounted? box.

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.2.2. 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.2.3. 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.2.5 shows the Configuration Options for audiotag.

Fig. 13.2.5 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 yourself, 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.2.6 is displayed:

Fig. 13.2.6 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.2.4. Starting Installed Software

After packages or ports are installed, they need to be configured and started. If you are 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 you are unfamiliar with the software, you will need to spend some time at the software’s website 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.3. Using the phpVirtualBox Template

If software requires a different operating system or a non-FreeBSD operating system is needed to manage software, use the VirtualBox template to create an instance of phpVirtualBox. In the Add Jail screen, click the Advanced Mode button. As shown in the example in Figure 13.3.1, enter a Jail Name, verify that the IPv4 address is valid and not in use by another host or jail, and select VirtualBox from the Template drop-down menu. Press the OK button to begin the installation.

Fig. 13.3.1 Creating a phpVirtualBox Instance

After installation, enter the IP address of the VirtualBox jail into a web browser and enter the username and password admin into the login screen. After authentication, the screen shown in Figure 13.3.2 appears in the web browser.

Fig. 13.3.2 phpVirtualBox Interface

Click the New button to create virtual machines. The desired operating systems and software can then be installed into the new virtual machines.

Note

By default, virtual machines are not started when the FreeNAS® system boots. To configure auto-start, refer to this forum post.

## 13.4. Managing Jail Templates

FreeNAS® supports the ability to add custom templates to the Templates drop-down menu described in Table 13.2.1.

By default, FreeNAS® provides the VirtualBox template. To view the default and any customized templates, click `Jails → Templates`. A listing showing the default template is seen in Figure 13.4.1.

Fig. 13.4.1 Default Jail Templates

The listing contains these columns:

- Name: appears in the Template drop-down menu when adding a new jail.
- URL: when adding a new jail using this template, the template is downloaded from this location.
- Instances: indicates if the template has been used to create a jail. In this example, the template has not yet been used so its Instances shows 0.

To create a custom template, first install the desired operating system and configure it as needed. The installation can be either to an existing jail or on another system.

Next, create an mtree specification using this command, replacing /path/to/jail with the actual path to the jail:

    mtree -c -p /path/to/jail -k sha256digest > file.mtree

After configuration is complete, create a tarball of the entire operating system to be used as a template. This tarball needs to be compressed with gzip and end in a `.tgz` extension. Be careful when creating the tarball as it is possible to end up in a recursive loop. In other words, the resulting tarball must be saved outside of the operating system being tarballed, such as to an external USB drive or network share. Alternately, create a temporary directory within the operating system and use the –exclude switch to tar to exclude this directory from the tarball. The exact tar command to use will vary, depending upon the operating system being used to create the tarball.

Save the generated `.mtree` and `.tgz` files to either an FTP share or an HTTP server. The FTP or HTTP URL is needed to add the template to the list of available templates.

To add the template, click `Jails → Templates → Add Jail Templates` which opens the screen shown in Figure 13.4.2.

Fig. 13.4.2 Adding A Custom Jail Template

Table 13.4.1 summarizes the fields in this screen.

Table 13.4.1 Jail Template Options
Setting | Value | Description
--- | --- | ---
Name | string | value appears in the Name column of View Jail Templates
OS | drop-down menu | choices are FreeBSD or Linux
Architecture | drop-down menu | choices are x86 (32-bit) or x64 (64-bit)
URL | string | enter the full URL to the `.tgz` file, including the protocol (ftp:// or or http://)
Mtree | string | paste the mtree specification for the template
Read-only | checkbox | when checked, the Name and URL of the template cannot be changed after creation

After adding a template, click the entry for the template to access the Edit and Delete buttons. Clicking a template’s Edit button opens the configuration screen shown in Figure 13.4.3.

Note

The Delete button is not available for the built-in VirtualBox template and the Edit button opens it as read-only.

Fig. 13.4.3 Editing Template Options

Clicking a template’s Delete button shows a warning message that prompts for confirmation of the deletion. Note that once a template is deleted, it is removed from the Templates drop-down menu and will no longer be available for creating new jails.

## 13.5. Using iohyve

Beginning with FreeNAS® 9.3.1, the iohyve command line utility is included for creating, managing, and launching bhyve guests.

Note

This type of virtualization requires an Intel processor with Extended Page Tables (EPT) or an AMD processor with Rapid Virtualization Indexing (RVI) or Nested Page Tables (NPT).

To verify that an Intel processor has the required features, use Shell to run grep VT-x /var/run/dmesg.boot. If the EPT and UG features are shown, this processor can be used with bhyve and iohyve.

To verify that an AMD processor has the required features, use Shell to run grep POPCNT /var/run/dmesg.boot. If the output shows the POPCNT feature, this processor can be used with bhyve and iohyve.

Run this command to initialize iohyve, substituting the name of the pool to hold the bhyve guests and the name of the network interface:

    iohyve setup pool=volume1 kmod=1 net=em0
    Setting up iohyve pool...
    Loading kernel modules...
    Setting up bridge0 on em0...
    net.link.tap.up_onopen: 0 -> 1

    ln -s /mnt/iohyve /iohyve

The next step is to tell iohyve which installation ISO to download. This example shows fetching the 64-bit version of FreeBSD 10.3, then verify that the fetch was successful:

    iohyve fetch ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/amd64/ISO-IMAGES/10.3/FreeBSD-10.3-RELEASE-amd64-bootonly.iso
    Fetching ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/amd64/ISO-IMAGES/10.3/FreeBSD-10.3-RELEASE-amd64-bootonly.iso...
    /iohyve/ISO/FreeBSD-10.3-RELEASE-amd64-bootonly.iso 100% of 232 MB 2443 kBps 01m38s

    iohyve isolist
    Listing ISO's...
    FreeBSD-10.3-RELEASE-amd64-bootonly.iso

Specify the name and size of the guest to create it and verify its status:

    iohyve create freebsd10.3 8G
    Creating freebsd10.3...

    iohyve list
    Guest          VMM?    Running?        rcboot?         Description
    freebsd10.3    NO      NO              NO              Thu_Mar_24_09:37:30_PDT_2016

The newly created guest is not yet running, nor is it set to automatically start (rcboot) when iohyve starts.

Install a guest using a specified ISO:

    iohyve install freebsd10.3 FreeBSD-10.3-RELEASE-amd64-bootonly.iso
    Installing freebsd10.3...

More information on iohyve:

> - Forum post on iohyve
> - Running virtual machines using iohyve on FreeNAS® 9.10