FreeNAS® is © 2011-2019 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.2

Copyright © 2011-2019 iXsystems

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

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.

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®.

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.2 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 pool 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.
Table 2 FreeNAS® Icons
Icon Usage
ADD Add a new item.
 (Settings) Show a settings menu.
 (Options) Show an Options menu.
 (Browse) Shows an expandable view of system directories.
⏻ (Power) Show a power options menu.
 (Show) Reveal characters in a password field.
 (Hide) Hide characters in a password field.
 (Configure) Edit settings.
襁 (Launch) Launch a service.
▶ (Start) Start jails.
 (Stop) Stop jails.
🕓 (Update) Update jails.
 (Delete) Delete jails.
 (Encryption Options) Encryption options for a pool.
 (Pin) Pin a help box to the screen.
 (Unpin) Unpin a help box from the screen.

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.2

FreeNAS® 11.2 is a feature release, which includes several new significant features, many improvements and bug fixes to existing features, and version updates to the operating system, base applications, and drivers. Users are encouraged to Update to this release in order to take advantage of these improvements and bug fixes.

These major features are new in this version:

  • The login screen defaults to the new, Angular-based UI. Users who wish to continue to use the classic UI can select “Legacy UI” in the login screen.
  • Beginning with this release, the screenshots that appear in the published version of the Guide and in the Guide option within the new UI are for the new UI. However, users who click on the Guide icon while logged into the classic UI will continue to see screenshots for the old UI. The availability of both versions of the Guide is to assist users as they become familiar with the new UI during the transition period before the classic UI is deprecated in a future release.
  • The rewrite from the old API to the new middlewared continues. Once the rewrite is complete, will be deprecated and replaced by the new API documentation. In the mean time, to see the API documentation for the new middleware, log into the new UI, click on the URL for the FreeNAS system in your browser’s location bar, and add /api/docs to the end of that URL.
  • The boot loader has changed from GRUB to the native FreeBSD boot loader. This should resolve several issues that some users experienced with GRUB. GRUB was introduced as a temporary solution until the FreeBSD boot loader had full support for boot environments, which it now has.
  • The Plugins and Jails backend has switched from warden to iocage and warden will no longer receive bug fixes. The new UI will automatically use iocage to create and manage Plugins and Jails. Users are encouraged to recreate any existing Plugins and Jails using the new UI to ensure that they are running the latest supported application versions.
  • Plugins have switched to FreeBSD 11.2-RELEASE and all Plugins have been rebuilt for this version.
  • Virtual Machines are more crash-resistant. When a guest is started, the amount of available memory is checked and an initialization error will occur if there is insufficient system resources. There is an option to overcommit memory to the guest when it is started, but this is not recommended for normal use. When a guest is stopped, its resources are returned to the system. In addition, the UEFI boot menu fix allows Linux kernels 4.15 and higher to boot properly.
  • Cloud Sync Tasks provides configuration options to encrypt data before it is transmitted and to keep it in the encrypted format while stored on the cloud. The filenames can also be encrypted.
  • Preliminary support has been added for Self-Encrypting Drives (SEDs).

This software has been added or updated:

  • The base operating system is the STABLE branch of FreeBSD 11.2, which brings in many updated drivers and bug fixes. This branch has been patched to include the FreeBSD security advisories up to FreeBSD-SA-18:13.nfs.
  • OpenZFS is up-to-date with Illumos and slightly ahead due to support for sorted scrubs which were ported from ZFS on Linux. Notable improvements include channel programs, data disk removal, more resilient volume import, the ability to import a pool with missing vdevs, pool checkpoints, improved compressed ARC performance, and ZIL batching. As part of this change, the default ZFS indirect block size is reduced to 32 KiB from 128 KiB. Note that many of these improvements need further testing so have not yet been integrated into the UI.
  • The IPsec kernel module has been added. It can be manually loaded with kldload ipsec.
  • Support for eMMC flash storage has been added.
  • The em, igb, ixgbe, and ixl Intel drivers have been patched to resolve a performance degradation issue that occurs when the MTU is set to 9000 (9k jumbo clusters). Before configuring 9k jumbo clusters for cxgbe create a Tunables with a Variable of hw.cxgbe.largest_rx_cluster, a Type of Loader, and a Value of 4096. The cxgb driver does not support jumbo clusters and should not use an MTU greater than 4096.
  • The bnxt driver has been added which provides support for Broadcom NetXtreme-C and NetXtreme-E Ethernet drivers.
  • The vt terminal is now used by default and the syscons terminal is removed from the kernel.
  • ncdu has been added to the base system. This CLI utility can be used to analyze disk usage from the console or an SSH session.
  • drm-next-kmod has been added to the base system, adding support for UTF-8 fonts to the console for Intel graphic cards.
  • Samba 4.7 has been patched to address the latest round of security vulnerabilities.
  • rsync has been updated to version 3.1.3.
  • rclone has been updated to version 1.44.
  • Minio has been updated to version 2018-04-04T05.
  • Netdata as been updated to version 1.10.0.
  • iocage has been synced with upstream as of October 3, providing many bug fixes and improved IPv6 support.
  • RancherOS has been updated to version 1.4.2.
  • zsh is the root shell for new installations. Upgrades will continue to use the csh shell as the default root shell.
  • ifconfig tap interface descriptions now show the name of the attached virtual machine.
  • xattr has been added to the base system and can be used to modify file extended attributes from the command line. Type xattr -h to view the available options.
  • convmv has been added to the base system and can be used to convert the encoding of filenames from the command line. Type convmv to view the available options.
  • The cloneacl CLI utility has been added. It can be used to quickly clone a complex ACL recursively to or from an existing share. Type cloneacl for usage instructions.
  • These switches have been added to freenas-debug: -M for dumping SATADOM info and -Z to delete old debug information. The -G switch has been removed as the system no longer uses GRUB. The -J switch has been removed and the -j switch has been reworked to show iocage jail information instead of Warden.
  • These switches have been added to arcstat: -a for displaying all available statistics and -p for displaying raw numbers without suffixes.

These screen options have changed:

  • The ATA Security User, SED Password, and Reset SED Password fields have been added to System ➞ Advanced.
  • The Enable Console Screensaver field has been removed from System ➞ Advanced.
  • The Enable automatic upload of kernel crash dumps and daily telemetry checkbox has been removed from System ➞ Advanced.
  • The Enable Power Saving Daemon option has been removed from System ➞ Advanced.
  • Alert Settings has been added to System and can be used to list the available alert conditions and to configure the notification frequency on a per-alert basis.
  • These Cloud Credentials have been added to System ➞ Cloud Credentials: Amazon Cloud Drive, Box, Dropbox, FTP, Google Drive, HTTP, hubiC, Mega, Microsoft OneDrive, pCloud, SFTP, WebDAV, and Yandex.
  • The Team Drive ID field has been added to System ➞ Cloud Credentials ➞ Add and appears when Google Drive is the Provider.
  • The Endpoint URL has been added to System -> Cloud Credentials -> Add Cloud Credential but only appears when Amazon S3 is selected as the Provider. This can be used to configure a connection to another S3-compatible service, such as Wasabi.
  • Drive Account Type and Drive ID has been added to System -> Cloud Credentials -> Add Cloud Credential. These fields appear when Microsoft OneDrive is selected as the Provider.
  • The Automatically check for new updates option in System ➞ Update has been renamed to Check for Updates Daily and Download if Available.
  • The Train selector in System ➞ Update has been changed so that only allowable trains are displayed in the drop-down menu. Each train option has an expanded description.
  • There is now an option to add a prompt to save a copy of the system configuration and include the Password Secret Seed before doing a system upgrade. This popup can be enabled by going to  (Settings) ➞ Preferences and unsetting Enable “Save Configuration” Dialog Before Upgrade.
  • The Container, Remote encryption, Filename encryption, Encryption password, and Encryption salt fields have been added to Tasks ➞ Cloud Sync Tasks ➞ Add Cloud Sync.
  • The NIC and Interface Name fields in Network ➞ Interfaces ➞ Add Interface are preconfigured with the web interface NIC settings when configuring the first interface. A warning is shown when a user attempts to configure a different interface before the web interface NIC.
  • The Block size field in Storage ➞ Pools ➞ Add Zvol ➞ ADVANCED MODE no longer allows choosing sizes smaller than 4K. This is to prevent performance issues from setting a block size that is too small for efficient processing.
  • The Exec field has been added to Storage ➞ Pools ➞ Add Dataset ➞ ADVANCED MODE. The Record Size field no longer allows choosing sizes smaller than 4K. This is to prevent performance issues from setting a block size that is too small for efficient processing.
  • A Date Created column has been added to Storage ➞ Snapshots.
  • The Password for SED column has been added to Storage ➞ Disks.
  • The MSDOSFS locale drop-down menu has been added to Storage ➞ Import Disk.
  • A Domain Account Password in Directory Services ➞ Active Directory is only required when configuring a domain for the first time.
  • The User Base and Group Base fields have been removed from Directory Services ➞ Active Directory ➞ Advanced Mode.
  • The Enable home directories, Home directories, Home share name, and Home Share Time Machine fields have been removed from Services ➞ AFP and the Time Machine Quota field has been removed from Sharing ➞ Apple (AFP) Shares. These fields have been replaced by Sharing ➞ Apple (AFP) Shares ➞ Use as home share.
  • The Umask field in Services ➞ TFTP has changed to a File Permissions selector.
  • The Hostname field has been added to Services ➞ UPS. This field replaces the Port field when a UPS Driver with snmp is selected.
  • The BitTorrent Sync plugin has been renamed to Resilio Sync.
  • Disk temperature graphs have been added to Reporting ➞ Disk. This category has been reworked to allow the user to choose the devices and metrics before graphs are displayed.
  • Uptime graphs have been removed from the Reporting ➞ System tab.
  • Virtual Machines ➞ Device add and edit forms now have a Device Order field to set boot priority for VM devices.

1.1.1. RELEASE-U1

  • Netatalk has been updated to 3.1.12 to address CVE-2018-1160.

1.1.2. U2

  • The base operating system has been patched to address these security advisories:
  • The mlx5ib(4) driver for the Mellanox ConnectX-4 family of infiniband drivers has been added.
  • Samba has been updated to 4.9.4 which is the current stable release receiving new features. This version bump provides significant performance improvements as well as improved Time Machine support. This deprecates the dfs_samba4, fake_acls, skel_opaque, skel_transparent, and snapper modules which have been removed from Sharing ➞ Windows (SMB) Shares ➞ ADD ➞ ADVANCED MODE ➞ VFS Objects.
  • OpenSSL has been updated to 1.0.2q to address CVE-2018-5407.
  • curl has been updated to 7.62.0 to address security vulnerabilities.
  • Pool widgets in the Dashboard now change color to reflect the current pool status.
  • Help text can now be pinned to the screen, remaining visible when the cursor moves from the help icon.
  • Disable Endpoint Region and Use Signature Version 2 checkboxes have been added to System ➞ Cloud Credentials ➞ Add Cloud Credential when Amazon S3 is chosen as the Provider.
  • The Reboot After Update checkbox has been added to System ➞ Update ➞ Manual Update
  • A  (Browse) option displays with the Folder field in Tasks ➞ Cloud Sync Tasks ➞ ADD. This allows browsing through the connected Credential remote filesystem.
  • Rollback for any dataset snapshot is supported in Storage ➞ Snapshots.
  • The ixnas VFS module has been added to and the aio_pthread VFS module has been removed from Sharing ➞ Windows (SMB) ➞ VFS Objects.
  • The Time Machine field has been added to Sharing ➞ Windows (SMB) Shares ➞ Add.
  • An NAA column has been added to Sharing ➞ Block (iSCSI) ➞ Extents.
  • The Enable SMB1 support checkbox has been added to Services ➞ SMB.
  • An ADVANCED PLUGIN INSTALLATION option has been added to Plugins ➞ Available ➞ Install. This allows full plugin jail customization before plugin installation.
  • The allow_mlock, vnet_interfaces, hostid_strict_check, and allow_tun fields have been added to the Jails ➞ Add ➞ Advanced Jail Creation and Jails ➞ Edit forms.
  • The ARC Size graph in Reporting now shows the compressed physical L2ARC size.
  • The openipmi package and usr/local/lib/collectd/ have been removed to disable the non-functional collectd IPMI plugin.
  • The Wait to Boot field in Virtual Machines ➞ Devices ➞ VNC Device ➞ Edit has been renamed to Delay VM Boot until VNC Connects.
  • An Alert for syslog-ng stopping has been added to System ➞ Alert Settings.

1.1.3. U3

  • ZeroTier has been updated to 1.2.12.
  • The Confirm Password field has been removed from System ➞ Email.
  • A  (Refresh) button has been added to System ➞ Update.
  • The Multipaths page has been added to Storage. This page only appears when compatible hardware is detected.
  • The chosen snapshot name and creation date has been added to the rollback warning dialog in Storage ➞ Snapshots ➞  (Options) ➞ Rollback.
  • The Pool column has been removed from Storage ➞ Disks.
  • Setting Enable AD Monitoring in Directory Services ➞ Active Directory now prevents modifying Services ➞ Domain Controller.
  • The shadow_copy_zfs VFS object has replaced the shadow_copy_test object in Sharing ➞ Windows (SMB) Shares ➞ ADD ➞ ADVANCED MODE.
  • The Host field has been added to Services ➞ TFTP.
  • Jails displays a DHCP prefix before the IPv4 Address for DHCP-enabled Plugins and Jails.
  • CPU Temperature graphs have been added to Reporting ➞ CPU.
  • Activity graphs have been updated to report Megabytes/s in Reporting ➞ Network.
  • Restart has been added to the  (Options) menu for a running VM in Virtual Machines.
  • The State column of Virtual Machines has changed to a start/stop slider. Hover over the slider to view the current state.
  • The Autostart column has been added to Virtual Machines.
  • The Raw filename password field has been added to Docker VM Storage File options in Virtual Machines ➞ ADD.
  • The Bind drop-down menu has been added to Virtual Machines ➞ ADD and to Virtual Machines ➞ Devices ➞ VNC ➞ Edit.

1.1.4. U4

  • Samba has been patched to address CVE-2019-3880.
  • Python has been updated to 2.7.15 to address multiple CVEs.
  • Apache has been updated to 2.4.39 to address multiple CVEs.
  • wget has been updated to 1.20.3 to address a buffer overflow vulnerability.
  • convmv has been updated to 2.05 which adds support for NFC/NFD conversion on APFS volumes.
  • ladvd has been updated to 1.1.2, which adds LLDP support to lagg interfaces.
  • rrdtool has been updated to 1.7.1.
  • The help box  (Pin) icon now changes to  (Unpin) when the help box is pinned to the screen.
  • The hw.vga.acpi_ignore_no_vga=1 tunable has been added to loader.conf. See vt(4).
  • The Update option has replaced Upgrade in Plugins ➞ Installed ➞  (Options).
  • The Administrators Group drop-down menu has been added to Services ➞ SMB.
  • Saving a new configuration in Services ➞ UPS now also requires values for the Identifier, Shutdown Command, Monitor User, and Monitor Password fields.

1.1.5. U5

  • The operating system has been patched to address FreeBSD-SA-19:07.
  • AMD CPU temperature drivers have been updated to accommodate the AMD Family 15H models. Temperature measurements are more accurate.
  • Python3 has been updated to version 3.6.8 and Python2 to version 2.7.16.
  • Samba has been updated to version 4.9.9 to address CVE-2019-12435.
  • Perl has been updated to version 5.26.2 to address several security vulnerabilities.
  • libnghttp2 has been updated to version 1.31.1 to address CVE-2018-1000168.
  • libgcrypt has been updated to version 1.8.3 to address CVE-2018-0495.
  • The hubiC cloud service suspended creation of new accounts.
  • A RESET LAYOUT button has been added to Storage ➞ Pools ➞ Create Pool.
  • The Asigra Plugin has been added to Plugins ➞ Available. See Backup Evolved: Asigra Plugin for FreeNAS for more details.
  • The noacl VFS module has been added to Sharing ➞ Windows (SMB) ➞ Add Windows (SMB) Share.

1.1.6. U6

The operating system has been patched for:
  • Some operating system and ZFS fixes were added.
  • Samba has been updated to version 4.9.13 to address CVE-2019-10197.
  • GnuTLS has been updated to version 3.6.8 to address CVE 2019-3829 and CVE 2019-3836.
  • The iconik plugin has been added. More information about iconik, a getting started guide, and an offer for 300 free credits is available here.
  • The Amazon Cloud Drive provider has been removed from System ➞ Cloud Credentials. See this rclone forum post about Amazon Drive for more details.

1.2. 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.2.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.


88 bytes is equal to 88 ASCII characters. The number of characters varies when using Unicode.


If the mounted path length for a snapshot exceeds 88 bytes, the data in the snapshot is safe but inaccessible. When the mounted path length of the snapshot is less than the 88 byte limit, the data will be accessible again.

The 88 byte limit affects automatic and manual snapshot mounts in slightly different ways:

  • Automatic mount: ZFS temporarily mounts a snapshot whenever a user attempts to view or search the files within the snapshot. The mountpoint used will be in the hidden directory .zfs/snapshot/name within the same ZFS dataset. For example, the snapshot mypool/dataset/snap1@snap2 is mounted at /mnt/mypool/dataset/.zfs/snapshot/snap2/. If the length of this path exceeds 88 bytes the snapshot will not be automatically mounted by ZFS and the snapshot contents will not be visible or searchable. This can be resolved by renaming the ZFS pool or dataset containing the snapshot to shorter names (mypool or dataset), or by shortening the second part of the snapshot name (snap2), so that the total mounted path length does not exceed 88 bytes. ZFS will automatically perform any necessary unmount or remount of the file system as part of the rename operation. After renaming, the snapshot data will be visible and searchable again.
  • Manual mount: The same example snapshot is mounted manually from the Shell with mount -t zfs mypool/dataset/snap1@snap2 /mnt/mymountpoint. The path /mnt/mountpoint/ must not exceed 88 bytes, and the length of the snapshot name is irrelevant. When renaming a manual mountpoint, any object mounted on the mountpoint must be manually unmounted with the umount command before renaming the mountpoint. It can be remounted afterwards.


A snapshot that cannot be mounted automatically by ZFS can still be mounted manually from the Shell with a shorter mountpoint path. This makes it possible to mount and access snapshots that cannot be accessed automatically in other ways, such as from the web interface or from features such as “File History” or “Versions”.

1.3. Hardware Recommendations

FreeNAS® 11.2 is based on FreeBSD 11.2 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.3.1. RAM

The best way to get the most out of a FreeNAS® system is to install as much RAM as possible. More RAM allows ZFS to provide better performance. The FreeNAS® Forums provide anecdotal evidence from users on how much performance can be gained by adding more RAM.

General guidelines for RAM:

  • A minimum of 8 GiB of RAM is required.

    Additional features require additional RAM, and large amounts of storage require more RAM for cache. An old, somewhat overstated guideline is 1 GiB of RAM per terabyte of disk capacity.

  • To use Active Directory with many users, add an additional 2 GiB of RAM for the winbind internal cache.

  • For iSCSI, install at least 16 GiB of RAM if performance is not critical, or at least 32 GiB of RAM if good performance is a requirement.

  • Jails are very memory-efficient, but can still use memory that would otherwise be available for ZFS. If the system will be running many jails, or a few resource-intensive jails, adding 1 to 4 additional gigabytes of RAM can be helpful. This memory is shared by the host and will be used for ZFS when not being used by jails.

  • Virtual Machines require additional RAM beyond any amounts listed here. Memory used by virtual machines is not available to the host while the VM is running, and is not included in the amounts described above. For example, a system that will be running two VMs that each need 1 GiB of RAM requires an additional 2 GiB of RAM.

  • When installing FreeNAS® on a headless system, disable the shared memory settings for the video card in the BIOS.

  • For ZFS deduplication, ensure the system has at least 5 GiB of RAM per terabyte of storage to be deduplicated.

If the hardware supports 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 your data is important, use ECC RAM. This Case Study describes the risks associated with memory corruption.

Do not use FreeNAS® to store data without at least 8 GiB of RAM. 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 GiB of RAM because of the abundance of information that FreeNAS® may not behave properly with less memory.

1.3.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 SSD, a small hard drive, or a USB stick.


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, while the other USB stick is the destination for the FreeNAS® installation. Be careful to select the correct USB device for the FreeNAS® installation. FreeNAS® cannot be installed onto the same device that contains 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® operating system device.

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

  • The absolute bare minimum size is 8 GiB. That does not provide much room. The recommended minimum is 16 GiB. This provides room for the operating system and several boot environments created by updates. More space provides room for more boot environments and 32 GiB or more is preferred.

  • SSDs (Solid State Disks) are fast and reliable, and make very good FreeNAS® operating system devices. Their one disadvantage is that they require a disk connection which might be needed for storage disks.

    Even a relatively large SSD (120 or 128 GiB) is useful as a boot device. While it might appear that the unused space is wasted, that space is instead used internally by the SSD for wear leveling. This makes the SSD last longer and provides greater reliability.

  • When planning to add your own boot environments, budget about 1 GiB 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.


Current versions of FreeNAS® run directly from the operating system device. Early versions of FreeNAS® ran from RAM, but that has not been the case for years.

1.3.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 Broadcom MegaRAID controller or a 3Ware twa-compatible controller.


Upgrading the firmware of Broadcom 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/GiB. An example configuration would be six 600 GiB 15K SAS drives in a RAID 10 which would yield 1.8 TiB of usable space, or eight 600 GiB 15K SAS drives in a RAID 10 which would yield 2.4 TiB of usable space.

For ZFS, Disk Space Requirements for ZFS Storage Pools recommends a minimum of 16 GiB of disk space. FreeNAS® allocates 2 GiB of swap space on each drive. Combined with ZFS space requirements, this means that it is not possible to format drives smaller than 3 GiB. Drives larger than 3 GiB but smaller than the minimum recommended capacity might be usable but lose a significant portion of storage space to swap allocation. For example, a 4 GiB drive only has 2 GiB of available space after swap allocation.

New ZFS users 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 TiB and two 4 TiB disks will only be able to use 2 TiB 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.3.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 MiB/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 igb0 interface:

[root@freenas ~]# ifconfig -m igb0
igb0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> metric 0 mtu 1500

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

1.4. Getting Started with ZFS

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