FreeNAS® is © 2011, 2012 iXsystems

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

FreeBSD is a registered trademark of the FreeBSD Foundation

Cover art by Jenny Rosenberg

Section 1: Introduction and Installation

Preface

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

Version 8.3.0

Published October 26, 2012

Copyright © 2011, 2012 iXsystems.

This Guide covers the installation and use of FreeNAS® 8.3.0. If you are running a version of FreeNAS® 8.x that is earlier than FreeNAS® 8.3.0, it is strongly recommended that you upgrade to or install FreeNAS® 8.3.0. This version fixes many bugs from previous 8.x versions and several features mentioned in this Guide were not available or did not work as documented in earlier versions of FreeNAS® 8.x.

The FreeNAS® Users 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, visit doc.freenas.org and create a wiki login account. If you use IRC Freenode, you are welcome to join the #freenas channel where you will find other FreeNAS® users.

The FreeNAS® Users 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.

3ware® and LSI® are trademarks or registered trademarks of LSI Corporation.

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.

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.

Marvell® is a registered trademark of Marvell or its affiliates.

m0n0wall is a registered trademark of Manuel Kasper, Kasper Systems.

OpenMediaVault is Copyright © 2009-2011 by Volker Theile.

SourceForge.net® is a registered trademark or trademark of Geeknet, Inc., in the United States and other countries. Geeknet is a trademark of Geeknet, Inc.

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® 8.3.0 Users Guide uses the following typographic conventions:

bold text: represents a command written at the command line. In usage examples, the font is changed to Courier 10 with any command output displayed in unbolded text.

italic text: used to represent device names, file name paths, or text that is input into a GUI field.

bold italic text: used to emphasize an important point.

1 Introduction

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

The FreeNAS® Project was originally founded by Olivier Cochard-Labbé in 2005 and was based on m0n0wall, an embedded firewall based on FreeBSD. It was PHP based, easy-to-use, and had lots of features. In December of 2009, Olivier announced that the .7 branch would be placed in maintenance-only mode as he no longer had time to devote to further FreeNAS® development. Volker Theile, a FreeNAS® developer who also develops on Debian in his day job, decided to start the OpenMediaVault project, which would be a rewrite of FreeNAS® based on Debian Linux and released under the terms of the GPLv3 license. Many FreeNAS® users were not pleased about the change of license and the loss of kernel-based ZFS support due to GPL incompatibilities with the CDDL license.

iXsystems, a provider of FreeBSD-based hardware solutions and professional support, took the initiative to sponsor the continued development of a BSD licensed FreeNAS® solution based on NanoBSD, an embedded version of FreeBSD. After analyzing the positives (lots of cool features) and negatives (monolithic, everything-but-the-kitchen-sink design that was difficult to maintain and support), it was decided that the next version would be rewritten from scratch using a modular design that would provide a basic core NAS with a modular plugin architecture for adding non-core features. This would allow FreeNAS® to have a small footprint that was easy to support while allowing users to install the additional features they desired. It would have the added benefit of allowing users to create and contribute plugins for niche features, allowing usage cases to grow according to users' needs.

Work on the new design began in 2010 when the 8.x branch was created to differentiate the new design from the original .7 branch. In late 2011, the .7 branch was considered to be EOL (end-of-life) and it was removed from the SourceForge site in mid-2012 when the legacy .7 branch was rebranded as NAS4Free. Users of the .7 branch should upgrade to either NAS4Free or to the latest release of FreeNAS® 8.x.

Table 1a lists the 8.x releases and provides links to the release notes for each released version:

Table 1a: FreeNAS® 8.x Releases

Except for the 8.3.0 release, each release in the 8.x branch is based on FreeBSD 8.2. Once the 8.x branch has reached the end of its development cycle, the 9.x branch will be created. This is expected to occur in late 2012.

1.1 Features

Notable features in FreeNAS® 8.3.0 include:

• supports AFP, CIFS, FTP, NFS, SSH (including SFTP), and TFTP as file sharing mechanisms

• supports exporting file or device extents via iSCSI

• supports Active Directory or LDAP for user authentication

• supports UFS2 based volumes, including gmirror, gstripe, and graid3

• supports ZFS, enabling many features not available in UFS2 such as quotas, snapshots, compression, replication, and datasets for sharing subsets of volumes

• upgrade procedure saves the current operating system to an inactive partition, allowing for an easy reversal of an undesirable upgrade

• system notifications are automatically mailed to the root user account

• Django-driven graphical user interface available through a web browser

• secure replication, automatic ZFS snapshots, scheduling of ZFS scrubs, and cron management are all configurable through the graphical interface

• support for menu localization and keyboard layouts

• multiple IPs can be specified per iSCSI portal

• ssh daemon logs to /var/log/auth.log

• SMART monitoring and UPS management in GUI

• USB 3.0 support

• support for Windows ACLs and UNIX file system permissions

• periodic ZFS snapshots are visible in Windows as shadow copies

• includes tmux, a BSD-licensed utility similar to GNU screen

• includes dmidecode which can provide very useful hardware diagnostic information

1.2 Known Issues

Before installing FreeNAS® you should be aware of the following known issues:

• UPGRADES FROM FreeNAS® 0.7x ARE UNSUPPORTED. The system has no way to import configuration settings from 0.7x versions of FreeNAS®, meaning that you will have to manually recreate your configuration. However, you should be able to import supported volumes created using FreeNAS® 0.7x.

• The ZFS upgrade procedure is non-reversible. Do not upgrade your ZFS version unless you are absolutely sure that you will never want to go back to the previous version. There is no reversing a ZFS pool upgrade, and there is no way for a system with an older version of ZFS to access pools that have been upgraded.

• The available space reported in the parent zpool may not reflect reality and can be confusing because the available space represented by datasets or zvols can exceed that of the parent zpool.

• Disks with certain configurations can get probed by GEOM and become essentially unwritable without manual intervention. For instance, if you use disks that previously had a gmirror on them, the system may pick that up and the disks will be unavailable until the existing gmirror is stopped and destroyed.

• USB 3.0 support is disabled by default as it panics some motherboards. To enable support, create a tunable with a variable of xhci_load and a value of YES.

1.3 What's New in 8.3.0

FreeNAS® 8.3.0 adds the following features:

• ZFSv28 adds deduplication, RAIDZ3, improved snapshot support, and a removable log device.

• Based on FreeBSD 8.3 which updated and added some new drivers as described in the FreeBSD 8.3 Release Notes.

• Add support for HighPoint 27xx and LSI 9265/9285 controllers.

• Add support for Areca 13xx SAS controllers. To load this driver, create a tunable with a variable of arcasa_load and a value of YES.

• Reporting graphs now provide buttons for navigating to different points in time.

• Automatic redirect from http:// to https:// when accessing the administrative GUI when SSL is enabled.

• Add the CARP module to the build. This module is not loaded by default and high availability must be configured manually from the command line. More information about CARP can be found in the OpenBSD FAQ.

• Add a begin and end time as well as a bandwidth cap to Replication Tasks.

• Add the ability to specify the SSL certificate and private key to be used for encrypting FTP connections.

• Add a memory device as an option when performing a GUI upgrade.

• In Active Directory configuration, add checkboxes for: Use default domain, UNIX extensions, and Verbose logging.

• Add additional SNMP MIBs.

• Add the ability to update the Plugins Jail without deleting installed plugins.

• Disable Nagle's algorithm in order to provide better LAN network performance at the expense of WAN performance.

• Add AES-NI hardware support for the Intel Core i5/i7 processors that support this encryption set. This support speeds up AES encryption and decryption.

• A host name database field has been added to Global Configuration, allowing entries to be added to /etc/hosts.

• Add option to set the serial port speed in System → Settings → Advanced.

• Add columns for viewing read/write/checksum errors to Volume Status screen.

• Allow non-root NFS mounts and the ability to specify a listen address for NFS.

• Add ability to specify multiple paths and multiple CIDR masks when creating an NFS share.

• Enable sysvipc in the Plugins Jail. Some applications, such as PostreSQL, require this.

• Add ZLE (zero length encryption) as a ZFS compression option. ZLE is a fast and simple compression algorithm to eliminate runs of zeroes.

• New ZFS pools are created with the autoexpand property set. This means that the pool will be resized according to the size of the expanded device. If the new device is part of a mirror or RAIDZ, all devices within that mirror/RAIDZ group must be expanded before the new space is made available to the pool.

1.4 Hardware Recommendations

Since FreeNAS® 8.3.0 is based on FreeBSD 8.3, it supports the same hardware found in the amd64 and i386 sections of the FreeBSD 8.3 Hardware Compatibility List.

Actual hardware requirements will vary depending upon what you are using your FreeNAS® system for. This section provides some guidelines to get you started. You can also skim through the FreeNAS® Hardware Forum for performance tips from other FreeNAS® users or to post questions regarding the hardware best suited to meet your requirements.

1.4.1 Architecture

While FreeNAS® is available for both 32-bit and 64-bit architectures, 64-bit hardware is recommended for speed and performance. A 32-bit system can only address up to 4 GB of RAM, making it poorly suited to the RAM requirements of ZFS. If you only have access to a 32-bit system, consider using UFS instead of ZFS.

1.4.2 RAM

The best way to get the most out of your FreeNAS® system is to install as much RAM as possible. If your RAM is limited, consider using UFS until you can afford better hardware. ZFS typically requires a minimum of 8 GB of RAM in order to provide good performance. 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. For systems with large disk capacity (greater than 6 TB), a general rule of thumb is 1 GB of RAM for every 1TB of storage. This post describes how RAM is used by ZFS.

NOTE: by default, ZFS disables pre-fetching (caching) for systems containing less than 4 GB of usable RAM. Not using pre-fetching can really slow down performance. 4 GB of usable RAM is not the same thing as 4 GB of installed RAM as the operating system resides in RAM. This means that the practical pre-fetching threshold is 6 GB, or 8 GB of installed RAM. You can still use ZFS with less RAM, but performance will be effected.

If you plan to use ZFS deduplication, a general rule of thumb is 5 GB RAM per TB of storage to be deduplicated.

If you use Active Directory with FreeNAS®, add an additional 2 GB of RAM for winbind's internal cache.

If you are installing FreeNAS® on a headless system, disable the shared memory settings for the video card in the BIOS.

1.4.3 Compact or USB Flash

The FreeNAS® operating system is a running image. This means that it should not be installed onto a hard drive, but rather to a USB or compact flash device that is at least 2 GB in size. If you don't have compact flash, you can instead use a USB thumb drive that is dedicated to the running image and which stays inserted in the USB slot. While technically you can install FreeNAS® onto a hard drive, this is discouraged as you will lose the storage capacity of the drive. In other words, the operating system will take over the drive and will not allow you to store data on it, regardless of the size of the drive.

The FreeNAS® installation will partition the operating system drive into two ~1 GB partitions. One partition holds the current operating system and the other partition is used when you upgrade. This allows you to safely upgrade to a new image or to revert to an older image should you encounter problems.

1.4.4 Storage Disks and Controllers

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

FreeNAS® supports hot pluggable drives. Make sure that AHCI is enabled in the BIOS. Make sure that AHCI is enabled in the BIOS. Note that hot plugging is not the same as hot swapping.

If you need reliable disk alerting, immediate reporting of a failed drive, and or swapping, use a fully manageable hardware RAID controller such as a LSI MegaRAID controller or a 3Ware twa-compatible controller. Until FreeBSD commits zfsd, its implementation of ZFS will not notice that a drive is gone until you reboot or put the volume on high load.

If you have some money to spend and wish to optimize your disk subsystem, consider your read/write needs, your budget, and your RAID requirements.

For example, moving the the ZIL (ZFS Intent Log) to a dedicated SSD only helps performance if you have synchronous writes, like a database server. SSD cache devices only help if your working set is larger than system RAM, but small enough that a significant percentage of it will fit on the SSD.

If you have 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.

If you have the budget and high performance is a key requirement, 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 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 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.

If you will be using 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, you can not format less than 3 GB of space with ZFS. However, on a drive that is below the minimum recommended size you lose a fair amount of storage space to swap: for example, on a 4 GB drive, 2 GB will be reserved for swap.

If you are new to ZFS and are purchasing hardware, read through ZFS Storage Pools Recommendations first.

ZFS uses dynamic block sizing, meaning that it is capable of striping different sized disks. However, if you care about performance, use disks of the same size. Further, when creating a RAIDZ, only the size of the smallest disk will be used on each disk.

1.4.5 Network Interfaces

The FreeBSD Ethernet section of the 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 if you are purchasing a new interface.

At a minimum you will want to use a GigE interface. While GigE interfaces and switches are affordable for home use, it should be noted that modern disks can easily saturate 110 MB/s. If you require a higher network throughput, you can "bond" multiple GigE cards together using the LACP type of Link Aggregation. However, any switches will need to support LACP which means you will need a more expensive managed switch rather than a home user grade switch.

If network performance is a requirement and you have some money to spend, use 10 GigE interfaces and a managed switch. If you are purchasing a managed switch, consider one that supports LACP and jumbo frames as both can be used to increase network throughput.

NOTE: at this time the following are not supported: InfiniBand, FibreChannel over Ethernet, or wireless interfaces.

If network speed is a requirement, consider both your hardware and the type of shares that you create. On the same hardware, CIFS will be slower than FTP or NFS as Samba is single-threaded. If you will be using CIFS, use a fast CPU.

1.4.6 RAID Overview

Data redundancy and speed are important considerations for any network attached storage system. Most NAS systems use multiple disks to store data, meaning you should decide which type of RAID to use before installing FreeNAS®. This section provides an overview of RAID types to assist you in deciding which type best suits your requirements.

RAID 0: provides optimal performance and allows you to add disks as needed. Provides zero redundancy, meaning if one disk fails, all of the data on all of the disks is lost. The more disks in the RAID 0, the more likely the chance of a failure.

RAID 1: provides redundancy as data is copied (mirrored) to two or more drives. Provides good read performance but may have slower write performance, depending upon how the mirrors are setup and the number of ZILs and L2ARCs.

RAID 5: requires a minimum of three disks and can tolerate the loss of one disk without losing data. Disk reads are fast but write speed can be reduced by as much as 50%. If a disk fails, it is marked as degraded but the system will continue to operate until the drive is replaced and the RAID is rebuilt. However, should another disk fail before the RAID is rebuilt, all data will be lost. If your FreeNAS® system will be used for steady writes, RAID 5 is a poor choice due to the slow write speed.

RAID 6: requires a minimum of four disks and can tolerate the loss of two disks without losing data. Benefits from having many disks as performance, fault tolerance, and cost efficiency are all improved relatively with more disks. The larger the failed drive, the longer it takes to rebuild the array. Reads are very fast but writes are slower than a RAID 5.

RAID 10: requires a minimum of four disks and number of disks is always even as this type of RAID mirrors striped sets. This type of RAID can survive the failure of any one drive. If you lose a second drive from the same mirrored set, you will lose the array. However, if you lose a second drive from a different mirrored set, the array will continue to operate in a degraded state. RAID 10 significantly outperforms RAIDZ2, especially on writes.

RAID 60: requires a minimum of eight disks. Combines RAID 0 striping with the distributed double parity of RAID 6 by striping 2 4-disk RAID 6 arrays. RAID 60 rebuild times are half that of RAID 6.

RAIDZ1: ZFS software solution that is equivalent to RAID5. Its advantage over RAID 5 is that it avoids the write-hole and does not require any special hardware, meaning it can be used on commodity disks. If your FreeNAS® system will be used for steady writes, RAIDZ is a poor choice due to the slow write speed.

RAIDZ2: double-parity ZFS software solution that is similar to RAID-6. Its advantage over RAID 5 is that it also avoids the write-hole and does not require any special hardware, meaning it can be used on commodity disks. RAIDZ2 allows you to lose one drive without any degradation as it basically becomes a RAIDZ1 until you replace the failed drive and restripe. At this time, RAIDZ2 on FreeBSD is slower than RAIDZ1.

RAIDZ3: triple-parity ZFS software solution. RAIDZ3 offers three parity drives and can operate in degraded mode if up to three drives fail with no restrictions on which drives can fail.

NOTE: instead of mixing ZFS RAID with hardware RAID, it is recommended that you place your hardware RAID controller in JBOD mode and let ZFS handle the RAID. According to Wikipedia: “ZFS can not fully protect the user's data when using a hardware RAID controller, as it is not able to perform the automatic self-healing unless it controls the redundancy of the disks and data. ZFS prefers direct, exclusive access to the disks, with nothing in between that interferes. If the user insists on using hardware-level RAID, the controller should be configured as JBOD mode (i.e. turn off RAID-functionality) for ZFS to be able to guarantee data integrity. Note that hardware RAID configured as JBOD may still detach disks that do not respond in time; and as such may require TLER/CCTL/ERC-enabled disks to prevent drive dropouts. These limitations do not apply when using a non-RAID controller, which is the preferred method of supplying disks to ZFS.”

When determining the type of RAIDZ to use, consider whether your goal is to maximum disk space or maximum performance:

• RAIDZ1 maximizes disk space and generally performs well when data is written and read in large chunks (128K or more).

• RAIDZ2 offers better data availability and significantly better mean time to data loss (MTTDL) than RAIDZ1.

• A mirror consumes more disk space but generally performs better with small random reads.

For better performance, a mirror is strongly favored over any RAIDZ, particularly for large, uncacheable, random read loads.

When determining how many disks to use in a RAIDZ, the following configurations provide optimal performance. Array sizes beyond 12 disks are not recommended.

• Start a RAIDZ1 at at 3, 5, or 9 disks.

• Start a RAIDZ2 at 4, 6, or 10 disks.

• Start a RAIDZ3 at 5, 7, or 11 disks.

The recommended number of disks per group is between 3 and 9. If you have more disks, use multiple groups.

The following resources can also help you determine the RAID configuration best suited to your storage needs:

• What is the Best RAIDZ Configuration

• Getting the Most out of ZFS Pools

• RAIDZ Configuration Requirements and Recommendations

• What number of drives are allowed in a RAIDZ config?

NOTE: NO RAID SOLUTION PROVIDES A REPLACEMENT FOR A RELIABLE BACKUP STRATEGY. BAD STUFF CAN STILL HAPPEN AND YOU WILL BE GLAD THAT YOU BACKED UP YOUR DATA WHEN IT DOES. See section 6.1 Periodic Snapshot Tasks and section 6.2 Replication Tasks if you would like to use ZFS snapshots and rsync as part of your backup strategy.

1.4.7 ZFS Overview

While ZFS isn't hardware, an overview is included in this section as the decision to use ZFS may impact on your hardware choices and whether or not to use hardware RAID.

If you are new to ZFS, the Wikipedia entry on ZFS provides an excellent starting point to learn about its features. These resources are also useful to bookmark and refer to as needed:

• ZFS Evil Tuning Guide

• FreeBSD ZFS Tuning Guide

• ZFS Best Practices Guide

• ZFS Administration Guide

• Becoming a ZFS Ninja (video)

• ZFS Troubleshooting Guide

ZFS version numbers change as features are introduced and are incremental, meaning that a version includes all of the features introduced by previous versions. Table 1.1a summarizes various ZFS versions, the features which were added by that ZFS version, and in which version of FreeNAS® that ZFS version was introduced.

Table 1.1a: Summary of ZFS Versions

The following is a glossary of terms used by ZFS:

Pool: a collection of devices that provides physical storage and data replication managed by ZFS. This pooled storage model eliminates the concept of volumes and the associated problems of partitions, provisioning, wasted bandwidth and stranded storage. Thousands of file systems can draw from a common storage pool, each one consuming only as much space as it actually needs. The combined I/O bandwidth of all devices in the pool is available to all file systems at all times. The Storage Pools Recommendations of the ZFS Best Practices Guide provides detailed recommendations for creating the storage pool.

Dataset: once a pool is created, it can be divided into datasets. A dataset is similar to a folder in that it supports permissions. A dataset is also similar to a filesystem in that you can set properties such as quotas and compression.

Zvol: ZFS storage pools can provide volumes for applications that need raw-device semantics such as swap devices or iSCSI device extents. In other words, a zvol is a virtual block device in a ZFS storage pool.

Snapshot: a read-only point-in-time copy of a file system. Snapshots can be created quickly and, if little data changes, new snapshots take up very little space. For example, a snapshot where no files have changed takes 0 MB of storage, but if you change a 10 GB file it will keep a copy of both the old and the new 10 GB version. Snapshots provide a clever way of keeping a history of files, should you need to recover an older copy or even a deleted file. For this reason, many administrators take snapshots often (e.g. every 15 minutes), store them for a period of time (e.g. for a month), and store them on another system. Such a strategy allows the administrator to roll the system back to a specific time or, if there is a catastrophic loss, an off-site snapshot can restore the system up to the last snapshot interval (e.g. within 15 minutes of the data loss). Snapshots can be cloned or rolled back, but the files on the snapshot cannot be accessed independently.

Clone: a writable copy of a snapshot which can only be created on the same ZFS volume. Clones provide an extremely space-efficient way to store many copies of mostly-shared data such as workspaces, software installations, and diskless clients. Clones do not inherit the properties of the parent dataset, but rather inherit the properties based on where the clone is created in the ZFS pool. Because a clone initially shares all its disk space with the original snapshot, its used property is initially zero. As changes are made to the clone, it uses more space.

Deduplication: the process of eliminating duplicate copies of data in order to save space. Once deduplicaton occurs, it can improve ZFS performance as less data is written and stored. However, the process of deduplicating the data is RAM intensive and a general rule of thumb is 5 GB RAM per TB of storage to be deduplicated. In most cases, enabling compression will provide comparable performance. In FreeNAS® 8.3, deduplication can be enabled at the dataset level and there is no way to undedup data once it is deduplicated: switching deduplication off has NO AFFECT on existing data. The more data you write to a deduplicated dataset, the more RAM it requires, and there is no upper bound on this. When the system starts storing the DDTs (dedup tables) on disk because they no longer fit into RAM, performance craters. Furthermore, importing an unclean pool can require between 3-5 GB of RAM per TB of deduped data, and if the system doesn't have the needed RAM it will panic, with the only solution being to add more RAM or to recreate the pool. Think carefully before enabling dedup!

ZIL: (ZFS Intent Log) is effectively a filesystem journal that manages writes. You can increase performance by dedicating a device (typically an SSD or a dedicated disk) to hold the ZIL by creating a log device in Volume Manager. If you are using VMWare, the speed of the ZIL device is essentially the write performance bottleneck when using NFS. In this scenario, iSCSI will perform better than NFS. If you decide to create a dedicated cache device to speed up NFS writes, it can be half the size of system RAM as anything larger than that is unused capacity. Mirroring the ZIL device won't increase the speed, but it will help performance and reliability if one of the devices fails. If you lose a non-mirrored ZIL device on a ZFSv15 pool, the pool is unrecoverable and the pool must be recreated and the data restored from a backup. If you lose a non-mirrored ZIL device on a ZFSv28 pool, only the data in the ZIL which has not been written to the pool will be lost. You can replace the lost ZIL device in the View Volumes → Volume Status screen.

L2ARC: on-disk cache used to manage reads. Losing an L2ARC device will not affect the integrity of the storage pool, but may have an impact on read performance, depending upon the workload and the ratio of dataset size to cache size. You can learn more about how L2ARC works here.

Scrub: similar to ECC memory scrubbing, all data is read to detect latent errors while they're still correctable. A scrub traverses the entire storage pool to read every data block, validates it against its 256-bit checksum, and repairs it if necessary.

2 Installing and Upgrading FreeNAS®

Before installing, it is important to remember that the FreeNAS® operating system must be installed on a separate device from the drive(s) that will hold the storage data. In other words, if you only have one disk drive you will be able to use the FreeNAS® graphical interface but won't be able to store any data, which after all, is the whole point of a NAS system. If you are a home user who is experimenting with FreeNAS®, you can install FreeNAS® on an inexpensive USB thumb drive and use the computer's disk(s) for storage.

This section describes the following:

• Getting FreeNAS®

• FreeNAS™ in a Virtual Environment

• Installing from CDROM

• Burning an IMG File

• Initial Setup

• Upgrading FreeNAS®

2.1 Getting FreeNAS®

FreeNAS® 8.3.0 can be downloaded from the FreeNAS-8.3.0 Sourceforge page. FreeNAS® is available for 32-bit (x386) and 64-bit (x64) architectures. You should download the architecture type that matches your CPU's capabilities..

The download page contains the following types of files:

• GUI_upgrade.xz: this is a compressed firmware upgrade image and requires a previous installation of FreeNAS® 8.x. If your intent is to upgrade FreeNAS®, download the correct .xz file for your architecture and see section 2.6 Upgrading FreeNAS®.

• .img.xz: this is a compressed image that needs to be written to a USB or compact flash device. Section 2.4 Burning an IMG File describes how to write the image. The format changed in 8.2.0-BETA3 from xz to txz. This means that you should download the .txz version if you are upgrading from 8.2.0-BETA3 or higher. If you are upgrading from any version prior to 8.2.0-BETA3, use the .xz file.

• .iso: this is a bootable image that can be written to CDROM. This is described in more detail in section 2.3 Installing from CDROM.

The download directory also contains the Release Notes for that version of FreeNAS®. This file contains the changes introduced by that release, any known issues, and the SHA256 checksums of the files in the download directory. The command you use to verify the checksum varies by operating system:

• on a BSD system use the command sha256 name_of_file

• on a Linux system use the command sha256sum name_of_file

• on a Mac system use the command shasum -a 256 name_of_file

• on a Windows system or Mac system, you can install a utility such as HashCalc or HashTab

2.2 FreeNAS® in a Virtual Environment

In order to install or run FreeNAS® within a virtual environment, you will need to create a virtual machine that meets the following minimum requirements:

• 512 MB base memory size

• a virtual disk at least 4 GB in size to hold the operating system and swap

• at least one more virtual disk at least 4 GB in size to be used as data storage

• a bridged adapter

This section demonstrates how to create and access a virtual machine within the VirtualBox and VMWare EXSi environments.

2.2.1 VirtualBox

VirtualBox is an open source virtualization program originally created by Sun Microsystems. VirtualBox runs on Windows, BSD, Linux, Macintosh, and OpenSolaris. It can be configured to use a downloaded FreeNAS® .iso or .img.xz file, and makes a good testing environment for practicing configurations or learning how to use the features provided by FreeNAS®.

2.2.1.1 Creating the Virtual Machine

To create the virtual machine, start VirtualBox and click the New button, seen in Figure 2.2a, to start the new virtual machine wizard.

Figure 2.2a: Initial VirtualBox Screen

Click the Next button to see the screen in Figure 2.2b.

Figure 2.2b: Type in a Name and Select the Operating System for the New Virtual Machine

Enter a name for the virtual machine, then click the Operating System drop down menu and select BSD which will automatically change the Version to FreeBSD. Click Next to see the screen in Figure 2.2c.

Figure 2.2c: Select the Amount of Memory Reserved for the Virtual Machine

The base memory size must be changed to at least 512 MB. If your system has enough memory, select at least 4096 MB so that you can use ZFS. When finished, click Next to see the screen in Figure 2.2d.

Figure 2.2d: Select Whether to Use an Existing or Create a New Virtual Disk

This screen is used to create the virtual hard disk to install FreeNAS® into. Click Next to launch the "Create New Virtual Disk Wizard". Click the Next button again to see the screen in Figure 2.2e.

Figure 2.2e: Create New Virtual Disk Wizard

The wizard can be used to create the following types of virtual disk formats:

• VDI: Virtual Disk Image is the format used by VirtualBox. Select this option if you downloaded the ISO.

• VMDK: Virtual Machine Disk is the format used by VMWare. Select this option if you converted the .img file to VMDK format using the instructions in section 2.2.1.4 Running FreeNAS® from a USB Image.

• VHD: Virtual Hard Disk is the format used by Windows Virtual PC.

• HDD: is the format used by Parallels.

Once you make a selection, click the Next button to see the screen in Figure 2.2f:

Figure 2.2f: Select the Storage Type for the Virtual Disk

You can now choose whether you want "Dynamically expanding storage" or "Fixed-size storage". The first option uses disk space as needed until it reaches the maximum size that you will set in the next screen. The second option creates a disk the same size as that specified amount of disk space, whether it is used or not. Choose the first option if you are worried about disk space; otherwise, choose the second option as it allows VirtualBox to run slightly faster. Once you select Next, you'll see the screen in Figure 2.2g.

Figure 2.2g: Select the File Name and Size of the Virtual Disk

This screen is used to set the size (or upper limit) of the virtual machine. Increase the default size to 4 GB. Use the folder icon to browse to a directory on disk with sufficient space to hold the virtual machine.

Once you make your selection and press Next, you will see a summary of your choices. Use the Back button to return to a previous screen if you need to change any values. Otherwise, click Finish to finish using the wizard. The virtual machine will be listed in the left frame, as seen in the example in Figure 2.2h.

Figure 2.2h: The New Virtual Machine

2.2.1.2 Creating Devices for Storage and Installation Media

Next, create the virtual disk(s) to be used for storage. Click the Storage hyperlink in the right frame to access the storage screen seen in Figure 2.2i:

Figure 2.2i: The Storage Settings of the Virtual Machine

Click the Add Attachment button, select Add Hard Disk from the pop-up menu, then click the Create New Disk button. This will launch the Create New Virtual Disk Wizard (seen in Figures 2.2e and 2.2f). Since this disk will be used for storage, create a size appropriate to your needs, making sure that it is at least 4 GB in size. If you wish to practice RAID configurations, create as many virtual disks as you need. You will be able to create 2 disks on the IDE controller. If you need additional disks, click the Add Controller button to create another controller to attach disks to.

Next, create the device for the installation media.

If you will be installing from an ISO, highlight the word Empty, then click the CD icon as seen in Figure 2.2j.

Figure 2.2j: Configuring the ISO Installation Media

Click “Choose a virtual CD/DVD disk file...” to browse to the location of the .iso file. Alternately, if you have burned the .iso to disk, select the detected “Host Drive”.

NOTE: depending upon the extensions available in your CPU, you may or may not be able to use a 64-bit ISO on a 64-bit system. If you receive the error "your CPU does not support long mode" when you try to boot a 64-bit ISO, your CPU either does not have the required extension or AMD-V/VT-x is disabled in the system BIOS. You can still use the 32-bit version of the ISO, but ZFS performance will be reduced.

2.2.1.3 Configuring the Bridged Adapter

To configure the network adapter, go to Settings → Network. In the Attached to drop-down menu select Bridged Adapter, then select the name of the physical interface from the Name drop-down menu. In the example shown in Figure 2.2k, the Intel Pro/1000 Ethernet card is attached to the network and has a device name of re0.

Figure 2.2k: Configuring a Bridged Adapter in VirtualBox

Once your configuration is complete, click the Start arrow. If you configured the ISO, install FreeNAS® as described in section 2.3 Installing from CDROM. Once FreeNAS® is installed, press F12 to access the boot menu in order to select the primary hard disk as the boot option. You can permanently boot from disk by removing the CD/DVD device in Storage or by unchecking CD/DVD-ROM in the Boot Order section of System.

If you configured the VMDK, the virtual machine will boot directly into FreeNAS®.

2.2.1.4 Running FreeNAS® from a USB Image

If you will be running FreeNAS® from an .img.xz file instead of installing it from the ISO, you must first download and install the Oracle VM VirtualBox Extension Pack that matches your version of VirtualBox. The extension pack enables USB support.

Next, uncompress and burn the FreeNAS® .img.xz file using the instructions at section 2.4 Burning an Image File. Once the image is burned to the USB device, leave the device inserted.

The VirtualBox GUI does not automatically provide a way to select a USB device to boot from. However, you can use a command line utility to link the USB device to a .vmdk file so that it can be selected as a boot device. To do this on a Windows system, open a command prompt in administrative mode (right-click cmd from the Run menu and select Run as administrator), and run the commands shown in Figure 2.2l. Before running these commands, verify the physical drive number from Start menu → right-click Computer → Manage → Storage → Disk Management. If the USB drive is different than Disk 1, change the number in \\.\PhysicalDrive1 to match the disk number. You can also specify where to save the .vmdk file. Make sure that the security tab of the saved file gives “Full control” permissions to Users so that the file can be accessed by VirtualBox.

Figure 2.2l: Creating the vmdk File in Windows

Once you have a .vmdk file, create a new virtual machine while the USB stick is inserted. When you get to Figure 2.2e, select “Use existing hard disk” and browse to your .vmdk file. Click Next, then Create. This will create the virtual machine and bring you to Figure 2.2h. You can then create your storage disks and bridged adapter as usual. When finished, start the virtual machine and it will boot directly into FreeNAS®.

2.2.2 VMWare ESXi

ESXi is is a "bare-metal" hypervisor architecture created by VMware Inc. Commercial and free versions of the VMWare Vsphere Hypervisor operating system (ESXi) are available from the VMWare website. Once the operating system is installed on supported hardware, use a web browser to connect to its IP address. The welcome screen will provide a link to download the VMware vSphere client which is used to create and manage virtual machines.

Once the VMware vSphere client is installed, use it to connect to the ESXi server. To create a new virtual machine, click File → New → Virtual Machine. The New Virtual Machine Wizard will launch as seen in Figure 2.2m.

Figure 2.2m: New Virtual Machine Wizard

Click Next and input a name for the virtual machine. Click Next and highlight a datastore. An example is shown in Figure 2.2n.

Figure 2.2n: Select a Datastore

Click Next. In the screen shown in Figure 2.2o, click Other then select a FreeBSD architecture that matches the FreeNAS® architecture.

Figure 2.2o: Select the Operating System

Click Next and create a virtual disk file of 4 GB to hold the FreeNAS® operating system, as shown in Figure 2.2p.

Figure 2.2p: Create a Disk for the Operating System

Click Next then Finish. Your virtual machine will be listed in the left frame. Right-click the virtual machine and select Edit Settings to access the screen shown in Figure 2.2q.

Figure 2.2q: Virtual Machine's Settings

Increase the Memory Configuration to at least 512 MB .

Under CPUs, make sure that only 1 virtual processor is listed, otherwise you will be unable to start any FreeNAS® services.

To create a storage disk, click "Hard disk 1" → Add. In the Device Type menu, highlight Hard Disk and click Next. Select "Create a new virtual disk" and click Next. In the screen shown in Figure 2.2r, select the size of the disk. If you would like the size to be dynamically allocated as needed, check the box "Allocate and commit space on demand (Thin Provisioning)". Click Next, then Next, then Finish to create the disk. Repeat to create the amount of storage disks needed to meet your requirements.

Figure 2.2r: Creating a Storage Disk

2.3 Installing from CDROM

If you prefer to install FreeNAS® using a menu-driven installer, download the ISO image that matches the architecture of the system you will install onto (32- or 64-bit) and burn it to a CDROM.

NOTE: the installer on the CDROM will recognize if a previous version of FreeNAS® 8.x is already installed, meaning the CDROM can also be used to upgrade FreeNAS®. However, the installer can not perform an upgrade from a FreeNAS® .7 system.

Insert the CDROM into the system and boot from it. Once the media has finished booting, you will be presented with the console setup menu seen in Figure 2.3a.

Figure 2.3a: FreeNAS® Console Setup

NOTE: if the installer does not boot, check that the CD drive is listed first in the boot order in the BIOS. Some motherboards may require you to connect the CDROM to SATA0 (the first connector) in order to boot from CDROM. If it stalls during boot, check the SHA256 hash of your ISO against that listed in the Release Notes; if the hash does not match, re-download the file. If the hash is correct, try burning the CD again at a lower speed.

Press enter to select the default option of “1 Install/Upgrade to hard drive/flash device, etc.”. The next menu, seen in Figure 2.3b, will list all available drives, including any inserted USB thumb drives which will begin with da. In this example, the user is installing into VirtualBox and has created a 4 GB virtual disk to hold the operating system.

NOTE: at this time, the installer does not check the size of the install media before attempting an installation. A 2 GB device is required, but the install will appear to complete successfully on smaller devices, only to fail at boot. If using a USB thumb drive, a 4 GB drive is recommended as many 2 GB thumb drives have a smaller capacity which will result in a seemingly successful installation that fails to boot.

Figure 2.3b: Selecting Which Drive to Install Into

Use your arrow keys to highlight the USB, compact flash device, or virtual disk to install into, then tab to OK and press enter. FreeNAS® will issue the warning seen in Figure 2.3c, reminding you not to install onto a storage drive.

Figure 2.3c: FreeNAS® Installation Warning

Press enter and FreeNAS® will extract the image from the ISO and transfer it to the device. Once the installation is complete, you should see a message similar to Figure 2.3d.

Figure 2.3d: FreeNAS® Installation Complete

Press enter to return to the first menu, seen in Figure 2.3a. Highlight “3 Reboot System” and press enter. Remove the CDROM. If you installed onto a USB thumb drive, leave the thumb drive inserted. Make sure that the device you installed to is listed as the first boot entry in the BIOS so that the system will boot from it. FreeNAS® should now be able to boot into the Console setup menu described in section 2.5 Initial Setup.

2.4 Burning an IMG File

If your system does not have a CDROM or you prefer to manually write the running image, download the img.xz file. This file will need to be uncompressed and then written to a compact flash card or USB thumbdrive that is 2 GB or larger (4 GB recommended).

NOTE: any data currently saved on the specified device will be erased. If you are writing the image to a compact flash card, make sure that it is MSDOS formatted.

DANGER! The dd command is very powerful and can destroy any existing data on the specified device. Be very sure that you know the device name to write to and that you do not typo the device name when using dd! If you are uncomfortable writing the image yourself, download the .iso file instead and use the instructions in section 2.3 Installing from CDROM.

Once you have written the image to the device, make sure the boot order in the BIOS is set to boot from that device and boot the system. It should boot into the Console setup menu described in section 2.5 Initial Setup.

NOTE: if the image does not boot, check the BIOS and change the USB emulation from CD/DVD/floppy to hard drive. If it still will not boot, check to see if the card/drive is UDMA compliant. Some users have also found that some cheap 2 GB USB sticks do not work as they are not really 2 GB in size, but changing to a 4 GB stick fixes the problem.

2.4.1 Using xzcat and dd on a FreeBSD or Linux System

On a FreeBSD or Linux system, the xzcat and dd commands can be used to uncompress and write the .xz image to an inserted USB thumb drive or compact flash device. Example 2.4a demonstrates writing the image to the first USB device (/dev/da0) on a FreeBSD system. Substitute the filename of your ISO and the device name representing the device to write to on your system.

Example 2.4a: Writing the Image to a USB Thumb Drive

xzcat FreeNAS-8.3.0-RELEASE-x64-img.xz | dd of=/dev/da0 bs=64k

0+244141 records in

0+244141 records out

2000000000 bytes transferred in 326.345666 secs (6128471 bytes/sec)

When using the dd command:

• of= refers to the output file; in our case, the device name of the flash card or removable USB drive. You may have to increment the number in the name if it is not the first USB device. On Linux, use /dev/sda to refer to the first USB device.

• bs= refers to the block size

2.4.2 Using Keka and dd on an OS X System

On an OS X system, you can download and install Keka to uncompress the image. In FINDER, navigate to the location where you saved the downloaded .xz file. Right-click the .xz file and select 'Open With Keka'. After a few minutes you will have a large file with the same name, but no .xz extension.

Insert the USB thumb drive and go to Launchpad → Utilities → Disk Utility. Unmount any mounted partitions on the USB thumb drive. Check that the USB thumb drive has only one partition, otherwise you will get GPT partition table errors on boot. If needed, use Disk Utility to setup one partition on the USB drive; selecting "free space" when creating the partition works fine.

Next, determine the device name of the inserted USB thumb drive. From TERMINAL, navigate to your Desktop then type this command:

diskutil list
/dev/disk0
  #:        TYPE NAME            SIZE       IDENTIFIER
  0:   GUID_partition_scheme    *500.1 GB   disk0
  1:                     EFI     209.7 MB   disk0s1
  2:  Apple_HFS Macintosh HD     499.2 GB   disk0s2
  3:  Apple_Boot Recovery HD     650.0 MB   disk0s3  
 /dev/disk1
  #:        TYPE NAME            SIZE       IDENTIFIER
  0:  FDisk_partition_scheme    *8.0 GB     disk1
  1:     DOS_FAT_32 UNTITLED     8.0 GB     disk1s1

This will show you which devices are available to the system. Locate your USB stick and record the path. If you are not sure which path is the correct one for the USB stick, remove the device, run the command again, and compare the difference. Once you are sure of the device name, navigate to the Desktop from TERMINAL, unmount the USB stick, and use the dd command to write the image to the USB stick. In Example 2.4b, the USB thumb drive is /dev/disk1. Substitute the name of your uncompressed file and the correct path to your USB thumb drive.

Example 2.4b: Using dd on an OS X System

diskutil unmountDisk /dev/disk1
Unmount of all volumes on disk1 was successful
dd if=FreeNAS-8.3.0-RELEASE-x64.img of=/dev/disk1 bs=64k

NOTE: if you get the error "Resource busy" when you run the dd command, go to Applications → Utilities → Disk Utility, find your USB thumb drive, and click on its partitions to make sure all of them are unmounted. If you get the error "dd: /dev/disk1: Permission denied", run the dd command by typing sudo dd if=FreeNAS-8.3.0-RELEASE-x64.img of=/dev/disk1 bs=64k, which will prompt for the root user's password.

The dd command will take some minutes to complete. Wait until you get a prompt back and a message that displays how long it took to write the image to the USB drive.

2.4.3 Using 7-Zip and Win32DiskImager on Windows

Windows users will need to download a utility that can uncompress .xz files and a utility that can create a USB bootable image from the uncompressed .img file.

This section will demonstrate how to use 7-Zip and Win32DiskImager to burn the image file. When downloading Win32DiskImager, download the latest version that ends in -binary.zip and use 7-Zip to unzip its executable.

Once both utilities are installed, launch the 7-Zip File Manager and browse to the location containing your downloaded .img.xz file, as seen in Figure 2.4a.

Figure 2.4a: Using 7-Zip to Extract Image File

Click the Extract button, browse to the path to extract to, and click OK. The extracted image will end in .img and is now ready to be written to a USB device using Win32DiskImager.

Next, launch Win32DiskImager, shown in Figure 2.4b. Use the browse button to browse to the location of the .img file. Insert a USB thumb drive and select its drive letter (in this example, drive D). Click the Write button and the image will be written to the USB thumb drive.

Figure 2.4b: Using Win32DiskImager to Write the Image

2.5 Initial Setup

When you boot into FreeNAS®, the Console Setup, shown in Figure 2.5a, will appear at the end of the boot process. If you have access to the the FreeNAS® system's keyboard and monitor, this Console Setup menu can be used to administer the system should the administrative GUI become inaccessible.

Figure 2.5a: FreeNAS® Console Setup Menu

This menu provides the following options:

• 1) Configure Network Interfaces: provides a configuration wizard to configure the system's network interfaces.

• 2) Configure Link Aggregation: allows you to either create a new link aggregation or to delete an existing link aggregation.

• 3) Create VLAN Interface: used to create a VLAN interface.

• 4) Configure Default Route: used to set the IPv4 or IPv6 default gateway. When prompted, input the IP address of the default gateway.

• 5) Configure Static Routes: will prompt for the destination network and the gateway IP address. Re-enter this option for each route you need to add.

• 6) Configure DNS: will prompt for the name of the DNS domain then the IP address of the first DNS server. To input multiple DNS servers, press enter to input the next one. When finished, press enter twice to leave this option.

• 7) Reset WebGUI login credentials: if you are unable to login to the graphical administrative interface, select this option. It will reset the system to not require a username and password to login. Don't forget to immediately set the administrative username and password once you enter the GUI.

• 8) Reset to factory defaults: if you wish to delete all of the configuration changes made in the administrative GUI, select this option. Once the configuration is reset, the system will reboot. You will need to go to Storage → Volumes → Auto Import Volume to re-import your volume.

• 9) Shell: enters a shell in order to run FreeBSD commands. To leave the shell, type exit.

• 10) Reboot: reboots the system.

• 11 Shutdown: halts the system.

During boot, FreeNAS® will automatically try to connect to a DHCP server from all live interfaces. If it successfully receives an IP address, it will display which IP address can be used to access the graphical console. In the example seen in Figure 2.5a, the FreeNAS® system is accessible from http://10.0.2.15.

If your FreeNAS® server is not connected to a network with a DHCP server, you can use the network configuration wizard to manually configure the interface as seen in Example 2.5a. In this example, the FreeNAS® system has one network interface (em0).

Example 2.5a: Manually Setting an IP Address from the Console Menu

Enter an option from 1-11: 1

1) em0

Select an interface (q to quit): 1

Delete existing config? (y/n) n

Configure interface for DHCP? (y/n) n

Configure IPv4? (y/n) y

Interface name: (press enter as can be blank)

Several input formats are supported

Example 1 CIDR Notation:

192.168.1.1/24

Example 2 IP and Netmask separate:

IP: 192.168.1.1

Netmask: 255.255.255.0, or /24 or 24

IPv4 Address: 192.168.1.108/24

Saving interface configuration: Ok

Configure IPv6? (y/n) n

Restarting network: ok

You may try the following URLs to access the web user interface:

http://192.168.1.108

Once the system has an IP address, input that address into a graphical web browser from a computer capable of accessing the network containing the FreeNAS® system. The administrative GUI, shown in Figure 2.5b, should be displayed. If it does not appear, check the following:

• Are proxy settings enabled in the browser configuration? If so, disable the settings and try connecting again.

• If the page does not load, make sure that you can ping the FreeNAS® system's IP address. If the address is in a private IP address range, you will only be able to access the system from within the private network.

• If the user interface loads but is unresponsive or seems to be missing menu items, try using a different web browser. IE9 has known issues and will not display the graphical administrative interface correctly if compatability mode is turned on. If you can't access the GUI using Internet Explorer, use Firefox instead.

Figure 2.5b: FreeNAS® Graphical Configuration Menu

If you click the flashing Alert icon in the upper right corner, it will alert you that you should immediately change the password for the admin user as currently no password is required to login. Section 3.1.2 Admin Account describes how to set the name and password for the account that is used to access the administrative interface.

2.6 Upgrading FreeNAS®

FreeNAS® provides two methods for performing an upgrade: an ISO upgrade or an upgrade using the graphical administrative interface. Unless the Release Notes indicate that your current version requires an ISO upgrade, you can use either upgrade method. Both methods are described in this section.

Before performing an upgrade, always backup your configuration file and your data.

When upgrading, be aware of the following caveats:

• Neither upgrade method can be used to migrate from FreeNAS 0.7x. Instead, install FreeNAS® and either auto-import supported software RAID (described in section 6.3.1) or import supported disks (described in section 6.3.2). You will need to recreate your configuration as the installation process will not import 0.7 configuration settings.

• Upgrades from versions prior to 8.0.1-BETA3 to any later 8.x version must be done using the ISO. For example, upgrading from 8.0-RELEASE to 8.0.3-RELEASE using the GUI will not work as the image size increased from 1 GB to 2 GB between 8.01-BETA2 and 8.0.1-BETA3.

• The format of the file used by the GUI upgrade process changed in 8.2.0-BETA3 from .xz to .txz. This means that you should download the .txz version if you are upgrading from 8.2.0-BETA3 or higher. If you are upgrading from any version prior to 8.2.0-BETA3, use the .xz file.

FreeNAS® supports two operating systems on the operating system device: the current operating system and, if you have performed an upgrade, the previously installed version of the operating system. This allows you to reboot into the previous version should you experience a problem with the upgraded version.

The upgrade process automatically configures the system to boot from the new operating system. Should you experience problems with a newly upgraded operating system, simply select the other boot option (typically F2) at the FreeNAS® console when you see the following options at the very beginning of the boot process. In this example, Boot: F1 refers to the default option (the newly upgraded version), so pressing F2 will boot into the previous version.

F1 FreeBSD
F2 FreeBSD
Boot: F1

2.6.1 Preparing for the Upgrade

Before upgrading the system, perform the following steps:

1. Depending upon the type of upgrade method, download either the .iso or the .GUI_Upgrade.* file that matches the system's architecture. Download the file to the computer that you use to access the FreeNAS® system.

2. Locate and confirm the SHA256 hash for the file that you downloaded in the Release Notes for the version that you are upgrading to.

3. Backup the FreeNAS® configuration in System → Settings → General → Save Config.

4. Warn users that the FreeNAS® shares will be unavailable during the upgrade; you should schedule the upgrade for a time that will least impact users.

5. Stop all services in Services → Control Services.

2.6.2 Using the ISO

To upgrade using this method, download the latest version of the ISO image that matches the architecture of the system (32- or 64-bit) and burn it to a CDROM.

Insert the CDROM into the system and boot from it. Once the media has finished booting into the installation menu, press enter to select the default option of "1 Install/Upgrade to hard drive/flash device, etc." As with a fresh install, the installer will present a screen showing all available drives; select the device FreeNAS® is installed into and press enter.

The installer will recognize that an earlier version of FreeNAS® is installed on the device and will present the message shown in Figure 2.6a.

Figure 2.6a: Upgrading a FreeNAS® Installation

NOTE: if you select No at this screen, the installer will do a fresh install of the version on the CD rather than upgrade the current version. This means that you will have to re-import your disks and restore the backup of your configuration.

To upgrade, press enter to accept the default of Yes. Again, the installer will remind you that the operating system should be installed on a thumb drive. Press enter to start the upgrade. Once the installer has finished unpacking the new image, you will see the menu shown in Figure 2.6b.

Figure 2.6b: FreeNAS® will Preserve and Migrate Settings

The database file that is preserved and migrated contains your FreeNAS® configuration settings.

Press enter and FreeNAS® will indicate that the upgrade is complete and that you should reboot, as seen in Figure 2.6c.

Figure 2.6c: Upgrade is Complete

During the reboot there may be a conversion of the previous configuration database to the new version of the database. This happens during the "Applying database schema changes" line in the reboot cycle. This conversion can take a long time to finish so be patient and the boot should complete normally. If for some reason you end up with database errors but the graphical administrative interface is accessible, go to Settings → General and use the Upload Config button to upload the configuration that you saved before you started the upgrade.

2.6.3 From the GUI

To perform the upgrade using this method, go to System → Settings → Advanced → Firmware Update as shown in Figure 2.6d.

Figure 2.6d: Upgrading FreeNAS® From the GUI

Use the drop-down menu to select an existing volume to temporarily place the firmware file during the upgrade. Alternately, select "Memory device" to allow the system to use system RAM to create a temporary RAM disk to be used during the upgrade. After making your selection, click the Apply Update button. You will be prompted to browse to the location of the downloaded .txz file and to paste its SHA256 sum.

When finished, click the Apply Update button to begin the upgrade progress. Behind the scenes, the following steps are occurring:

• the SHA256 hash is confirmed and an error will display if it does not match; if you get this error, double-check that you pasted the correct checksum and try pasting again

• the new image is uncompressed and written to the USB compact or flash drive; this can take a few minutes so be patient

• once the new image is written, you will momentarily lose your connection as the FreeNAS® system will automatically reboot into the new version of the operating system

• FreeNAS® will actually reboot twice: once the new operating system loads, the upgrade process applies the new database schema and reboots again

• assuming all went well, the FreeNAS® system will receive the same IP from the DHCP server; refresh your browser after a moment to see if you can access the system

2.6.4 If Something Goes Wrong

If the FreeNAS® system does not become available after the upgrade, you will need physical access to the system to find out what went wrong. From the console menu you can determine if it received an IP address and use option "1) Configure Network Interfaces" if it did not.

If this does not fix the problem, go into option "9) Shell" and read the system log with this command:

more /var/log/messages

If the problem is not obvious or you are unsure how to fix it, see section 10 FreeNAS® Support Resources.

If the system remains inaccessible and you wish to revert back to the previous installation, type reboot from the shell or select "10) Reboot" from the console menu. Watch the boot screens and press the other boot option (typically F2) when you see this menu:

F1 FreeBSD
F2 FreeBSD
Boot: F1

NOTE: if a previously working FreeNAS® system hangs after a FreeNAS® upgrade, check to see if there is a BIOS/BMC firmware upgrade available as that may fix the issue.

2.6.5 Upgrading a ZFS Pool

FreeNAS® 8.3.0 supports ZFSv28, while previous 8.x versions of FreeNAS® use ZFSv15. This means that any existing or imported ZFS volumes (pools) will still be at ZFSv15, whereas any new pools that you create will be at version ZFSv28.

If you wish to upgrade your existing ZFS pool after upgrading to FreeNAS® 8.3.0, be aware of the following caveats first:

• the ZFS version upgrade must be performed from the command line, it can not be performed using the GUI.

• the pool upgrade is a one-way street meaning that if you change your mind you can not go back to an earlier ZFS version or downgrade to an earlier version of FreeNAS® that does not support ZFSv28.

• before performing any operation that may affect the data on a storage disk, always backup your data first and verify the integrity of the backup. While it is unlikely that the pool upgrade will affect the data, it is always better to be safe than sorry.

To perform the ZFS version upgrade, open Shell. The following commands will determine the pool state and version. In this example, the pool name is volume1 and the ZFS version is 15.

zfs status
pool: volume1                                                                 
state: ONLINE                                                                  
status: The pool is formatted using an older on-disk format.  The pool can      
       still be used, but some features are unavailable.                       
action: Upgrade the pool using 'zpool upgrade'.  Once this is done, the         
       pool will no longer be accessible on older software versions.           
scan: none requested                                                          
config:                                                                                                                                                        
       NAME        STATE     READ WRITE CKSUM                                  
       volume1     ONLINE       0     0     0                                  
         raidz1-0  ONLINE       0     0     0                                  
           ada0p2  ONLINE       0     0     0                                  
           ada1p2  ONLINE       0     0     0                                  
           ada2p2  ONLINE       0     0     0                                  
           ada3p2  ONLINE       0     0     0                                                                                                                
errors: No known data errors 
zpool get version volume1
NAME     PROPERTY  VALUE  SOURCE
volume1  version   15     default

Next, verify that the status of the pool is healthy:

zpool status -x
all pools are healthy

NOTE: do not upgrade the pool if its status does not show as healthy.

To upgrade a pool named volume1:

zpool upgrade volume1                                         
This system is currently running ZFS pool version 28.                           
Successfully upgraded 'volume1' from version 15 to version 28                   

zpool get version volume1                                     
NAME     PROPERTY  VALUE    SOURCE                                              
volume1  version   28       default

Section 2: Using the Graphical Interface

This section of the Guide describes all of the configuration screens available within the FreeNAS® graphical administrative interface. It begins with a Quick Start Guide that provides an overview of the FreeNAS® configuration workflow.

The configuration screens are listed in the order that they appear within the FreeNAS® configuration tree found in the left frame of the graphical administrative interface:

NOTE: it is important to use the GUI (or the console) for all configuration changes. FreeNAS® uses a configuration database to store its settings. While you can use the command line to modify your configuration, changes made at the command line are not written to the configuration database. This means that any changes made at the command line will not persist after a reboot and will be overwritten by the values in the configuration database during an upgrade.

3 Quick Start Guide and Account Configuration

This section contains a Quick Start Guide to get you started with your FreeNAS® configuration. It is followed by the account section of the GUI which allows you to change the administrative password and manage users and groups.

3.1 Quick Start Guide

This section demonstrates the initial preparation that should be performed before you start to configure the FreeNAS® system. It then provides an overview of the configuration workflow along with pointers to the section in the 8.3.0 Users Guide that contains the details and configuration examples for each step in the configuration workflow.

3.1.1 Set Administrative Access

By default, no password is required to access the FreeNAS® administrative interface using the built-in admin account. For security reasons, you should immediately change the default administrative account name and set a password for that account using the instructions in section 3.2.1 Admin Account. A flashing red alert will appear in the upper right corner of the administrative GUI until you set this account information.

NOTE: at this time, FreeNAS® only supports one user account for accessing the administrative GUI.

3.1.2 Set the Administrative Email Address

FreeNAS® provides an Alert icon in the upper right corner to provide a visual indication of events that warrant administrative attention. The alert system automatically emails the root user account whenever an alert is issued. FreeNAS® also sends a daily email to the root user which should be read in order to determine the overall health of the system.

To set the email address for the root account, go to Account → Users → View Users. Click the Change E-mail button associated with the root user account and input the email address of the person to receive the administrative emails.

3.1.3 Enable Console Logging

To view system messages within the graphical administrative interface, go to System → Settings → Advanced. Check the box “Show console messages in the footer” and click Save. The output of tail -f /var/log/messages will now be displayed at the bottom of the screen. If you click the console messages area, it will pop-up as a window, allowing you to scroll through the output and to copy its contents.

You are now ready to start configuring the FreeNAS® system. Typically, the configuration workflow will use the following steps in this order:

3.1.4 Configure Volumes

FreeNAS® supports the creation of both UFS and ZFS volumes; however, ZFS volumes are recommended to get the most out of your FreeNAS® system.

When creating a volume, you have several choices depending upon your storage requirements and whether or not data already exists on the disk(s). The following options are available:

1. Auto-import an existing UFS disk, gstripe (RAID0), gmirror (RAID1), or graid3 (RAID3) in Storage → Volumes → Auto-import.

2. Auto-import an existing ZFS disk, stripe, mirror, RAIDZ1, RAIDZ2, or RAIDZ3 in Storage → Volumes → Auto-import. Auto-importing is described in more detail in section 6.3.1 Auto Importing Volumes.

3. Import a disk that is formatted with UFS, NTFS, MSDOS, or EXT2 in Storage → Volumes → Import. This is described in more detail in section 6.3.2 Importing Volumes.

4. Format disk(s) with UFS and optionally create a gstripe (RAID0), gmirror (RAID1), or graid3 (RAID3) in Storage → Volumes → Volume Manager.

5. Format disk(s) with ZFS and optionally create a stripe, mirror, RAIDZ1, RAIDZ2, or RAIDZ3 in Storage → Volumes → Volume Manager. Formatting disks is described in more detail in section 6.3.3 Volume Manager.

If you format your disk(s) with ZFS, additional options are available:

1. Dedicate a disk(s) to the ZFS log or cache as described in section 6.3.3 Volume Manager .

2. Divide the ZFS pool into datasets to provide more flexibility when configuring user access to data. Dataset creation is described in section 6.3.5 Creating ZFS Datasets.

3. Create a Zvol to be used when configuring an iSCSI device extent. Zvol creation is described in section 6.3.6 Creating a zvol.

3.1.5 Create Users/Groups or Integrate with AD/LDAP

FreeNAS® supports a variety of user access scenarios:

• the use of an anonymous or guest account that everyone in the network uses to access the stored data

• the creation of individual user accounts where each user has access to their own ZFS dataset

• the addition of individual user accounts to groups where each group has access to their own volume or ZFS dataset

• the import of existing accounts from an OpenLDAP or Active Directory server

When configuring your FreeNAS® system, select one of the following, depending upon whether or not the network has an existing OpenLDAP or Active Directory domain. OpenLDAP and Active Directory are mutually exclusive, meaning that you can not use both but must choose one or the other.

1. Manually create users and groups. User management is described in section 3.2.3 Users and group management is described in section 3.2.2 Groups.

2. Import existing Active Directory account information using the instructions in section 8.2 Active Directory.

3. Import existing OpenLDAP account information using the instructions in section 8.8 LDAP.

3.1.6 Configure Permissions

Setting permissions is an important aspect of configuring access to storage data. The graphical administrative interface is meant to set the initial permissions in order to make a volume or dataset accessible as a share. Once a share is available, the client operating system should be used to fine-tune the permissions of the files and directories that are created by the client.

Configured volumes and datasets will appear in Storage → Volumes. Each volume and dataset will have its own Configure Permissions option, allowing for greater flexibility when providing access to data.

Before creating your shares, determine which users should have access to which data. This will help you to determine if multiple volumes, datasets, and/or shares should be created to meet the permissions needs of your environment.

3.1.7 Configure Sharing

Once your volumes have been configured with permissions, you are ready to configure the type of share or service that you determine is suitable for your network.

FreeNAS® supports several types of shares and sharing services for providing storage data to the clients in a network. It is recommended that you select only one type of share per volume or dataset in order to prevent possible conflicts between different types of shares. The type of share you create depends upon the operating system(s) running in your network, your security requirements, and expectations for network transfer speeds. The following types of shares and services are available:

• Apple (AFP): FreeNAS® uses Netatalk to provide sharing services to Apple clients. This type of share is a good choice if all of your computers run Mac OS X. Configuration examples can be found in section 7.1.

• Unix (NFS): this type of share is accessible by Mac OS X, Linux, BSD, and professional/enterprise versions of Windows. It is a good choice if there are many different operating systems in your network. Configuration examples can be found in section 7.2.

• Windows (CIFS): FreeNAS® uses Samba to provide the SMB/CIFS sharing service. This type of share is accessible by Windows, Mac OS X, Linux, and BSD computers, but it is slower than an NFS share. If your network contains only Windows systems, this is a good choice. Configuration examples can be found in section 7.3.

• FTP: this service provides fast access from any operating system, using a cross-platform FTP and file manager client application such as Filezilla. FreeNAS® supports encryption and chroot for FTP. Configuration examples can be found in section 8.6.

• SSH: this service provides encrypted connections from any operating system using SSH command line utilities or the graphical WinSCP application for Windows clients. Configuration examples can be found in section 8.14.

• iSCSI: FreeNAS® uses istgt to export virtual disk drives that are accessible to clients running iSCSI initiator software. Configuration examples can be found in section 8.7.

3.1.8 Start Applicable Service(s)

Once you have configured your share or service you will need to start its associated service(s) in order to implement the configuration. By default, all services are off until you start them. The status of services is managed using Services → Control Services. To start a service, click its red OFF button. After a second or so, it will change to a blue ON, indicating that the service has been enabled. Watch the console messages as the service starts to determine if there are any error messages.

3.1.9 Test Configuration from Client

If the service successfully starts, try to make a connection to the service from a client system. For example, use Windows Explorer to try to connect to a CIFS share, use an FTP client such as Filezilla to try to connect to an FTP share, or use Finder on a Mac OS X system to try to connect to an AFP share.

If the service starts correctly and you can make a connection but receive permissions errors, check that the user has permissions to the volume/dataset being accessed.

3.1.10 Backup the Configuration

Once you have tested your configuration, be sure to back it up. Go to System → Settings and click the Save Config button. Your browser will provide an option to save a copy of the configuration database.

You should backup your configuration whenever you make configuration changes and always before upgrading FreeNAS®.

3.2 Account Configuration

This section describes how to manage the account used to log into the GUI administrative interface and how to manually create users and groups using the FreeNAS® GUI.

3.2.1 Admin Account

By default, no password is required to access the FreeNAS® administrative interface using the built-in admin account. For security reasons, you should immediately change the default administrative account name and set a password for that account. To change the administrative account name, go to Account → Admin Account → Change Admin User. This will open the screen shown in Figure 3.2a.

Figure 3.2a: Changing the FreeNAS® Administrative Account

Replace admin with the name of the account that will be used to login to the FreeNAS® graphical administrative interface. The First and Last name fields are optional. Click the Change Admin User button to save your changes.

NOTE: in FreeNAS® the administrative account is not the same as the root user account. The administrative account is used to access the graphical administrative interface. This separation makes it possible to disable root logins while maintaining the ability of logging into the graphical administrative interface.

To change the password of the administrative account, click on Account → Admin Account → Change Password. This will open the screen shown in Figure 3.2b.

Figure 3.2b: Setting the FreeNAS® Administrative Password

Type in and confirm the password which will be used when accessing the graphical administrative interface. If you wish to allow root logins using the same password, leave the "Change root password as well" box checked. Uncheck this box to keep the root user account disabled.

NOTE: for security reasons, the root password, the SSH service, and root SSH logins are all disabled by default. Unless these are set, the only way to access a shell as root is to gain physical access to the console menu or to access the web shell within the administrative GUI. This means that the FreeNAS® system should be kept physically secure and that the administrative GUI should be behind a properly configured firewall and protected by a secure username and password.

3.2.2 Groups

The Groups interface allows you to manage UNIX-style groups on the FreeNAS® system.

NOTE: if Active Directory or OpenLDAP is running on your network, you do not need to recreate the network's users or groups. Instead, import the existing account information into FreeNAS® using Services → Active Directory (described in section 8.2) or Services → LDAP (described in section 8.8).

This section describes how to create a group and assign it user accounts. The next section will describe how to create user accounts.

If you click Groups → View Groups, you will see a screen similar to Figure 3.2c.

Figure 3.2c: FreeNAS® Groups Management

All groups that came with the operating system will be listed and the screen will indicate if any additional groups have been defined by the administrator. Each group has an entry indicating the group ID and group name; click the group's Members button to view and modify that group's membership.

If you click the Add New Group button, you will see the screen shown in Figure 3.2d. Table 3.2a summarizes the available options when creating a group.

Figure 3.2d: Creating a New Group

Table 3.2a: Options When Creating a Group

Once the group and users are created, you can assign users as members of a group. Click on View Groups then the Members button for the group you wish to assign users to. Highlight the user in the Member users list (which shows all user accounts on the system) and click the >> to move that user to the right frame. The user accounts which appear in the right frame will be added as members of that group.

In the example shown in Figure 3.2e, the data1 group has been created and the user1 user account has been created with a primary group of user1. The Members button for the data1 group has been selected and user1 has been added as a member of that group.

Figure 3.2e: Assigning a User as a Member of a Group

3.2.3 Users

FreeNAS® supports users, groups, and permissions, allowing great flexibility in configuring which users have access to the data stored on FreeNAS®. In order to assign permissions which will be used by shares, you will need to do one of the following:

1. Create a guest account that all users will use.

2. Create a user account for every user in the network where the name of each account is the same as a logon name used on a computer. For example, if a Windows system has a login name of bobsmith, you should create a user account with the name bobsmith on FreeNAS®. If your intent is to assign groups of users different permissions to shares, you will need to also create groups and assign users to the groups.

3. If your network uses Active Directory to manage user accounts and permissions, enable the Active Directory service as described in section 8.2.

4. If your network uses an OpenLDAP server to manage user accounts and permissions, enable the LDAP service as described in section 8.8.

User accounts can be given permissions to volumes or datasets. If you wish to use groups to manage permissions, you should create the user accounts first, then assign the accounts as members of the groups. This section demonstrates how to create a user account.

NOTE: if Active Directory or OpenLDAP is running on your network, you do not need to recreate the network's users or groups. Instead import the existing account information into FreeNAS® using Services → Active Directory or Services → LDAP.

Account → Users → View Users provides a listing of all of the system accounts that were installed with the FreeNAS® operating system, as shown in Figure 3.2f. The accounts that you create will be listed above the system accounts. A "No users defined" message will be displayed in this area if you have not yet created any user accounts.

Figure 3.2f: Managing User Accounts

Each account entry indicates the account ID, account name, default group, home directory, and default shell. Each account also provides the following buttons:

• Change Password: provides fields to enter and confirm the new password.

• Modify User: used to modify the account's settings, as listed in Table 3.2b.

• Auxiliary Groups: used to make the account a member of additional groups.

• Change E-mail: used to change the email address associated with the account.

NOTE: it is important to set the email address for the built-in root user account as important system messages are sent to the root user. For security reasons, password logins are disabled for the root account and changing this setting is highly discouraged.

Every account that came with the FreeNAS® operating system, except for the root user, is a system account. Each system account is used by a service and should not be available for use as a login account. For this reason, the default shell is nologin(8). For security reasons, and to prevent breakage of system services, you should not modify the system accounts.

To create a user account, click the Add New User button to open the screen shown in Figure 3.2g. Table 3.2b summarizes the options which are available when you create or modify a user account.

Figure 3.2g: Adding or Editing a User Account

Table 3.2b: User Account Configuration

4 System Configuration

The System section of the administrative GUI contains the following entries:

• Cron Jobs: provides a graphical front-end to crontab(5)

• NTP Servers: used to configure NTP server settings

• Reporting: provides reports and graphs monitoring the system's CPU, disk capacity and other metrics

• Rsync Tasks: allows you to schedule rsync tasks

• S.M.A.R.T. Tests: allows you to schedule which S.M.A.R.T. tests to run on a per-disk basis

• Settings: used to configure system wide settings such as timezone, email setup, HTTPS access, and firmware upgrades

• Sysctls: provides a front-end for tuning the FreeNAS® system by interacting with the underlying FreeBSD kernel

• System Information: provides general FreeNAS® system information such as hostname, operating system version, platform, and uptime

• Tunables: provides a front-end to load additional kernel modules at boot time

Each of these is described in more detail in this section.

4.1 Cron Jobs

cron(8) is a daemon that runs a command or script on a regular schedule as a specified user. Typically, the user who wishes to schedule a task manually creates a crontab(5) using syntax that can be perplexing to new Unix users. The FreeNAS® GUI makes it easy to schedule when you would like the task to occur.

NOTE: due to a limitation in FreeBSD, users with account names that contain spaces or exceed 17 characters are unable to create cron jobs.

Figure 4.1a shows the screen that opens when you click System → Cron Jobs → Add Cron Job.

Figure 4.1a: Creating a Cron Job

Table 4.1a summarizes the configurable options when creating a cron job.

Table 4.1a: Cron Job Options

4.2 NTP Servers

The network time protocol (NTP) is used to synchronize the time on the computers in a network. Accurate time is necessary for the successful operation of time sensitive applications such as Active Directory.

By default, FreeNAS® is pre-configured to use three public NTP servers. If your network is using Active Directory, ensure that the FreeNAS® system and the Active Directory Domain Controller have been configured to use the same NTP servers.

Figure 4.2a shows the default NTP configuration for FreeNAS®.

Figure 4.2a: Default NTP Configuration

If you wish to change a default server to match the settings used by your network's domain controller, click an entry's Edit button. Alternately, you can delete the default NTP servers and click Add NTP Server to create your own. Figure 4.2b shows the Add NTP Server screen and Table 4.2a summarizes the options when adding or editing an NTP server. ntp.conf(5) explains these options in more detail.

Figure 4.2b: Add or Edit a NTP Server

Table 4.2a: NTP Server Options

4.3 Reporting

System → Reporting displays several graphs, as seen in the example in Figure 4.3a.

Figure 4.3a: Reporting Graphs

The graphs will display system load, processes, disk space of each volume and dataset, uptime, CPU usage, swap utilization, physical memory utilization, and the interface traffic for each interface. Reporting data is saved, allowing you to view and monitor usage trends over time. Reporting data is preserved across system upgrades and at shutdown.

Use the magnifier buttons next to each graph to increase or decrease the displayed time increment from 10 minutes, hourly, daily, weekly, or monthly. You can also use the << and >> buttons to scroll through the output.

4.4 Rsync Tasks

Rsync is a utility that automatically copies specified data from one system to another over a network. Once the initial data is copied, rsync reduces the amount of data sent over the network by sending only the differences between the source and destination files. Rsync can be used for backups, mirroring data on multiple systems, or for copying files between systems.

To configure rsync, you need to configure both ends of the connection:

• the rsync server: this system pulls (receives) the data. This system is referred to as PULL in the configuration examples.

• the rsync client: this system pushes (sends) the data. This system is referred to as PUSH in the configuration examples.

FreeNAS® can be configured as either an rsync client or an rsync server. The opposite end of the connection can be another FreeNAS® system or any other system running rsync. In FreeNAS® terminology, an rysnc task defines which data is synchronized between the two systems. If you are synchronizing data between two FreeNAS® systems, create the rsync task on the rsync client.

FreeNAS® supports two modes of rsync operation:

• rsync module mode: exports a directory tree, and its configured settings, as a symbolic name over an unencrypted connection. This mode requires that at least one module be defined on the rsync server. It can be defined in the FreeNAS® GUI under Services → Rsync → Rsync Modules. In other operating systems, the module is defined in rsyncd.conf(5).

• rsync over SSH: synchronizes over an encrypted connection. Requires the configuration of SSH user and host public keys.

This section summarizes the options when creating an Rsync Task. It then provides a configuration example between two FreeNAS® systems for each mode of rsync operation.

4.4.1 Creating an Rsync Task

Figure 4.4a shows the screen that appears when you click System → Rsync Tasks → Add Rsync Task. Table 4.4a summarizes the options that can be configured when creating an rsync task.

Figure 4.4a: Adding an Rsync Task

Table 4.4a: Rsync Configuration Options

If the rysnc server requires password authentication, input --password-file=/PATHTO/FILENAME in the "Extra options" box, replacing /PATHTO/FILENAME with the appropriate path to the file containing the value of the password.

4.4.2 Configuring Rsync Module Mode Between Two FreeNAS® Systems

This configuration example will configure rsync module mode between the two following FreeNAS® systems:

• 192.168.2.2 has existing data in /mnt/local/images. It will be the rsync client, meaning that an rsync task needs to be defined. It will be referred to as PUSH.

• 192.168.2.6 has an existing volume named /mnt/remote. It will be the rsync server, meaning that it will receive the contents of /mnt/local/images. An rsync module needs to be defined on this system and the rsyncd service needs to be started. It will be referred to as PULL.

On PUSH, an rsync task is defined in System → Rsync Tasks → Add Rsync Task as shown in Figure 4.4b. In this example:

• the Path points to /usr/local/images, the directory to be copied

• the Remote Host points to 192.168.2.6, the IP address of the rsync server

• the Rsync Mode is Rsync module

• the Remote Module Name is backups; this will need to be defined on the rsync server

• the Direction is Push

• the rsync is scheduled to occur every 15 minutes

• the User is set to root so it has permission to write anywhere

• the Preserve Permissions checkbox is checked so that the original permissions are not overwritten by the root user

Figure 4.4b: Configuring the Rsync Client

On PULL, an rsync module is defined in Services → Rsync Modules → Add Rsync Module, shown in Figure 4.4c. In this example:

• the Module Name is backups; this needs to match the setting on the rsync client

• the Path is /mnt/remote; a directory called images will be created to hold the contents of /usr/local/images

• the User is set to root so it has permission to write anywhere

• Hosts allow is set to 192.168.2.2, the IP address of the rsync client

Descriptions of the configurable options can be found in section 8.11.1 Rsync Modules.

To finish the configuration, start the rsync service on PULL in Services → Control Services. If the rsync is successful, the contents of /mnt/local/images/ will be mirrored to /mnt/remote/images/.

Figure 4.4c: Configuring the Rsync Server

4.4.3 Configuring Rsync over SSH Mode Between Two FreeNAS® Systems

SSH replication mode does not require the creation of an rsync module or for the rsync service to be running on the rsync server. It does require SSH to be configured before creating the rsync task:

• a public/private key pair for the rsync user account (typically root) must be generated on PUSH and the public key copied to the same user account on PULL

• to mitigate the risk of man-in-the-middle attacks, the public host key of PULL must be copied to PUSH

• the SSH service must be running on PULL

To create the public/private key pair on PUSH, open Shell. The / filesystem must first be mounted as read-write. In the following example, the root user is generating an ECDSA type of public/private key pair. When creating the key pair, do not enter the passphrase as the key is meant to be used for an automated task.

mount -o rw /
ssh-keygen -t ecdsa                                           
Generating public/private ecdsa key pair.                                       
Enter file in which to save the key (/root/.ssh/id_ecdsa):                      
Enter passphrase (empty for no passphrase):                                     
Enter same passphrase again:                                                    
Your identification has been saved in /root/.ssh/id_ecdsa.                      
Your public key has been saved in /root/.ssh/id_ecdsa.pub.                      
The key fingerprint is: 
a8:ed:da:f1:02:36:b9:10:06:40:02:9f:00:2e:da:dc root@truenas.local              
The key's randomart image is:                                                   
+--[ECDSA  256]---+                                                             
|@.               |                                                             
|+o .             |                                                             
|.oo              |                                                             
|ooo.   .         |                                                             
|..o.E.. S        |                                                             
|  . =o           |                                                             
|   o.+o          |                                                             
|    .o.o         |                                                             
|    ..o..        |  
+-----------------+        

NOTE: FreeNAS® supports the following types of SSH keys: ECDSA, DSA, and RSA. When creating the key, specify the type you wish to use or, if you are generating the key on another operating system, select a type of key the key generation software supports.

Next, view and copy the contents of the generated public key:

more .ssh/id_ecdsa.pub
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBGN8gxT0
V81KblGNhv2VPRX/9QcUNReQWG0Rc9HMgmxo1LfMyEDEBiRjCr3vs2oIE8AF6y2wgus18G7ghfJWEFQ=

Go to PULL and paste (or append) the copied key into the SSH Public Key field of Account → Users → View Users → root → Modify User. The paste for the above example is shown in Figure 4.4d. When pasting the key, ensure that it is pasted as one long line and, if necessary, remove any extra spaces representing line breaks.

Figure 4.4d: Pasting the User's SSH Public Key

While on PULL, verify that the SSH service is running in Services → Control Services and start it if it is not.

Next, copy the host key of PULL using Shell on PUSH. The following command copies the ECDSA host key of the PULL server used in our previous example. Be sure to include the double bracket >> to prevent overwriting any existing entries in the known_hosts file.

ssh-keyscan -t ecdsa 192.168.2.6 >> /root/.ssh/known_hosts 

You are now ready to create the rsync task on PULL. To configure rsync SSH mode using the systems in our previous example, the configuration would be as follows:

• the Path points to /mnt/local/images, the directory to be copied

• the Remote Host points to 192.168.2.6, the IP address of the rsync server

• the Rsync Mode is Rsync over SSH

• the rsync is scheduled to occur every 15 minutes

• the User is set to root so it has permission to write anywhere; the public key for this user must be generated on PUSH and copied to PULL

• the Preserve Permissions checkbox is checked so that the original permissions are not overwritten by the root user

Once you save the rsync task, the rsync will automatically occur according to your schedule. In this example, the contents of /mnt/local/images/ will automatically appear in /mnt/remote/images/ after 15 minutes. If the content does not appear, use Shell on PULL to read /var/log/messages. If the message indicates a \n (newline character) in the key, remove the space in your pasted key--it will be after the character that appears just before the \n in the error message.

4.5 S.M.A.R.T. Tests

S.M.A.R.T. (Self-Monitoring, Analysis and Reporting Technology) is a monitoring system for computer hard disk drives to detect and report on various indicators of reliability. When a failure is anticipated by S.M.A.R.T., the drive should be replaced. Most modern ATA, IDE and SCSI-3 hard drives support S.M.A.R.T.--refer to your drive's documentation if you are unsure.

Figure 4.5a shows the configuration screen that appears when you click System → S.M.A.R.T. Tests → Add S.M.A.R.T. Test. The tests that you create will be listed under View S.M.A.R.T. Tests. After creating your tests, check the configuration in Services → S.M.A.R.T., then click the slider to ON for the S.M.A.R.T. service in Services → Control Services. The S.M.A.R.T. service will not start if you have not created any volumes.

NOTE: to prevent problems, do not enable the S.M.A.R.T. service if your disks are controlled by a RAID controller as it is the job of the controller to monitor S.M.A.R.T. and mark drives as Predictive Failure when they trip.

Figure 4.5a: Adding a S.M.A.R.T. Test

Table 4.5a summarizes the configurable options when creating a S.M.A.R.T. test.

Table 4.5a: S.M.A.R.T. Test Options

4.6 Settings

The Settings tab, shown in Figure 4.6a, contains 4 tabs: General, Advanced, Email, and SSL.

Figure 4.6a: General Tab of Settings

4.6.1 General Tab

Table 4.6a summarizes the settings that can be configured using the General tab:

Table 4.6a: General Tab's Configuration Settings

NOTE: by default, logs are stored in RAM as there is no space on the embedded device to store logs. This means that logs are deleted whenever the system reboots. If you wish to save the system logs, either configure a remote syslog server, create a script to store the logs on a volume and add the script as a cron job, or use the FreeNAS-Change-Logging script.

If you make any changes, click the Save button.

This tab also contains the following buttons:

Factory Restore: replaces current configuration with the factory default. This means that all of your customizations will be erased, but can be handy if you mess up your system or wish to return a test system to the original configuration.

Save Config: used to create a backup copy of the current configuration database in the format hostname-version-architecture. Always save the configuration after making changes and verify that you have a saved configuration before performing an upgrade.

Upload Config: allows you to browse to location of saved configuration file in order to restore that configuration.

4.6.2 Advanced Tab

The Advanced tab, shown in Figure 4.6b, allows you to set some miscellaneous settings on the FreeNAS® system. The configurable settings are summarized in Table 4.6b.

Figure 4.6b: Advanced Tab

Table 4.6b: Advanced Tab's Configuration Settings

If you make any changes, click the Save button.

This tab also contains the following buttons:

Rebuild LDAP/AD Cache: click if you add a user to Active Directory who needs immediate access to FreeNAS®; otherwise this occurs automatically once a day as a cron job.

Save Debug: used to generate a text file of diagnostic information. In the screen shown in Figure 4.6c, check the box(es) for the information that you wish to generate then click the Save button to be prompted for the location to save the generated ASCII text file.

Firmware Update: used to Upgrade FreeNAS®. See section 2.6.3 Upgrading FreeNAS® From the GUI for details.

Figure 4.6c: Save Debug Screen

4.6.2.1 Autotune

FreeNAS® provides an autotune script which attempts to optimize the system depending upon the hardware which is installed. For example, if a ZFS volume exists on a system with limited RAM, the autotune script will automatically adjust some ZFS sysctl values in an attempt to minimize ZFS memory starvation issues.

The "Enable autotune" checkbox in System → Settings → Advanced is unchecked by default; check it if you would like the autotuner to run at boot time. If you would like the script to run immediately, reboot the system.

If autotuner finds any settings that need adjusting, the changed values will appear in System → Sysctls (for sysctl.conf values) and in System → Tunables (for loader.conf values). If you do not like the changes, you can modify the values that are displayed in the GUI and your changes will override the values that were created by the autotune script. However, if you delete a sysctl or tunable that was created by autotune, it will be recreated at next boot. This is because autotune only creates values that do not already exist.

If you are trying to increase the performance of your FreeNAS® system and suspect that the current hardware may be limiting performance, try enabling autotune.

If you wish to read the script to see which checks are performed, the script is located in /usr/local/bin/autotune.

4.6.3 Email Tab

The Email tab, shown in Figure 4.6d, is used to configure the email settings on the FreeNAS® system. Table 4.6c summarizes the settings that can be configured using the Email tab.

NOTE: it is important to configure the system so that it can successfully send emails. An automatic script send a nightly email to the root user account containing important information such as the health of the disks. Alert events are also emailed to the root user account.

Figure 4.6d: Email Tab

Table 4.6c: Email Tab's Configuration Settings

4.6.4 SSL Tab

When you change the Protocol value to HTTPS in System → Settings → General, an unsigned RSA certificate and key are auto-generated. Once generated, the certificate and key will be displayed in the SSL Certificate field in System → Settings → SSL, shown in Figure 4.6e. If you already have your own signed certificate that you wish to use for SSL/TLS connections, replace the values in the SSL certificate field with a copy/paste of your own key and certificate. The certificate can be used to secure the HTTP connection (enabled in the Settings → General Tab) to the FreeNAS® system.

Table 4.6d summarizes the settings that can be configured using the SSL tab. This howto shows how to manually generate your own certificate using OpenSSL and provides some examples for the values shown in Table 4.6d.

Figure 4.6e: SSL Tab

Table 4.6d: SSL Tab's Configuration Settings

4.7 Sysctls

sysctl(8) is an interface that is used to make changes to the FreeBSD kernel running on a FreeNAS® system. It can be used to tune the system in order to meet the specific needs of a network. Over five hundred system variables can be set using sysctl(8). Each variable is known as a MIB as it is comprised of a dotted set of components. Since these MIBs are specific to the kernel feature that is being tuned, descriptions can be found in many FreeBSD man pages (e.g. sysctl(3), tcp(4) and tuning(7)) and in many sections of the FreeBSD Handbook.

DANGER! changing the value of a sysctl MIB is an advanced feature that immediately affects the kernel of the FreeNAS® system. Do not change a MIB on a production system unless you understand the ramifications of that change. A badly configured MIB could cause the system to become unbootable, unreachable via the network, or can cause the system to panic under load. Certain changes may break assumptions made by the FreeNAS® software. This means that you should always test the impact of any changes on a test system first.

FreeNAS® provides a graphical interface for managing sysctl MIBs. To add a sysctl, go to System → Sysctls → Add Sysctl, shown in Figure 4.7a.

Figure 4.7a: Adding a Sysctl

Table 4.7a summarizes the options when adding a sysctl.

Table 4.7a: Adding a Sysctl

As soon as you add or edit a sysctl, the running kernel will change that variable to the value you specify. As long as the sysctl exists, that value will persist across reboots and upgrades.

Any MIBs that you add will be listed in System → Sysctls → View Sysctls. To change the value of a MIB, click its Edit button. To remove a MIB, click its Delete button.

At this time, the GUI does not display the sysctl MIBs that are pre-set in the installation image. 8.3.0 ships with the following MIBs set:

kern.metadelay=3
kern.dirdelay=4
kern.filedelay=5
kern.coredump=0
net.inet.tcp.delayed_ack=0  

Do not add or edit the default MIBS as sysctls as doing so will overwrite the default values which may render the system unusable.

4.8 System Information

System → System Information displays general information about the FreeNAS® system. The information includes the hostname, the build version, type of CPU (platform), the amount of memory, the current system time, the system's uptime, the current load average, and the IP address being used for the connection to the administrative GUI. An example is seen in Figure 4.8a:

Figure 4.8a: System Information Tab

4.9 Tunables

When a FreeBSD-based system boots, loader.conf(5) is read to determine if any parameters should be passed to the kernel or if any additional kernel modules (such as drivers) should be loaded. Since loader values are specific to the kernel parameter or driver to be loaded, descriptions can be found in the man page for the specified driver and in many sections of the FreeBSD Handbook.

FreeNAS® provides a graphical interface for managing loader values. This advanced functionality is intended to make it easier to load additional kernel modules at boot time. A typical usage would be to load a FreeBSD hardware driver that does not automatically load after a FreeNAS® installation. The default FreeNAS® image does not load every possible hardware driver. This is a necessary evil as some drivers conflict with one another or cause stability issues, some are rarely used, and some drivers just don't belong on a standard NAS system. If you need a driver that is not automatically loaded, you need to add a tunable.

DANGER! adding a tunable is an advanced feature that could adversely effect the ability of the FreeNAS® system to successfully boot. It is very important that you do not have a typo when adding a tunable as this could halt the boot process. Fixing this problem requires physical access to the FreeNAS® system and knowledge of how to use the boot loader prompt as described in section 4.9.1 Recovering From Incorrect Tunables. This means that you should always test the impact of any changes on a test system first.

To add a tunable, go to System → Tunables → Add Tunable, as seen in Figure 4.9a.

Figure 4.9a: Adding a Tunable

Table 4.9a summarizes the options when adding a tunable.

Table 4.9a: Adding a Tunable

The changes you make will not take effect until the system is rebooted as loader settings are only read when the kernel is loaded at boot time. As long as the tunable exists, your changes will persist at each boot and across upgrades.

Any tunables that you add will be listed alphabetically in System → Tunables → View Tunables. To change the value of a tunable, click its Edit button. To remove a tunable, click its Delete button.

At this time, the GUI does not display the tunables that are pre-set in the installation image. 8.3.0 ships with the following tunables set:

autoboot_delay="2"
loader_logo="freenas"
kern.cam.boot_delay=30000
fuse_load="YES"
geom_mirror_load="YES"
geom_stripe_load="YES"
geom_raid3_load="YES"
geom_raid5_load="YES"
geom_gate_load="YES"
geom_multipath_load=”YES”
debug.debugger_on_panic=1
hw.hptrr.attach_generic=0
kern.ipc.nmbclusters="262144"  

Do not add or edit the default tunables as doing so will overwrite the default values which may render the system unusable.

4.9.1 Recovering From Incorrect Tunables

If a tunable is preventing the system from booting, you will need physical access to the FreeNAS® system. Watch the boot messages and press the number 6 key to select "6. Escape to loader prompt" when you see the FreeNAS® boot menu shown in Figure 4.9b.

Figure 4.9b: FreeNAS® Boot Menu

The boot loader prompt provides a minimal set of commands described in loader(8). Once at the prompt, use the unset command to disable a problematic value, the set command to modify the problematic value, or the unload command to prevent the problematic driver from loading.

Example 4.9a demonstrates several examples using these commands at the boot loader prompt. The first command disables the current value associated with the kern.ipc.nmbclusters MIB and will fail with a "no such file or directory" error message if a current tunable does not exist to set this value. The second command disables ACPI. The third command instructs the system not to load the fuse driver. When finished, type boot to continue the boot process.

Example 4.9a: Sample Commands at the Boot Loader Prompt

Type '?' for a list of commands, 'help' for more detailed help.
OK unset kern.ipc.nmbclusters
OK set hint.acpi.0.disabled=1 
OK unload fuse 
OK boot

Any changes made at the boot loader prompt only effect the current boot. This means that you need to edit or remove the problematic tunable in System → Tunables → View Tunables to make your change permanent and to prevent future boot errors.

5 Network Configuration

The Network section of the administrative GUI contains the following components for viewing and configuring the FreeNAS® system's network settings:

• Global Configuration: used to to set non-interface specific network settings.

• Interfaces: used to configure a specified interface's network settings.

• Link Aggregations: used to configure link aggregation and link failover.

• Network Summary: provides an overview of the current network settings.

• Static Routes: used to add static routes.

• VLANs: used to configure IEEE 802.1q tagging.

Each of these is described in more detail in this section.

5.1 Global Configuration

Network → Global Configuration, shown in Figure 5.1a, allows you to set non-interface specific network settings.

Figure 5.1a: Global Configuration Screen

Table 5.1a summarizes the settings that can be configured using the Global Configuration tab. The hostname and domain will be pre-filled for you, as seen in Figure 5.1a, but can be changed to meet the local network's requirements.

If you will be installing the Plugins Jail, input the default gateway for the network containing the IP address to be used by the Plugins Jail.

If you will be using Active Directory, set the IP address of the DNS server used in the realm.

If your network does not have a DNS server or NFS, SSH, or FTP users are receiving "reverse DNS" or timeout errors, add an entry for the IP address of the FreeNAS® system in the "Host name database" field.

NOTE: if you add a gateway to the Internet, make sure that the FreeNAS® system is protected by a properly configured firewall.

Table 5.1a: Global Configuration Settings

5.2 Interfaces

Network → Interfaces is used to view which interfaces have been configured, to add an interface to configure, and to edit an interface's current configuration. Figure 5.2a shows the screen that opens when you click Interfaces → Add Interface.

Table 5.2a summarizes the configuration options when you Add an interface or Edit an already configured interface.

Figure 5.2a: Adding or Editing an Interface

Table 5.2a: Interface Configuration Settings

This screen also allows you to configure an alias for the interface. If you wish to set multiple aliases, click the "Add extra alias" link for each alias you wish to configure.

5.3 Link Aggregations

FreeNAS® uses FreeBSD's lagg(4) interface to provide link aggregation and link failover. The lagg interface allows aggregation of multiple network interfaces into a single virtual lagg interface, providing fault-tolerance and high-speed multi-link throughput. The aggregation protocols supported by lagg determine which ports are used for outgoing traffic and whether a specific port accepts incoming traffic. The link state of the lagg interface is used to validate if the port is active or not.

Aggregation works best on switches supporting LACP, which distributes traffic bi-directionally while responding to failure of individual links. FreeNAS® also supports active/passive failover between pairs of links.

The LACP, FEC and load-balance modes select the output interface using a hash that includes the Ethernet source and destination address, VLAN tag (if available), IP source and destination address, and flow label (IPv6 only). The benefit can only be observed when multiple clients are transferring files from your NAS. The flow entering into your NAS depends on the Ethernet switch load-balance algorithm.

The lagg driver currently supports the following aggregation protocols:

Failover: the default protocol. Sends traffic only through the active port. If the master port becomes unavailable, the next active port is used. The first interface added is the master port; any interfaces added after that are used as failover devices. By default, received traffic is only accepted when received through the active port. This constraint can be relaxed, which is useful for certain bridged network setups, by setting net.link.lagg.failover_rx_all to a non-zero value in System → Sysctls → Add Sysctl.

FEC: supports Cisco EtherChannel on older Cisco switches. This is a static setup and does not negotiate aggregation with the peer or exchange frames to monitor the link.

LACP: supports the IEEE 802.3ad Link Aggregation Control Protocol (LACP) and the Marker Protocol. LACP will negotiate a set of aggregable links with the peer into one or more link aggregated groups (LAGs). Each LAG is composed of ports of the same speed, set to full-duplex operation. The traffic will be balanced across the ports in the LAG with the greatest total speed; in most cases there will only be one LAG which contains all ports. In the event of changes in physical connectivity, link aggregation will quickly converge to a new configuration. LACP must be configured on the switch as well.

Load Balance: balances outgoing traffic across the active ports based on hashed protocol header information and accepts incoming traffic from any active port. This is a static setup and does not negotiate aggregation with the peer or exchange frames to monitor the link. The hash includes the Ethernet source and destination address, VLAN tag (if available), and IP source and destination address. Requires a switch which supports IEEE 802.3ad static link aggregation.

Round Robin: distributes outgoing traffic using a round-robin scheduler through all active ports and accepts incoming traffic from any active port. This mode can cause unordered packet arrival at the client. This has a side effect of limiting throughput as reordering packets can be CPU intensive on the client. Requires a switch which supports IEEE 802.3ad static link aggregation.

None: this protocol disables any traffic without disabling the lagg interface itself.

NOTE: the FreeNAS® system must be rebooted after configuring the lagg device and TCP access will be lost during reboot. Do not configure the interfaces used in the lagg device before creating the lagg device.

5.3.1 Considerations When Using LACP, MPIO, NFS, or ESXi

LACP bonds Ethernet connections in order to improve bandwidth. For example, four phsycial interfaces can be used to create one mega interface.

LACP reads the sender and receiver IP addresses and, if they are deemed to belong to the same TCP connection, always sends the packet over the same interface to ensure that TCP does not need to reorder packets. This makes LACP ideal for load balancing many simultaneous TCP connections, but does nothing for increasing the speed over one TCP connection.

MPIO operates at the iSCSI protocol level. For example, if you create four IP addresses and there are four simultaneous TCP connections, MPIO will send the data over all available links. When configuring MPIO, make sure that the IP addresses on the interfaces are configured to be on separate subnets with non-overlapping netmasks or configure static routes to do point to point communication. Otherwise, all packets will pass through one interface.

LACP and other forms of link aggregation generally do not work well with virtualization solutions. In a virtualized environment, consider the use of iSCSI MPIO through the creation of an iSCSI Portal. This allows an iSCSI initiator to recognize multiple links to a target, utilizing them for increased bandwidth or redundancy. This how-to contains instructions for configuring MPIO on ESXi.

NFS does not understand MPIO. Therefore, you will need one fast interface since creating an iSCSI portal will not improve bandwidth when using NFS. LACP does not work well to increase the bandwidth for point to point NFS (one server and one client). LACP is a good solution for link redundancy or for one server and many clients.

5.3.2 Creating a Link Aggregation

Figure 5.3a shows the configuration options when adding a lagg interface using Network → Link Aggregations → Create Link Aggregation.

Figure 5.3a: Creating a lagg Interface

NOTE: if interfaces are installed but do not appear in the Physical NICs in the LAGG list, check that a FreeBSD driver for the interface exists here.

Select the desired aggregation protocol, highlight the interface(s) to associate with the lagg device, and click the OK button.

Once the lagg device has been created, it will be listed in the tree under an entry which indicates the type of protocol. As seen in Figure 5.3b, it will also appear in View Link Aggregations.

Figure 5.3b: Viewing Link Aggregations

Each link aggregation entry provides buttons to edit the lagg interface, edit its member interfaces, or to delete the link aggregation.

Figure 5.3c shows the Edit Interface configuration screen and Table 5.3a describes the options in this screen.

Figure 5.3c: Edit lagg Interface

Table 5.3a: Configurable Options for a lagg Interface

This screen also allows you to configure an alias for the lagg interface. If you wish to set multiple aliases, click the "Add extra Alias" link for each alias you wish to configure.

If you click an entry's Edit Members button, the interfaces within the link aggregation will be listed. Each interface entry will have an Edit and a Delete button. Figure 5.3d shows the configuration screen that appears when you click the Edit button of a member interface. The configurable options are summarized in Table 5.3b.

Figure 5.3d: Editing a Member Interface

Table 5.3b: Configuring a Member Interface

NOTE: options can be set at either the lagg level or the individual parent interface level. Do not set the option at both levels as each level automatically inherits its options from the other. Typically, changes are made at the lagg level (Figure 5.3b) as each interface member will inherit from the lagg. If you instead configure the interface level (Figure 5.3c), you will have to repeat the configuration for each interface within the lagg. However, some lagg options can only be set by editing the interface. For instance, the MTU of a lagg is inherited from the interface. To set an MTU on a lagg, set all the interfaces to the same MTU.

5.4 Network Summary

Network → Network Summary allows you to quickly view the addressing information of every configured interface. For each interface name, the configured IP address(es), DNS server(s), and default gateway will be displayed.

5.5 Static Routes

By default, no static routes are defined on the FreeNAS® system. Should you need a static route to reach portions of your network, add the route using Network → Static Routes → Add Static Route, shown in Figure 5.5a.

Figure 5.5a: Adding a Static Route

The destination network and gateway fields are mandatory; the description field is optional.

If you add any static routes, they will show in “View Static Routes”. Each route will have an action of Edit or Delete.

5.6 VLANs

FreeNAS® uses FreeBSD's vlan(4) interface to demultiplex frames with IEEE 802.1q tags. This allows nodes on different VLANs to communicate through a layer 3 switch or router. A vlan interface must be assigned a parent interface and a numeric VLAN tag. A single parent can be assigned to multiple vlan interfaces provided they have different tags. If you click Network → VLANs → Add VLAN, you will see the screen shown in Figure 5.6a.

NOTE: VLAN tagging is the only 802.1q feature that is implemented. Additionally, not all Ethernet interfaces support full VLAN processing–see the HARDWARE section of vlan(4) for details.

Figure 5.6a: Adding a VLAN

Table 5.6a summarizes the configurable fields.

Table 5.6a: Adding a VLAN

6 Storage Configuration

The Storage section of the graphical interface allows you to configure the following:

• Periodic Snapshot Tasks: used to schedule the automatic creation of ZFS snapshots.

• Replication Tasks: used to schedule the replication of snapshots over an encrypted connection.

• Volumes: used to create and manage storage volumes.

• ZFS Scrubs: used to schedule ZFS scrubs as part of ongoing disk maintenance.

These configurations are described in more detail in this section.

6.1 Periodic Snapshot Tasks

A periodic snapshot task allows you to schedule the creation of read-only versions of ZFS volumes and datasets at a given point in time. Snapshots can be created quickly and, if little data changes, new snapshots take up very little space. For example, a snapshot where no files have changed takes 0 MB of storage, but if you change a 10 GB file it will keep a copy of both the old and the new 10 GB version. Snapshots provide a clever way of keeping a history of files, should you need to recover an older copy or even a deleted file. For this reason, many administrators take snapshots often (e.g. every 15 minutes), store them for a period of time (e.g. for a month), and store them on another system (e.g. using Replication Tasks). Such a strategy allows the administrator to roll the system back to a specific time or, if there is a catastrophic loss, an off-site snapshot can restore the system up to the last snapshot interval.

Before you can create a snapshot, you need to have an existing ZFS volume. How to create a volume is described in section 6.3.3 Volume Manager.

To create a periodic snapshot task, click Storage → Periodic Snapshot Tasks → Add Periodic Snapshot which will open the screen shown in Figure 6.1a.

NOTE: if you just need a one-time snapshot, instead use Storage → Volumes → View Volumes and click the Create Snapshot button for the volume or dataset that you wish to snapshot.

Figure 6.1a: Creating a ZFS Periodic Snapshot

Table 6.1a summarizes the fields in this screen:

Table 6.1a: Options When Creating a Periodic Snapshot

Once you click the OK button, a snapshot will be taken and this task will be repeated according to your settings. An entry for the snapshot task will be added to View Periodic Snapshot Tasks. As seen in Figure 6.1b, this entry provides an overview of the snapshot tasks' configuration as well as Modify and Delete buttons.

Figure 6.1b: View Periodic Snapshot Tasks

If you click the ZFS Snapshots tab (above the Add Periodic Snapshot button), you can review the listing of available snapshots. In the example shown in Figure 6.1c, volume1 was selected when the periodic snapshot task was created and this volume contains two datasets named software and jail.

Figure 6.1c: Viewing Available Snapshots

The most recent snapshot for a volume or dataset will be listed last and will have 3 icons instead of 2. The icons associated with a snapshot allow you to:

Clone Snapshot: will prompt for the name of the clone to create. The clone will be a writable copy of the snapshot and can only be created on the same ZFS volume. Clones do not inherit the properties of the parent dataset, but rather inherit the properties based on where the clone is created in the ZFS pool. Because a clone initially shares all its disk space with the original snapshot, its used property is initially zero. As changes are made to the clone, it uses more space.

Destroy Snapshot: a pop-up message will ask you to confirm this action. Child clones must be destroyed before their parent snapshot can be destroyed.

Rollback Snapshot: a pop-up message will ask if you are sure that you want to rollback to this snapshot state. If you click Yes, any files that have changed since the snapshot was taken will be reverted back to their state at the time of the snapshot.

NOTE: rollback is a potentially dangerous operation and will cause any configured replication tasks to fail as the replication system uses the existing snapshot when doing an incremental backup. If you do need to restore the data within a snapshot, the recommended steps are:

1. Clone the desired snapshot.

2. Share the clone with the share type or service running on the FreeNAS® system.

3. Once users have recovered the needed data, destroy the clone.

This approach will never destroy any on-disk data and has no impact on replication.

Periodic snapshots can be configured to appear as shadow copies in newer versions of Windows Explorer. Users can access the files in the shadow copy using Explorer without requiring any interaction with the FreeNAS® graphical administrative interface.

The ZFS Snapshots screen allows you to create filters to view snapshots by selected criteria. To create a filter, click the Define filter icon (near the text “No filter applied”). When creating a filter:

• select the column or leave the default of Any Column.

• select the condition. Possible conditions are: contains (default), is, starts with, ends with, does not contain, is not, does not start with, does not end with, and is empty.

• input a value that meets your view criteria.

• click the Filter button to save your filter and exit the define filter screen. Alternately, click the + button to add another filter.

If you create multiple filters, select the filter you wish to use before leaving the define filter screen. Once a filter is selected, the “No filter applied” text will change to “Clear filter”. If you click “Clear filter”, a pop-up message will indicate that this will remove the filter and all available snapshots will be listed.

6.2 Replication Tasks

A replication task allows you to automate the copy of ZFS snapshots to another system over an encrypted connection. This allows you to create an off-site backup of a ZFS dataset or pool.

This section will refer to the system generating the ZFS snapshots as PUSH and the system to receive a copy of the ZFS snapshots as PULL.

Before you can configure a replication task, the following pre-requisites must be met:

• a ZFS volume must exist on both PUSH and PULL.

• a periodic snapshot task must be created on PUSH. You will not be able to create a replication task before the first snapshot exists.

• the SSH service must be enabled on PULL. The first time the service is enabled, it will generate the required SSH keys.

A replication task uses the following keys:

• /data/ssh/replication.pub: the public key used for authenticating the PUSH replication user. This key needs to be copied to the root user account on PULL.

• /etc/ssh/ssh_host_dsa_key.pub: the host public key of PULL used to authenticate the receiving side in order to prevent a man-in-the-middle attack. This key needs to be copied to the replication task on PUSH.

This section will demonstrate how to configure a replication task between the following two FreeNAS® systems:

• 192.168.2.2 will be referred to as PUSH. This system has a periodic snapshot task for the ZFS dataset /mnt/local/data.

• 192.168.2.6 will be referred to as PULL. This system has an existing ZFS volume named /mnt/remote which will store the pushed snapshots.

6.2.1 Configure PULL

A copy of the public key for the replication user on PUSH needs to be pasted to the public key of the root user on the PULL system.

To obtain a copy of the replication key: on PUSH go to Storage → View Replication Tasks. Click the View Public Key button and copy its contents. An example is shown in Figure 6.2a.

Figure 6.2a: Copy the Replication Key

Go to PULL and click Account → Users → View Users. Click the Modify User button for the root user account. Paste the copied key into the "SSH Public Key" field and click OK. If a key already exists, append the new text after the existing key.

On PULL, ensure that the SSH service is enabled in Services → Control Services. Start it if it is not already running.

6.2.2 Configure PUSH

On PUSH, verify that a periodic snapshot task has been created and that at least one snapshot is listed in Storage → Periodic Snapshot Tasks → View Periodic Snapshot Tasks → ZFS Snapshots.

To create the replication task, click Storage → Replication Tasks → Add Replication Task. Figure 6.2b shows the required configuration for our example:

• the Filesystem/Volume is local/data

• the Remote ZFS filesystem is remote

• the Remote hostname is 192.168.2.6

• the Begin and End times are at their default values, meaning that replication will occur whenever a snapshot is created

• once the Remote hostname is input, click the SSH Key Scan button; assuming the address is reachable and the SSH service is running on PULL, its key will automatically be populated to the Remote hostkey box

Table 6.2a summarizes the available options in the Add Replication Task screen.

Figure 6.2b: Adding a Replication Task

Table 6.2a: Adding a Replication Task

NOTE: the Begin and End times can be used to create a window of time where replication occurs. Change the default times (which allow replication to occur at any time of the day) if snapshot tasks are scheduled during office hours but the replication itself should occur after office hours. For the End time, consider how long replication will take so that it finishes before the next day's office hours begin.

Once the replication task is created, it will appear in the View Replication Tasks of PUSH, as seen in Figure 6.2c. Buttons are provided to delete and to edit the replication task.

Figure 6.2c: Viewing the Replication Task

PUSH will immediately attempt to replicate its latest snapshot to PULL. If the replication is successful, the snapshot will appear in the Storage → Periodic Snapshot Tasks → View Periodic Snapshot Tasks → ZFS Snapshots tab of PULL, as seen in Figure 6.2d.

Figure 6.2d: Verifying the Snapshot was Replicated

If the snapshot is not replicated, see the next section for troubleshooting tips.

6.2.3 Troubleshooting Replication

If you have followed all of the steps above and have PUSH snapshots that are not replicating to PULL, check to see if SSH is working properly. On PUSH, open Shell and try to ssh into PULL. Replace hostname_or_ip with the value for PULL:

ssh -vv -i /data/ssh/replication hostname_or_ip

This command should not ask for a password. If it asks for a password, SSH authentication is not working. Go to Storage → Replication Tasks → View Replication Tasks and click the "View Host Key" button. Make sure that it matches the value of /etc/ssh/ssh_host_dsa_key.pub on PULL.

Also check /var/log/auth.log on PULL to see if it gives an indication of the error.

If the key is correct and replication is still not working, try deleting all snapshots on PULL except for the most recent one. In Storage → Periodic Snapshot Tasks → View Periodic Snapshot Tasks → ZFS Snapshots check the box next to every snapshot except for the last one (the one with 3 icons instead of 2), then click the global Destroy button at the bottom of the screen.

Once you have only one snapshot, open Shell on PUSH and use the zfs send command. To continue our example, the ZFS snapshot on the local/data dataset of PUSH is named auto-20110922.1753-2h, the IP address of PULL is 192.168.2.6, and the ZFS volume on PULL is remote. Note that the @ is used to separate the volume/dataset name from the snapshot name.

zfs send local/data@auto-20110922.1753-2h | ssh -i /data/ssh/replication 192.168.2.6 zfs receive local/data@auto-20110922.1753-2h

NOTE: if this command fails with the error "cannot receive new filesystem stream: destination has snapshots", check the box "initialize remote side for once" in the replication task and try again. If the zfs send command still fails, you will need to open Shell on PULL and use the zfs destroy -R volume_name@snapshot_name command to delete the stuck snapshot. You can then use the zfs list -t snapshot on PULL to confirm if the snapshot successfully replicated.

After successfully transmitting the snapshot, recheck again after the time period between snapshots lapses to see if the next snapshot successfully transmitted. If it is still not working, you can manually send an incremental backup of the last snapshot that is on both systems to the current one with this command:

zfs send local/data@auto-20110922.1753-2h | ssh -i /data/ssh/replication 192.168.2.6 zfs receive local/data@auto-20110922.1753-2h

6.3 Volumes

Since the storage disks are separate from the FreeNAS® operating system, you don't actually have a NAS (network-attached storage) system until you configure your disks into at least one volume. FreeNAS® supports the creation of both UFS and ZFS volumes; however, ZFS volumes are recommended to get the most out of your FreeNAS® system. This section demonstrates how to perform the following actions:

• If your disks are using an existing UFS or ZFS software RAID, see section 6.3.1 Auto Importing Volumes.

• If your disks are already formatted with UFS, NTFS, MSDOS, or EXT2, see section 6.3.2 Importing Volumes.

• If you wish to format your disks into a UFS volume or ZFS pool, see section 6.3.3 Volume Manager.

• If you wish to grow the size of an existing ZFS pool, see section 6.3.4 Using Volume Manager After a Volume Has Been Created.

• If you wish to divide an existing ZFS pool into datasets, see section 6.3.5 Creating ZFS Datasets.

• If you wish to create a ZFS block device to use as an iSCSI device extent, see section 6.3.6 Creating a zvol.

• If you wish to view and manage volumes, see section 6.3.7 Viewing Volumes.

• If you wish to view or configure disk properties, see section 6.3.8 Viewing Disks.

• If you wish to control user/group access to an existing UFS volume, ZFS pool, or ZFS dataset, see section 6.3.9 Setting Permissions.

• If your hardware supports multipath, FreeNAS® will automatically configure this for you. You can verify the configuration as described in section 6.3.10 Viewing Multipaths.

• If you need to replace a failed ZFS drive, see section 6.3.11 Replacing a Failed Drive or ZIL Device.

6.3.1 Auto Importing Volumes

If you click Storage → Volumes → Auto Import Volume, you can configure FreeNAS® to use an existing software UFS or ZFS RAID volume. Supported volumes are UFS GEOM stripes (RAID0), UFS GEOM mirrors (RAID1), UFS GEOM RAID3, as well as existing ZFS pools. UFS RAID5 is not supported as it is an unmaintained summer of code project which was never integrated into FreeBSD.

NOTE: versions of FreeNAS® up to and including 0.7.2 are based on ZFSv13. You can import these pools, but this is a one-way street. In other words, once you import a ZFSv13 volume, you can not revert back. FreeNAS® 8.3.0 does not support compatibility with Nexenta pools or Linux fuse-zfs.

Existing software RAID volumes should be available for selection from the drop-down menu. In the example shown in Figure 6.3a, the FreeNAS® system has an existing ZFS volume named test. Once the volume is selected, click the "Import Volume" button.

Figure 6.3a: Importing an Existing RAID Volume

NOTE: FreeNAS® will not import a dirty volume. If an existing UFS RAID does not show in the drop-down menu, you will need to fsck the volume. If an existing ZFS pool does not show in the drop-down menu, run zpool import from Shell to import the pool. If you suspect that your hardware is not being detected, run camcontrol devlist from Shell. If the disk does not appear in the output, check to see if the controller driver is supported or if it needs to be loaded by creating a tunable.

6.3.2 Importing Volumes

The Volume → Import Volume screen, shown in Figure 6.3b, is used to import a single disk or partition that has been formatted with a supported filesystem. FreeNAS® supports the import of disks that have been formatted with UFS, NTFS, MSDOS, or EXT2.

Figure 6.3b: Importing a Volume

Input a name for the volume, use the drop-down menu to select the disk or partition that you wish to import, and select the type of filesystem on the disk.

Before importing a disk, be aware of the following caveats:

• FreeNAS® will not import a dirty filesystem. If a supported filesystem does not show in the drop-down menu, you will need to fsck or run a disk check on the filesystem.

• earlier versions of FreeNAS® 8 had a bug that prevented the successful import of NTFS drives. Don't try to import NTFS if you are running a version earlier than FreeNAS® 8.0.1-RC1.

• FreeNAS® can not import dynamic NTFS volumes at this time. A future version of FreeBSD may address this issue.

6.3.3 Volume Manager

If you have unformatted disks or wish to overwrite the filesystem (and data) on your disks, use the Volume Manager to format the desired disks as a UFS volume or a ZFS pool.

If you click on Storage → Volume Manager, you will see a screen similar to the example shown in Figure 6.3c.

Figure 6.3c: Creating a ZFS Pool Using Volume Manager

Use the mouse to select the disk(s) to be formatted. To select multiple disks, highlight the first disk, then hold the shift key as you highlight the last disk.

The options available in the Group type differ depending upon the selected filesystem and the number of highlighted disks:

• if you select one disk, you can choose to format with UFS or ZFS

• if you select two disks, you can create a UFS or ZFS mirror or stripe

• if you select three disks, you can create a UFS or ZFS stripe, a UFS RAID3, or a ZFS mirror or RAIDZ1

• if you select four disks, you can create a UFS or ZFS mirror or stripe, or a ZFS RAIDZ1 or RAIDZ2

• if you select five disks, you can create a UFS or ZFS stripe, a UFS RAID3, or a ZFS mirror, RAIDZ1, RAIDZ2, or RAIDZ3

If you have more than five disks and are using ZFS, consider the size of your disk groups for best performance and scalability. An overview of the various RAID levels and recommended disk group sizes can be found in section 1.4.6 RAID Overview.

Table 6.3a summarizes the configuration options of this screen.

Table 6.3a: Options When Creating a Volume

NOTE: if deduplication is changed to "On", duplicate data blocks are removed synchronously. The result is that only unique data is stored and common components are shared among files. If deduplication is changed to "Verify", ZFS will do a byte-to-byte comparsion when two blocks have the same signature to make sure that the block contents are identical. Unless you have a lot of RAM and a lot of duplicate data, do not change the default deduplication setting of "Off". The dedup tables used during deduplication need ~8 GB of RAM per 1TB of data to be deduplicated. For performance reasons, consider using dataset compression rather than turning this option on. If you really do have a lot of RAM and a lot of duplicate data, consider creating a dataset for the duplicate data and enabling deduplication on that dataset instead.

The Add Volume button warns that creating a volume destroys all existing data on selected disk(s).

Depending upon the size and number of disks, the type of controller, the group type, and the type of filesystem, creating the volume may take a few minutes. Since UFS volume creation will format the disks, it may take as long as 10 or 15 minutes for a number of large disks. Once the volume is created, the screen will refresh and the new volume will be listed under Storage → Volumes.

The ZFS extra options can be used to create a log, cache, or spare device. When creating the volume, if you leave some disks/SSDs unchecked, they will appear as available within the ZFS extra section. The following options are available:

None: disk(s) are still available to be selected for formatting.

Log: selected disk will be dedicated for storing the ZIL (ZFS Intent Log). See the Separate Log Devices section of the ZFS Best Practices Guide for size recommendations. When two or more log devices are specified, FreeNAS® will mirror them. This is a prevention measure because losing the ZIL on a ZFSv15 pool could lead to disastrous results such as making the entire pool inaccessible. On a ZFSv28 pool, losing the ZIL can still cause the loss of in-flight writes.

Putting the ZIL on high speed devices can improve performance for certain workloads, especially those requiring synchronous writes such as NFS clients connecting to FreeNAS® running on VMWare ESXi. In such cases, a dedicated ZIL will make a big difference in performance. Applications that do not do a lot of synchronous writes are less likely to benefit from having dedicated ZIL devices. For VMWare, if a high speed ZIL device is not an option, using iSCSI instead of NFS is a workaround to achieve better performance.

Cache: selected device, typically an SSD, will be dedicated to L2ARC on-disk cache. See the Separate Cache Devices section of the ZFS Best Practices Guide for size recommendations. Losing an L2ARC device will not affect the integrity of the storage pool, but may have an impact on read performance, depending upon the workload and the ratio of dataset size to cache size.

Spare: will create a hot spare that is only used when another disk fails. Hot spares speed up healing in the face of hardware failures and are critical for high mean time to data loss (MTTDL) environments. One or two spares for a 40-disk pool is a commonly used configuration. Use this option with caution as there is a known bug in the current FreeBSD implementation. This will be fixed by zfsd which will be implemented once it is committed to FreeBSD.

6.3.4 Using Volume Manager After a Volume Has Been Created

Once a volume exists, an extra “Volume to extend” field will be added to Storage → Volumes → Volume Manager, as seen in Figure 6.3d. This field is mutually exclusive with the "Volume name" field in that you can only use one or the other.

Figure 6.3d: Volume to Extend Field

This screen can be used to perform the following tasks:

1. Create another UFS or ZFS volume. Input a "Volume name" and create a volume as usual.

2. Add a ZFS log or cache device to an existing ZFS volume. Select the volume name using the drop-down menu, select the device to add, then select Log or Cache from the ZFS Extra field.

3. Extend an existing ZFS volume as described below.

NOTE: you can not extend an existing UFS volume.

When extending a volume, ZFS supports the addition of virtual devices (vdevs) to an existing volume (ZFS pool). A vdev can be a single disk, a stripe, a mirror, a RAIDZ1, RAIDZ2, or a RAIDZ3. Once a vdev is created, you can not add more drives to that vdev ; however, you can stripe a new vdev (and its disks) with the same type of existing vdev in order to increase the overall size of ZFS the pool. In other words, when you extend a ZFS volume, you are really striping similar vdevs. Here are some examples:

• to extend a ZFS stripe, add one or more disks. Since there is no redundancy, you do not have to add the same amount of disks as the existing stripe.

• to extend a ZFS mirror, add the same number of drives. The resulting striped mirror is a RAID 10.

• to extend a three drive RAIDZ1, add three additional drives. The result is a RAIDZ+0, similar to RAID 50 on a hardware controller.

• to extend a RAIDZ2 requires a minimum of four additional drives. The result is a RAIDZ2+0, similar to RAID 60 on a hardware controller.

In the “Volume to extend” section, select the existing volume that you wish to stripe with. This will grey out the Volume name field and select ZFS as the filesystem type. Highlight the required number of additional disk(s), select the same type of RAID used on the existing volume, and click Add Volume.

6.3.5 Creating ZFS Datasets

An existing ZFS volume can be divided into datasets. Permissions, compression, deduplication, and quotas can be set on a per dataset basis, allowing more granular control over access to storage data. A dataset is similar to a folder in that you can set permissions; it is also similar to a filesystem in that you can set properties such as quotas and compression as well as create snapshots.

NOTE: ZFS provides thick provisioning using quotas and thin provisioning using reserved space.

If you select an existing ZFS volume → Create ZFS Dataset, you will see the screen shown in Figure 6.3e. Table 6.3b summarizes the options available when creating a ZFS dataset.

Once a dataset is created, you can click on that dataset and select Create ZFS Dataset, thus creating a nested dataset, or a dataset within a dataset. When creating datasets, double-check that you are using the Create ZFS Dataset option for the intended volume or dataset. If you get confused when creating a dataset on a volume, click all existing datasets to close them--the remaining Create ZFS Dataset will be for the volume.

Figure 6.3e: Creating a ZFS Dataset

Table 6.3b: ZFS Dataset Options

NOTE on compression: most media (e.g. .mp3, .mp4, .avi) is already compressed, meaning that you'll increase CPU utilization for no gain if you store these files on a compressed dataset. However, if you have raw .wav rips of CDs or .vob rips of DVDs, you will see a performance gain using a compressed dataset. When selecting a compression type, you need to balance performance with the amount of compression. For example, lzjb is optimized for performance while providing decent data compression. gzip varies from levels 1 to 9 where gzip fastest (level 1) gives the least compression and gzip maximum (level 9) provides the best compression but is discouraged due to its performance impact. zle is a fast and simple algorithm to eliminate runs of zeroes.

6.3.6 Creating a zvol

A zvol is a feature of ZFS that creates a block device over ZFS. This allows you to use a zvol as an iSCSI device extent.

To create a zvol, select an existing ZFS volume → Create ZFS Volume which will open the screen shown in Figure 6.3f.

Figure 6.3f: Creating a zvol

The configuration options are described in Table 6.3c:

Table 6.3c: zvol Configuration Options

6.3.7 Viewing Volumes

If you click Storage → Volumes → View Volumes, you can view and further configure existing volumes and datasets, as seen in the example shown in Figure 6.3g.

Figure 6.3g: Viewing Volumes

The icons towards the top of the right frame allow you to: access Volume Manager, import a volume, auto import a volume, and view disks. If the system has multipath-capable hardware, an extra button will be added to view multipaths.

The eight icons associated with a ZFS volume are used to:

• Detach Volume: allows you to either detach a disk before removing it from the system (also known as a ZFS export) or to delete the contents of the volume, depending upon the choice you make in the screen that pops up when you click this button. The pop-up message, seen in Figure 6.3h, will show the current used space, provide the check box "Mark the disks as new (destroy data), prompt you to make sure that you want to do this, warn you if the volume has any associated shares and ask if you wish to delete them, and the browser will turn red to alert you that you are about to do something that will make the data inaccessible. If you do not check the box to mark the disks as new, the volume will be exported (ZFS volumes only). This means that the data is not destroyed and the volume can be re-imported at a later time. If you will be moving a ZFS drive from one system to another, perform this export action first. This operation flushes any unwritten data to disk, writes data to the disk indicating that the export was done, and removes all knowledge of the pool from the system. If you do check the box to mark the disks as new, the volume and all of its data will be destroyed and the underlying disks will be returned to their raw state.

Figure 6.3h: Detaching or Deleting a Volume

• Scrub Volume: ZFS scrubs and how to schedule them are described in more detail in section 6.4 ZFS Scrubs. This button allows you to manually initiate a scrub. A scrub is I/O intensive and can negatively impact performance, meaning that you should not initiate one while the system is busy. A cancel button is provided should you need to cancel a scrub.

NOTE: if you do cancel a scrub, the next scrub will start over from the beginning, not where the cancelled scrub left off.

• Edit ZFS Options: allows you to edit the volume's compression level, atime setting, dataset quota, and reserved space for quota.

• Create ZFS Dataset: allows you to create a dataset.

• Create ZFS Volume: allows you to create a zvol to use as an iSCSI device extent.

• Change Permissions: allows you to edit the volume's user, group, Unix rwx permissions, type of ACL, and to enable recursive permissions on the volume's subdirectories.

• Create Snapshot: allows you to configure the snapshot's name and whether or not it is recursive before manually creating a one-time snapshot. If you wish to schedule the regular creation of snapshots, instead create a periodic snapshot task.

• Volume Status: as seen in the example in Figure 6.3i, this screen shows the device name and status of each disk in the ZFS pool as well as any read, write, or checksum errors. For each device, buttons are provided to edit the device's options (shown in Figure 6.3j), replace the device (as described in section 6.3.11 Replacing a Failed Drive or ZIL Device), or to offline the device.

Figure 6.3i: Volume Status

If you click a disk's Edit button in Volume Status, you will see the screen shown in Figure 6.3j:

Figure 6.3j: Editing a Disk

Table 6.3d summarizes the configurable options.

Table 6.3d: Disk Options

A ZFS dataset only has five icons as the scrub volume, create ZFS volume, and volume status buttons only apply to volumes. In a dataset, the Detach Volume button is replaced with the Destroy Dataset button. If you click the Destroy Dataset button, the browser will turn red to indicate that this is a destructive action. The pop-up warning message will warn that destroying the dataset will delete all of the files on that dataset.

6.3.8 Viewing Disks

Storage → Volumes → View Disks allows you to view all of the disks recognized by the FreeNAS® system. An example is shown in Figure 6.3k.

Figure 6.3k: Viewing Disks

For each device, the current configuration of the options described in Table 6.3d is displayed. Click a disk's Edit button to change its configuration.

The Wipe button is used to blank a disk and will provide a progress bar of the wipe's status. Use this option before discarding a disk.

6.3.9 Setting Permissions

Setting permissions is an important aspect of configuring volumes. The graphical administrative interface is meant to set the initial permissions for a volume or dataset in order to make it available as a share. Once a share is available, the client operating system should be used to fine-tune the permissions of the files and directories that are created by the client.

Section 7 Sharing contains configuration examples for several types of permission scenarios. This section provides an overview of the screen that is used to set permissions.

Once a volume or dataset is created, it will be listed by its mount point name in Storage → Volumes → View Volumes. If you click the Change Permissions icon for a specific volume/dataset, you will see the screen shown in Figure 6.3l. Table 6.3e summarizes the options in this screen.

Figure 6.3l: Changing Permissions on a Volume or Dataset

Table 6.3e: Options When Changing Permissions

When in doubt, or if you have a mix of operating systems in your network, select Unix ACLs as all clients understand them. Windows ACLs are appropriate when the network contains only Windows clients and are the preferred option within an Active Directory domain. Windows ACLs add a superset of permissions that augment those provided by Unix ACLs. While Windows clients also understand Unix ACLs, they won't benefit from the extra permissions provided by Active Directory and Windows ACLs when Unix ACLs are used.

NOTE: if you change your mind about the type of ACL, you do not have to recreate the volume. That is, existing data is not lost if the type of ACL is changed. However, if you change from Windows ACLs to Unix ACLs, the extended permissions provided by Windows ACLs will be removed from the existing files.

6.3.10 Viewing Multipaths

FreeNAS® uses gmultipath(8) to provide multipath I/O support on systems containing hardware that is capable of multipath. An example would be a dual SAS expander backplane in the chassis or an external JBOD.

Multipath hardware adds fault tolerance to a NAS as the data is still available even if one disk I/O path has a failure.

FreeNAS® automatically detects active/active and active/passive multipath-capable hardware. Any multipath-capable devices that are detected will be placed in multipath units with the parent devices hidden. The configuration will be displayed in Storage → Volumes → View Multipaths, as seen in the example in Figure 6.3m. Note that this option will not be displayed in the Storage → Volumes tree on systems that do not contain multipath-capable hardware.

Figure 6.3m: Viewing Multipaths

Figure 6.3m provides an example of a system with a SAS ZIL and a SAS hard drive. The ZIL device is capable of active/active writes, whereas the hard drive is capable of active/read.

6.3.11 Replacing a Failed Drive or ZIL Device

If you are using any form of redundant RAID, you should replace a failed drive as soon as possible to repair the degraded state of the RAID. Depending upon the capability of your hardware, you may or may not need to reboot in order to replace the disk. AHCI capable hardware does not require a reboot.

NOTE: a stripe (RAID0) does not provide redundancy. If you lose a disk in a stripe, the data on the stripe is lost.

Before physically removing the failed drive or ZIL device, go to Storage → Volumes → View Volumes → Volume Status and locate the failed device. Once you have located the failed device in the GUI, perform the following steps:

1. If the disk is formatted with ZFS, click the disk's Offline button in order to change its status to OFFLINE. This step is needed to properly remove the device from the ZFS pool and to prevent swap issues. If your hardware supports hot-pluggable disks, click the disk's Offline button, pull the disk, then skip to step 3.

NOTE: if the process of changing the disk's status to OFFLINE fails with a "disk offline failed - no valid replicas" message, you will need to scrub the ZFS volume first using its Scrub Volume button in Storage → Volumes → View Volumes. Once the scrub completes, try to Offline the disk again before proceeding.

2. If the hardware is not AHCI capable, shutdown the system in order to physically replace the disk. When finished, return to the GUI and locate the OFFLINE disk.

3. Once the disk is showing as OFFLINE, click the disk's Replace button. Select the replacement disk from the drop-down menu and click the Replace Disk button. If the disk is being added to a ZFS pool, it will start to resilver. You can use the zpool status command in Shell to monitor the status of the resilvering.

4. If the replaced disk continues to be listed after resilvering is complete, use the Detach button to remove the disk from the list.

In the example shown in Figure 6.3n, failed disk ada0 is being replaced by disk ada3.

Figure 6.3n: Replacing a Failed Disk

6.4 ZFS Scrubs

Storage → ZFS Scrubs allows you to schedule and manage scrubs on a ZFS volume. Performing a ZFS scrub on a regular basis helps to identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and to provide early alerts to disk failures. If you have consumer-quality drives, consider a weekly scrubbing schedule. If you have datacenter-quality drives, consider a monthly scrubbing schedule.

NOTE: depending upon the amount of data, a scrub can take a long time. Scrubs are I/O intensive and can negatively impact performance. They should be scheduled for evenings or weekends to minimize the impact to users.

When you create a volume that is formatted with ZFS, a ZFS scrub is automatically scheduled for you. An entry of the same volume name is added to Storage → ZFS Scrubs and a summary of this entry can be viewed in Storage → ZFS Scrubs → View ZFS Scrubs. Figure 6.4a displays the default settings for the volume named volume1. Table 6.4a summarizes the options in this screen.

Figure 6.4a: Viewing a Volume's Default Scrub Settings

Table 6.4a: ZFS Scrub Options

You should review the default selections and, if necessary, modify them to meet the needs of your environment.

While a delete button is provided, deleting a scrub is not recommended as a scrub provides an early indication of disk issues that could lead to a disk failure. If you find that a scrub is too intensive for your hardware, consider disabling the scrub as a temporary measure until the hardware can be upgraded.

If you do delete a scrub, you can create a new scrub task by clicking Storage → Volumes → ZFS Scrubs → Add ZFS Scrub.

7 Sharing Configuration

Once you have a volume, create at least one share so that the storage is accessible by the other computers in your network. The type of share you create depends upon the operating system(s) running in your network, your security requirements, and expectations for network transfer speeds. The following types of shares and services are available:

Apple (AFP) Shares: the Apple File Protocol (AFP) type of share is a good choice if all of your computers run Mac OS X.

Unix (NFS) Shares: the Network File System (NFS) type of share is accessible by Mac OS X, Linux, BSD, and the professional/enterprise versions (not the home editions) of Windows. It is a good choice if there are many different operating systems in your network. Depending upon the operating system, it may require the installation or configuration of client software on the desktop.

Windows (CIFS) Shares: the Common Internet File System (CIFS) type of share is accessible by Windows, Mac OS X, Linux, and BSD computers, but it is slower than an NFS share due to the single-threaded design of Samba. It provides more configuration options than NFS and is a good choice on a network containing only Windows systems. However, it is a poor choice if the CPU on the FreeNAS® system is limited; if your CPU is maxed out, you need to upgrade the CPU or consider another type of share.

If you are looking for a solution that allows fast access from any operating system, consider configuring the FTP service instead of a share and use a cross-platform FTP and file manager client application such as Filezilla. Secure FTP can be configured if the data needs to be encrypted.

If data security is a concern and your network's users are familiar with SSH command line utilities or WinSCP, consider configuring the SSH service instead of a share. It will be slower than unencrypted FTP due to the overhead of encryption, but the data passing through the network will be encrypted.

NOTE: while the GUI will let you do it, it is a bad idea to share the same volume or dataset using multiple types of access methods. Different types of shares and services use different file locking methods. For example, if the same volume is configured to use both NFS and FTP, NFS will lock a file for editing by an NFS user, but a FTP user can simultaneously edit or delete that file. This will result in lost edits and confused users. Another example: if a volume is configured for both AFP and CIFS, Windows users may be confused by the extra filenames used by Mac files and delete the ones they don't understand; this will corrupt the files on the AFP share. Pick the one type of share or service that makes the most sense for the types of clients that will access that volume, and configure that volume for that one type of share or service. If you need to support multiple types of shares, divide the volume into datasets and use one dataset per share.

This section will demonstrate how to create AFP, NFS, and CIFS shares. FTP and SSH configurations are described in section 8 Services Configuration.

7.1 Apple (AFP) Shares

FreeNAS® uses the Netatalk AFP server to share data with Apple systems. Configuring AFP shares is a multi-step process that requires you to create or import users and groups, set volume/dataset permissions, create the AFP share(s), configure the AFP service, then enable the AFP service in Services → Control Services.

This section describes the configuration screen for creating the AFP share. It then provides configuration examples for creating a guest share, configuring Time Machine to backup to a dataset on the FreeNAS® system, and for connecting to the share from a Mac OS X client.

7.1.1 Creating AFP Shares

If you click Sharing → Apple (AFP) Shares → Add Apple (AFP) Share, you will see the screen shown in Figure 7.1a. Some settings are only available in Advanced Mode. To see these settings, either click the Advanced Mode button or configure the system to always display these settings by checking the box “Show advanced fields by default” in System → Settings → Advanced.

Figure 7.1a: Creating an AFP Share

Table 7.1a summarizes the available options when creating an AFP share. Refer to Chapter 3. Setting up Netatalk for a more detailed explanation of the available options.

Once you press the OK button when creating the AFP share, a pop-up menu will ask "Would you like to enable this service?" Click Yes and Services → Control Services will open and indicate whether or not the AFP service successfully started.

Table 7.1a: AFP Share Configuration Options

7.1.2 Connecting to AFP Shares As Guest

AFP supports guest logins, meaning that all of your Mac OS X users can access the AFP share without requiring their user accounts to first be created on or imported into the the FreeNAS® system. In this configuration example, the AFP share has been configured for guest access as follows:

1. A ZFS volume named /mnt/data has its permissions set to the built-in nobody user account and nobody group.

2. An AFP share has been created with the following attributes:

• Name: freenas (this is the name that will appear to Mac OS X clients)

• Path: /mnt/data

• Share Password: the password that will be used to access the share has been input and confirmed

• Allow List: set to nobody

• Read-write Access: set to nobody

• Disk Discovery: checkbox has been checked

3. Services → AFP has been configured as follows:

• Server Name: freenas

• Guest Access: checkbox is checked

• nobody is selected in the Guest account drop-down menu

Once the AFP service has been started in Services → Control Services, Mac OS X users can connect to the AFP share by clicking Go → Connect to Server. In the example shown in Figure 7.1b, the user has input afp:// followed by the IP address of the FreeNAS® system.

Figure 7.1b: Connect to Server Dialogue

Click the Connect button and a login box, seen in Figure 7.1c, will appear. Since a password has been configured for this AFP share, the user must input the share password (i.e. not their own password).

Figure 7.1c: Authenticating to the AFP Share

Once connected, Finder will automatically open. The name of the AFP share will be displayed in the SHARED section in the left frame and the contents of the share will be displayed in the right frame. In the example shown in Figure 7.1d, /mnt/data has one folder named images. The user can now copy files to and from the share.

Figure 7.1d: Viewing the Contents of the Share From a Mac System

To disconnect from the volume, click the eject button in the Shared sidebar.

7.1.3 Using Time Machine

Mac OS X includes the Time Machine application which can be used to schedule automatic backups. In this configuration example, Time Machine will be configured to backup to an AFP share on a FreeNAS® system. To configure the AFP share on the FreeNAS® system:

1. A ZFS dataset named /mnt/data/backup_user1 with a quota of 60G was created in Storage → Volumes → Create ZFS Dataset.

2. A user account was created as follows:

• Username: user1

• Home Directory: /mnt/data/backup_user1

• the Full Name, E-mail, and Password fields were set where the Username and Password match the values for the user on the Mac OS X system

3. An AFP share with a Name of backup_user1 has been created with the following attributes:

• Path: /mnt/data/backup_user1

• Allow List: set to user1

• Read-write Access: set to user1

• Disk Discovery: checkbox has been checked

• Disk Discovery mode: set to Time Machine

4. Services → AFP has been configured as follows:

• Server Name: freenas

• Guest Access: checkbox is unchecked

5. The AFP service has been started in Services → Control Services.

To configure Time Machine on the Mac OS X client, go to System Preferences → Time Machine which will open the screen shown in Figure 7.1e. Click ON and a pop-up menu should show the FreeNAS® system as a backup option. In our example, it is listed as backup_user1 on "freenas". Highlight the entry representing the FreeNAS® system and click the “Use Backup Disk” button. A connection bar will open and will prompt for the user account's password--in this example, the password for the user1 account.

Figure 7.1e: Configuring Time Machine on Mac OS X Lion

Time Machine will create a full backup after waiting two minutes. It will then create a one hour incremental backup for the next 24 hours, and then one backup each day, each week and each month. Since the oldest backups are deleted when the ZFS dataset becomes full, make sure that the quota size you set is sufficient to hold the backups. Note that a default installation of Mac OS X is ~21 GB in size.

If you receive a "Time Machine could not complete the backup. The backup disk image could not be created (error 45)" error when backing up to the FreeNAS® system, you will need to create a sparsebundle image using these instructions.

7.2 Unix (NFS) Shares

FreeNAS® supports the Network File System (NFS) for sharing volumes over a network. Once the NFS share is configured, clients use the mount command to mount the share. Once mounted, the share appears as just another directory on the client system. Some Linux distros require the installation of additional software in order to mount an NFS share. On Windows systems, enable Services for NFS in the Ultimate or Enterprise editions or install an NFS client application.

NOTE: for performance reasons, iSCSI is preferred to NFS shares when FreeNAS is installed on ESXi. If you are considering creating NFS shares on ESXi, read through the performance analysis at Running ZFS over NFS as a VMware Store.

Configuring NFS is a multi-step process that requires you to create NFS share(s), configure NFS in Services → NFS, then start NFS in Services → Control Panel. It does not require you to create users or groups as NFS uses IP addresses to determine which systems are allowed to access the NFS share.

This section demonstrates how to create an NFS share, provides a configuration example, demonstrates how to connect to the share from various operating systems, and provides some troubleshooting tips.

7.2.1 Creating NFS Shares

To create an NFS share, click Sharing → Unix (NFS) Shares → Add Unix (NFS) Share, shown in Figure 7.2a.

Figure 7.2a: Creating an NFS Share

Once you press the OK button when creating the NFS share, a pop-up menu will ask "Would you like to enable this service?" Click Yes and Services → Control Services will open and indicate whether or not the NFS service successfully started.

Table 7.2a summarizes the options in this screen.

Table 7.2a: NFS Share Options

When creating the NFS share, keep the following points in mind:

1. The Maproot and Mapall options are exclusive, meaning you can only use one or the other--the GUI will not let you use both. The Mapall options supersede the Maproot options. If you only wish to restrict the root user's permissions, set the Maproot option. If you wish to restrict the permissions of all users, set the Mapall option.

2. Each volume or dataset is considered to be its own filesystem and NFS is not able to cross filesystem boundaries.

3. The network or host must be unique per share and per filesystem or directory.

4. The "All directories" option can only be used once per share per filesystem.

To better understand these restrictions, consider the following scenario where there are:

• 2 networks named 10.0.0.0/8 and 20.0.0.0/8

• a ZFS volume named volume1 with 2 datasets named dataset1 and dataset2

• dataset1 has a directory named directory1

Because of restriction #3, you will receive an error if you try to create one NFS share as follows:

• Authorized networks: 10.0.0.0/8,20.0.0.0/8

• Path: /mnt/volume1/dataset1 and /mnt/volume1/dataset1/directory1

Instead, you should select the Path of /mnt/volume1/dataset1 and check the "All directories" box.

However, you could restrict that directory to one of the networks by creating two shares as follows.

First NFS share:

• Authorized networks: 10.0.0.0/8

• Path: /mnt/volume1/dataset1

Second NFS share:

• Authorized networks: 20.0.0.0/8

• Path: /mnt/volume1/dataset1/directory1

Note that this requires the creation of two shares as it can not be accomplished in one share.

7.2.2 Sample NFS Share Configuration

By default the Mapall options shown in Figure 7.2a show as N/A. This means that when a user connects to the NFS share, they connect with the permissions associated with their user account. This is a security risk if a user is able to connect as root as they will have complete access to the share.

A better scenario is to do the following:

1. Specify the built-in nobody account to be used for NFS access.

2. In the permissions of the volume/dataset that is being shared, change the owner and group to nobody and set the permissions according to your specifications.

3. Select nobody in the Mapall User and Mapall Group drop-down menus for the share in Sharing → Unix (NFS) Shares.

With this configuration, it does not matter which user account connects to the NFS share, as it will be mapped to the nobody user account and will only have the permissions that you specified on the volume/dataset. For example, even if the root user is able to connect, it will not gain root access to the share.

7.2.3 Connecting to the NFS Share

In the following examples, an NFS share on a FreeNAS® system with the IP address of 192.168.2.2 has been configured as follows:

1. A ZFS volume named /mnt/data has its permissions set to the nobody user account and the nobody group.

2. A NFS share has been created with the following attributes:

• Path: /mnt/data

• Authorized Network: 192.168.2.0/24

• MapAll User and MapAll Group are both set to nobody

• the All Directories checkbox has been checked

7.2.3.1 From BSD or Linux Clients

To make this share accessible on a BSD or a Linux system, run the following command as the superuser (or with sudo) from the client system (repeat for each client that needs access to the NFS share):

mount -t nfs 192.168.2.2:/mnt/data /mnt

The mount command uses the following options:

• -t nfs: specifies the type of share.

• 192.168.2.2: replace with the IP address of the FreeNAS® system

• /mnt/data: replace with the name of the NFS share

• /mnt: a mount point on the client system. This must be an existing, empty directory. The data in the NFS share will be made available to the client in this directory.

The mount command should return to the command prompt without any error messages, indicating that the share was successfully mounted.

Once mounted, this configuration allows users on the client system to copy files to and from /mnt (the mount point) and all files will be owned by nobody:nobody. Any changes to /mnt will be saved to the FreeNAS® system's /mnt/data volume.

Should you wish to make any changes to the NFS share's settings or wish to make the share inaccessible, first unmount the share on the client as the superuser:

umount /mnt

7.2.3.2 From Microsoft Clients

Enterprise versions of Windows systems can connect to NFS shares using Services for NFS. Connecting to NFS shares is often faster than connecting to CIFS shares due to the single-threaded limitation of Samba. Instructions for connecting from an Enterprise version of Windows 7 can be found at Mount Linux NFS Share on Windows 7.

NOTE: Services for NFS is only available in the Ultimate or Enterprise editions of Windows.

If your Windows client is running a Home Edition of Windows 7, Nekodrive provides an open source graphical NFS client. To use this client, you will need to install the following on the Windows system:

• 7zip to extract the Nekodrive download files

• NFSClient and NFSLibrary from the Nekodrive download page; once downloaded, extract these files using 7zip

• .NET Framework 4.0

Once everything is installed, run the NFSClient executable to start the GUI client. In the example shown in Figure 7.2b, the user has connected to the example /mnt/data share of the FreeNAS® system at 192.168.2.2.

Figure 7.2b: Using the Nekodrive NFSClient from Windows 7 Home Edition

7.2.3.3 From Mac OS X Clients

To mount the NFS volume from a Mac OS X client, click on Go → Connect to Server. In the Server Address field, input nfs:// followed by the IP address of the FreeNAS® system and the name of the volume/dataset being shared by NFS. The example shown in Figure 7.2c continues with our example of 192.168.2.2:/mnt/data.

Figure 7.2c: Mounting the NFS Share from Mac OS X

Once connected, Finder will automatically open. The IP address of the FreeNAS® system will be displayed in the SHARED section in the left frame and the contents of the share will be displayed in the right frame. In the example shown in Figure 7.2d, /mnt/data has one folder named images. The user can now copy files to and from the share.

Figure 7.2d: Viewing the NFS Share in Finder

7.2.4 Troubleshooting

Some NFS clients do not support the NLM (Network Lock Manager) protocol used by NFS. You will know that this is the case if the client receives an error that all or part of the file may be locked when a file transfer is attempted. To resolve this error, add the option -o nolock when running the mount command on the client in order to allow write access to the NFS share.

If you receive an error about a "time out giving up" when trying to mount the share from a Linux system, make sure that the portmapper service is running on the Linux client and start it if it is not. If portmapper is running and you still receive timeouts, force it to use TCP by including -o tcp in your mount command.

If you receive an error "RPC: Program not registered", upgrade to the latest version of FreeNAS® and restart the NFS service after the upgrade in order to clear the NFS cache.

If your clients are receiving "reverse DNS" or timeout errors, add an entry for the IP address of the FreeNAS® system in the "Host name database" field of Network → Global Configuration.

7.3 Windows (CIFS) Shares

FreeNAS® uses Samba to share volumes using Microsoft's CIFS protocol. CIFS is built into the Windows and Mac OS X operating systems and most Linux and BSD systems pre-install the Samba client which provides support for CIFS. If your distro did not, install the Samba client using your distro's software repository.

Configuring CIFS shares is a multi-step process that requires you to set permissions, create CIFS share(s), configure the CIFS service in Services → CIFS, then enable the CIFS service in Services → Control Services. If your Windows network has a Windows server running Active Directory, you will also need to configure the Active Directory service in Services → Active Directory. Depending upon your authentication requirements, you may need to create or import users and groups.

This section will demonstrate some common configuration scenarios:

• If you would like an overview of the configurable parameters, see section 7.3.1 Creating CIFS Shares.

• If you would like an example of how to configure access that does not require authentication, see section 7.3.2 Configuring Anonymous Access.

• If you would like each user to authenticate before accessing the share, see section 7.3.3 Configuring Local User Access.

• If you would like to use Shadow Copies, see section 7.3.4 Configuring Shadow Copies.

• If you are having problems accessing your CIFS share, see section 8.4.1 Troubleshooting Tips.

7.3.1 Creating CIFS Shares

Figure 7.3a shows the configuration screen that appears when you click Sharing → Windows (CIFS Shares) → Add Windows (CIFS) Share. Some settings are only available in Advanced Mode. To see these settings, either click the Advanced Mode button or configure the system to always display these settings by checking the box “Show advanced fields by default” in System → Settings → Advanced.

Table 7.3a summarizes the options when creating a CIFS share. smb.conf(5) provides more details for each configurable option.

Once you press the OK button when creating the CIFS share, a pop-up menu will ask "Would you like to enable this service?" Click Yes and Services → Control Services will open and indicate whether or not the CIFS service successfully started.

Figure 7.3a: Adding a CIFS Share

Table 7.3a: Options for a CIFS Share

NOTE: hostname lookups add some time to accessing the CIFS share. If you only use IP addresses, uncheck the "Hostnames lookups" box in Services → CIFS.

If you wish some files on a shared volume to be hidden and inaccessible to users, put a veto files= line in the Auxiliary Parameters field. The syntax for this line and some examples can be found here.

7.3.2 Configuring Anonymous Access

To share a volume without requiring users to input a password, configure anonymous CIFS sharing. This type of share can be configured as follows:

1. Create a guest user account to be used for anonymous access in Account → Users → Add User with the following attributes:

• Username: guest

• Home Directory: browse to the volume to be shared

• check the Disable logins box

2. Associate the guest account with the volume in Storage → Volumes. Expand the volume's name then click Change Permissions. Select guest as the Owner(user) and Owner(group) and check that the permissions are appropriate for the share. If non-Windows systems will be accessing the CIFS share, leave the type of permissions as Unix. Only change the type of permissions to Windows if the share is only accessed by Windows systems.

3. Create a CIFS share in Sharing → Windows (CIFS) Shares → Add Windows (CIFS) Share with the following attributes:

• Name: freenas

• Path: browse to the volume to be shared

• check the boxes Allow Guest Access and Only Allow Guest Access

• Hosts Allow: add the addresses which are allowed to connect to the share; acceptable formats are the network or subnet address with CIDR mask (e.g. 192.168.2.0/24 or 192.168.2.32/27) or specific host IP addresses, one address per line

4. Configure the CIFS service in Services → CIFS with the following attributes:

• Authentication Model: Anonymous

• Guest Account: guest

• check the boxes boxes Allow Empty Password and Enable Home Directories

• Home Directories: browse to the volume to be shared

5. Start the CIFS service in Services → Control Services. Click the click the red OFF button next to CIFS. After a second or so, it will change to a blue ON, indicating that the service has been enabled.

6. Test the share.

To test the share from a Windows system, open Explorer, click on Network and you should see an icon named FREENAS. Since anonymous access has been configured, you should not be prompted for a username or password in order to see the share. An example is seen in Figure 7.3b.

Figure 7.3b: Accessing the CIFS Share from a Windows Computer

If you click on the FREENAS icon, you can view the contents of the CIFS share.

To prevent Windows Explorer from hanging when accessing the share, map the share as a network drive. To do this, right-click the share and select "Map network drive..." as seen in Figure 7.3c.

Figure 7.3c: Mapping the Share as a Network Drive

Choose a drive letter from the drop-down menu and click the Finish button as shown in Figure 7.3d.

Figure 7.3d: Selecting the Network Drive Letter

7.3.3 Configuring Local User Access

If you would like each user to authenticate before accessing the CIFS share, configure local user access as follows:

1. If you are not using Active Directory or LDAP, create a user account for each user in Account → Users → Add User with the following attributes:

• Username and Password: matches the username and password on the client system

• Home Directory: browse to the volume to be shared

• Repeat this process to create a user account for every user that will need access to the CIFS share

2. If you are not using Active Directory or LDAP, create a group in Account → Groups → Add Group. Once the group is created, click its Members button and add the user accounts that you created in step 1.

3. Give the group permission to the volume in Storage → View Volumes. When setting the permissions:

• set Owner(user) to nobody

• set the Owner(group) to the one you created in Step 2

• Mode: check the write checkbox for the Group as it is unchecked by default

4. Create a CIFS share in Sharing → CIFS Shares → Add CIFS Share with the following attributes:

• Name: input the name of the share

• Path: browse to the volume to be shared

• keep the Browsable to Network Clients box checked

NOTE: be careful about unchecking the Browsable to Network Clients box. When this box is checked (the default), other users will see the names of every share that exists using Windows Explorer, but they will receive a permissions denied error message if they try to access someone else's share. If this box is unchecked, even the owner of the share won't see it or be able to create a drive mapping for the share in Windows Explorer. However, they can still access the share from the command line. Unchecking this option provides limited security and is not a substitute for proper permissions and password control.

5. Configure the CIFS service in Services → CIFS as follows:

• Authentication Model: if you are not using Active Directory or LDAP, select Local User

• Workgroup: if you are not using Active Directory or LDAP, set to the name being used on the Windows network; unless it has been changed, the default Windows workgroup name is WORKGROUP

6. Start the CIFS service in Services → Control Services. Click the click the red OFF button next to CIFS. After a second or so, it will change to a blue ON, indicating that the service has been enabled.

7. Test the share.

To test the share from a Windows system, open Explorer and click on Network. For this configuration example, a system named FREENAS should appear with a share named backups. If you click on backups, a Windows Security pop-up screen should prompt for the user's username and password. Once authenticated, the user can copy data to and from the CIFS share.

NOTE: since the share is group writable, any authenticated user can change the data in the share. If you wish to setup shares where a group of users have access to some folders but only individuals have access to other folders (where all these folders reside on the same volume), create these directories and set their permissions using Shell. Instructions for doing so can be found at the forum post Set Permission to allow users to share a common folder & have private personal folder.

7.3.4 Configuring Shadow Copies

Shadow Copies, also known as the Volume Shadow Copy Service (VSS) or Previous Versions, is a Microsoft service for creating volume snapshots. Shadow copies allow you to easily restore previous versions of files from within Windows Explorer. Shadow Copy support is built into Vista and Windows 7. Windows XP or 2000 users need to install the Shadow Copy client.

When you create a periodic snapshot task on a ZFS volume that is configured as a CIFS share in FreeNAS®, it is automatically configured to support shadow copies.

7.3.4.1Prerequisites

Before using shadow copies with FreeNAS®, be aware of the following caveats:

• if the Windows system is not fully patched to the latest service pack, Shadow Copies may not work. If you are unable to see any previous versions of files to restore, use Windows Update to make sure that the system is fully up-to-date.

• at this time, shadow copy support only works for ZFS pools or datasets. This means that the CIFS share must be configured on a volume or dataset, not on a directory. Directory support will be added in a future version of FreeNAS®.

• at this time, there must be a one-to-one mapping between the periodic snapshot task and the CIFS share. In practical terms, this means that you can either share a ZFS volume to be shared by all users, or you can create a dataset plus an associated CIFS share for each user. Since directories can not be shadow copied at this time, if you configure "Enable home directories" on the CIFS service, any data stored in the user's home directory will not be shadow copied.

• shadow copies will not work with a manual snapshot, you must create a periodic snapshot task for the pool or dataset being shared by CIFS. At this time, if multiple snapshot tasks are created for the same pool/dataset being shared by CIFS, shadow copies will only work on the last executed task at the time the CIFS service started. A future version of FreeNAS® will address this limitation.

• the periodic snapshot task should be created and at least one snapshot should exist before creating the CIFS share. If you created the CIFS share first, restart the CIFS service in Services → Control Services.

• Windows ACLs and appropriate permissions must be configured on the volume/dataset being shared by CIFS.

• users can not delete shadow copies on the Windows system due to the way Samba works. Instead, the administrator can remove snapshots from the FreeNAS® administrative GUI. The only way to disable shadow copies completely is to remove the periodic snapshot task and delete all snapshots associated with the CIFS share.

7.3.4.2 Configuration Example

In this example, a Windows 7 computer has two users: user1 and user2. To configure FreeNAS® to provide shadow copy support:

1. For the ZFS volume named /mnt/data, create two ZFS datasets in Storage → Volumes → /mnt/data → Create ZFS Dataset. The first dataset is named /mnt/data/user1 and the second dataset is named /mnt/data/user2.

2. If you are not using Active Directory or LDAP, create two users, user1 and user2 in Account → Users → Add User. Each user has the following attributes:

• Username and Password: matches that user's username and password on the Windows system

• Home Directory: browse to the dataset created for that user

3. Set the permissions on /mnt/data/user1 so that the Owner(user) and Owner(group) is user1. Set the permissions on /mnt/data/user2 so that the Owner(user) and Owner(group) is user2. For each dataset's permissions, enable Windows ACLs and tighten the Mode so that Other can not read or execute the information on the dataset.

4. Create two periodic snapshot tasks in Storage → Periodic Snapshot Tasks → Add Periodic Snapshot, one for each dataset. Before continuing to the next step, confirm that at least one snapshot for each dataset is displayed in the ZFS Snapshots tab. When creating your snapshots, keep in mind how often your users need to access modified files and during which days and time of day they are likely to make changes.

5. Create two CIFS shares in Sharing → Windows (CIFS) Shares → Add Windows (CIFS) Share. The first CIFS share is named user1 and has a Path of /mnt/data/user1; the second CIFS share is named user2 and has a Path of /mnt/data/user2. When creating the first share, click the No button when the pop-up button asks if the CIFS service should be started. When the last share is created, click the Yes button when the pop-up button prompts to start the CIFS service. Verify that the CIFS service is set to ON in Services → Control Services.

6. From a Windows system, login as user1 and open Windows Explorer → Network → FREENAS. Two shares should appear, named user1 and user2. Due to the permissions on the datasets, user1 should receive an error if they click on the user2 share. Due to the permissions on the datasets, user1 should be able to create, add, and delete files and folders from the user1 share.

Figure 7.3e provides an example of using shadow copies while logged in as user1. In this example, the user right-clicked modified file and selected "Restore previous versions" from the menu. This particular file has three versions: the current version, plus two previous versions stored on the FreeNAS® system. The user can choose to open one of the previous versions, copy a previous version to the current folder, or restore one of the previous versions, which will overwrite the existing file on the Windows system.

Figure 7.3e: Viewing Previous Versions within Explorer

8 Services Configuration

The Services section of the GUI allows you to configure, start, and stop the various services that ship with the FreeNAS® system. FreeNAS® supports the following services:

• Active Directory

• AFP

• CIFS

• Dynamic DNS

• FTP

• iSCSI

• LDAP

• NFS

• Plugins

• Rsync

• S.M.A.R.T.

• SNMP

• SSH

• TFTP

• UPS

This section demonstrates how to start a FreeNAS® service then describes the available configuration options for each FreeNAS® service.

8.1 Control Services

Services → Control Services, shown in Figure 8.1a, allows you to quickly determine which services are currently running, to start and stop services, and to configure services. By default, all services (except for the S.M.A.R.T. service) are off until you start them.

Figure 8.1a: Control Services

In order to provide a separation between the services that were installed with FreeNAS®, and are considered to be core to the NAS, and those third-party services which were installed into the Plugins Jail, this screen is divided into two tabs:

Core: lists the services that are installed with FreeNAS®.

Plugins: lists the services which were installed using Plugins. This tab contains a warning if the Plugins service has not been started in the Core tab of Control Services.

A service is stopped if its icon is a red OFF. A service is running if its icon is a blue ON. To start or stop a service, click its ON/OFF icon.

To configure a core service, click the wrench icon associated with the service or click the name of the service in the Services section of the tree menu.

If a service does not start, go to System → Settings → Advanced and check the box “Show console messages in the footer”. Console messages will now show at the bottom of your browser. If you click the console messages area, it will pop-up as a window, allowing you to scroll through the output and to copy messages. Watch these messages for errors when you stop and start the problematic service.

If you would like to read the system logs to get more information about a service failure, open Shell and type more /var/log/messages.

NOTE: if you are unable to start any core services within ESXi, make sure that you only have one vcpu. If that is not the issue, create a Tunable called kern.hz with a value of 100.

8.2 Active Directory

Active Directory (AD) is a service for sharing resources in a Windows network. AD can be configured on a Windows server that is running Windows Server 2000 or higher or on a Unix-like operating system that is running Samba version 4. Since AD provides authentication and authorization services for the users in a network, you do not have to recreate these user accounts on the FreeNAS® system. Instead, configure the Active Directory service so that it can import the account information and imported users can be authorized to access the CIFS shares on the FreeNAS® system.

NOTE: many changes and improvements have been made to Active Directory support within FreeNAS®. If you are not running FreeNAS® 8.3.0-RELEASE, it is strongly recommended that you upgrade before attempting Active Directory integration.

Before configuring the Active Directory service, ensure name resolution is properly configured by pinging the domain name of the Active Directory domain controller from Shell on the FreeNAS® system. If the ping fails, check the DNS server and default gateway settings in Network → Global Configuration on the FreeNAS® system.

Next, add a DNS record for the FreeNAS® system on the Windows server and verify that you can ping the hostname of the FreeNAS® system from the domain controller.

Active Directory relies on Kerberos, which is a time sensitive protocol. This means that the time on both the FreeNAS® system and the Active Directory Domain Controller can not be out of sync by more than a few minutes. The best way to ensure that the same time is running on both systems is to configure both systems to:

• use the same NTP server (set in System → NTP Servers on the FreeNAS® system)

• have the same timezone

• be set to either localtime or universal time at the BIOS level

Figure 8.2a shows the Active Directory Configuration screen and Table 8.2a describes the configurable options.

Figure 8.2a: Configuring Active Directory

Table 8.2a: Active Directory Configuration Options

NOTE: Active Directory places restrictions on which characters are allowed in Domain and NetBIOS names. If you are having problems connecting to the realm, verify that your settings do not include any disallowed characters. Also, the Administrator Password cannot contain the $ character. If a $ exists in the domain administrator's password, kinit will report a "Password Incorrect" error and ldap_bind will report an "Invalid credentials (49)" error.

Once you have configured the Active Directory service, start it in Services → Control Services. It may take a few minutes for the Active Directory information to be populated to the FreeNAS® system. Once populated, the AD users and groups will be available in the drop-down menus of the permissions screen of a volume/dataset. For performance reasons, every available user may not show in the listing. However, it will autocomplete all applicable users if you start typing in a username.

You can verify which Active Directory users and groups have been imported to the FreeNAS® system by using these commands within the FreeNAS® Shell:

wbinfo -u (to view users)

wbinfo -g (to view groups)

In addition, wbinfo -t will test the connection and, if successful, will give a message similar to:

checking the trust secret for domain YOURDOMAIN via RPC calls succeeded

To manually check that a specified user can authenticate:

net ads join -S dcname -U username

If no users or groups are listed in the output of those commands, these commands will provide more troubleshooting information:

getent passwd
getent group

8.2.1 Troubleshooting Tips

If you are running AD in a 2003/2008 mixed domain, see this forum post for instructions on how to prevent the secure channel key from becoming corrupt.

The LDAP code uses DNS to determine the location of the domain controllers and global catalog servers in the network. Use the host -t srv _ldap._tcp.domainname.com command to determine the network's SRV records and, if necessary, change the weight and/or priority of the SRV record to reflect the fastest server. More information about SRV records can be found in the Technet article How DNS Support for Active Directory Works.

The realm that is used depends upon the priority in the SRV DNS record, meaning that DNS can override your Active Directory settings. If you are unable to connect to the correct realm, check the SRV records on the DNS server. This article describes how to configure KDC discovery over DNS and provides some examples of records with differing priorities.

If the cache becomes out of sync due to an AD server being taken off and back online, resync the cache using System → Settings → Advanced → Rebuild LDAP/AD Cache.

8.3 AFP

The Apple Filing Protocol (AFP) is a network protocol that offers file services for Mac computers. Before configuring this service, you should first create your AFP Shares in Sharing → Apple (AFP) Shares → Add Apple (AFP) Share. After configuring this service, go to Services → Control Panel to start the service. The AFP shares will not be available on the network if this service is not running.

Enabling this service will open the following ports on the FreeNAS® system:

• TCP 548 (afpd)

• TCP 4799 (cnid_metadata)

• UDP 5353 and a random UDP port (avahi)

Figure 8.3a shows the configuration options which are described in Table 8.3a:

Figure 8.3a: AFP Configuration

Table 8.3a: AFP Configuration Options

8.4 CIFS

Common Internet File System (CIFS) is a network protocol that offers file services for (typically) Windows computers. Unix-like systems that provide a CIFS client can also connect to CIFS shares. Before configuring this service, you should first create your CIFS shares in Sharing → Windows (CIFS) Shares → Add Windows (CIFS) Share. After configuring this service, go to Services → Control Services to start the service. The CIFS shares will not be available on the network if this service is not running.

NOTE: after starting the CIFS service, it may take several minutes for the master browser election to occur and for the FreeNAS® system to become available in Windows Explorer.

Starting this service will open the following ports on the FreeNAS® system:

• TCP 139 (smbd)

• TCP 445 (smbd)

• UDP 137 (nmbd)

• UDP 138 (nmbd)

Figure 8.4a shows the configuration options which are described in Table 8.4a. This configuration screen is really a front-end to smb.conf(5).

Figure 8.4a: Configuring CIFS

Table 8.4a: CIFS Configuration Options