Starting with version 12.0, FreeNAS and TrueNAS are unifying into “TrueNAS”. Documentation for TrueNAS 12.0 and later releases has been unified and moved to the TrueNAS Documentation Hub.

Copyright iXsystems 2011-2020

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

Welcome to the TrueNAS® User Guide.

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

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

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

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

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.

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

Linux® is a registered trademark of Linus Torvalds.

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

UNIX® is a registered trademark of The Open Group.

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 TrueNAS® Administrator Guide uses these typographic conventions:

Table 1 Text Format Examples
Item Visual Example
Graphical elements: buttons, icons, fields, columns, and boxes Click the Import CA button.
Menu selections Select System ➞ Information.
Commands Use the scp command.
File names and pool and dataset names Locate the /etc/rc.conf file.
Keyboard keys Press the Enter key.
Important points This is important.
Values entered into fields, or device names Enter in the address field.
Table 2 TrueNAS® Icons
Icon Usage
ADD Add a new item.
 (Settings) Show a settings menu.
 (Options) Show an Options menu.
 (Browse) Shows an expandable view of system directories.
⏻ (Power) Show a power options menu.
 (Show) Reveal characters in a password field.
 (Hide) Hide characters in a password field.
 (Configure) Edit settings.
襁 (Launch) Launch a service.
▶ (Start) Start jails.
 (Stop) Stop jails.
🕓 (Update) Update jails.
 (Delete) Delete jails.
 (Encryption Options) Encryption options for a pool.
 (Pin) Pin a help box to the screen.
 (Close) Close a help box.

1. Introduction

This Guide provides information about configuring and managing the TrueNAS® Unified Storage Array. Your iXsystems support engineer will assist with the initial setup and configuration of the array. After becoming familiar with the configuration workflow, this document can be used as a reference guide to the many features provided by TrueNAS®.

1.1. Contacting iXsystems

For assistance, please contact iX Support:

Contact Method Contact Options

Monday - Friday, 6:00AM to 6:00PM Pacific Standard Time:

  • US-only toll-free: 855-473-7449 option 2
  • Local and international: 408-943-4100 option 2

After Hours (24x7 Gold Level Support only):

  • US-only toll-free: 855-499-5131
  • International: 408-878-3140 (international calling rates will apply)

1.2. Path and Name Lengths

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

Table 1.2.1 Path and Name Lengths
Type Maximum Length Description
File Paths 1023 bytes

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

Using very long file or directory names can be problematic. If a path with long directory and file names exceeds the 1023-byte limit, it prevents direct access to that file until the directory names or filename are shortened or the file is moved into a directory with a shorter total path length.

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


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


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

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

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


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

1.3. Using the Web Interface

1.3.1. Tables and Columns

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

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

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

1.3.2. Advanced Scheduler

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


Fig. 1.3.1 Creating a Custom Schedule

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

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

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

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

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

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

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

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

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

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

1.3.3. Schedule Calendar

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


Fig. 1.3.2 Example Schedule Popup

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

1.3.4. Changing TrueNAS® Settings

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

1.3.5. Web Interface Troubleshooting

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

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

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

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

1.3.6. Help Text

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

1.3.7. Humanized Fields

Some numeric value fields accept humanized values. This means that the field accepts numbers or numbers followed by a unit, like M or MiB for megabytes or G or GiB for gigabytes. Entering 1048576 or 1M are equivalent. Units of KiB, MiB, GiB, TiB, and PiB are available, and decimal values like 1.5 GiB are supported when the field allows them. Some fields have minimum or maximum limits on the values which can restrict the units available.

1.3.8. File Browser

Certain sections of the web interface have a built in file browser. The file browser is used to traverse through directories and choose datasets on the system. Datasets that have complex ACL permissions are tagged so they can be distinguished from non-ACL datasets.