Setting up Services in a FreeNAS Jail

This piece demonstrates the setup of a server service in a FreeNAS jail and how to share files with a jail using Apache 2.4 as an example. Jails are powerful, self-contained FreeBSD environments with separate network settings, package management, and access to thousands of FreeBSD application packages. Popular packages such as Apache, NGINX, LigHTTPD, MySQL, and PHP can be found and installed with the pkg search and pkg install commands. 

This example shows creating a jail, installing an Apache web server, and setting up a simple web page. 

NOTE: Do not directly attach FreeNAS to an external network (WAN). Use port forwarding, proper firewalls and DDoS protections when using FreeNAS for external web sites. This example demonstrates expanding the functionality of FreeNAS in an isolated LAN environment.

Jail and service setup

In the FreeNAS web interface, go to Jails on the sidebar. Click ADD. Click DHCP for most home networks, though a static IP address can also be assigned. In advanced settings, set the Auto-start checkbox to automatically start the jail after booting FreeNAS.

To start the jail manually, click the jail options menu (three dots icon) and click Start. After the jail starts and status is up, open the jail options again and click Shell to open a terminal to the jail.

Jails have a unique IP address shown in the web interface. The default DHCP setting dynamically obtains an IP address. Type ifconfig to see jail network information in the terminal.

TIP: For networks without DHCP support, a static IP address can be set in the advanced settings menu. 

On first start, pkg will ask to run pkg update to gather the latest list of packages available to search through and install.

Type pkg install apache24 in the terminal to download and install Apache web server. Start the web server by typing service apache24 onestart. To have Apache start each time the jail is started edit /etc/rc.conf and add apache24_enable=”YES” at the bottom. Then type service apache24 start.

Open a new browser tab and enter the jail IP address. 

Sharing and editing files with the jail

For security reasons, jails are restricted in what access they have by default, but there are several ways to share files to the jail. This section will cover three methods: share a folder in the jail using a NAS share, mount a dataset to the jail, and using FTP/SFTP to download files.

Method 1: Share the jail service’s folder

This method is complicated to set up, but the easiest to use in practice, allowing a webadmin or designer direct access to the Apache service from their client computer or workstation.

Go to Accounts -> Users and create a new user in FreeNAS, could be webadmin or anything, and set their home directory to the folder in the jail. Because Apache 2.4 serves files from /usr/local/www/apache24/data, this example will refer to that.

Go to Sharing in the FreeNAS web interface and choose the desired protocol — SMB, NFS, or AFP.  For the most platform compatibility SMB is likely the best choice as it works with Windows, Linux, and macOS. Click on the iocage dataset, then jails, then the name of the desired jail and select the exact folder to share. In Apache 2.4, web files are served from the /usr/local/www/apache24/data directory. Ensure the user of the share is the same as that just created in FreeNAS.

Start the jail and open the Shell. Add a user using the adduser command. Ensure all credentials are the same as the user just created in the FreeNAS UI including the home folder. Also, ensure the group is set to www the same as Apache 2.4 uses.

On a Windows client, open the Explorer and search for the SMB share created by typing \\<Physical FreeNAS IP or DNS name>\<share name>, for example \\\WebServer. Enter the user name and password for the account created in FreeNAS.

Copy, create, or edit the files directly from your client device.

If you have any trouble editing or saving changes on the files, it could be due to permissions on the folder itself in the jail. These can be adjusted using the chmod(1) command in the jail. More details can be found here. For Apache 2.4, chmod -R 754 /usr/local/www/apache24/data should be the correct level of permission.

Method 2: Mounting a dataset to the jail

Begin by turning off the jail. Click the three dot menu on the right hand side of the jail menu and select Mount points from the options.

Click Actions -> Add Mount Point. In the web interface, select the source dataset path and the folder in the jail as the mount point. The option Read-Only is useful for jails designed just to show information and not alter data on the host.

NOTE: Unless mounted as a read only file system, mounting a directory to a jail changes the permissions of all files in the directory to those of the jail. A separate directory should be mounted to the jail to ensure other files within the file share are not affected. Create a ‘mount’ or ‘publish’ folder within an existing SMB or NFS dataset and only mount that specific directory to the jail. For example, if /mnt/Storage/NFS was the NFS shared dataset, create a sub-directory /mnt/Storage/NFS/publish and just mount that directory to the jail. Doing so avoids files not associated with the jail having their permissions changed, and you can copy only those files ready to be shared to the jail.

Start the jail, open the Shell, locate the mount point directory and type ls to see the files. Files in the directory can then be copied to the Apache 2.4 source directory which by default is /usr/local/www/apache24/data/.

Method 3: Use FTP/SFTP from the jail shell

The FTP/SFTP client in a jail can access the FTP service on FreeNAS to transfer files. Share files from a PC or workstation to FreeNAS, then transfer to the jail with this FTP command below. For better security, using an encrypted FTP or SFTP connection is recommended. FTP also avoids the permission issue that mounting the directory can cause, though requires more command line use.

Go to the Apache default web file location with cd /usr/local/www/apache24/data/. Log into the FTP server with the FreeNAS IP address:

Type mget *html and press a to copy all the html files to the jail. Use get [remotefile] [localfile] to copy individual files.

Viewing your website

Once the web files are available in the Apache 2.4 source directory, change the existing index.html file to a desired homepage using the mv command. 

Open the jail’s IP address or domain name in a browser to view the updates.

Source: W3 Schools template –

Your website is now active on your network, and protected with the same ultra-reliable ZFS file system as file shares on your FreeNAS. Using the ZFS features of FreeNAS, you can regularly snapshot, clone, or replicate the webserver jail or any other service you choose to run.

One More TIP: For users familiar with Ubuntu and many Linux distros, FreeBSD also has a Nano text editor. If unfamiliar with Vi, you can install Nano using pkg install nano-3.2, and edit text files the same way as in Ubuntu by typing nano <file to edit>.


  1. Michael Cole

    I am following your example fairly well. However, I am having an issue with permissions. I was able to install apache24 to the jail, start it and find it with the browser. I can see the SMB share but I do not have permission to open the folder.
    The user is webadmin, group is www.
    Using Windows 10 and freenas11.3.
    What can I read or view to get some more ideas?

    • Michael Cole

      Jun 28, 2019 | Blog, FreeNAS |
      Not sure if you need this information regarding the blog to which I am commenting.


Submit a Comment

Your email address will not be published. Required fields are marked *

ESG Labs: TrueNAS Technical Report
Download Enterprise Storage Guide Button
iXsystems values privacy for all visitors. Learn more about how we use cookies and how you can control them by reading our Privacy Policy.