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 9.10.2

This Guide covers the installation and use of FreeNAS^® 9.10.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.

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^® 9.10.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 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 127.0.0.1 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 9.10.2¶

The installer now provides an option to install the updated system into a new boot environment instead of formatting the boot device. This makes updates safer and testing different versions more convenient.
The installer warns the user if the computer has less than the minimum recommended amount of memory.
The installer offers an option to set up either UEFI or traditional BIOS/MBR booting.
A new Setup mode drop-down menu has been added to Storage → Replication Tasks → Add Replication.
A new FQDN checkbox has been added to the Advanced System settings. Checking this causes fully-qualified domain names to be included in syslogd output, making it easier to identify individual systems when groups of computers have similar hostnames.
A Manual Update button has been added to the Update screen in System. Update files can be applied manually with this method.
An Auxiliary Parameters field has been added to Sharing → Apple (AFP) → Add Apple (AFP) Share.
Modifying network settings only affects the changed network components, avoiding the disruption of restarting all networking.
Chelsio T3/T4/T5 network cards can now take advantage of TCP Offload Engine (TOE) for improved network performance. Add toe to the Options field of the interface to enable the feature.
LDAP failing to bind to the domain on startup causes an alert.
A new script for backing up Samba4 domain controller settings has been added. See Samba Domain Controller Backup.
The winmsa VFS module has been added to Samba. This module emulates Microsoft’s MoveSecurityAttributes=0 registry option, setting the ACL for file and directory hierarchies to inherit from the parent directory into which they are moved.
The UPS shutdown command can now be customized.
freenas-debug can now include GRUB configuration information.
The php-virtualbox jail template has been removed.
iohyve has been updated to version 0.7.7.
Additional disks statistics for percent busy, latency, operations per second, and pending I/O requests have been added to Reporting.
A new API has been added. The old API is still present for compatibility.

1.2. Changes in 9.10.2-U2¶

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 9.10.2-U2 was released.

Note

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

An alert is shown when running on certain models of ASrock Rack motherboards with flawed BMC firmware that require an update. See ASrock Rack BMC Issue.
Patches have been applied to fix the FreeBSD-SA-17:01.openssh Security Advisory.
During user creation, non-ASCII characters are prevented from being entered in the username.
When moving the system dataset, a new message notifies the user that the dataset is only moved after clicking Save.
Samba has been updated to 4.5.5.
Extents are not allowed to be created inside the jail root directory.

1.3. Hardware Recommendations¶

FreeNAS^® 9.10.2 is based on FreeBSD 10.3 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.

Note

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

Note

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

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

Note

Dell PERC H730 disk controllers can be problematic. For best results, set the controller to HBA mode and add a loader tunable with a Variable of hw.mfi.mrsas_enable, a Value of 1, and a Type of Loader.

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.
7200 RPM SATA disks are designed for single-user sequential I/O and are not a good choice for multi-user writes.

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

Note

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
re0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> metric 0 mtu 1500
        options=42098<VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,WOL_MAGIC,VLAN_HWTSO>
        capabilities=5399b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4,WOL_UCAST,WOL_MCAST, WOL_MAGIC,VLAN_HWFILTER,VLAN_H WTSO>

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.