FreeNAS® is © 2011-2017 iXsystems

FreeNAS® and the FreeNAS® logo are registered trademarks of iXsystems

FreeBSD® is a registered trademark of the FreeBSD Foundation

Written by users of the FreeNAS® network-attached storage operating system.

Version 11.0

Copyright © 2011-2017 iXsystems

This Guide covers the installation and use of FreeNAS® 11.0.

The FreeNAS® User Guide is a work in progress and relies on the contributions of many individuals. If you are interested in helping us to improve the Guide, read the instructions in the README. IRC Freenode users are welcome to join the #freenas channel where you will find other FreeNAS® users.

The FreeNAS® User Guide is freely available for sharing and redistribution under the terms of the Creative Commons Attribution License. This means that you have permission to copy, distribute, translate, and adapt the work as long as you attribute iXsystems as the original source of the Guide.

FreeNAS® and the FreeNAS® logo are registered trademarks of iXsystems.

Active Directory® is a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries.

Apple, Mac and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries.

Avago is a trademark of Avago Technologies.

Broadcom is a trademark of Broadcom Corporation.

Chelsio® is a registered trademark of Chelsio Communications.

Cisco® is a registered trademark or trademark of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries.

Django® is a registered trademark of Django Software Foundation.

Facebook® is a registered trademark of Facebook Inc.

FreeBSD® and the FreeBSD® logo are registered trademarks of the FreeBSD Foundation®.

Fusion-io is a trademark or registered trademark of Fusion-io, Inc.

Intel, the Intel logo, Pentium Inside, and Pentium are trademarks of Intel Corporation in the U.S. and/or other countries.

LinkedIn® is a registered trademark of LinkedIn Corporation.

Linux® is a registered trademark of Linus Torvalds.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates.

Twitter is a trademark of Twitter, Inc. in the United States and other countries.

UNIX® is a registered trademark of The Open Group.

VirtualBox® is a registered trademark of Oracle.

VMware® is a registered trademark of VMware, Inc.

Wikipedia® is a registered trademark of the Wikimedia Foundation, Inc., a non-profit organization.

Windows® is a registered trademark of Microsoft Corporation in the United States and other countries.

Typographic Conventions

The FreeNAS® 11.0 User Guide uses these typographic conventions:

Table 1 Text Format Examples
Item Visual Example
Graphical elements: buttons, icons, fields, columns, and boxes Click the Import CA button.
Menu selections Select System Information.
Commands Use the scp command.
File names and volume and dataset names Locate the /etc/rc.conf file.
Keyboard keys Press the Enter key.
Important points This is important.
Values entered into fields, or device names Enter in the address field.

1. Introduction

FreeNAS® is an embedded open source network-attached storage (NAS) operating system based on FreeBSD and released under a 2-clause BSD license. A NAS has an operating system optimized for file storage and sharing.

FreeNAS® provides a browser-based, graphical configuration interface. The built-in networking protocols provide storage access to multiple operating systems. A plugin system is provided for extending the built-in features by installing additional software.

1.1. New Features in 11.0

  • The base operating system has been updated to FreeBSD 11-STABLE. This brings in many significant features, including important speed improvements for 40/100GigE networking.
  • An updated version of ZFS includes new pool Feature Flags, the skein and SHA512 hash functions.
  • The Ports version of SSH has been updated to 7.4p1 to address CVE-2016-10012. Please use the /usr/local/bin/ssh and /usr/local/bin/sshd binaries.
  • Python has been updated to version 3.6.1.
  • The sas3flash firmware upgrade tool for LSI/Avago/Broadcom 9305-8i, 9305-16i, and 9305-24i host adapters has been updated to the latest version.
  • The Zerotier distributed network hypervisor has been added.
  • The mrsas(4) driver is loaded by default for the Dell PERC H330, Dell PERC H730, and other controllers which are supported by both the mrsas(4) and mfi(4) drivers.
  • Drivers for PMC Adaptec host bus adapters have been added with the pmspcv(4) driver.
  • The installer can now be run through a serial port for systems without directly-connected keyboards or monitors.
  • The login dialog now has a link to try a preliminary version of the new Angular-based GUI. Click on Demo our upcoming UI! to try it.
  • An option to save the encryption seed has been added to the System Save Config button.
  • Email notices about available updates are only sent once instead of once per day.
  • A new Alert Services section in System Alert Services makes it possible to send important alerts through external services, including AWS-SNS, Hipchat, InfluxDB, Slack, Mattermost, OpsGenie, PagerDuty, and VictorOps.
  • Encrypted volumes now use the AES-256 cipher.
  • An experimental Active Directory Enable Monitoring option has been added. When enabled, this restarts the Active Directory service after a temporary loss of communications with an Active Directory server. Previously, a loss of communications with the AD server would stop the Active Directory service, requiring a manual restart. At present, this experimental feature is recommended only for testing in non-production environments. Please submit bug reports at if any problems are encountered.
  • An enhanced Services screen adds a checkbox to directly set which services start at boot.
  • Plugin and jail templates have been updated to address CVE-2016-2107.
  • A new VMs (Virtual Machines) feature has been added. Based on bhyve(8), it offers support for BSDs (FreeBSD, OpenBSD, NetBSD), Linux (including CentOS, Debian, Fedora, OpenSUSE, Ubuntu), SmartOS, Windows, and Windows Server. Future versions will include additional features like VM templates, hardware pass-through, and UEFI screen resolution adjustment.
  • Netatalk has been updated to version 3.1.11.
  • Samba has been updated to version 4.6.5.
  • The new S3 service has been added, allowing the FreeNAS® system to provide S3 file sharing.
  • The Mosh mobile shell has been added.
  • Pipe Viewer, a utility for monitoring the progress of data through a pipeline, has been added. This can be useful for monitoring zfs send | zfs recv commands.
  • The Unison file synchronization tool has been added.
  • The Alert about mismatching driver and firmware versions for Avago disk controllers has been removed as unnecessary. Driver and firmware versions no longer correspond.

1.2. Changes Since 11.0

FreeNAS® uses a “rolling release” model instead of point releases. The Update mechanism makes it easy to keep up-to-date with the latest security fixes, bug fixes, and new features. Some updates affect the user interface, so this section lists any functional changes that have occurred since 11.0 was released.


The screenshots in this documentation assume that the system has been fully updated to the latest STABLE version of FreeNAS® 11.0-U4. If a screen on the system is not the same as shown in this guide, make sure that all updates have been applied.

1.2.1. U1

  • The Read only checkbox has been removed from Jails Templates Add Jail Templates.
  • The NT4 option has been removed from Directory Services as it is no longer supported by Samba.

1.2.2. U2

1.2.3. U3

  • The boot volume Automatic scrub interval has been changed to 7 days for earlier detection of problems with boot devices.

1.2.4. U4

1.3. Path and Name Lengths

Names of files, directories, and devices are subject to some limits imposed by the FreeBSD operating system. The limits shown here are for names using plain-text characters that each occupy one byte of space. Some UTF-8 characters take more than a single byte of space, and using those characters reduces these limits proportionally. System overhead can also reduce the length of these limits by one or more bytes.

Table 1.3.1 Path and Name Lengths
Type Maximum Length Description
File Paths 1024 bytes

Total file path length (PATH_MAX). The full path includes directory separator slash characters, subdirectory names, and the name of the file itself. For example, the path /mnt/tank/mydataset/mydirectory/myfile.txt is 42 bytes long.

Using very long file or directory names can be problematic. A complete path with long directory and file names can exceed the 1024-byte limit, preventing direct access to that file until the directory names or filename are shortened or the file is moved into a directory with a shorter total path length.

File and Directory Names 255 bytes Individual directory or file name length (NAME_MAX).
Mounted Filesystem Paths 88 bytes Mounted filesystem path length (MNAMELEN). Longer paths can prevent a device from being mounted.
Device Filesystem Paths 63 bytes devfs(8) device path lengths (SPECNAMELEN). Longer paths can prevent a device from being created.

1.4. Hardware Recommendations

FreeNAS® 11.0 is based on FreeBSD 11 and supports the same hardware found in the FreeBSD Hardware Compatibility List. Supported processors are listed in section 2.1 amd64. FreeNAS® is only available for 64-bit processors. This architecture is called amd64 by AMD and Intel 64 by Intel.


FreeNAS® boots from a GPT partition. This means that the system BIOS must be able to boot using either the legacy BIOS firmware interface or EFI.

Actual hardware requirements vary depending on the usage of the FreeNAS® system. This section provides some starter guidelines. The FreeNAS® Hardware Forum has performance tips from FreeNAS® users and is a place to post questions regarding the hardware best suited to meet specific requirements. Hardware Recommendations gives detailed recommendations for system components, with the FreeNAS® Quick Hardware Guide providing short lists of components for various configurations. Building, Burn-In, and Testing your FreeNAS® system has detailed instructions on testing new hardware.

1.4.1. RAM

The best way to get the most out of a FreeNAS® system is to install as much RAM as possible. The recommended minimum is 8 GB of RAM. The more RAM, the better the performance, and the FreeNAS® Forums provide anecdotal evidence from users on how much performance is gained by adding more RAM.

Depending upon the use case, your system may require more RAM. Here are some general rules of thumb:

  • To use Active Directory with many users, add an additional 2 GB of RAM for winbind’s internal cache.
  • For iSCSI, install at least 16 GB of RAM if performance is not critical, or at least 32 GB of RAM if good performance is a requirement.
  • When installing FreeNAS® on a headless system, disable the shared memory settings for the video card in the BIOS.
  • To use ZFS deduplication, ensure the system has at least 5 GB of RAM per TB of storage to be deduplicated.

If the hardware supports it and the budget allows for it, install ECC RAM. While more expensive, ECC RAM is highly recommended as it prevents in-flight corruption of data before the error-correcting properties of ZFS come into play, thus providing consistency for the checksumming and parity calculations performed by ZFS. If you consider your data important, use ECC RAM. This Case Study describes the risks associated with memory corruption.

Unless the system has at least 8 GB of RAM, consider adding RAM before using FreeNAS® to store data. Many users expect FreeNAS® to function with less memory, just at reduced performance. The bottom line is that these minimums are based on feedback from many users. Requests for help in the forums or IRC are sometimes ignored when the installed system does not have at least 8 GB of RAM because of the abundance of information that FreeNAS® may not behave properly with less memory.

1.4.2. The Operating System Device

The FreeNAS® operating system is installed to at least one device that is separate from the storage disks. The device can be a USB stick, SSD, compact flash, or DOM (Disk on Module). Installation to a hard drive is discouraged as that drive is then not available for data storage.


To write the installation file to a USB stick, two USB ports are needed, each with an inserted USB device. One USB stick contains the installer. The other USB stick is the destination for the FreeNAS® installation. Take care to select the correct USB device for the FreeNAS® installation. It is not possible to install FreeNAS® onto the same USB stick containing the installer. After installation, remove the installer USB stick. It might also be necessary to adjust the BIOS configuration to boot from the new FreeNAS® USB stick.

When determining the type and size of the target device where FreeNAS® will be installed, keep these points in mind:

  • the bare minimum size is 8 GB. This provides room for the operating system and several boot environments. Since each update creates a boot environment, this is the recommended minimum. 32 GB provides room for more boot environments.
  • if you plan to make your own boot environments, budget about 1 GB of storage per boot environment. Consider deleting older boot environments after making sure they are no longer needed. Boot environments can be created and deleted using System Boot.
  • use quality, name-brand USB sticks, as ZFS will quickly reveal errors on cheap, poorly-made sticks.
  • for a more reliable boot disk, use two identical devices and select them both during the installation. This will create a mirrored boot device.

1.4.3. Storage Disks and Controllers

The Disk section of the FreeBSD Hardware List lists the supported disk controllers. In addition, support for 3ware 6 Gbps RAID controllers has been added along with the CLI utility tw_cli for managing 3ware RAID controllers.

FreeNAS® supports hot pluggable drives. Using this feature requires enabling AHCI in the BIOS.

Reliable disk alerting and immediate reporting of a failed drive can be obtained by using an HBA such as an Avago MegaRAID controller or a 3Ware twa-compatible controller.


Upgrading the firmware of Avago SAS HBAs to the latest version is recommended.

Some Highpoint RAID controllers do not support pass-through of S.M.A.R.T. data or other disk information, potentially including disk serial numbers. It is best to use a different disk controller with FreeNAS®.


The system is configured to prefer the mrsas(4) driver for controller cards like the Dell PERC H330 and H730 which are supported by several drivers. Although not recommended, the mfi(4) driver can be used instead by removing the loader Tunable: hw.mfi.mrsas_enable or setting the Value to 0.

Suggestions for testing disks before adding them to a RAID array can be found in this forum post. Additionally, badblocks is installed with FreeNAS® for testing disks.

If the budget allows optimization of the disk subsystem, consider the read/write needs and RAID requirements:

  • For steady, non-contiguous writes, use disks with low seek times. Examples are 10K or 15K SAS drives which cost about $1/GB. An example configuration would be six 600 GB 15K SAS drives in a RAID 10 which would yield 1.8 TB of usable space, or eight 600 GB 15K SAS drives in a RAID 10 which would yield 2.4 TB of usable space.

When high performance is a key requirement and budget permits, consider a Fusion-I/O card which is optimized for massive random access. These cards are expensive and are suited for high-end systems that demand performance. A Fusion-I/O card can be formatted with a filesystem and used as direct storage; when used this way, it does not have the write issues typically associated with a flash device. A Fusion-I/O card can also be used as a cache device when your ZFS dataset size is bigger than your RAM. Due to the increased throughput, systems running these cards typically use multiple 10 GigE network interfaces.

For ZFS, Disk Space Requirements for ZFS Storage Pools recommends a minimum of 16 GB of disk space. Due to the way that ZFS creates swap, it is not possible to format less than 3 GB of space with ZFS. However, on a drive that is below the minimum recommended size, a fair amount of storage space is lost to swap: for example, on a 4 GB drive, 2 GB will be reserved for swap.

Users new to ZFS who are purchasing hardware should read through ZFS Storage Pools Recommendations first.

ZFS vdevs, groups of disks that act like a single device, can be created using disks of different sizes. However, the capacity available on each disk is limited to the same capacity as the smallest disk in the group. For example, a vdev with one 2 TB and two 4 TB disks will only be able to use 2 TB of space on each disk. In general, use disks that are the same size for the best space usage and performance.

The ZFS Drive Size and Cost Comparison spreadsheet is available to compare usable space provided by different quantities and sizes of disks.

1.4.4. Network Interfaces

The Ethernet section of the FreeBSD Hardware Notes indicates which interfaces are supported by each driver. While many interfaces are supported, FreeNAS® users have seen the best performance from Intel and Chelsio interfaces, so consider these brands when purchasing a new NIC. Realtek cards often perform poorly under CPU load as interfaces with these chipsets do not provide their own processors.

At a minimum, a GigE interface is recommended. While GigE interfaces and switches are affordable for home use, modern disks can easily saturate their 110 MB/s throughput. For higher network throughput, multiple GigE cards can be bonded together using the LACP type of Link Aggregations. The Ethernet switch must support LACP, which means a more expensive managed switch is required.

When network performance is a requirement and there is some money to spend, use 10 GigE interfaces and a managed switch. Managed switches with support for LACP and jumbo frames are preferred, as both can be used to increase network throughput. Refer to the 10 Gig Networking Primer for more information.


At present, these are not supported: InfiniBand, FibreChannel over Ethernet, or wireless interfaces.

Both hardware and the type of shares can affect network performance. On the same hardware, SMB is slower than FTP or NFS because Samba is single-threaded. So a fast CPU can help with SMB performance.

Wake on LAN (WOL) support depends on the FreeBSD driver for the interface. If the driver supports WOL, it can be enabled using ifconfig(8). To determine if WOL is supported on a particular interface, use the interface name with the following command. In this example, the capabilities line indicates that WOL is supported for the re0 interface:

ifconfig -m re0

If WOL support is shown but not working for a particular interface, create a bug report using the instructions in Support.

1.5. Getting Started with ZFS

Readers new to ZFS should take a moment to read the ZFS Primer.