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

Copyright © 2011-2019 iXsystems

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

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.

Asigra Inc. Asigra, the Asigra logo, Asigra Cloud Backup, Recovery is Everything, Recovery Tracker and Attack-Loop are trademarks of Asigra Inc.

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.3 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.
 (Close) Close a help box.

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

FreeNAS® 11.3 is a feature release, which includes 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.

Major New Features and Improvements

The replication framework has been redesigned, adding new back-end systems, files, and screen options to the Replication system and Periodic Snapshot Tasks. The redesign adds these features:

  • New peers/credentials API for creating and managing credentials. The SSH Connections and SSH Keypairs screens have been added and a wizard makes it easy to generate new keypairs. Existing SFTP and SSH replication keys created in 11.2 or earlier will be automatically added as entries to SSH Keypairs during upgrade.
  • New transport API adds netcat support, for greatly improved speed of transfer.
  • Snapshot creation has been decoupled from replication tasks, allowing replication of manually created snapshots.
  • The ability to use custom names for snapshots.
  • Configurable snapshot retention on the remote side.
  • A new replication wizard makes it easy to configure replication scenarios, including local replication and replication to systems running legacy replication (pre-11.3).
  • Replication is resumable and failed replication tasks will automatically try to resume from a previous checkpoint. Each task has its own log which can be accessed from the State column.

Network interface management has been redesigned to streamline management of both physical and virtual interfaces using one screen. VLANs and LAGGs are now classified as interface types and support for the Bridge interface type has been added. The addressing details for all physical interfaces, including DHCP, are now displayed but are read-only if the interface is a member of a LAGG. When applying interface changes, the web interface provides a window to cancel the change and revert to the previous network configuration. A new MTU field makes it easier to set the MTU as it no longer has to be typed in as an Auxiliary Parameter.

Automatic Certificate Management Environment (ACME) support has been added. ACME simplifies the process of issuing and renewing certificates using a set of DNS challenges to verify a user is the owner of the domain. While the new API supports the addition of multiple DNS authenticators, support for Amazon Route 53 has been added as the initial implementation. The ACME DNS screen is used for authenticator configuration which adds the ACME Certificates option for Certificate Signing Requests. Once configured, FreeNAS® will automatically renew ACME certificates as they expire.

Support for collecting daily anonymous usage statistics has been added. Collected non-identifying data includes hardware information such as CPU type, number and size of disks, and configured NIC types as well as an indication of which services, types of shares, and Plugins are configured. The collected data will assist in determining where to best focus engineering and testing efforts. Collection is enabled by default. To opt-out, unset System ➞ General ➞ Usage collection.

The Alert system has been improved:

  • Support for one-shot critical alerts has been added. These alerts remain active until dismissed by the user.
  • Alert Settings has been reorganized: alerts are grouped functionally rather than alphabetically and per-alert severity and alert thresholds are configurable.
  • Periodic alert scripts have been replaced by the Alert framework. Periodic alert emails are disabled by default and previous email alert conditions have been added to the FreeNAS® alert system. E-mail or other alert methods can be configured in Alert Services.

The Dashboard has been rewritten to provide an overview of the current state of the system rather than repeat the historical data found in Reporting. It now uses middleware to handle data collection and provide the web interface with real-time events. Line charts have been replaced with meters and gauges. CPU graphs have been consolidated into a single widget which provides average usage and per-thread statistics for both temperature and usage. Interfaces are represented as a separate card per physical NIC unless they are part of a LAGG card. Pool and Interface widgets feature mobile-inspired lateral navigation, allowing users to “drill down” into the data without leaving the page.

Reporting has been greatly improved. Data is now prepared on the backend by the middleware and operating system. Any remaining data manipulation is done in a web worker, keeping expensive processing off of the main UI thread/context. The SVG-based charting library was replaced with a GPU-accelerated canvas-based library. Virtual scroll and lazy loading prevent overloading the browser and eliminate the need for a pager. Users can zoom by X or Y axis and reset the zoom level with a double click. Graphs do not display if there is no related data. Support for UPS and NFS statistics has been added.

Options for configuring the reporting database have been moved to System ➞ Reporting. This screen adds the ability to configure Graph Age as well as the number of points for each hourly, daily, weekly, monthly, or yearly graph (Graph Points). The location of the reporting database defaults to tmpfs and a configurable alert if the database exceeds 1 GiB has been added to Alert Settings.

The web interface has received many improvements and bug fixes. Usability enhancements include: ability to move, pin, and copy help text, persistent layout customizations, customizable column views, size units which accept humanized input, improved caching and browser support, and improved error messages, popup dialogs, and help text. An iX Official theme has been added which is the default for new installations.

NAT support has been added as the default for most Plugins. With NAT, a plugin is contained in its own network and does not require any knowledge of the physical network to work properly. This removes the need to manually configure IP addresses or have a DHCP server running. When installing a plugin into a virtualized environment, NAT removes the requirement to enable Promiscuous Mode for the network.

The Plugins page has been streamlined so that most operations can be performed without having to go to the Jails page. Support for collections has been added to differentiate between iXsystems plugins, which receive updates every few weeks, and Community plugins. In addition, there have been many bug fixes and improvements to iocage, the Plugins backend, resulting in a much better Plugins user experience.

An ACL Manager has been added to Storage ➞ Pools ➞  (Options) and the permissions editor has been redesigned.

A new iSCSI wizard in Block (iSCSI) makes it easy to configure iSCSI shares.

There have been several Pool Manager improvements. The labels and tooltips for encryption operations are clearer. Disk type, rotation rate, and manufacturer information makes it easier to differentiate between selectable disks when creating a pool. A REPEAT button makes it easy to create large pools using the same vdev layout, such as a series of striped mirrors.

Significant improvements to SMB sharing include ZFS user quotas support, web service discovery support, and improved directory listing performance for newly-created shares.

The middleware and websockets APIv2 rewrite is complete. APIv1 remains for backwards compatibility but will be deprecated and no longer available in the next major release.

Deprecated and Removed Features

  • The legacy web interface has been removed and no longer appears as an option in the login screen.
  • Warden has been removed along with all CLI and web interface support for warden jails or plugins installed using FreeNAS® 11.1 or earlier.
  • Domain Controller has been removed from Services.
  • Netdata has been removed from Services due to a long-standing upstream memory leak. TrueCommand provides similar reporting plus advanced management capabilities for single or multiple FreeNAS® systems and is free to use to manage up to 50 drives.
  • The built-in Docker template has been removed from Virtual Machines. Instructions for manually installing Docker can be found in Installing Docker.

New or Updated Software

  • OS support for reporting the CPU temperature of AMD Family 15h, Model >=60h has been added.
  • QLogic 10 Gigabit Ethernet driver support has been added with qlxgbe(4).
  • The base FreeBSD ports have been updated to their latest versions as of September 24, 2019.
  • Angular has been updated to version 8.
  • Samba has been updated to version 4.10.8.
  • Netatalk has been updated to version 3.1.12_2,1.
  • Rclone has been updated to version 1.49.4.
  • collectd has been updated to version 5.8.1_1.
  • p7zip has been added.
  • The zettarepl replication tool has been added.

Misc UI Changes

  • The Hostname and Domain set in Global Configuration are shown under the iXsystems logo at the top left of the web interface.
  • The web interface now indicates when a system update is in progress.
  • Directory Services Monitor has been added to the top toolbar row.
  • The Theme Selector has been removed from the top navigation bar. The theme is now selected in Preferences.
  • Add to Favorites, Enable Help Text, and Enable “Save Configuration” Dialog Before Upgrade have been removed from Preferences.
  • Right-click help dialog has been added to the Shell.


  • The GUI SSL Certificate, WebGUI HTTP -> HTTPS Redirect, Usage collection, and Crash reporting fields have been added to and the Protocol field has been removed from General.
  • The WebGUI IPv4 Address and WebGUI IPv6 Address fields in the General system options have been updated to allow selecting multiple IP addresses.
  • The Language field can now be sorted by Name or Language code.
  • An Export Pool Encryption Keys option has been added to the SAVE CONFIG dialog.
  • System ➞ Boot Environments has been renamed to Boot.
  • Periodic Notification User has been removed from the Advanced system options because periodic script notifications have been replaced by alerts.
  • Setting messages in the Advanced system options provides a button to show console messages on busy spinner dialogs.
  • From Name has been added to Email.
  • Reporting Database has moved from System Dataset to System ➞ Reporting.
  • Level has been added and the SHOW SETTINGS button removed from the Alert Services options.
  • API URL has been added to the OpsGenie alert service options.
  • IPMI SEL Low Space Left, IPMI System Event, Rsync Task Failed, and Rsync Task Succeeded have been added to Alert Settings. Clear All Alerts has has been changed to Dismiss All Alerts.
  • OAuth Client ID and OAuth Client Secret have been removed from the Box, Dropbox, Microsoft OneDrive, pCloud, and Yandex providers in the Cloud Credentials options.
  • VERIFY CREDENTIAL has been added to the Cloud Credentials options.
  • Region has been added to the Amazon S3 Cloud Credentials options.
  • PEM-encoded private key file path has been changed to Private Key ID in the SFTP cloud credential options.
  • Elliptic Curve Cryptography (ECC) key support has been added to the options for Certificate Authorities and Certificates.
  • Organizational Unit has been added to the CAs and Certificates options.
  • Import Certificate Signing Request has been added to the Certificates options.



  • The Interface name field has been renamed to Description and the MTU field has been added to Interfaces options.


  • Disk type, rotation rate, and manufacturer information can be viewed on the Disks page and when creating a pool.
  • The Export/Disconnect Pool dialog shows system services that are affected by the export action.
  • The dataset permissions editor has been redesigned. The ACL Type, Apply User, Apply Group, and Apply Access Mode fields have been removed and Traverse has been added.
  • ACL Mode has been added to the Add Dataset advanced mode.
  • A dataset deletion confirmation dialog with a force delete option has been added to the Delete Dataset dialog.
  • Time Remaining displays when the pool has an active scrub in Pool Status.
  • Naming Schema has been added to the single snapshot options.
  • Critical, Difference, and Informational fields have been added to Disk Options.
  • Detach and REFRESH options have been added to Pool Status.
  • The Filesystem type option behavior in Import Disk has been updated to select the detected filesystem of the chosen disk. After importing a disk, a dialog allows viewing or downloading the disk import log.
  • Adding a dataset shows options to configure warning or critical alerts when a dataset reaches a certain percent of the quota.

Directory Services

  • Computer Account OU has been added and the Enable AD monitoring, UNIX extensions, Domain Controller, Global Catalog Server, Connectivity Check, and Recovery Attempts fields have been removed from Active Directory.
  • fruit and tdb2 have been removed from the Idmap backend options.
  • Validate Certificate has been added to Active Directory and LDAP configuration options.
  • The Disable LDAP User/Group Cache checkbox has been added and the User Suffix, Group Suffix, Password Suffix, Machine Suffix, SUDO Suffix, Netbios Name, and Netbios alias fields have been removed from LDAP configuration options.
  • The Hostname in LDAP supports multiple hostnames as a failover priority list.


  • Enable Shadow Copies has been added to the Windows Shares (SMB) options. Default Permissions has been removed from Windows (SMB) Shares as permissions are now configured using ACL manager.
  • The acl_tdb, acl_xattr, aio_fork, cacheprime, commit, expand_msdfs, linux_xfs_sgid, netatalk, posix_eadb, shadow_copy, streams_depot, syncops, and xattr_tdb VFS objects have been removed.


  • Email has been removed from the S.M.A.R.T. Service Options. S.M.A.R.T. alerts are configured as part of an alert service. Note that email addresses previously configured to receive S.M.A.R.T. alerts now receive all FreeNAS® alerts.
  • Time Server for Domain, File Mask, Directory Mask, Allow Empty Password, DOS Charset, and Allow Execute Always have been removed from the SMB service options.
  • Unix Extensions, Domain logons, and Obey pam restrictions have been removed from the SMB services options. These options are now dynamically enabled.
  • Expose zilstat via SNMP has been added to the SNMP service options.
  • Host Sync has been added to the UPS service options and search functionality has been added to Driver.
  • UPS events now generate Alerts.
  • NUT (Network UPS Tools) now listens on ::1 (IPv6 localhost) in addition to (IPv4 localhost).

Virtual Machines

  • Grub boot loader support has been added for virtual machines that will not boot with other loaders.
  • Description and System Clock have been added to the Virtual Machines wizard. The Wizard now displays system memory and Delay VM boot Until VNC Connects has been added to the first step of the Wizard.
  • An optional, custom name can be specifed when cloning Virtual Machines.
  • Log files for each VM are stored in /var/log/vm/. Log files have the same name as the VM.

Plugins and Jails

  • Browse a Collection, REFRESH INDEX, and POST INSTALL NOTES have been added to Plugins.
  • Template jails can now be created from the web interface.
  • allow_vmm, allow_mount_fusefs, ip_hostname, assign_localhost, Autoconfigure IPv6 with rtsold, NAT, and nat_forwards options have been added in Advanced Jail Creation.
  • ip6_saddrsel and ip4_saddresel in Advanced Jail Creation have been renamed to ip6.saddrsel and ip4.saddresel.
  • Log files for jail status and command output are stored in /var/log/iocage.log.

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 1023 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. If a path with long directory and file names exceeds the 1023-byte limit, it prevents 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. Using the Web Interface

1.3.1. Tables and Columns

Tables show a subset of all available columns. Additional columns can be shown or hidden with the COLUMNS button. Set a checkmark by the fields to be shown in the table. Column settings are remembered from session to session.

The original columns can be restored by clicking Reset to Defaults in the column list.

Each row in a table can be expanded to show all the information by clicking the  (Expand) button.

1.3.2. Advanced Scheduler

When choosing a schedule for different FreeNAS® Tasks, clicking Custom opens the custom schedule dialog.


Fig. 1.3.1 Creating a Custom Schedule

Choosing a preset schedule fills in the rest of the fields. To customize a schedule, enter crontab values for the Minutes/Hours/Days.

These fields accept standard cron values. The simplest option is to enter a single number in the field. The task runs when the time value matches that number. For example, entering 10 means that the job runs when the time is ten minutes past the hour.

An asterisk (*) means “match all values”.

Specific time ranges are set by entering hyphenated number values. For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.

Lists of values can also be entered. Enter individual values separated by a comma (,). For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).

A slash (/) designates a step value. For example, while entering * in Days means the task runs every day of the month, */2 means the task runs every other day.

Combining all these examples together creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.

There is an option to select which Months the task will run. Leaving each month unset is the same as selecting every month.

The Days of Week schedules the task to run on specific days. This is in addition to any listed Days. For example, entering 1 in Days and setting W for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.

Schedule Preview shows when the current schedule settings will cause the task to run.

1.3.3. Schedule Calendar

The Schedule column has a calendar icon (). Clicking this icon opens a dialog showing scheduled dates and times for the related task to run.


Fig. 1.3.2 Example Schedule Popup

Scrub Tasks can have a number of Threshold days set. The configured scrub task continues to follow the displayed calendar schedule, but it does not run until the configured number of threshold days have elapsed.

1.3.4. Changing FreeNAS® Settings

It is important to use the web interface or the Console Setup menu for all configuration changes. FreeNAS® stores configuration settings in a database. Commands entered at the command line do not modify the settings database. This means that changes made at the command line will be lost after a restart and overwritten by the values in the settings database.

1.3.5. Web Interface Troubleshooting

If the web interface is shown but seems unresponsive or incomplete:

  • Make sure the browser allows cookies, Javascript, and custom fonts from the FreeNAS® system.
  • Try a different browser. Firefox is recommended.

If a web browser cannot connect to the FreeNAS® system by IP address, DNS hostname, or mDNS name:

  • Check or disable proxy settings in the browser.
  • Verify the network connection by pinging the FreeNAS® system by IP address from another computer on the same network. For example, if the FreeNAS® system is at IP address, enter ping on the command line of the other computer. If there is no response, check network configuration.

1.3.6. Help Text

Most fields and settings in the web interface have a  (Help Text) icon. Additional information about the field or setting can be shown by clicking  (Help Text). The help text window can be dragged to any location, and will remain there until  (Close) or  (Help Text) is clicked to close the window.

1.4. Hardware Recommendations

FreeNAS® 11.3 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.4.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.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 SSD or USB stick. 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, 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.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 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.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 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.5. Getting Started with ZFS

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