Back to Docs Hub
Welcome to TrueNAS CORE tutorials!
This guide collects various how-tos for both simple and complex tasks using primarily the TrueNAS web interface. Tutorials are organized parallel to the TrueNAS web interface structure and grouped by topic. Tutorials are living articles and continually updated with new content or additional in-depth tutorials that guide in unlocking the full potential of TrueNAS.
To display all tutorials in a linear HTML format, export it to PDF, or physically print it, please select ⎙ Download or Print.
If you are interested in writing a TrueNAS tutorial, see the Contributing articles for guidance!
The Task Manager displays a list of tasks performed by the TrueNAS system. It starts with the most recent task.
Click the assignment to open the Task Manager.
Click a task name to display its start time, finish time, and whether the task succeeded. If a task fails, the error status shows.
Tasks with log file output have a View Logs button to show the log files.
Click CLOSE or anywhere outside the Task Manager dialog to close it, or press Esc.
There are several options to get support for your TrueNAS installation. TrueNAS CORE users can engage with the TrueNAS community to answer questions and resolve issues. TrueNAS Enterprise hardware customers can also access the fast and effective support directly provided by iXsystems.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
iXsystems Customer Support | |
---|---|
Support Portal | https://support.ixsystems.com |
support@ixsystems.com | |
Telephone and Other Resources | https://www.ixsystems.com/support/ |
Creating users and assigning them to groups allows you to efficiently tune permissions and share data for large numbers of users.
Only the root user account can log in to the TrueNAS web interface.
When the network uses a directory service, import the existing account information using the instructions in Directory Services. Using Active Directory requires setting Windows user passwords inside Windows.
To see user accounts, go to Accounts > Users.
TrueNAS hides all built-in users by default. To see all built-in users, click settings and SHOW.
Go to Accounts > Users and click ADD.
Fields with an*
must be configured to submit or change the UI configuration.
TrueNAS subdivides account options into groups of similar options.
Enter a Full Name. TrueNAS suggests a simplified Username from the Full Name, but you override it with your own choice.
You can associate an Email address with a user account.
Set and confirm the user password.
Next, you must set a user ID. TrueNAS automatically suggests the user ID starting at 1000, but you can change it. We recommend using an ID of 1000 or more for non-built-in users.
By default, TrueNAS creates a new primary group with the same name as the user. To add the user to an existing primary group instead, unset New Primary Group and select a group from the Primary Group drop-down. You can add the user to more groups using the Auxiliary Groups drop-down.
When creating a user, TrueNAS sets the home directory path to
Directly under the file browser, you can set the home directory permissions. TrueNAS default user accounts cannot change their permissions.
You can assign a public SSH key to a user for key-based authentication by pasting the public key into the SSH Public Key field.
If you are using an SSH public key, always keep a backup.
Click DOWNLOAD SSH PUBLIC KEY to download the pasted key as a
When Disable Password is Yes, the Password field is unavailable. The system removes the existing password from the account and disables the Lock User and Permit Sudo options. The account can’t use password-based logins for services. For example, disabling the password prevents using account credentials to log in to an SMB share or open an SSH session on the system. By default, Disable Password is No.
A specific shell can be set for the user from the Shell drop-down:
Shell | Description |
---|---|
csh | C shell for UNIX system interactions. |
sh | Bourne shell |
tcsh | Enhanced C shell that includes editing and name completion. |
bash | Bourne Again shell for the GNU operating system. |
ksh93 | Korn shell that incorporates features from both csh and sh. |
mksh | MirBSD Korn Shell |
rbash | Restricted bash |
rzsh | Restricted zsh |
scponly | scponly restricts the user’s SSH usage to only the scp and sftp commands. |
zsh | Z shell |
git-shell | restricted git shell |
nologin | Use when creating a system account or to create a user account that can authenticate with shares but which cannot log in to the TrueNAS system using ssh . |
Setting Lock User disables all password-based functionality for the account until you unset the option.
Permit Sudo allows the account to act as the system administrator using the sudo
command.
For better security, leave this option disabled.
If the user account is accessing TrueNAS data using a Windows 8 or newer client, set Microsoft Account to enable additional authentication methods available from those operating systems.
By default, Samba Authentication is enabled. It allows users to access SMB share data using account credentials.
Using groups in TrueNAS is an efficient way to manage permissions for many similar user accounts. The interface lets you manage UNIX-style groups. If the network uses a directory service, import the existing account information using the instructions in Active Directory.
To see saved groups, go to Accounts > Groups
By default, TrueNAS hides built-in groups. To see built-in groups, click settings and SHOW.
Go to Accounts > Groups and click ADD.
Each group gets a Group ID (GID). Enter a number above 1000 for a group with user accounts. You cannot change the GID later. Groups used by a system service must have an ID that matches the default port number used by the service.
Next, enter a descriptive group Name. Group names cannot begin with a hyphen (-) or contain a space, tab, or these characters: , : + & # % ^ ( ) ! @ ~ * ? < > =.
By default, the Permit Sudo option is unset. Setting it allows group members to act as the root account by using sudo. Leave Permit Sudo unset for better security.
Samba Authentication is set by default. It allows group members to use SMB permissions and authentication.
Finally, Allow Duplicate GIDs lets you duplicate group IDs but can complicate system configurations. We recommend leaving it unset.
Register user accounts to a group to simplify permissions and access to many user accounts. To manage group membership, go to Accounts > Groups, click the navigate_next for a group, then click group MEMBERS:
To add user accounts to the group, select them in All users and click . Select multiple users by holding CTRL while clicking each entry.
We highly recommend backing up the system configuration regularly. Doing so preserves settings when migrating, restoring, or fixing the system if it runs into any issues. Save the configuration file each time the system configuration changes.
Backup configs store information for accounts, network, services, tasks, virtual machines, and system settings. Backup configs also index ID’s and credentials for account, network, and system services. Users can view the contents of the backup config using database viewing software like SQLite DB Browser.
Go to System > General and click SAVE CONFIG, then enter your password.
The configuration file contains sensitive data about the TrueNAS system. Ensure that it is stored somewhere safe.
TrueNAS automatically backs up the configuration database to the system dataset every morning at 3:45 (relative to system time settings). However, this backup does not occur if the system is off at that time. If the system dataset is on the boot pool and it becomes unavailable, the backup also loses availability.
You must backup SSH keys separately. TrueNAS does not store them in the configuration database. System host keys are files with names beginning with ssh_host_ in/usr/local/etc/ssh/ . The root user keys are stored in/root/.ssh .
The system backup affects two types of passwords: hashed and encrypted.
Hashed: TrueNAS stores user account passwords for the base operating system as hashed values. The system saves them in the system configuration backup, so they do not need to be encrypted to be secure.
Encrypted: The system saves other passwords, like iSCSI CHAP passwords, Active Directory bind credentials, and cloud credentials in an encrypted form to prevent them from being visible as plain text in the saved system configuration. The key or seed for this encryption is usually only on the operating system device.
There are two options after clicking SAVE CONFIG:
Export Password Secret Seed includes encrypted passwords in the configuration file. Encrypted passwords allow you to restore the configuration file to a different operating system device where the decryption seed is not present. Users must physically secure configuration backups containing the seed to prevent unauthorized access or password decryption.
Export Legacy Encryption (GELI) Keys includes encrypted legacy encryption keys in the configuration file. Users can restore the encryption keys by uploading the configuration file to the system using UPLOAD CONFIG.
To reset the system configuration to factory settings, go to System > General and click RESET CONFIG.
Save the system’s current configuration before resetting.
If you do not save the system config before resetting it, you may lose any data that you did not back up. You cannot revert to the previous settings.
After resetting the system configuration, the system restarts, and you must set a new login password.
Users can restore configurations by going to System > General and clicking UPLOAD CONFIG.
When uploading a config, you can select any previously saved config files for their system.
TrueNAS supports a ZFS feature known as boot environments. These are snapshot clones that TrueNAS can boot into. You can only use one boot environment for booting.
Sometimes, rolling back to an older boot environment can be useful. For example, if an update process doesn’t go as planned, it is easy to roll back to a previous boot environment. TrueNAS automatically creates a boot environment when the system updates.
There are two different methods for changing the active boot environment: using the web interface and through a Command Line Interface (CLI)
Go to System > Boot and click more_vert for the desired boot environment, then click Activate.
Reboot the system to activate the new boot environment.
Reboot the system.
When the welcome screen appears, press the key that corresponds with the option Boot Environments (usually 7).
The Boot Environments options does not appear when no additional boot environments are present.
Choose the new boot environment to activate byt pressing the key for the Active: option.
Press the key to cycle through existing boot environments. When you select the desired boot environment, press Backspace to return to the welcome menu, then press 4 to reboot the system.
Go to System > Boot and click ACTIONS.
Click Add to make a new boot environment from the active environment.
Name the new boot environment and click SUBMIT.
You may only use alphanumeric characters, dashes (-), and underscores (_) in the Name.
Click Stats/Settings to display statistics for the operating system device.
By default, TrueNAS scrubs the operating system device every 7 days. To change the default, input a different number in the Scrub interval (in days) field and click UPDATE INTERVAL.
Click Boot Pool Status to see the status of each boot-pool device, including any read, write, or checksum errors.
Click Scrub Boot Pool to perform a manual (data integrity check) of the operating system device.
Adding a second storage device to the boot pool changes the configuration to a Mirror. This allows one of the devices to fail and the system still boots. If one of the two devices were to fail, that device is easily detached and replaced.
When adding a second device to create a mirrored boot pool, consider these caveats:
Capacity: The new device must have at least the same capacity as the existing device. Larger capacity devices can be added, but the mirror will only have the capacity of the smallest device. Different models of devices which advertise the same nominal size are not necessarily the same actual size. For this reason, adding another device of the same model of is recommended.
Device Type: We strongly recommend using SSDs rather than USB devices when creating a mirrored boot pool.
Removing devices from storage pools can result in data loss!
Go to System > Boot > ACTIONS > Boot Pool Status.
Click on the boot device, then click attach.
Select a new Member Disk from the drop-down and click SUBMIT.
Only compatible TrueNAS hardware and expansion shelves available from iXsystems allow seeing the View Enclosure option. To learn more about available iXsystems products, see the TrueNAS Systems Overview or browse the TrueNAS Systems documentation.
Go to System > View Enclosure to display the status of connected disks and hardware.
The screen shows the primary system. Other detected TrueNAS hardware is available from a column on the right side of the screen. Click an enclosure to show details about that hardware.
The screen is divided into different tabs which reflect the active sensors in the chosen hardware.
You can rename a system by clicking EDIT LABEL.
In the Disks tab, select a disk on the enclosure image and click IDENTIFY DRIVE. The drive LED on the physical system flashes so you can find it.
The TrueNAS Mini Series models do not support drive light identification.
An automatic script sends a nightly email to the administrator (root) account containing important information such as issues with the health of the disks, or other system functions. Alerts sent are based on the default options set on the Alerts Settings screen. TrueNAS emails alert events to the email set up for the root user account.
Go to Accounts > Users, click more_vert next to the root user, then click Edit. Enter a remote email address for the system administrator that regularly monitors the system in Email, then click SAVE.
Configuring user email addresses follows the same process.
Go to System > Email and enter a From Name for system emails.
Next, select a Send Mail Method and fill out the remaining fields (SMTP) or log in (GMail OAuth).
Click SEND TEST MAIL to verify the configured email settings are working. If the test email fails, double-check that the root user Email field is correctly configured.
The system dataset stores debugging core files, encryption keys for encrypted pools, and Samba4 metadata such as the user and group cache and share level permissions.
To view the current location of the system dataset, go to System > System Dataset.
Users can store the system log on the system dataset. We recommend users store the log information on the system dataset when the system generates large amounts of data and has limited memory or a limited-capacity operating system device.
Set Syslog to store the system log on the system dataset.
Leave unset to store the system log in
Select an existing pool from the System Dataset Pool dropdown.
You can move the system dataset to unencrypted pools or encrypted pools that do not have passphrases.
Moving the system dataset to an encrypted pool disables that volume’s passphrase capability.
You cannot move the system dataset to a passphrase-encrypted or read-only pool.
Reboots Required
- The SMB service must restart, which causes a brief outage for any active SMB connections.
- Highly Available TrueNAS systems must reboot the standby controller when the system dataset moves.
If a user changes the pool storing the system dataset later, TrueNAS migrates the existing data in the system dataset to the new location.
The alert system integrates with various third-party services. Tuning alerts helps personalize TrueNAS to any highly-sensitive issues.
Go to System > Alert Services and click ADD.
Choose a Type and fill out the options specific to that alert service, then test the service configuration by clicking SEND TEST ALERT.
Go to System > Alert Settings.
The UI groups alerts based on type. For example, alerts related to pools appear in the Storage alert section.
Customize each alert Warning Level and Frequency using the drop-down menus.
Changing any of these options affects every configured alert service.
Click SAVE before leaving the page.
Secure Socket Shell (SSH) is a cryptographic network protocol. It provides a secure method to access and transfer files between two hosts. This is possible even if the two hosts use an unsecured network. SSH establishes secure connections by means of user account credentials. It also uses key pairs shared between host systems for authentication.
TrueNAS generates and stores RSA-encrypted SSH public and private keypairs in System > SSH Keypairs. The system typically uses keypairs when configuring SSH Connections or SFTP Cloud Credentials. Encrypted keypairs or keypairs with passphrases are not supported.
The creation of a new SSH Connection or Replication task generates new keypairs. To manually generate a new keypair, go to System > SSH Keypairs, click ADD, and give the keypair a unique Name.
Click GENERATE KEYPAIR to add values to the public and private key fields. Copy these strings or download them into text files for later use.
TrueNAS offers a semi-automatic setup mode for setting up an SSH connection. This simplifies setting up an SSH connection with another FreeNAS or TrueNAS system. In semi-automatic setup mode it is not necessary to log in to the remote system to transfer SSH keys.
Semi-automatic setup requires an SSH keypair on the local system. You must have administrator account credentials for the remote TrueNAS. You must also configure the remote system to allow root access with SSH.
The semi-automatic configuration can generate the needed keypair. You can manually create the keypair by going to System > SSH Keypairs.
Go to System > SSH Connections and click ADD.
Use a valid URL scheme for the remote TrueNAS URL. Leave the username as root and enter the account password for the remote TrueNAS system. You can import the private key from a SSH keypair that you created before. Or create a new private key with a new SSH keypair.
Save the new configuration. TrueNAS opens a connection to the remote TrueNAS and exchanges SSH keys.
You can configure a secure SSH connection that does not generate a password prompt. This involves copying a public encryption key from the local system to the remote system.
Log in to the TrueNAS system that generated the SSH keypair and go to System > SSH Keypairs. Open the keypair you want to use for the SSH connection. Copy the text of the SSH public key or download the public key as a text file.
Log in to the TrueNAS system that needs to register the public key. Go to Accounts > Users and edit the root account. Paste the SSH public key text into the SSH Public Key field.
Generate a new SSH keypair in System > SSH Keypairs. Copy or download the value for the public key and add it to the remote NAS. If the remote NAS is not a TrueNAS system, please see the system documentation on adding a SSH public key.
Log back into the local TrueNAS system and go to System > SSH Connections. Add a new connection and change the setup method to Manual.
Select the private key from the SSH keypair you used when you transferred the public key on the remote NAS.
Be careful when adding or editing the default tunables. Changing the default tunables can make the system unusable.
TrueNAS allows you to add system tunables from the web interface. You can manually define tunables, or TrueNAS can run an autotuning script to attempt to optimize the system. Tunables are used to manage TrueNAS sysctls, loaders, and rc.conf options.
Adding a sysctl, loader, orrc.conf option is an advanced feature. A sysctl immediately affects the kernel running the TrueNAS system, and a loader can adversely affect the TrueNAS boot process. Do not create a tunable on a production system before testing the ramifications of that change.
To configure a tunable, go to System > Tunables and click ADD.
Select the Type of tunable to add or modify. Enter the name of the loader, sysctl, or rc.conf variable to configure.
Next, enter the value to use for the loader, sysctl, or rc.conf.
If you wish to create the system tunable but not immediately enable it, unset the Enabled checkbox. Configured tunables remain in effect until deleted or Enabled is unset.
We recommend restarting the system after making sysctl changes. Some sysctls only take effect at system startup, and restarting the system guarantees that the setting values correspond with what the running system uses.
TrueNAS provides an autotune script that optimizes the system depending on the installed hardware.
For example, if a pool exists on a system with limited RAM, the autotune script automatically adjusts some ZFS sysctl values to minimize memory starvation issues. Autotuning can introduce system performance issues. You must only use it as a temporary measure until you address the underlying hardware issue. Autotune always slows a RAM-starved system as it caps the ARC.
We do not recommend TrueNAS Enterprise customers use the autotuning script, as it can override any specific tunings made by iXsystems Support.
Enabling autotune runs the autotuner script at boot. To run the script immediately, reboot the system.
Any tuned settings appear in System > Tunables.
TrueNAS lets users create or import certificates, certificate signing requests (CSRs), and certificate authorities (CAs) that enable encrypted connections to the web interface.
TrueNAS can act as a certificate authority (CA). When encrypting SSL or TLS connections to the TrueNAS system, you can import an existing CA or create a CA and certificate on the TrueNAS system. The certificate appears on the dropdown menus for services that support SSL or TLS.
Go to System > CAs and click ADD. Enter a name for the CA, then choose the type from the Type dropdown list of three, Internal CA, Intermediate CA, or Import CA. The process to add a CA for each type is slightly different.
A CA must exist in CORE to add an Intermediate CA. This can be an internal or imported CA.
To create a CA:
Enter or select the Identifier and Type setting options.
a. Enter a name for this CA. b. Select Internal CA from the Type dropdown list to create an internal certificate. Select Intermediate CA to create an intermediate certificate. This displays the Signing Certificate Authority field in Certificate Options.
Select an option from the Profiles dropdown list. A profile for the CA auto-fills options like Key Type, Key Length, and Digest Algorithm. Otherwise, you must set options manually.
To add an OpenVPN Root CA, select OpenVPN Root CA. The configuration form populates with default settings, enables Basic Constraints, Authority Key Identifier, Extended Key Usage, and Key Usage, and sets the options for each extension.
To add CA certificate, select CA. The configuration form populates with default settings, enables Basic Constraints, Authority Key Identifier, Extended Key Usage, and Key Usage, and sets the options for each extension.
Select the Certificate Options.
a. Select a Key Type from the dropdown list. We recommend the RSA key type. Use EC for elliptic curve certificates.
b. Select the Key Length. We recommend a minimum of 2048 for security reasons.
c. Select a Digest Algorithm. We recommend SHA256.
d. Enter the Lifetime of the CA in days to set how long the CA remains valid.
Enter or select the Certificate Subject settings.
a. Enter the geographic information in Country, Locality, Organizational Unit (optional), Common Name, State, Organization, Email, and Subject Alternate Names.
b. (Optional) Enter a fully-qualified hostname (FQDN) that is unique within a certificate chain in Common Name.
Select enable and select extensions to use if you did not select an option in Profiles. If manually selecting and entering extension:
a. Select Enable, then enter the extensions for Basic Constraints.
Enter a value in Path Length that determines how many non-self-issued intermediate certificates can follow the certificate in a valid certification path. Entering 0 allows a single additional certificate to follow in the certificate path. Then select the extension(s) to use.
Select an option from the Basic Constraints Config dropdown list. Select CA to use a certificate authority. Selecting Critical Extension can result in rejection of the certificate by the system that is using the certificate if that system does not recognize the extension.
b. Select Enable, then enter the extensions for Authority Key Identifier.
Enabling Authority Key Config adds the authority key identifier extension which provides a means of identifying the public key corresponding to the private key used to sign the certificate. Used when an issue has multiple signing keys, possibly due to multiple concurrent key pairs or due to changeover. Options are Authority Cert Issuer or Critical Extension.
c. Select Enable, then enter the extensions for Extended Key Usage. Select one or more usages for the public key from the Usages dropdown list. TrueNAS uses Extended Key Usage for end-entity certificates.
Enable Critical Extension to identify this extension as critical for the certificate. Do not enable Critical Extension if Usages contains ANY_EXTENDED_KEY_USAGE.
Using Extended Key Usage and Key Usage extensions requires that the certificate purpose is consistent with both extensions. See RFC 3280, section 4.2.1.13 for more details.
Click Submit to create the CA.
Use this procedure to import a CA.
Enter a name for this certificate.
Select Import CA from the Type dropdown list.
Copy the certificate for the CA you want to import and paste it into the Certificate field.
Paste the certificate private key of at least 1024 bits in length into Private Key when available.
Enter and confirm the passphrase for the private key into Passphrase and Confirm Passphrase.
Click Submit.
Before deleting a CA, verify it is not used by another service such as S3, FTP, etc. You cannot delete a CA when in use by other services.
Also, before you can delete a CA, you need to delete certificates issued by the CA or those relying on the CA before you can delete it. If you receive an error that mentions foreign keys reference, ensure the certificates on your system do not use the CA you want to delete.
By default, TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface.
You can either import or create a new certificate or signing request by navigating to System > Certificates and clicking ADD.
To add an internal certificate:
Enter the name for the certificate, then select Internal Certificate from the Type dropdown list.
Select an option from the Profiles dropdown list. A profile for the certificate auto-fills options like Key Type, Key Length, Digest Algorithm. Otherwise, you must set options manually.
To add an HTTPS RSA certificate, the default certificate type, select HTTPS RSA Certificate. The configuration form populates with default settings, enables Basic Constraints, Authority Key Identifier, Extended Key Usage, and Key Usage, and set the options for each extension.
To add an elliptical curve certificate select HTTPS ECC Certificate. The configuration form populates with default settings, enables Basic Constraints, Authority Key Identifier, Extended Key Usage, and Key Usage, and set the options for each extension.
To add an OpenVPN certificate, select the client or server option that fits the certificate type you want to create. The configuration form populates with default settings, enables Basic Constraints, Authority Key Identifier, Extended Key Usage, and Key Usage, and set the options for each extension.
Enter or select the Certificate Options settings if you did not select a Profile option.
a. Select a Signing Certificate Authority from the dropdown list.
b. Select a Key Type from the dropdown list. We recommend selecting RSA.
c. Select the Key Length. We recommend a minimum of 2048 for security reasons.
d. Select a Digest Algorithm. We recommend SHA256.
e. Enter the Lifetime of the certificate CA in days to set how long the CA remains valid.
Enter or select the Certificate Subject setting options.
Enter the geographic and other information in Country, Locality, Organizational Unit (optional), Common Name, State, Organization, Email, and Subject Alternate Names.
Enter a fully-qualified hostname (FQDN) that us unique within a certificate chain in Common Name.
Select enable and select extensions to use if you did not select an option in Profiles. If manually selecting and entering extension:
a. Select Enable, then enter the extensions for Basic Constraints.
Enter a value in Path Length that determines how many non-self-issued intermediate certificates can follow the certificate in a valid certification path. Entering 0 allows a single additional certificate to follow in the certificate path. Then select the extension(s) to use.
b. Select Enable, then enter the extensions for Authority Key Identifier.
c. Select Enable, then enter the extensions for Extended Key Usage. Select one or more usages for the public key from the Usages dropdown list. TrueNAS uses Extended Key Usage for end-entity certificates.
Enable Critical Extension if you want to identify this extension as critical for the certificate. Do not enable Critical Extension if Usages contains ANY_EXTENDED_KEY_USAGE.
Using Extended Key Usage and Key Usage extensions requires that the certificate purpose is consistent with both extensions. See RFC 3280, section 4.2.1.13 for more details.
d. Select Enable, then enter the extensions for Key Usage. Select any extensions from the Key Usage Config dropdown list.
Click Submit.
To add a certificate singing request (CSR) certificate:
Enter the name for the certificate, then select Certificate Signing Request from the Type dropdown list.
Select Certificate Signing Request from the Profiles dropdown list. A profile for the certificate auto-fills options like Key Type, Key Length, Digest Algorithm. Otherwise, you must set options manually.
To use an HTTPS RSA certificate, the default certificate type, select HTTPS RSA Certificate. The configuration form populates with default settings, enables Basic Constraints, Authority Key Identifier, Extended Key Usage, and Key Usage, and set the options for each extension.
To use an elliptical curve certificate, select HTTPS ECC Certificate. The configuration form populates with default settings, enables Basic Constraints, Authority Key Identifier, Extended Key Usage, and Key Usage, and set the options for each extension.
To use an OpenVPN certificate, select the client or server option that fits the certificate type. The configuration form populates with default settings, enables Basic Constraints, Authority Key Identifier, Extended Key Usage, and Key Usage, and set the options for each extension.
Enter or select the Certificate Options settings if you did not select a Profile option.
a. Select a Key Type from the dropdown list. We recommend selecting RSA.
b. Select a Digest Algorithm. We recommend SHA256.
Enter or select the Certificate Subject setting options.
Enter the geographic and other information in Country, Locality, Organizational Unit (optional), Common Name, State, Organization, Email, and Subject Alternate Names.
Enter a fully-qualified hostname (FQDN) that us unique within a certificate chain in Common Name.
Select enable and select extensions to use if you did not select an option in Profiles. If manually selecting and entering extension:
a. Select Enable, then enter the extensions for Basic Constraints.
Enter a value in Path Length that determines how many non-self-issued intermediate certificates can follow the certificate in a valid certification path. Entering 0 allows a single additional certificate to follow in the certificate path. Then select the extension(s) to use.
b. Select Enable, then enter the extensions for Authority Key Identifier.
c. Select Enable, then enter the extensions for Extended Key Usage. Select one or more usages for the public key from the Usages dropdown list. TrueNAS uses Extended Key Usage for end-entity certificates.
Enable Critical Extension if you want to identify this extension as critical for the certificate. Do not enable Critical Extension if Usages contains ANY_EXTENDED_KEY_USAGE.
Using Extended Key Usage and Key Usage extensions requires that the certificate purpose is consistent with both extensions. See RFC 3280, section 4.2.1.13 for more details.
d. Select Enable, then enter the extensions for Key Usage. Select any extensions from the Key Usage Config dropdown list.
Click Submit.
To import a certificate:
Select Import Certificate as the Type.
Select the Certificate Options. To import a previously-added certificate for a CSR, select CSR exists on this system, then select one from the Signing Certificate Authority dropdown list.
Copy the certificate for the CA you want to import and paste it into the Certificate field.
Paste the certificate key that is least 1024 bits long into Private Key when available.
Enter and confirm the Private Key Passphrase.
Click Submit.
To import a certificate signing request (CSR):
Select Import Certificate Signing Request as the Type.
Copy the certificate for the CA you want to import and paste it into the Certificate field.
Paste the certificate key that is least 1024 bits long into Private Key when available.
Enter and confirm the Private Key Passphrase.
Click Submit.
TrueNAS EnterpriseThis article only applies to licensed TrueNAS Enterprise High availability (HA) systems. Contact the iXsystems Sales Team to inquire about purchasing TrueNAS Enterprise licenses.
Warning: To avoid the potential for data loss, contact iXsystems before replacing a controller or upgrading to High Availability.
Power on both system controllers and log in to the web interface for one of them. For first-time logins, TrueNAS prompts you to upload the TrueNAS Enterprise License. Otherwise, go to System > Support and update the license.
Paste the HA license received from iXsystems and save it. The license contains the serial numbers for both units in the chassis. Activating an HA license adds the System > Failover screen and modifies fields throughout the UI so that you can configure hostnames and IP addresses for both controllers.
After configuring HA, an icon displays when HA is active or unavailable. When the system administrator disables HA, the status icon changes to show HA is unavailable. If the standby TrueNAS controller is not available because it is powered off, still starting up, disconnected from the network, or does not have failover configured, the status icon changes to show HA is unavailable. HA also becomes unavailable if the controllers have different numbers of disks.
If both TrueNAS controllers reboot simultaneously, you must enter the passphrase for an encrypted pool at the web interface login screen.
To ensure system networking is configured for HA, go to Network > Global Configuration.
You can set the host names for both controllers and a virtual host name that reaches whichever controller is currently active.
Next, go to Network > Interfaces and edit the primary interface.
Editing interfaces is disabled when HA is active. To disable HA, go to System > Failover and disable failover. Edit the interface, then reactivate failover immediately. TrueNAS automatically synchronizes the configuration changes to the standby controller
You can designate the interface as critical for failover and combine multiple interfaces into a failover group. There are also options to configure IP addresses for each controller and a virtual IP address with virtual host ID for administrative access.
After the network configuration is complete, log out and log back in using the virtual IP address. You can now configure pools and shares as usual, and configuration automatically synchronizes between the active and standby TrueNAS controllers.
All subsequent logins should use the virtual IP address. Connecting directly to the standby TrueNAS controller with a browser does not allow web interface logins.
When troubleshooting HA networking, the ifconfig
command adds two additional fields to the output to help with failover troubleshooting: CriticalGroup and Interlink.
To make general changes to the Failover settings, go to System > Failover
You can manually disable failover on this screen.
Make sure to set one of the controllers as the default so that it becomes active when both boot simultaneously. Booting an HA pair with failover disabled causes both TrueNAS controllers to come up in standby mode. In this situation, the web interface shows an option to force a TrueNAS controller to activate.
To have the system wait to failover during a network timeout, replace 0 with a new number of seconds.
Do not sync the TrueNAS configuration unless directed by an iXsystems Support Engineer! TrueNAS automatically synchronizes the system configuration. The manual sync options are only for dangerous or high-risk troubleshooting situations.
This feature is only available in the open-source supported TrueNAS CORE.
Automatic Certificate Management Environment (ACME) is available for automating certificate issuing and renewal. The user must verify ownership of the domain before certificate automation is allowed.
ACME certificate automation requires an ACME DNS Authenticator and a Certificate Signing Request.
Go to System > ACME DNS and click ADD.
Name the authenticator. Leave Authenticator set to Route53. Enter the Access ID Key and Secret Access Key from Amazon.
Amazon Route 53 is the only supported DNS provider in TrueNAS CORE. See the AWS documentation for more details about generating the Access ID Key and Secret Access Key.
Click SUBMIT to register the DNS Authenticator and add it to the authenticator options for ACME Certificates.
You can create ACME certificates for existing certificate signing requests. The certificates use an ACME DNS authenticator to confirm domain ownership. Then, they are automatically issued and renewed.
To create a new ACME certificate, go to System > Certificates, click (Options) for an existing certificate signing request, and select Create ACME Certificate.
Give the ACME certificate an identifier (name), and accept the TOS by setting Terms of Service.
For the Authenticator, select the ACME DNS authenticator you created, then click SUBMIT.
TrueNAS EnterpriseKMIP is only available for TrueNAS Enterprise licensed systems. Contact the iXsystems Sales Team to inquire about purchasing TrueNAS Enterprise licenses.
The Key Management Interoperability Protocol (KMIP) is an extensible client/server communication protocol for storing and maintaining keys, certificates, and secret objects. KMIP on TrueNAS Enterprise integrates the system within an existing centralized key management infrastructure and uses a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.
Keys can be created on a single server and then retrieved by TrueNAS. Keys wrapped within keys, symmetric, and asymmetric keys are supported. Alternately, KMIP can be used for clients to ask a server to encrypt or decrypt data without the client ever having direct access to a key. KMIP also can be used to sign certificates.
To connect TrueNAS to a KMIP server, import a Certificate Authority (CA) and Certificate from the KMIP server, then configure the KMIP options.
For security reasons, we strongly recommend protecting the CA and Certificate values.
Go to System > KMIP.
Enter the central key server Server host name or IP address and the number of an open connection Port on the key server. Select the Certificate and Certificate Authority that you imported from the central key server. To ensure the Certificate and CA chain is correct, set Validate Connection and click SAVE.
When the certificate chain verifies, choose the encryption values, SED passwords, or ZFS data pool encryption keys to move to the central key server. Set Enabled to begin moving the passwords and keys immediately after clicking SAVE.
Refresh the KMIP screen to show the current KMIP Key Status.
If you want to cancel a pending key synchronization, set Force Clear and click SAVE.
We recommend two-factor authentication (2FA) for increased security. TrueNAS offers 2FA to ensure that a compromised administrator (root) password alone cannot grant access to the administrator interface. To utilize 2FA, you need a mobile device with Google Authenticator installed. Other authenticator applications can be used, but you will need to confirm the settings and QR codes generated in TrueNAS are compatible with your particular app before permanently activating 2FA.
The default shell for a new installations is zsh
.
You can change the default shell in Accounts > Users.
Click for the root user and click Edit.
Choose the desired shell from the Shell dropdown list and click SAVE.
For more information on the web shell see Shell
For more information on using the keyboard and CLI commands in the Shell see Using Shell
Because TrueNAS is both Open Source and complicated, the massive user community often creates recommendations for specific hardware or environments. User-created recommendations can be added in this location, but be aware these are provided “as-is” and are not officially supported by iXsystems, Inc.
Domain Name resolution is the process of mapping host or domain names, such as mytruenas
or truenas1.mycompany.com
, to their associated IP addresses.
This is done by a variety of methods.
The quickest method is to read entries in the hosts file, which is a local text file containing a list of IP addresses mapped to domain/host names.
Every operating system (OS) that communicates through the TCP/IP protocol has a hosts file.
The hosts file can speed up name resolution when a DNS server is not available on the local network. A DNS server runs networking software that allows it to join the Domain Name System. This is the standard service used on the Internet for name resolution. When adding entries to a TrueNAS system hosts file, use the TrueNAS web interface to save the entries directly to the configuration database. Do not edit the hosts file directly, as any changes are overwritten by the configuration database during reboot.
TrueNAS accepts different Transport Layer Security (TLS) cipher suites for secure web interface connections. Only use TLS 1.2 or newer for best security. By default, all options are available if you need to adjust this setting to match your particular network environment or security concerns.
Go to System > General and click on HTTPS Protocols to open a drop-down menu with the various cipher suites.
Unsetting a cipher restricts its use in TrueNAS. After enabling or disabling a cipher, you must reboot the TrueNAS system.
TLSv1 provides Internet communication security using encryption and other secure messaging techniques. While not officially deprecated, TLSv1 was considered obsolete in 2008. For security, we discourage enabling TLSv1 unless your network environment requires it.
TLSv1.1 is a revision of v1.0 with additional protections against CBC attacks. While not officially deprecated, TLSv1.1 was considered obsolete in 2008. For security reasons, users are encouraged to avoid enabling this suite unless required by the network environment.
TLSv1.2 increases the protocol’s ability to handle cryptographic algorithms. TLSv1.2 represented a major step forward in security effectiveness and resulted in the “soft” deprecation of TLS versions 1.0 and 1.1.
TLSv1.3 represents another major improvement to the protocol. TLSv1.3 removes legacy or insecure encryption algorithms, adds encryption for handshake messages, and separates authentication and key exchange concepts.
The web interface has a web shell that makes it convenient to run command line tools from the web browser as the root user.
The prompt shows that the current user is root@truenas, the host name is truenas, and the current working directory is ~, where root is the user, truenas is the home directory of the logged-in user, and the symbol between the square brackets is the working directory.
The default shell for a new installations is zsh. See Changing the Default Shell for instructions on changing to a different shell.
Not all shell features render correctly in Chrome. Firefox is the recommended browser when using the shell.
Most FreeBSD command line utilities are available in the Shell, including additional troubleshooting applications for TrueNAS Core and Enterprise.
For TrueNAS SCALE, most Linux command line utilities are available in the shell.
Shell command history is available for the current session.
See Shell for information on the shell UI screen.
Use the keyboard Up and Down arrow keys to scroll through previously entered commands.
After you edit a command press Enter to re-enter the command.
The keyboard Home, End, and Delete keys are supported.
Using keyboard Tab completion is also available. Type a few letters and press Tab to complete a command name or filename in the current directory.
Right-click in the terminal window to display a reminder about using Command+c and Command+v or Ctrl+Insert and Shift+Insert for copy and paste operations in the shell.
Navigating away from the Shell screen clears the command history.
Entering the CLI command exit
leaves the session.
Clicking other web interface menus closes the shell session and stops commands running in the shell.
Click Reconnect to start a new session.
The CLI tmux
command provides the ability to detach shell sessions and then reattach to them later.
Commands continue to run in a detached session.
TrueNAS includes an easy to use interface for common tasks a sysadmin needs to preform on a NAS on a regular basis. These can roughly be broken down into three groups.
TrueNAS allows users to run specific commands or scripts on a regular schedule using cron(8).
Go to Tasks > Cron Jobs and click ADD.
The Description helps identify the purpose of the cron job and is optional.
Enter the Command to run on the Schedule. Alternately, enter the path to a script file to run instead of a specific command.
Don’t forget to define the shell type when using a path to a script file. For example, a script written for sh must be specified as sh /mnt/pool1/helloWorld.sh.
Select a TrueNAS user account with the necessary permissions to run the Command or script.
Next, define the Command Schedule.
Additional Options:
Go to Tasks > Cron Jobs and click the next to an entry to see details and options.
Clicking RUN NOW immediately starts the job Command, separately from any Schedule. EDIT changes any setting available during task creation. DELETE removes the cron job from TrueNAS. Once you delete a cron job, you cannot restore the job configuration.
TrueNAS can schedule commands or scripts to run at system startup or shutdown.
Go to Tasks > Init/Shutdown Scripts and click ADD.
Enter a Description, then select a Type.
Enter a command with any options you want. You can find commands here or on our Community Forums.
Select when you want the Command to run and fill out the rest of the fields to your needs, then click SUBMIT.
Select the path to the Script. The Script runs using sh(1). You can find some helpful scripts on our Community Forums.
Select when you want the Script to run and fill out the rest of the fields to your needs, then click SUBMIT.
Always test the script to verify it executes and achieves the desired results. All init/shutdown scripts are run withsh
.
All saved Init/Shutdown tasks are in Tasks > Init/Shutdown Scripts. Click (Options) next to a task to EDIT or DELETE that task.
Rsync is a fast and secure way to copy data to another system, either for backup or data migration purposes. An rsync task requires configuration of both a Host and Remote system. These instructions assume a TrueNAS system for both the Host and Remote configurations.
Rysnc requires a dataset with the needed data on the Host or Remote system. Rsync provides the ability to either push or pull data. When using rsync to push, data copies from a Host system to a Remote system. When using rsync to pull, data pulls from a Remote system. It is then put on the Host system.
TrueNAS has extra requirements depending on if you choose the Module or SSH rsync mode.
Before you create an rsync task on the Host system, you must create a module on the Remote system. The Remote system must have rsync service activated. When TrueNAS is the Remote system, create a module by going to Services and clicking edit for the rsync service. Click the Rsync Module tab, then click ADD. See ConfiguringRsync for more information.
Log in to the Host system interface, go to Tasks > Rsync Tasks, and click ADD.
Select the Source dataset to use with the rsync task and a User account to run the rsync task. Select a Direction for the rsync task.
Select a Schedule for the rsync task.
Enter the Remote Host IP address or host name.
Use the format username@remote_host
when the user name differs on the Remote host.
Select Module in the Rsync Mode dropdown list.
Enter the Remote Module Name as it appears on the Remote system.
Configure the remaining options according to your specific needs.
Clearing Enabled disables the task schedule. You can still save the rsync task and run it as a manual task.
The Remote system must have SSH enabled. To enable SSH in TrueNAS, go to Services and click the SSH toggle button. The toggle button turns blue when the service is on.
The Host system needs an established SSH connection to the Remote for the rsync task. To create the connection, go to System > SSH Connections and click ADD. Configure a Semi-automatic connection and from the Private Key dropdown list select Generate New.
Go to Tasks > Rsync Tasks and click ADD.
Configure the SSH settings first by selecting SSH in the Rsync Mode dropdown list. Enter the Port number and Remote Path.
Define the Source dataset for the rsync task and select an account in User. The name in User must be identical to the SSH Connection Username.
Select a direction for the rsync task, either Push or Pull, and define the task Schedule.
Enter the Remote host IP address or host name.
Use the format username@remote_host
if the user name differs on the Remote host.
Configure the remaining options according to your specific needs.
Clearing the Enabled checkbox disables the task schedule without deleting the configuration. You can still run the rsync task by going to Tasks > Rsync Tasks and clicking , then RUN NOW.
The rsync task does not work when the related system service is off. To turn the rsync service on, go to Services and click the rsync toggle button. The toggle button turns blue when the service is on. See ConfiguringRsync for more information on rsync configuration and module creation.
S.M.A.R.T. (Self-Monitoring, Analysis and Reporting Technology) is an industry standard for disk monitoring and testing. Disks are monitored for problems using several different kinds of self-tests. TrueNAS can adjust when and how alerts for S.M.A.R.T. are issued. When S.M.A.R.T. monitoring reports an issue, we recommend you replace that disk. Most modern ATA, IDE, and SCSI-3 hard drives support S.M.A.R.T. Refer to your respective drive documentation for confirmation.
S.M.A.R.T. tests run on a disk. Running tests can reduce drive performance, so we recommend scheduling tests when the system is in a low-usage state. Avoid scheduling disk-intensive tests at the same time! For example, do not schedule S.M.A.R.T. tests on the same day as a disk scrub or resilver.
To quickly test a disk for errors, go to Storage > Disks and select the disks to be tested. After selecting the desired disks, click MANUAL TEST.
Next, select the test Type. Each test type can differ based on the drive connection, ATA or SCSI:
For more information, refer to smartctl(8).
Click START to begin the test. Depending on the test type you choose, the test can take some time to complete. TrueNAS generates alerts when tests discover issues.
Go to Tasks > S.M.A.R.T. Tests and click ADD.
Select the Disks to test, Type of test to run, and Schedule for the task.
S.M.A.R.T. tests can offline disks! Avoid scheduling S.M.A.R.T. tests simultaneously with scrub or resilver operations.
Saved schedules appear in the Tasks > S.M.A.R.T. Tests list.
You must enable S.M.A.R.T. service to run automatic S.M.A.R.T. tests.
A periodic snapshot task allows scheduling the creation of read-only versions of pools and datasets at a given point in time.
Go to Tasks > Periodic Snapshot Tasks and click ADD.
Choose the dataset (or zvol) to schedule as a regular backup with snapshots and determine how long to store them. Define the task Schedule and configure the remaining options for your use case.
TrueNAS deletes snapshots when they reach the end of their life and preserves snapshots when at least one periodic task requires it. For example, you have two schedules created where one schedule takes a snapshot every hour and keeps them for a week, and the other takes a snapshot every day and keeps them for three years. Each has an hourly snapshot taken. After a week, snapshots created at 01.00 through 23.00 get deleted, but you keep snapshots timed at 00.00 because they are necessary for the second periodic task. These snapshots get destroyed at the end of 3 years.
The Naming Schema determines how automated snapshot names generate. A valid schema requires the %Y (year), %m (month), %d (day), %H (hour), and %M (minute) time strings, but you can add more identifiers to the schema too, using any identifiers from the Python strptime function.
For Periodic Snapshot Tasks used to set up a replication task with the Replication Task function:
You can use custom naming schemas for full backup replication tasks. If you are using the snapshot for incremental replication tasks, use the default naming schema. Go to Using a Custom Schema for additional information.
This uses some letters differently from POSIX (Unix) time functions.
For example, including %z
(time zone) ensures that snapshots do not have naming conflicts when daylight time starts and ends, and %S (second) adds finer time granularity.
Examples:
Naming Scheme | Snapshot Names Look Like |
---|---|
replicationsnaps-1wklife-%Y%m%d_%H:%M | replicationsnaps-1wklife-20210120_00:00 , replicationsnaps-1wklife-20210120_06:00 |
autosnap_%Y.%m.%d-%H.%M.%S-%z | autosnap_2021.01.20-00.00.00-EST , autosnap_2021.01.20-06.00.00-EST |
When referencing snapshots from a Windows computer, avoid using characters like:
that are invalid in a Windows file path. Some applications limit filename or path length, and there might be limitations related to spaces and other characters. Always consider future uses and ensure the name given to a periodic snapshot is acceptable.
Click SUBMIT to save the task in Tasks > Periodic Snapshot Tasks. You can find any snapshots from this task in Storage > Snapshots.
To check the log for a saved snapshot schedule, go to Tasks > Periodic Snapshot Tasks and click the task State.
TrueNAS provides a wizard for quickly configuring different simple replication scenarios.
While we recommend regularly scheduled replications to a remote location as the optimal backup scenario, the wizard can quickly create and copy ZFS snapshots to another location on the same system. This is useful when you have no remote backup locations or when a disk is in danger of failure.
All you need to create a local replication are datasets or zvols in a storage pool to use as the replication source and (preferably) a second storage pool to store replicated snapshots. You can set up the local replication entirely in the Replication Wizard.
To open the Replication Wizard, go to Tasks > Replication Tasks and click ADD.
Set the source location to the local system and pick which datasets to snapshot.
The wizard takes new snapshots of the sources when it can’t find existing source snapshots.
Enabling Recursive replicates all snapshots contained within the selected source dataset snapshots.
Local sources can also use a naming schema to identify and include custom snapshots in the replication.
A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
Set the Destination to the local system and define the path to the storage location for replicated snapshots. When manually defining the Destination, type the full path to the destination location.
TrueNAS suggests a default name for the task based on the selected source and destination locations, but you can type your name for the replication. You can load any saved replication task into the wizard to make creating new replication schedules even easier.
You can define a specific schedule for this replication or choose to run it immediately after saving the new task. Unscheduled tasks are still saved in the replication task list and can be run manually or edited later to add a schedule.
The destination lifetime is how long copied snapshots store in the Destination before the system deletes them. We usually recommend defining a snapshot lifetime to prevent storage issues. Choosing to keep snapshots indefinitely can require you to manually clean old ones from the system if or when the Destination fills to capacity.
Clicking START REPLICATION saves the new task and immediately attempts to replicate snapshots to the Destination. When TrueNAS detects that the Destination already has unrelated snapshots, it asks to delete the unrelated ones and do a full copy of the new ones. START REPLICATION can delete data, so be sure you are okay with deleting any existing snapshots. Alternatively, back them up in another location.
The simple replication is added to the replication task list and shows that it is currently running. Clicking the task state shows the replication log with an option to download it to your local system.
To confirm that snapshots replicated, go to Storage > Snapshots and verify the destination dataset has new snapshots with correct timestamps.
Configure SSH and automatic dataset snapshots in TrueNAS before creating a remote replication task. This ensures that both systems can connect and new snapshots are regularly available for replication.
To streamline creating simple replication configurations, the replication wizard assists with creating a new SSH connection and automatically creates a periodic snapshot task for sources with no existing snapshots.
Go to Tasks > Replication Tasks and click ADD.
You can load any saved replication to prepopulate the wizard with that configuration. Saving changes to the configuration creates a new replication task without altering the one you loaded into the wizard. This saves time when creating multiple replication tasks between the same two systems.
Start by configuring the replication sources. Sources are the datasets or zvols with snapshots to use for replication. Choosing a remote source requires selecting an SSH connection to that system. Expanding the directory browser shows the current datasets or zvols available for replication. You can select multiple sources or manually type the names into the field.
TrueNAS shows how many snapshots are available for replication. We recommend you manually snapshot the sources or create a periodic snapshot task before creating the replication task. However, when the sources are on the local system and don’t have any existing snapshots, TrueNAS can create a basic periodic snapshot task and snapshot the sources immediately before starting the replication. Enabling Recursive replicates all snapshots contained within the selected source dataset snapshots.
Remote sources require entering a Snapshot Naming Schema to identify the snapshots to replicate. A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
Local sources can also use a naming schema to identify and include custom snapshots in the replication.
The destination is where replicated snapshots are stored. Choosing a remote destination requires an SSH connection to that system. Expanding the directory browser shows the current datasets that are available for replication. You can select a destination dataset or manually type a path in the field. You cannot use Zvols as a remote replication destination. Adding a name to the end of the path creates a new dataset in that location.
Encryption: To use encryption when replicating data, check the Encryption box.
Using encryption for SSH transfer security is always recommended.
If you are using two systems within a secure network for replication, disabling encryption speeds up the transfer. However, the data is not protected from malicious sources.
Choosing no encryption for the task is the same as choosing the SSH+NETCAT transport method from the advanced options screen. NETCAT uses common port settings, but these can be overridden by switching to the advanced options screen or editing the task after creation.
TrueNAS suggests a name based on the selected sources and destination, but you can overwrite it with a custom name.
Adding a schedule automates the task to run according to your chosen times. You can choose between several preset schedules or create a custom schedule for when the replication runs. Choosing to run the replication once runs the replication immediately after saving the task, but you must manually trigger any additional replications.
Finally, define how long you want to keep snapshots on the destination system. We recommend defining snapshot lifetime to prevent cluttering the system with obsolete snapshots.
Start Replication saves the new replication task. TrueNAS enables new tasks by default and activates them according to their schedule (or immediately if you didn’t choose a schedule). The first time a replication task runs, it takes longer because the snapshots must copy entirely fresh to the destination. Later replications run faster, as only the subsequent changes to snapshots replicate. Clicking the task state opens the log for that task.
Requirements:
To use the advanced editor to create a replication task, go to Tasks > Replication Tasks, click ADD to open the Wizard, then click ADVANCED REPLICATION CREATION.
Options group by category. Options can appear, disappear, or be disabled depending on the configuration choices you make. Start by configuring the General options first, then the Transport options before configuring replication Sources and Destination.
Name the task. Each task name must be unique, and we recommend you name it in a way that makes it easy to remember what the task is doing.
Choose whether the local system is sending (Push) or receiving data (Pull) and decide what Transport method to use for the replication before configuring the other sections.
The Transport selector determines the method to use for the replication: SSH is the standard option for sending or receiving data from a remote system, but SSH+NETCAT is faster for replications within completely secure networks. Local is only used for replicating data to another location on the same system.
With SSH-based replications, configure the transport method by selecting the SSH Connection to the remote system that sends or receives snapshots. Options for compressing data, adding a bandwidth limit, or other data stream customizations are available. Stream Compression options are only available when using SSH. Before enabling Compressed WRITE Records, verify that the destination system supports compressed WRITE records.
For SSH+NETCAT replications, you also need to define the addresses and ports to use for the Netcat connection.
Allow Blocks Larger than 128KB is a one-way toggle. Replication tasks using large block replication only continue to work as long as this option remains enabled.
The replication Source is the datasets or zvols to replicate. Select the sources for the replication task by opening the file browser or entering dataset names in the field. Pulling snapshots from a remote source requires a valid SSH Connection before the file browser can show any directories. If the file browser shows a connection error after selecting the correct SSH Connection, you might need to log in to the remote system and ensure it allows SSH connections. Go to the Services screen and check the SSH service configuration. Start the service.
By default, replication tasks use snapshots to quickly transfer data to the receiving system. When Full Filesystem Replication is set, the chosen Source completely replicates, including all dataset properties, snapshots, child datasets, and clones. When choosing this option, we recommend allocating additional time for the replication task to run. Leaving Full Filesystem Replication unset but setting Include Dataset Properties includes just the dataset properties in the snapshots to be replicated. Additional options allow you to recursively replicate child dataset snapshots or exclude specific child datasets or properties from the replication.
Local sources replicate by snapshots you generated from a periodic snapshot task or from a defined naming schema that matches manually created snapshots.
Remote sources require entering a snapshot naming schema to identify the snapshots to replicate.
A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
For example, entering the naming schema custom-%Y-%m-%d_%H-%M
finds and replicates snapshots like custom-2020-03-25_09-15
.
Multiple schemas can be entered by pressing Enter to separate each schema.
To define specific snapshots from the periodic task to replicate, set Replicate Specific Snapshots and enter a schedule. The only periodically generated snapshots in the replication task are those that match your defined schedule. Alternately, you can use your Replication Schedule to determine which snapshots replicate by setting Run Automatically, Only Replicate Snapshots Matching Schedule, and defining when the replication task runs.
When a replication task has difficulty completing, set Save Pending Snapshots. Save Pending Snapshots prevents the source TrueNAS from automatically deleting any snapshots that fail to replicate to the destination system.
The destination is where replicated data is stored. Choosing a remote destination requires an SSH Connection to that system. Expanding the file browser shows the current available datasets on the destination system. You can click a destination or manually type a path in the field. Adding a name to the end of the path creates a new dataset in that location.
DO NOT use zvols for a remote destination
By default, the destination dataset is SET to be read-only after the replication is complete. You can change the Destination Dataset Read-only Policy to only start replication when the destination is read-only (REQUIRE) or to disable checking the dataset’s read-only state (IGNORE).
Encryption adds another layer of security to replicated data by encrypting the data before transfer and decrypting it on the destination system. Setting the checkbox allows using a HEX key or defining your own encryption PASSPHRASE. The encryption key can be stored in the TrueNAS system database or in a custom-defined location.
Synchronizing Destination Snapshots With Source destroys any snapshots in the destination that do not match the source snapshots. TrueNAS also fully replicates the source snapshots as if the replication task had never run before, which leads to excessive bandwidth consumption. This can be a destructive option, so be sure that any snapshots that the task deletes from the destination are obsolete or otherwise backed up in a different location.
Defining the Snapshot Retention Policy is generally recommended to prevent cluttering the system with obsolete snapshots. Choosing Same as Source keeps the snapshots on the destination system for the same duration as the defined snapshot lifetime from the source system periodic snapshot task. You can also define your own Custom lifetime for snapshots on the destination system.
By default, setting the task to Run Automatically starts the replication immediately after the related periodic snapshot task is complete.
Setting the Schedule checkbox allows scheduling the replication to run at a separate time.
Setting Only Replicate Snapshots Matching Schedule restricts the replication to only replicate those snapshots created at the same time as the replication schedule.
You can use Snapshot Tasks set up or imported with a custom schema name for “full backup” replication tasks. Incremental replication tasks will not work.
There are several ways to create a custom schema:
To view and download the replication task log, go to Tasks > Replication Tasks. Click on the state of the replication task.
Click the DOWNLOAD LOGS button to download the log file.
To edit the replication task, go to Tasks > Replication Tasks.
Click the >
to expand the replication task information, then click EDIT.
See Replication Advanced Options for descriptions of the available fields.
To customize the importance and frequency of a Replication task alert (success or failure), go to System > Alert Settings and scroll down to the Tasks area. Set the Warning Level and how often the alert notification sends.
See Alert Settings for more information about this UI screen.
Question: If the internet connection goes down for a while, does the replication restart where it left off - including any intermediate snapshots?
Answer: Yes.
Question: If a site changes a lot of data at once and the internet bandwidth is not enough to finish sending the snapshot before the next one begins, do the replication jobs run one after the other and not stomp on each other?
Answer: Yes.
Resilvering is a process that copies data to a replacement disk. Complete it as quickly as possible. Resilvering is a high priority task. It can run in the background while performing other system functions, however, this can put a higher demand on system resources. Increasing the priority of resilvers helps them finish faster as the system runs tasks with higher priority ranking.
Use the Resilver Priority screen to schedule a time where a resilver task can become a higher priority for the system and when the additional I/O or CPU use does not affect normal usage.
Select Enabled, then use the dropdown lists to select a start time in Begin and time to finish in End to define a priority period for the resilver. To select the day(s) to run the resilver, use the Days of the Week dropdown to select when the task can run with the priority given.
A resilver process running during the time frame defined between the beginning and end times likely runs faster than during times when demand on system resources is higher. We advise you to avoid putting the system under any intensive activity or heavy loads (replications, SMB transfers, NFS transfers, Rsync transfers, S.M.A.R.T. tests, pool scrubs, etc.) during a resilver process.
A “scrub” is when ZFS scans the data on a pool. Scrubs identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and provide early disk failure alerts.
By default, TrueNAS creates a scrub task when you create a new pool. The default schedule for a scrub is to run every Sunday at 12:00 AM. To edit the default scrub, go to Tasks > Scrub Tasks, click , and EDIT.
To create a scrub task for a pool, go to Tasks > Scrub Tasks and click ADD.
Select a Pool, enter the Threshold (in days), and give the scrub a description. Assign a Schedule and click SUBMIT.
Cloud sync tasks let TrueNAS integrate with a Cloud Storage provider for additional backup storage. Cloud Sync tasks allow for single time transfers or recurring transfers on a schedule, and are an effective method to back up data to a remote location.
These providers are supported for Cloud Sync tasks in TrueNAS CORE:
Using the Cloud means that data can go to a third party commercial vendor not directly affiliated with iXsystems. Please investigate and fully understand vendor pricing policies and services before creating any Cloud Sync task. iXsystems is not responsible for any charges incurred from the use of third party vendors with the Cloud Sync feature.
Transferring data from TrueNAS to the Cloud requires saving Cloud Storage Provider credentials on the system.
To maximize security, TrueNAS encrypts credentials after saving. However, this means that to restore any cloud credentials from a TrueNAS configuration file, you must enable Export Password Secret Seed when generating that configuration backup. Remember to protect any downloaded TrueNAS configuration files.
Go to System > Cloud Credentials and click ADD.
Enter a credential Name and choose a Provider. The rest of the options vary by Provider.
Enter the required Authentication strings to enable saving the credential.
Some providers can automatically populate the required Authentication strings by logging in to the account. To automatically configure the credential, click Login to Provider and entering your account username and password.
We recommend verifying the credential before saving it.
Go to Tasks > Cloud Sync Tasks and click ADD.
Give the task a Description and select a cloud credential. TrueNAS connects to the chosen Cloud Storage Provider and shows the available storage locations.
Decide if data is transferring to (PUSH) or from (PULL) the Cloud Storage location (Remote).
Choose a Transfer Mode:
SYNC keeps all the files identical between the two storage locations. If a sync encounters an error, the destination does not delete the files.
Syncing to a Backblaze B2 bucket does not delete files from the bucket, even when you delete those files locally. Instead, Backblaze tags files with a version number or moves them to a hidden state. To automatically delete old or unwanted files from the bucket, adjust the Backblaze B2 Lifecycle Rules.
COPY duplicates each source file into the destination, overwriting any destination files with the same name as the source. Copying is the least potentially destructive option.
MOVE transfers the files from the source to the destination and deletes the original source files. It also overwrites files with the same names on the destination.
Next, select a Schedule from the drop-down, or unset Enable to make the task available without running on a schedule.
Test the settings before saving by clicking DRY RUN. TrueNAS connects to the Cloud Storage Provider and simulates a file transfer without sending or receiving data.
Saved tasks activate based on their schedule, or when you click RUN NOW. An in-progress cloud sync must finish before another can begin. Stopping an in-progress task cancels the file transfer and requires starting the file transfer over.
To view logs about a running task or a task most recent run, click the task status.
To quickly create a new cloud sync task that uses the same options but reverses the data transfer, expand () on an existing task and click RESTORE.
Give the new task a Description and define the path to a storage location for the transferred data.
TrueNAS saves the restored cloud sync task as another entry in Tasks > Cloud Sync Tasks.
If the restore destination dataset is the same as the original source dataset, the restored files might have their ownership altered to root. If root did not create the original files and they need a different owner, you can recursively reset ACL Permissions of the restored dataset through the GUI or by running chown
from the CLI.
Choosing a Presets option automatically populates all fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
The simplest option is to enter a single number in the field. The task runs when the time value matches that number. Entering 10 runs the task when the time is ten minutes past the hour.
An asterisk (*) matches all values.
Set specific time ranges by entering hyphenated number values. Entering 30-35 in the Minutes field runs the task at minutes 30, 31, 32, 33, 34, and 35.
You can list individual values separated by a comma (,). Entering 1,14 in the Hours field runs the task at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value. Entering * in Days runs the task every day of the month, while */2 runs it every other day.
Combining all the above examples 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 runs. Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days plus any listed days. Entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Google Drive and G Suite are widely used to create and share documents, spreadsheets, and presentations with team members.
Although cloud-based tools have inherent backups and replications included by the cloud provider, certain users may require additional backup or archive capabilities.
For example, companies using G Suite for important work may need to keep records for years, potentially beyond the scope of the G Suite subscription.
TrueNAS can easily back up Google Drive using its built-in cloud sync.
Go to System > Cloud Credentials and click ADD. Name the Credential and select Google Drive as the Provider. Click LOGIN TO PROVIDER and log in with the appropriate Google user account.
Google requests permission to access all the Google Drive files for the FreeNAS device.
Allow access. The appropriate access key generates in the FreeNAS access token. You may assign a Team ID if necessary.
Click VERIFY CREDENTIAL and wait for it to verify, then click SUBMIT
Go to Tasks > Cloud Sync Tasks and set the backup time frame, frequency, and folders (cloud-based folder and TrueNAS dataset). Set whether the synchronization should sync all changes, copy new files, or move files. Add a description for the task and select the cloud credentials. Choose the appropriate cloud folder target and TrueNAS storage location.
Select the file transfer mode:
Once you create the task, attempt a Dry Run.
If the Dry Run succeeds, click SAVE..
Expand the section down to see the task options.
Clicking RUN NOW prompts the task to start immediately.
The web interface shows the status as RUNNING and SUCCESS upon completion. You can see details in the Task Manager. While the task runs, clicking on the RUNNING button reveals a popup log.
Once the sync reports SUCCESS, you can verify it by opening the folder on another computer if it is a share, through SSH access, or by checking the destination directory through the TrueNAS CLI.
One caveat is that Google Docs and other files created with Google tools have their own proprietary set of permissions and their read/write characteristics unknown to the system over a standard file share. Files are unreadable as a result.
To allow Google-created files to become readable, allow link sharing to access the files before the backup. Doing so ensures that other users can open the files with read access, make changes, and then save them as another file if further edits are needed. Note that this is only necessary if the file was created using Google Docs, Google Sheets, or Google Slides; other files should not require modification of their share settings.
TrueNAS is perfect for storing content, including cloud-based content, for the long term. Not only is it simple to sync and backup from the cloud, but users can rest assured that their data is safe, with snapshots, copy-on-write, and built-in replication functionality.
We recommend setting up your system connections before setting up data sharing. This integrates TrueNAS into your specific security and network environment. Configure these settings before attempting to store or share critical data.
The Network Summary gives a concise overview of the current network setup. It provides information about the currently active Interfaces, Default Routes and Nameservers. These areas are not editable.
Interfaces shows any configured physical, bridge, LAGG, and vlan interfaces. All detected physical interfaces are listed, even when unconfigured. The IPv4 or IPv6 address displays when a Static IP is saved for an interface.
Default Routes lists all saved TrueNAS Default Routes. Go to Network > Global Configuration to configure Default Routes.
Nameservers lists any configured DNS name servers that TrueNAS uses. To change this list, go to Network > Global Configuration. Network > Global Configuration contains the TrueNAS Hostname and Domain and Default Gateway. It also contains other options.
Define any Static Routes in Network > Static Routes.
Out of Band Management is managed from Network > IPMI. This option is visible only when TrueNAS detects the appropriate physical hardware.
A bridge generally refers to various methods of combining (aggregating) many network connections. These form a single total network. TrueNAS uses bridge(4) to manage bridges.
To set up a bridge interface, go to Network > Interface > Add.
Select Bridge as the Type and enter a name for the interface. The name must use the format bridgeX*, where X is a number representing a non-parent interface. It is also recommended to add any notes or reminders. Enter details about this particular bridge in Description.
The next section is Bridge Settings. Use the dropdown list next to Bridge Members to select the correct interfaces. Configure the remaining interface options to match your networking needs.
See Interfaces Screen for more information on settings.
Every kind of network interface has common settings:
Disabling Hardware Offloading can reduce network performance. It is not recommended.
Disabling this option is sometimes necessary. For example, when the interface is managing jails, plugins, or virtual machines.
MTU stands for maximum transmission unit. It is the largest protocol unit for transferring data. MTU size varies. Physical hardware and available network interfaces determine the largest workable MTU size. 1500 and 9000 are standard Ethernet MTU sizes. The recommendation is to use the default 1500. The permissible range of MTU values is 1492-9216. Leaving this field blank sets the default value of 1500.
You can enter more tuning ifconfig settings in the Options.
Additional aliases for the interface can also be defined:
It is possible to define either IPv4 or IPv6 addresses and subnets from 1-32. Clicking Add provides another field for defining an IP address.
A Link Aggregation (LAGG) is a general method of combining (aggregating) many network connections. The connections are either parallel or in series. This provides extra bandwidth or redundancy for critical networking situations. TrueNAS uses lagg(4) to manage LAGGs.
To set up a LAGG interface, go to Network > Interface > Add.
Set the Type to Link Aggregation.
Enter a name for the interface. The name must use the format laggX, where X is a number representing a non-parent interface. Enter any notes or reminders about this particular LAGG in the Description field.
Go to LAGG Settings and then Lagg Protocol to configure the interface ports to match your networking needs:
Now define the Lagg Interfaces and review the remaining interface options.
See Interfaces Screen for more information on settings.
Every kind of network interface has common settings:
Disabling Hardware Offloading can reduce network performance. It is not recommended.
Disabling this option is sometimes necessary. For example, when the interface is managing jails, plugins, or virtual machines.
MTU stands for maximum transmission unit. It is the largest protocol unit for transferring data. MTU size varies. Physical hardware and available network interfaces determine the largest workable MTU size. 1500 and 9000 are standard Ethernet MTU sizes. The recommendation is to use the default 1500. The permissible range of MTU values is 1492-9216. Leaving this field blank sets the default value of 1500.
You can enter more tuning ifconfig settings in the Options.
Additional aliases for the interface can also be defined:
It is possible to define either IPv4 or IPv6 addresses and subnets from 1-32. Clicking Add provides another field for defining an IP address.
A virtual LAN (VLAN) is a specialized domain in a computer network. It is a domain partitioned and isolated at the data link layer (OSI layer 2). See here for more information on VLANs. TrueNAS uses vlan(4) to manage VLANS.
To set up a VLAN interface, go to Network > Interface > Add.
Set the Type to VLAN and enter a name for the interface in Name. The name must use the format vlanX, where X is a number representing a non-parent interface. Enter any notes or reminders about this VLAN in the Description field.
Determine the requirements of your network environment before enabling DHCP or AutoconfigureIPv6. It is important to understand how this new interface functions in your situation. By default, TrueNAS allows only one network interface to have DHCP enabled.
Give careful attention to the remaining VLAN Settings. These need proper configuration in order for the network interface to function.
There are a few extra interface options to review after the VLAN options are set.
See Interfaces Screen for more information on settings.
Every kind of network interface has common settings:
Disabling Hardware Offloading can reduce network performance. It is not recommended.
Disabling this option is sometimes necessary. For example, when the interface is managing jails, plugins, or virtual machines.
MTU stands for maximum transmission unit. It is the largest protocol unit for transferring data. MTU size varies. Physical hardware and available network interfaces determine the largest workable MTU size. 1500 and 9000 are standard Ethernet MTU sizes. The recommendation is to use the default 1500. The permissible range of MTU values is 1492-9216. Leaving this field blank sets the default value of 1500.
You can enter more tuning ifconfig settings in the Options.
Additional aliases for the interface can also be defined:
It is possible to define either IPv4 or IPv6 addresses and subnets from 1-32. Clicking Add provides another field for defining an IP address.
Disruptive Change
It is possible to make changes to the network interface that the web interface uses. But this can result in losing connection to the TrueNAS system! Very often fixing misconfigured network settings requires command line knowledge. Physical access to the system is often required as well.
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet.
You can combine multiple interfaces with Link Aggregation (LAGG) or a Network Bridge. Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
TrueNAS can configure physical network interfaces with static IP addresses. Use either the web interface or the system console menu.
The recommendation is to use the web interface for this process. There are extra safety features to prevent saving misconfigured interface settings.
Log in to the web interface and go to Network > Interfaces. This contains creation and configuration options for physical and virtual network interfaces.
You can configure static IP addresses while creating or editing an interface.
To edit an active interface on TrueNAS Enterprise systems, you must first disable High Availability.
Type the desired address in the IP Address field and select a subnet mask.
Multiple interfaces cannot be members of the same subnet.
If an error displays when setting the IP addresses on multiple interfaces, check the subnet.
Use the buttons to Add and Delete more IP addresses as needed.
To avoid saving invalid or unusable settings, network changes are at first temporary. Applying any interface changes adds a dialog to the Network > Interfaces list.
You can adjust how long to test the network changes before they revert back to the previous settings. If the test is successful, another dialog allows making the network changes permanent.
To view system networking settings, go to Network > Network Summary.
You need to have a monitor and keyboard attached to the system to use the console. If the system hardware allows it, you can connect with IPMI. The console menu displays after the system completes booting.
To add static IP addresses to a physical interface, go to Configure Network Interfaces. Other interface types have a similar process to add static IP addresses. Interfaces that are already configured for DHCP have that option disabled. There are many prompts to answer before you can add a static address. This example shows adding static IPv4 addresses to interface igb0:
Saving interface configuration changes disrupts the web interface while system networking restarts. The new settings might need a system reboot to take effect. If the web interface is unavailable, this could also require a reboot. Check if the network interface you changed is the one utilized by the web interface.Be careful when configuring the network interface that controls the TrueNAS® web interface. An error can result in the loss of web connectivity.
Network > Interfaces lists all the physical Network Interface Controllers (NICs) connected to your TrueNAS® system.
To edit an interface, click > next to it to expand the view. This provides a general description about the chosen interface. Click EDIT.
TrueNAS Enterprise customers: you cannot edit an interface with High Availability (HA) enabled.
Go to System > Failover and check the Disable Failover box, then click SAVE.
The Type of interface determines the interface editing options available.
See Interfaces Screen for more information on settings.
After you’re done editing, click SAVE. You have the option to TEST CHANGES or REVERT CHANGES. The default time for testing any changes is 60 seconds, but you can change it to your desired setting.
After clicking TEST CHANGES, confirm your choice and click TEST CHANGES again.
Users can either SAVE CHANGES or REVERT CHANGES. A user has the time they specified to make their choice. If you select SAVE CHANGES, a dialog box asks you to CANCEL or SAVE network interface changes. Click SAVE.
The system displays a dialog box to show that network interface changes are now permanent.
Static routes are fixed, or non-adaptive routes. They are manually configured routes in the routing table.
It is recommended to use the web UI for all configuration tasks. TrueNAS does not have static routes defined by default. When required, add a static route by going to Network > Static Routes and clicking ADD.
Enter a Destination IP address. Use the format A.B.C.D/E where E is the CIDR mask.
Enter the IP address of the Gateway.
Enter any notes or identifiers describing the route in Description.
WireGuard is a popular option in the VPN marketplace. It is fast, simple, and uses modern cryptography standards. It is possible to connect your NAS to a WireGuard network in a few easy steps. Systems running FreeNAS version 11.3-RC1 through TrueNAS 13.0 have WireGuard capability.
Go to System > Tunables > Add and use these settings to enable the service:
Next, create another tunable to define the networking interface:
When finished, TrueNAS sets and enables the two variables.
Next, create a post-init script. This places the WireGuard config in the correct location at startup.
Go to Tasks > Init/Shutdown Scripts and click Add.
Configure the script to load the WireGuard
mkdir -p /usr/local/etc/wireguard && cp /root/wg0.conf /usr/local/etc/wireguard/wg0.conf && /usr/local/etc/rc.d/wireguard start
You can configure the
Now create the
There are quickstart guides and tutorials available online as well as the built-in wg-quick manpage.
Determine that you have a valid ifconfig
.
IPMI requires compatible hardware! Refer to your hardware documentation. Hardware compatibility determines if the IPMI option displays in the TrueNAS web interface.
Many TrueNAS systems provide a built-in out-of-band management port. If the system becomes unavailable through the web interface, you can use this port to provide side-band management. Use IPMI to perform several vital functions. These include checking the log, accessing the BIOS setup, and powering on the system. IPMI does not need physical access to the system. You can use it to allow another person remote access to the system. This is useful when investigating a configuration or troubleshooting issue.
Some IPMI implementations need updates to work with newer versions of Java. See PSA: Java 8 Update 131 breaks ASRock’s IPMI Virtual console for more information.
Configure IPMI by going to Network > IPMI. The IPMI configuration screen provides a shortcut to the most basic IPMI configuration.
Use the Network > IPMI screen to configure IPMI settings. See IPMI Screen for more information on IPMI settings.
Click SAVE to save the IPMI settings.
Save the configuration. Access the IPMI interface using a web browser and the IP address specified in Network > IPMI. The management interface prompts for login credentials. Refer to your IPMI device documentation to learn the default administrator account credentials.
Log in to the management interface. Here you can change the default administrative user name and create extra IPMI users. The appearance of the IPMI utility and the functions that are available vary by hardware.
TrueNAS uses ZFS data storage pools to efficiently store and protect data.
It is strongly recommended that you review the available system resources and plan the storage use case before creating a storage pool.
Determining your specific storage requirements is a critical step before creating a pool.
To create a new pool, go to Storage > Pools and click ADD. The Create or Import Pool screen of the pool creation screens displays. Select Create new pool and click CREATE POOL to open the Pool Manager.
To begin, enter a name for the pool in Name. Do not include spaces in the pool name as this could cause problems with other functions.
Next, configure the virtual devices (vdevs) that make up the pool.
Clicking SUGGEST LAYOUT allows TrueNAS to review all available disks and populate the primary data vdevs with identically sized drives in a balanced configuration between storage capacity and data redundancy. To clear the suggestion, click RESET LAYOUT.
To manually configure the pool, add vdevs according to your use case. Select the Disk checkboxes and click the to move the disks into the Data VDevs list.
Warning: USB-connected disks might report their serial numbers inaccurately, making them indistinguishable from each other.
Pools have many different kinds of vdevs available. These store data or enable unique features for the pool:
To add a different vdev type during pool creation, click ADD VDEV and select the type. Select disks from Available Disks and use the (right arrow) next to the new VDev to add it to that section.
Disks added to a vdev arrange in different layouts, according to the specific pool use case.
The Pool Manager suggests a vdev layout from the number of disks added to the vdev. For example, if two disks are added, TrueNAS automatically configures the vdev as a mirror, where the total available storage is the size of one added disk while the other disk provides redundancy.
To change the vdev layout, open the Data VDevs list and select the desired layout.
This procedure only applies to disks with a ZFS storage pool. To import disks with different file systems, see Import Disk.
ZFS pool importing works for pools that were exported or disconnected from the current system, created on another system, and pools to reconnect after reinstalling or upgrading the TrueNAS system. To import a pool, go to Storage > Pools > ADD.
There are two kinds of pool imports, standard ZFS pool imports and ZFS pools with legacy GELI encryption.
After creating a data storage pool, there are a variety of options to change the initial configuration of that pool. Changing a pool can be disruptive, so make sure you are aware of existing resources on the system and consider backing up any stored data before changing the pool. To find an existing pool, log in to the web interface and go to Storage > Pools.
The current status and storage usage of each pool is shown. To see more details about a pool, click the
expand symbol on the right side of the pool entry. Click the for all pool management options.A TrueNAS dataset is a file system that is created within a data storage pool. Datasets can contain files, directories (child datasets), and have individual permissions or flags. Datasets can also be encrypted, either using the encryption created with the pool or with a separate encryption configuration.
It is recommended to organize your pool with datasets before configuring data sharing, as this allows for more fine-tuning of access permissions and using different sharing protocols.
To create a dataset in the desired pool, go to Storage > Pools.
Find the pool and top-level (root) dataset for that pool, then click and Add Dataset.
To quickly create a dataset with the default options, enter a name for the dataset and click SUBMIT.
The Name and Options fields is required to create the dataset. Datasets typically inherit most of these settings from the root or parent dataset, only a dataset name is required before clicking SUBMIT.
See Dataset Screens for more information on basic and advanced settings.
By default, datasets inherit the Encryption Options from the root or parent dataset. To configure the dataset with different encryption settings, clear the checkmark from Inherit and choose the new in Encryption Options. For detailed descriptions of the encryption options, see the Encryption article.
Clicking ADVANCED OPTIONS adds dataset quota management tools and a few additional fields to the Other Options:
After a dataset is created, additional management options are available by going to Storage > Pools and clicking for a dataset:
Deleting datasets can result in unrecoverable data loss! Be sure that any critical data is moved off the dataset or is otherwise obsolete.
TrueNAS allows setting data or object quotas for user accounts and groups cached on or connected to the system.
Setting a quota defines the maximum allowed space for the dataset. You can also reserve a defined amount of pool space for the dataset to help prevent situations where automatically generated data like system logs consume all space on the dataset. Quotas can be configured for either the new dataset or to include all child datasets in the quota.
Dataset Screens for more information on quota settings.
To view and edit user quotas, go to Storage > Pools and click to open the Dataset Actions menu, and then click User Quotas.
The User Quotas page displays the names and quota data of any user accounts cached on or connected to the system.
To edit individual user quotas, go to the user row and click the button, then click edit.
The Edit User window allows editing the User Data Quota, which is the amount of disk space that can be used by the selected users, and the User Object Quota, which is the number of objects that can be owned by each of the selected users.
To edit user quotas in bulk, click Actions and select Set Quotas (Bulk).
The Set Quotas window allows editing user data and object quotas after selecting any cached or connected users.
Go to Storage > Pools and click to open the Dataset Actions menu. Click Group Quotas.
The Group Quotas page displays the names and quota data of any groups cached on or connected to the system.
To edit individual group quotas, go to the group row and click the > button, then click edit.
The Edit Group window allows editing the Group Data Quota and Group Object Quota.
To edit group quotas in bulk, click Actions and select Set Quotas (Bulk).
The same options for single groups are presented, along with choosing groups for these new quota rules.
A ZFS Volume (Zvol) is a dataset that represents a block device. These are needed when configuring an iSCSI Share.
To create a zvol in a pool, go to Storage > Pools then click and Add Zvol.
To quickly create a Zvol with the default options, enter a name for the Zvol, a size, and click SAVE.
See Zvols Screen for more information on zvol settings.
To set the zvol block size, click ADVANCED OPTIONS on the ADD ZVOL screen. This adds the Block Size setting near the bottom of the screen. Select that option that suits the use case or uses the information below to help determine the correct setting to use.
To see options for an existing zvol, click more_vert next to the desired zvol in Storage > Pools:
Use Delete zvol to remove the zvol from TrueNAS.
Deleting a zvol also deletes all snapshots of that zvol. Use Edit Zvol to open the zvol creation form to change the previously saved settings. Similar to datasets, a zvol name cannot be changed. Use Create Snapshot to take a single current-point-in-time image of the zvol and save it to Storage > Snapshots. A snapshot name is suggested in Name along with an extra option to make the snapshot Recursive is available.Deleting zvols can result in unrecoverable data loss! Be sure that any critical data is moved off the zvol or is otherwise obsolete.
When the selected zvol is cloned from an existing snapshot, Promote Dataset is available. When a clone is promoted, the original volume becomes a clone of the clone, making it possible to delete the volume that the clone was created from. Otherwise, a clone cannot be deleted while the original volume exists.
When the zvol is created with encryption enabled, additional Encryption Actions are displayed.
Permissions control the actions users can perform on dataset contents. TrueNAS allows using both a simple permissions manager and editing a full Access Control List (ACL) for defining dataset permissions.
To change dataset permissions, go to Storage > Pools > more_vert Edit Permissions for a dataset.
The Edit Permissions option allows basic adjustments to a datasets ACL.
The Owner section controls which TrueNAS user and group has full control of this dataset.
Access Mode defines the basic read, write, and execute permissions for the user, group, and other accounts that might access this dataset.
Advanced has several tuning options to set how permissions apply to directories and files within the current dataset.
To switch from the basic editor to the advanced ACL editor, click USE ACL MANAGER.
An Access Control List (ACL) is a set of account permissions associated with a dataset and applied to directories or files within that dataset. ACLs are typically used to manage user interactions with shared datasets and are created when a dataset is added to a pool.
When creating a dataset, you can choose how the ACL can be modified by selecting an ACL Mode:
Passthrough only updates ACL entries (ACEs) that are related to the file or directory mode.
Restricted does not allow chmod
to make changes to files or directories with a non-trivial ACL.
An ACL is trivial if it can be fully expressed as a file mode without losing any access rules.
Setting the ACL Mode to Restricted is typically used to optimize a dataset for SMB sharing, but can require further optimizations.
For example, configuring an rsync task with this dataset could require adding --no-perms
as an extra option for the task.
To view an ACL, go to Storage > Pools > more_vert Edit Permissions for a nested dataset within a pool.
The ACL for a new file or directory is typically inherited from the parent directory and is preserved when it is moved or renamed within the same dataset. An exception is when there are no File Inherit or Directory Inherit flags in the parent ACL owner@, group@, or everyone@ entries. These non-inheriting entries are added to the ACL of the newly created file or directory based on the Samba create and directory masks or the umask value.
Click ACL Manager to adjust file ownership or account permissions to the dataset. The first time viewing the ACL Manager a dialog suggests using basic presets. The ACL can be edited at any time after choosing to either apply a preset or create a custom ACL.
Choose Select a preset ACL and choose a preset. The preset options are OPEN, RESTRICTED, or HOME.
Choose Create a custom ACL to create a new list of customized permissions.
File Information
The selected User controls the dataset and always has permission to modify the ACL and other attributes. The selected Group also controls the dataset, but permissions change by adding or modifying a group@ ACE. Any user accounts or groups imported from a directory service can be selected as the primary in User or Group.
To add a new item to the ACL, define Who the Access Control Entry (ACE) applies to, and configure permissions and inheritance flags for the ACE.
Permissions are divided between Basic and Advanced options. The basic options are commonly used groups of the advanced options.
Basic Permissions
r-x---a-R-c---
): view file or directory contents, attributes, named attributes, and ACL.
Includes the Traverse permission.rwxpDdaARWc--s
): adjust file or directory contents, attributes, and named attributes.
Create new files or subdirectories.
Includes the Traverse permission.
Changing the ACL contents or owner is not allowed.--x---a-R-c---
): Execute a file or move through a directory.
Directory contents are restricted from view unless the Read permission is also applied.
To traverse and view files in a directory, but not be able to open individual files, set the Traverse and Read permissions, then add the advanced Directory Inherit flag.rwxpDdaARWcCos
): Apply all permissions.Advanced Permissions
r
): View file contents or list directory contents.w
): Create new files or modify any part of a file.p
): Add new data to the end of a file.R
): view the named attributes directory.W
): create a named attribute directory. Must be paired with the Read Named Attributes permission.x
): Execute a file, move through, or search a directory.D
): delete files or subdirectories from inside a directory.a
): view file or directory non-ACL attributes.A
): change file or directory non-ACL attributes.d
): remove the file or directory.c
): view the ACL.C
): change the ACL and the ACL mode.o
): change the user and group owners of the file or directory.s
): synchronous file read/write with the server. This permission does not apply to FreeBSD clients.Basic inheritance flags only enable or disable ACE inheritance. Advanced flags offer finer control for applying an ACE to new files or directories.
Basic Flags
fd-----
): enable ACE inheritance.-------
): disable ACE inheritance.Advanced Flags
f
): The ACE is inherited with subdirectories and files. It applies to new files.d
): new subdirectories inherit the full ACE.n
): The ACE can only be inherited once.i
): Remove the ACE from permission checks but allow it to be inherited by new files or subdirectories. Inherit Only is removed from these new objects.I
): set when the ACE has been inherited from another dataset.TrueNAS supports different encryption options for critical data.
Users are responsible for backing up and securing encryption keys and passphrases! Losing the ability to decrypt data is similar to a catastrophic data loss.
Data-at-rest encryption is available with:
The local TrueNAS system manages keys for data-at-rest. The user is responsible for storing and securing their keys. The Key Management Interface Protocol (KMIP) is included in TrueNAS 12.0.
Encrypting the root dataset of a new storage pool further increases data security. All datasets added to a pool with encryption applied inherit encryption. This means all datasets added to a pool with encryption are also encrypted.
Create a new pool and set Encryption in the Pool Manager. TrueNAS shows a warning.
Read the warning, select Confirm, and click I Understand.
We recommend using the default encryption in Cipher, but other ciphers are available.
TrueNAS can encrypt new datasets within an existing unencrypted storage pool without having to encrypt the entire pool. To encrypt a single dataset, go to Storage > Pools, open the more_vert for an existing dataset, and click Add Dataset.
In the Encryption Options area, clear the Inherit checkbox, then select Encryption.
Now select the authentication to use from the two options in Type: either a Key or Passphrase. The remaining options are the same as a new pool. Datasets with encryption enabled show additional icons on the Storage > Pools list.
The dataset locked/unlocked status is determined from an icon:
NOTE: An unencrypted pool with an encrypted dataset also shows this icon:
You can only lock or unlock encrypted datasets when they are secured with a passphrase instead of a key file. Before locking a dataset, verify that it is not currently in use, then click (Options) and Lock.
Use the Force unmount option only if you are certain no one is currently accessing the dataset. After locking a dataset, the unlock icon changes to a locked icon. While the dataset is locked, it is not available for use.
To unlock a dataset, click more_vert and Unlock.
Enter the passphrase and click Submit. To unlock child datasets, select Unlock Children. Child datasets that inherited encryption settings from the parent dataset unlock when the parent unlocks. Users can simultaneously unlock child datasets with different passphrases from the parent by entering their passphrases.
Confirm unlocking the datasets and wait for a dialog to show the unlock is successful.
There are two ways to manage the encryption credentials, with either key files or passphrases.
Always back up the key file to a safe and secure location!
Creating a new encrypted pool automatically generates a new key file and prompts you to download it.
Manually download a copy of the inherited and non-inherited encrypted dataset key files for the pool by opening the pool settings menu and selecting Export Dataset Keys. Enter the root password and click CONTINUE.
To manually download a back up of a single key file for the dataset, click the dataset more_vert and select Export Key. Enter the root password and click CONTINUE. Click DOWNLOAD KEY.
To change the key, click the dataset more_vert and Encryption Options.
Enter your custom key or click Generate Key.
To use a passphrase instead of a key file, click the dataset more_vert and Encryption Options. Change the Encryption Type from Key to Passphrase.The passphrase is the only means to decrypt the information stored in a dataset using passphrase encryption keys. Be sure to create a memorable passphrase or physically secure the passphrase.
Set the rest of the options:
Passphrase is a user-defined string of eight to 512 characters in length, to use instead of an encryption key to decrypt the dataset.
pbkdf2iters is the number of password-based key derivation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Entering a number greater than 100000 is required.
TrueNAS Enterprise users may connect a Key Management Interoperability Protocol (KMIP) server to centralize keys when they are not using passphrases to unlock a dataset or zvol.
Users with TrueNAS CORE or Enterprise installations without KMIP should either replicate the dataset or zvol without properties to disable encryption at the remote end or construct a special json manifest to unlock each child dataset/zvol with a unique key.
This does not affect TrueNAS Enterprise installs with KMIP.
TrueNAS no longer supports GELI encryption (deprecated).
Data can be migrated from the GELI-encrypted pool to a new ZFS-encrypted pool. Unlock the GELI-encrypted pool before attempting any data migrations. The new ZFS-encrypted pool must be at least the same size as the previous GELI-encrypted pool. Do not delete the GELI dataset until you verify the data migration.
There are a few options to migrate data from a GELI-encrypted pool to a new ZFS-encrypted pool:
GELI encrypted pools continue to be detected and supported in the TrueNAS web interface as Legacy Encrypted pools. As of TrueNAS version 12.0-U1, a decrypted GELI pool can migrate data to a new ZFS encrypted pool using the Replication Wizard.
The web interface supports using Tasks > Rsync Tasks to transfer files out of the GELI pool.This method does not preserve file ACLs.
Fusion Pools are also known as ZFS allocation classes, ZFS special vdevs, and metadata vdevs (Metadata vdev type on the Pool Manager screen.).
Go to Storage > Pools, click ADD, and select Create new pool.
A pool must always have one normal (non-dedup/special) VDEV before other devices can be assigned to the special class. Configure the Data VDevs, then click ADD VDEV and select Metadata.
Add SSDs to the new Metadata VDev and select the same layout as the Data VDevs.
The metadata special VDEV is critical for pool operation and data integrity, so you must protect it with hot spare(s).
Using special VDEVs identical to the data VDEVs (so they can use the same hot spares) is recommended, but for performance reasons you can make a different type of VDEV (like a mirror of SSDs). In that case you must provide hot spare(s) for that drive type as well. Otherwise, if the special VDEV fails and there is no redundancy, the pool becomes corrupted and prevents access to stored data.
Drives added to a metadata VDEV cannot be removed from the pool.
When more than one metadata VDEV is created, then allocations are load-balanced between all these devices. If the special class becomes full, then allocations spill back into the normal class.
After the fusion pool is created, the Status shows a Special section with the metadata SSDs.
See Managing Pools.
Over-provisioning SLOG SSDs is useful for different scenarios. The most useful benefit of over-provisioning is greatly extending SSD life. Over-provisioning an SSD distributes the total number of writes and erases across more flash blocks on the drive.
Seagate provides a thoughtful investigation into over-provisioning SSDs here: https://www.seagate.com/blog/ssd-over-provisioning-benefits-master-ti/.
Some SATA devices are limited to one resize per power cycle. Some BIOS can block resize during boot and require a live power cycle.
Storage > VMware-Snapshots coordinates ZFS snapshots when using TrueNAS as a VMware datastore. When a ZFS snapshot is created, TrueNAS automatically snapshots any running VMware virtual machines before taking a scheduled or manual ZFS snapshot of the dataset or zvol backing that VMware datastore.
To copy TrueNAS snapshots to VMWare, virtual machines must be powered-on. The temporary VMware snapshots are then deleted on the VMware side but still exist in the ZFS snapshot and are available as stable restore points. These coordinated snapshots go on the Storage > Snapshots list.
You need a paid-edition for VMware ESXi to use VMware-Snapshots. If you try to use them with ESXi free edition you see the following error message: Error: Can’t create snapshot, current license or ESXi version prohibits execution of the requested operation. ESXi free has a locked (read-only) API that prevents using TrueNAS VMware-Snapshots. The cheapest ESXi edition that is compatible with TrueNAS VMware-Snapshots is VMware vSphere Essentials Kit.
Go to Storage > VMware Snapshots and click ADD.
After entering the Hostname, Username, and Password, click FETCH DATASTORES to populate the menu and then select the datastore to synchronize.
TrueNAS connects to the VMware host after clicking FETCH DATASTORES. The ZFS Filesystem and Datastore drop-down menus populate from the VMware host response. Choosing a datastore also selects any previously mapped dataset.
The wipe function deletes obsolete data off an unused disk.
This is a destructive action and results in permanent data loss! Back up any critical data off the disk to be wiped.
To wipe a disk, go to Storage > Disks. Click the chevron_right for a disk to see all the options.
The wipe option is only available when the disk is not in use. Click WIPE to open a dialog with additional options:
The disk Name (da1, da2, ada4) helps confirm that you have selected the right disk to wipe
The Method dropdown list shows the different available wipe options available. Select Quick to erase only the partitioning information on a disk, making it easy to reuse but without clearing other old data. Quick wipes take only a few seconds. Select Full with zeros to overwrite the entire disk with zeros. This can take several hours to complete. Select Full with random to overwrite the entire disk with random binary code and takes even longer than Full with zeros to complete.
Ensure all data is backed up and the disk is no longer in use. Triple check that the correct disk is selected for the wipe. Recovering data from a wiped disk is usually impossible.
After selecting the appropriate method, click WIPE. A dialog asks for confirmation of the action.
Verify the name to ensure you have the correct disk chosen. When satisfied the disk can be wiped, select Confirm and click CONTINUE. A dialog shows the disk wipe progress.
See Disks Screens for more information on Disks screen settings.
Hard drives and solid-state drives (SSDs) have a finite lifetime and can fail unexpectedly. When a disk fails in a Stripe (RAID0) pool, you must recreate the entire pool and restore all data backups. We always recommend creating non-stripe storage pools that have disk redundancy.
To prevent further redundancy loss or eventual data loss, always replace a failed disk as soon as possible! TrueNAS integrates new disks into a pool to restore it to full functionality.
TrueNAS requires you to replace a disk with another disk of the same or greater capacity as a failed disk. You must install the disk in the TrueNAS system. It should not be part of an existing storage pool. TrueNAS wipes the data on the replacement disk as part of the process.
Disk replacement automatically triggers a pool resilver.
The TrueNAS Dashboard shows when a disk failure degrades a pool.
Click the settings on the pool card to go to the Storage > Pools > Pool Status screen to locate the failed disk.
To replace a disk in a pool without a hot spare available:
To replace a disk in a pool with a hot spare:
Go to Storage > Pools screen.
Go to the Storage > Pools screen, click on the settings settings icon, and then select Status to open the Pool Status screen and display the disks in the pools.
Click the more_vert icon for the disk you plan to remove and then click Offline.
Select Confirm, then click OFFLINE.
When the disk status shows as Offline, physically remove the disk from the system.
If replacing the failed disk that you have taken offline and removed, insert the replacement disk now. If replacing a failed disk with an available disk in the system, proceed to the next step.
In the Pool Status screen, open the options for the offline disk and click Replace
Select a new member disk and click Replace Disk. The new disk must have the same or greater capacity as the disk you are replacing. The replacement fails when the chosen disk has partitions or data present. To destroy any data on the replacement disk and allow the replacement to continue, set the Force option.
When the disk wipe completes and TrueNAS starts replacing the failed disk, the Pool Status screen changes to show the in-progress replacement.
TrueNAS resilvers the pool during the replacement process. For pools with large amounts of data, resilvering can take a long time.
When the resilver completes, the Pool Status screen updates to show the new disk, and the pool status returns to Online.
A Hot Spare vdev sets up drives as reserved to prevent larger pool and data loss scenarios. TrueNAS automatically inserts an available hot spare into a Data vdev when an active drive fails. The pool resilvers after the hot spare is activated.
To replace a disk in a pool with a hot spare:
Go to the Storage > Pools screen, click on the settings settings icon, and then select Status to open the Pool Status screen and display the disks in the pools.
After taking the failed disk offline and removing it from the system, the disk status changes to REMOVED and the disk name displays the gptid.
Click the more_vert icon for the removed disk and then click Detach.
Select Confirm, then click DETACH. TrueNAS detaches the disk from the pool and promotes the hot spare disk to a full member of the pool.
After promoting the hot spare, recreate the Spare vdev and assign a disk to it.
If recreating the spare with a replacement in place of the failed disk, insert the replacement disk now. If recreating the spare with an available disk in the system, proceed to the next step.
Go to the Storage > Pools screen, click on the settings settings icon, and then select Add Vdevs to open the Pool Manager screen and display the disks in the pools.
Click ADD VDEV and select Hot Spare.
Select an available disk and click to add it to the Spare VDev.
Click ADD VDEVS. Select Confirm, then click ADD VDEVS.
After completing the job, TrueNAS returns to the Storage > Pools screen. Click on the settings settings icon, and then select Status to open the Pool Status screen and confirm the hot spare is added.
TrueNAS version 11.1-U5 introduced Self-Encrypting Drive (SED) support.
Pyrite Version 1 SEDs do not have PSID support and can become unusable if the password is lost.
See this Trusted Computing Group and NVM Express® joint white paper for more details about these specifications.
TrueNAS implements the security capabilities of camcontrol for legacy devices and sedutil-cli for TCG devices.
When managing a SED from the command line, it is recommended to use the sedhelper
wrapper script for sedutil-cli
to ease SED administration and unlock the full capabilities of the device. Examples of using these commands to identify and deploy SEDs are provided below.
A SED can be configured before or after assigning the device to a pool.
By default, SEDs are not locked until the administrator takes ownership of them. Ownership is taken by explicitly configuring a global or per-device password in the web interface and adding the password to the SEDs. Adding SED passwords in the web interface also allows TrueNAS to automatically unlock SEDs.
A password-protected SED protects the data stored on the device when the device is physically removed from the system. This allows secure disposal of the device without having to first wipe the contents. Repurposing a SED on another system requires the SED password.
For TrueNAS High Availability (HA) systems, SED drives only unlock on the active controller!
Enter command sedutil-cli --scan
in the Shell to detect and list devices. The second column of the results identifies the drive type:
Character | Standard |
---|---|
no | non-SED device |
1 | Opal V1 |
2 | Opal V2 |
E | Enterprise |
L | Opalite |
p | Pyrite V1 |
P | Pyrite V2 |
r | Ruby |
Example:
root@truenas1:~ # sedutil-cli --scan
Scanning for Opal compliant disks
/dev/ada0 No 32GB SATA Flash Drive SFDK003L
/dev/ada1 No 32GB SATA Flash Drive SFDK003L
/dev/da0 No HGST HUS726020AL4210 A7J0
/dev/da1 No HGST HUS726020AL4210 A7J0
/dev/da10 E WDC WUSTR1519ASS201 B925
/dev/da11 E WDC WUSTR1519ASS201 B925
TrueNAS supports setting a global password for all detected SEDs or setting individual passwords for each SED. Using a global password for all SEDs is strongly recommended to simplify deployment and avoid maintaining separate passwords for each SED.
Go to System > Advanced > SED Password and enter the password.
Now configure the SEDs with this password. Go to the Shell and enter commandRecord this password and store it in a safe place!
sedhelper setup <password>
, where <password>
is the global password entered in System > Advanced > SED Password.sedhelper
ensures that all detected SEDs are properly configured to use the provided password:
root@truenas1:~ # sedhelper setup abcd1234
da9 [OK]
da10 [OK]
da11 [OK]
Rerun command sedhelper setup <password>
every time a new SED is placed in the system to apply the global password to the new SED.
Go to Storage > Disks. Click the > next to an SED, then select Edit. Enter and confirm the password in the SED Password field.
You must configure the SED to use the new password. Go to the Shell and enter command sedhelper setup --disk <da1> <password>
, where <da1>
is the SED to configure and <password>
is the created password from Storage > Disks > Edit Disks > SED Password.
Repeate this process for each SED and any SEDs added to the system in the future.
Remember SED passwords! If you lose the SED password, you cannot unlock SEDs or access their data. Always record SED passwords whenever they are configured or modified and store them in a secure place!
When SED devices are detected during system boot, TrueNAS checks for configured global and device-specific passwords.
Unlocking SEDs allows a pool to contain a mix of SED and non-SED devices. Devices with individual passwords are unlocked with their password. Devices without a device-specific password are unlocked using the global password.
To verify SED locking is working correctly, go to the Shell. Enter command sedutil-cli --listLockingRange 0 <password> </dev/da1>
, where <dev/da1>
is the SED and <password>
is the global or individual password for that SED. The command returns ReadLockEnabled: 1
, WriteLockEnabled: 1
, and LockOnReset: 1
for drives with locking enabled:
root@truenas1:~ # sedutil-cli --listLockingRange 0 abcd1234 /dev/da9
Band[0]:
Name: Global_Range
CommonName: Locking
RangeStart: 0
RangeLength: 0
ReadLockEnabled: 1
WriteLockEnabled:1
ReadLocked: 0
WriteLocked: 0
LockOnReset: 1
This section contains command line instructions to manage SED passwords and data. The command used is sedutil-cli(8). Most SEDs are TCG-E (Enterprise) or TCG-Opal (Opal v2.0). Commands are different for the different drive types, so the first step is identifying which type is used.
These commands can be destructive to data and passwords. Keep backups and use the commands with caution.
Check SED version on a single drive, /dev/da0 in this example:
root@truenas:~ # sedutil-cli --isValidSED /dev/da0
/dev/da0 SED --E--- Micron_5N/A U402
All connected disks can be checked at once:
root@truenas:~ # sedutil-cli --scan
Scanning for Opal compliant disks
/dev/ada0 No 32GB SATA Flash Drive SFDK003L
/dev/ada1 No 32GB SATA Flash Drive SFDK003L
/dev/da0 E Micron_5N/A U402
/dev/da1 E Micron_5N/A U402
/dev/da12 E SEAGATE XS3840TE70014 0103
/dev/da13 E SEAGATE XS3840TE70014 0103
/dev/da14 E SEAGATE XS3840TE70014 0103
/dev/da2 E Micron_5N/A U402
/dev/da3 E Micron_5N/A U402
/dev/da4 E Micron_5N/A U402
/dev/da5 E Micron_5N/A U402
/dev/da6 E Micron_5N/A U402
/dev/da9 E Micron_5N/A U402
No more disks present ending scan
root@truenas:~ #
Use Storage > Import Disk to integrate UFS (BSD Unix), NTFS (Windows), MSDOS (FAT), or EXT2 (Linux) formatted disks into TrueNAS. This is a one-time import, copying the data from that disk into a TrueNAS dataset. Only one disk can be imported at a time, and the disk must be installed or physically connected to the TrueNAS system.
Use the dropdown list to select the Disk to import.
TrueNAS attempts to detect and select the the Filesystem type. Selecting the MSDOSFS file system shows an additional MSDOSFS locale dropdown menu. Use this option to select the locale when non-ASCII characters are present on the disk.
Finally, browse to the ZFS dataset to hold the copied data and define the Destination Path.
After clicking SAVE, the chosen disk mounts and its contents copied to the specified dataset at the end of the entry in Destination Path. To monitor an in-progress import, open the Task Manager by clicking the assignment in the top menu bar. The disk unmounts after the copy operation completes. A dialog allows viewing or downloading the disk import log.
Snapshots are one of the most powerful features of ZFS. A snapshot provides a read only point-in-time copy of a file system or volume. This copy does not consume extra space in the ZFS pool. The snapshot only records the differences between storage block references whenever the data is modified.
Taking snapshots requires the system have all pools, datasets, and zvols already configured.
Consider making a Periodic Snapshot Task to save time and create regular, fresh snapshots.
To perform a quick snapshot of existing storage, go to Storage > Snapshots and click ADD.
Use the Dataset dropdown list to select an existing ZFS pool, dataset, or zvol to snapshot.
The TrueNAS software displays a suggested name that you can override with any custom string.
To include the snapshot in local or remote replication tasks choose a proper naming schema. The Naming Schema drop-down list populates with schemas already created from periodic snapshot tasks.
To include child datasets with the snapshot, select Recursive.
Go to Storage > Snapshots to manage created snapshots.
Each entry in the list includes the dataset and snapshot names. Click chevron_right to view options for a snapshot.
DATE CREATED shows the exact time and date of the snapshot creation.
USED shows the amount of space consumed by this dataset and all of its descendants. This value, checked against the dataset quota and reservation, shows the space used but does not include the dataset reservation. It takes into account the reservations of any descendant datasets. The amount of space that a dataset consumes from its parent, and the amount of space freed if this dataset is recursively deleted, is the greater of its space used and its reservation.
At creation, a snapshot shares space between the snapshot, file system, and even with previous snapshots. File system changes reduce the shared space and count toward space used by a snapshot. Deleting a snapshot often increases the space that is unique and used in other snapshots.
REFERENCED shows the amount of data accessible by this dataset. This could be shared with other datasets in the pool. New snapshots or clones reference the same amount of space as the file system it was created from, as the contents are identical.
Another method to view the space used by an individual snapshot is to go to the Shell and enter command zfs list -t snapshot
.
The space used, available, or referenced does not account for pending changes. In general, pending changes update within a few seconds, but larger disk changes slow usage updates.
The Delete option destroys the snapshot. You must delete child clones before you can delete their parent snapshot. While creating a snapshot is instantaneous, deleting one is I/O intensive and can take a long time, especially when deduplication is enabled.
Use CLONE TO NEW DATASET to create a new snapshot clone (dataset) from the snapshot contents.
A dialog prompts for the new dataset name. The suggested name derives from the snapshot name.Reverts the dataset back to the point in time saved by the snapshot.
Rollback is a dangerous operation that causes any configured replication tasks to fail. Replications use the existing snapshot when doing an incremental backup, and rolling back can put the snapshots out of order. To restore the data within a snapshot, the recommended steps are:
Clone the desired snapshot.
Share the clone with the share type or service running on the TrueNAS system.
Allow users to recover their needed data.
Delete the clone from Storage > Pools.
This approach does not destroy any on-disk data and has no impact on replication.
TrueNAS asks for confirmation before rolling back to the chosen snapshot state. Clicking Yes reverts all dataset files to the state they were in at the time of snapshot creation.
To delete multiple snapshots, select the left column box for each snapshot to include. Click the delete Delete button that displays.
To search through the snapshots list by name, type a matching criteria into the search Filter Snapshots text field. The list now displays only the snapshot names that match the filter text.
Browsing a snapshot collection is an advanced capability that requires ZFS and command-line experience.
All dataset snapshots are accessible as an ordinary hierarchical file system, accessed from a hidden
A snapshot and any files it contains are not accessible or searchable if the snapshot mount path is longer than 88 characters. The data within the snapshot is safe but to make the snapshot accessible again shorten the mount path.
A user with permission to access the hidden file can view and explore all snapshots for a dataset from the Shell or the Sharing screen using services like SMB, NFS, and SFTP.
In summary, the main required changes to settings are:
veto files
command to not hide the zfsacl:expose_snapdir=true
.The effect is that any user who can access the dataset contents can view the list of snapshots by going to the dataset
When creating a snapshot, permissions or ACLs set on files within that snapshot might limit access to the files.
Snapshots are read-only, so users do not have permission to modify a snapshot or its files, even if they had write permissions when creating the snapshot.
The zfs diff
ZFS command, which can run in the Shell, lists all changed files between any two snapshot versions within a dataset, or between any snapshot and the current data.
The Active Directory (AD) service shares resources in a Windows network. AD provides authentication and authorization services for the users in a network. This eliminates the need to recreate the user accounts on TrueNAS.
Domain users and groups in local ACLs are accessible after joining AD. Setting up shares acts as a file server.
Joining an AD domain configures the Privileged Access Manager (PAM). This allows domain users to log on via SSH or authenticate to local services.
It is possible to configure AD services on Windows. Or on Unix-like operating systems running Samba version 4.
To configure a connection, you need to know the following items:
Preparing the following before configuring Active Directory helps ensure the connection process.
To connect to Active Directory, go to Directory Services > Active Directory. Enter the AD Domain Name and account credentials. Select Enable to attempt to join the AD domain immediately after saving the configuration.
The preconfigured defaults are generally suitable. Advanced options are available for fine-tuning the AD configuration. Click ADVANCED OPTIONS to access extra options.
Click REBUILD DIRECTORY SERVICE CACHE to resync the cache if it becomes out of sync. Or if fewer users than expected are available in the permissions editors.
When the import completes, AD users and groups become available. These have basic dataset permissions or an Access Control List (ACL). Enabled is the default status for the TrueNAS cache.
Joining AD adds default Kerberos realms and generates a default AD_MACHINE_ACCOUNT
keytab.
TrueNAS automatically begins using this default keytab. TrueNAS removes any administrator credentials stored in the TrueNAS configuration file.
The recommendation is to use SFTP over FTP. But joined systems do allow FTP access. Keep these caveats in mind:
proftpd
handles ACLs.pam_mkhomedir
) must ensure that these paths exist.Resync the cache if it becomes out of sync. Or if fewer users than expected are available in the permissions editors. Go to Directory Services > Active Directory > REBUILD DIRECTORY SERVICE CACHE.
If you are using Windows Server with 2008 R2 or older, try the following options:
Create a Computer entry on the Windows server Organizational Unit (OU). When creating this entry, enter the TrueNAS host name in the name field. Make sure it is the same name as the one set in the Hostname field in Network > Global Configuration. Must match the NetBIOS alias from Directory Services > Active Directory > Advanced Options.
Lightweight Directory Access Protocol (LDAP) is an open and cross-platform protocol. It is often used to centralize authentication. TrueNAS includes an Open LDAP client for accessing information from an LDAP server. An LDAP server provides directory services for finding network resources. This includes finding users and their associated permissions.
To integrate an LDAP server with TrueNAS, go to Directory Services > LDAP.
Enter any LDAP server host names or IP addresses. Separate entries with an empty space. Entering more than one host name or IP address creates an LDAP failover priority list.
Enter the Base DN.
This is the top level of the LDAP directory tree used when searching for resources.
For example, dc=test,dc=org
.
Enter the Bind DN.
This is the administrative account name on the LDAP server.
For example, cn=Manager,dc=test,dc=org
.
Enter the Bind Password. This is the password associated with the account in Bind DN.
The final basic option is Enable. Clearing the Enable checkbox disables the LDAP configuration without deleting it. Enable it at a later time without reconfiguring the options.
To make further changes to the LDAP configuration, click ADVANCED OPTIONS.
See LDAP Screen for information on basic and advanced option settings.
See Kerberos for more information on using Kerberos.
To configure LDAP certificate-based authentication for the LDAP provider to sign, see Certificate Signing Requests.
Samba 4.13.0 deprecated Samba Schema. Select if SMB shares need LDAP authentication and the LDAP server is already configured with Samba attributes. If selected, specify the type of schema from the Schema dropdown list.
NIS (Network Information Service) is a client–server directory service protocol. It assists in distributing system configuration data between computers on a network. This data can include user and host names.
NIS is limited in scalability and security. For modern networks, LDAP has replaced NIS.
To configure NIS, go to Directory Services > NIS.
Enter the NIS Domain name and list any NIS Servers (host names or IP addresses). Press Enter to separate server entries. Configure the remaining options as needed:
ypbind
to bind to the fastest responding server.Click SAVE to save configuration settings.
Click REBUILD DIRECTORY SERVICE CACHE to resync the cache if it becomes out of sync. Or if fewer users than expected are available in the permissions editors.
Kerberos is a web authentication protocol that uses strong cryptography. It proves the identity of both client and server over an insecure network connection.
Kerberos uses realms and keytabs to authenticate clients and servers. A Kerberos realm is an authorized domain that a Kerberos server can use to authenticate a client. Kerberos keytabs allow systems and clients to join an Active Directory or LDAP. Keytabs make it possible to join without entering a password.
TrueNAS allows configuring both Kerberos realms and keytabs.
Your network must contain a Key Distribution Center (KDC) to add a realm. Users can configure Kerberos realms. Go to Directory Services > Kerberos Realms** and click ADD. By default, TrueNAS creates a Kerberos realm for the local system.
Enter the Realm name and click SUBMIT.
See Kerberos Screens for more information on Kerberos screens and settings.
Kerberos keytabs allow systems and clients to join an Active Directory or LDAP. Keytabs make it possible to join without entering a password. A keytab (key table) is a file that stores encryption keys for various authentication scenarios. With keytabs, the TrueNAS system database benefits from this security feature. It does not store the Active Directory or LDAP administrator account password. This could be a security risk in some environments.
When using a keytab, create and use a less privileged account to perform any required queries. The TrueNAS system database stores the password for that account.
To create the keytab on a Windows Server system, open a command prompt and use the ktpass
command:
ktpass -princ USERNAME@REALM.COM -pass PASSWORD -crypto ENCRYPTION TYPE -ptype KRB5_NT_PRINCIPAL -kvno 0 -out c:\PATH\KEYTABNAME.KEYTAB
where USERNAME@REALM.COM
is the Windows Server user and principal name written in the format username@KERBEROS.REALM
.
The Kerberos realm is typically in all caps, but the Kerberos realm case should match the realm name.
Refer to this note about using /princ
for more details.
PASSWORD
is the Windows Server user password.
ENCRYPTION TYPE
is the cryptographic type you want to use. Setting ENCRYPTION TYPE
to ALL
allows using all supported cryptographic types.
Users can specify each key instead of ALL:
Specifying cryptographic types creates a keytab with enough privileges to grant tickets.
PATH\KEYTABNAME.KEYTAB
is the path where you want to save the keytab and the name you want it to have.
After generating the keytab, add it to the TrueNAS system in Directory Services > Kerberos Keytabs > Add Kerberos Keytab.
To instruct the Active Directory service to use the keytab, go to Directory Services > Active Directory and click Advanced Options. Select the installed keytab using the Kerberos Principal dropdown list.
When using a keytab with Active Directory, username and userpass in the keytab should match the Domain Account Name and Domain Account Password fields in Directory Services > Active Directory.
To instruct LDAP to use a principal from the keytab, go to Directory Services > Active Directory. Click Advanced Options, then select the installed keytab using the Kerberos Principal dropdown list.
File sharing is a core benefit of a NAS. TrueNAS helps foster collaboration between users through network shares.
TrueNAS can use AFP, iSCSI shares, Unix NFS shares, Windows SMB shares, and WebDAV shares.
The Apple Filing Protocol (AFP) is a network protocol that allows file sharing over a network. It is like SMB and NFS, but it is for Apple systems.
Apple began using the SMB sharing protocol as the default option for file sharing in 2013. At that time Apple ceased development of the AFP sharing protocol. The recommendation is to use SMB sharing instead of AFP. AFP sharing is still used if files are being shared with legacy Apple products. Please see https://en.wikipedia.org/wiki/Apple_Filing_Protocol and https://appleinsider.com/articles/13/06/11/apple-shifts-from-afp-file-sharing-to-smb2-in-os-x-109-mavericks
To create a new share, make sure a dataset is available with all the data for sharing.
To configure the new share, go to Sharing > Apple Shares (AFP) and click ADD. Because AFP sharing is deprecated, confirm that you intend to create an AFP share. Next, use the file browser to select a dataset to share and enter a descriptive name for the share in Name.
Select Time Machine if the share is to have Apple Time Machine backups. This advertises the share to other Mac systems as a disk that stores Time Machine backups. Having multiple AFP shares configured for Time Machine backups is not recommended.
Select Use as Home Share to create home directories for users that connect to the share. Only one AFP share can be a home share.
The AFP share is enabled by default. To create the share but not immediately enable it, clear Enabled. Clicking SUBMIT creates the share.
See Sharing AFP screen for more information on screen settings.
To edit an existing AFP share, go to Sharing > Apple Shares (AFP) and click .
To begin advertising the AFP shared location, go to Services. To determine the current state of the AFP service, hover the mouse over the toggle. The toggle turns blue when it is running. Click the AFP toggle to start the service if it is not running, or to stop the service if it is already running. To automatically start the service after TrueNAS boots, select Start Automatically.
If the AFP service is running, stop it before attempting to edit settings.
It is recommended to use the default settings for the AFP service. To adjust the service settings, click the edit icon.
See Adding AFP Service for more information on AFP service settings.
Use an Apple operating system to connect to the share.
Open the Finder app on the Mac and click Go > Connect to Server… in the top menu bar on the Mac.
Enter afp://{IPofTrueNASsystem}
and click Connect.
For example, entering afp://192.168.2.2
connects to the TrueNAS AFP share at 192.168.2.2.
Internet Small Computer Systems Interface (iSCSI) represents standards for using Internet-based protocols for linking binary data storage device aggregations. IBM and Cisco submitted the draft standards in March 2000. Since then, iSCSI has seen widespread adoption into enterprise IT environments.
iSCSI functions through encapsulation. The Open Systems Interconnection Model (OSI) encapsulates SCSI commands and storage data within the session stack. The OSI further encapsulates the session stack within the transport stack, the transport stack within the network stack, and the network stack within the data stack. Transmitting data this way permits block-level access to storage devices over LANs, WANs, and even the Internet itself (although performance may suffer if your data traffic is traversing the Internet).
The table below shows where iSCSI sits in the OSI network stack:
OSI Layer Number | OSI Layer Name | Activity as it relates to iSCSI |
---|---|---|
7 | Application | An application tells the CPU that it needs to write data to non-volatile storage. |
6 | Presentation | OSI creates a SCSI command, SCSI response, or SCSI data payload to hold the application data and communicate it to non-volatile storage. |
5 | Session | Communication between the source and the destination devices begins. This communication establishes when the conversation starts, what it talks about, and when the conversion ends. This entire dialogue represents the session. OSI encapsulates the SCSI command, SCSI response, or SCSI data payload containing the application data within an iSCSI Protocol Data Unit (PDU). |
4 | Transport | OSI encapsulates the iSCSI PDU within a TCP segment. |
3 | Network | OSI encapsulates the TCP segment within an IP packet. |
2 | Data | OSI encapsulates the IP packet within the Ethernet frame. |
1 | Physical | The Ethernet frame transmits as bits (zeros and ones). |
Unlike other sharing protocols on TrueNAS, an iSCSI share allows block sharing and file sharing. Block sharing provides the benefit of block-level access to data on the TrueNAS. iSCSI exports disk devices (zvols on TrueNAS) over a network that other iSCSI clients (initiators) can attach and mount.
There are a few different approaches for configuring and managing iSCSI-shared data:
TrueNAS CORE web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares. This requires creating and populating zvol block devices with data, then setting up the iSCSI Share. TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS SCALE web interface: TrueNAS SCALE offers a similar experience to TrueNAS CORE for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.
TrueNAS EnterpriseTrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores. This is all managed through the vCenter web interface.
For more information on iSCSI shares also see:
To get started, make sure you have created a zvol or a dataset with at least one file to share.
Go to Sharing > Block Shares (iSCSI). You can either set one up manually or use WIZARD to guide you through creation.
On Create or Choose Block Device:
Enter a name for the iSCSI share. It can only contain lowercase alphanumeric characters plus a dot (.), dash (-), or colon (:). We recommend keeping the name short or at most 63 characters.
Choose the Extent Type.
If the Extent Type is Device, select the Zvol to share from the Device menu.
If the Extent Type is File, select the path to the extent and indicate the file size.
Select the type of platform to use for the share. For example, if using the share from an updated Linux OS, choose Modern OS.
Click Next. The Portals screen displays.
Select an existing portal or click Create New to add a portal.
If you create a new portal, you must select a discovery authentication method.
a. Select either CHAP or MUTUAL CHAP in the Discovery Authentication Method field.
b. Select either None or Create New in the Discovery Authentication Group field. Create New displays additional configuration fields. If you select None you can leave Discovery Authentication Group empty.
c. Enter a number in the Group ID field to identify the group.
d. Enter the user name in the User field. This can be the same as the initiator.
e. Enter a password of 12 to 16 characters in the Secret field and again in Secret (Confirm).
f. Select the IP address(es) to use. If adding more than one IP address, click ADD and then select the IP address. Use 0.0.0.0. to listen on all IPv4 or :: to listen on all IPv6 IP addresses.
G. Select the TCP port number to use if different from the default.
H. Click Next to display the Initiator screen.
Enter the initiator information to use. Decide which initiators or networks can use the iSCSI share. Leave the list empty to allow all initiators or networks, or add entries to the list to limit access to those systems. Use the keyboard Enter between each entry. Click Next to display the Confirm Options screen.
Confirm the settings you entered. To change any setting click BACK until you see the screen where you want to make changes.
Click SUBMIT to save the iSCSI block share.
To add or edit an existing iSCSI share, use the seven tab to access the various iSCSI configuration screens.
Configure the share global configuration settings. Click the Target Global Configuration tab.
Configure the portal settings. Click on the Portals tab.
To add a new portal, click ADD and enter the basic and IP address information.
To edit an existing portal, click more_vert next to the portal and select Edit.
Configure the initiator settings (not required). Click on the Initiators Groups tab. Both the Add and Edit forms have the same settings fields.
Use ADD to display the Initiators Add configuration screen. Either leave Allow All Initiators checked or configure your own allowed initiators and authorized networks.
Click the more_vert icon for the initiator group and select Edit to display the Initiator Group Edit configuration screen.
Configure authorized access networks. Click the Authorized Access tab.
Click ADD to add a new authorized access network. Fill out the group, user and peer user information.
Click more_vert next to the authorized access network and select Edit.
Configure targets. Click the Targets tab.
To add a new target, click ADD and enter the basic and iSCSI group information.
To edit an existing target, click more_vert next to it and select Edit.
Configure extents. Click the Extents tab.
To add a new extent, click ADD and enter the basic, type, and compatibility information.
To edit an existing extent, click more_vert next to it and select Edit.
Configure any associated targets. Click on the Associated Targets tab.
To add a new associated target, click ADD and fill out the information.
To edit an existing associated target, click more_vert next to it and select Edit.
To turn on the iSCSI service, go to Services locate iSCSI and click on the toggle. It should display the status Running.
To set it to start automatically when TrueNAS boots up, select the Start Automatically checkbox.
Click on the edit returns to the options in Sharing > iSCSI.
TrueNAS lets users expand Zvol and file-based LUNs to increase the available storage that the iSCSI shares.
To expand a Zvol LUN, go to Storage > Pools and click the more_vert next to the Zvol LUN, then select Edit Zvol.
Enter a new size in the Size for this zvol field, then click SAVE.
To prevent data loss, the web interface does not allow users to reduce the Zvol size. TrueNAS also does not allow users to increase the Zvol size past 80% of the pool size.
To expand a file-based LUN, you need to know the path to the file. To find the path, go to Sharing > Block Shares (iSCSI) and click the Extents tab. Click the more_vert next to the file-based LUN and select Edit.
Highlight and copy the path, then click CANCEL
Go to Shell and input command truncate -s +[size] [path to file]
where [size] is how much space you want to grow the file by, and [path to file] is the file path you copied earlier, then press Enter.
An example of the command could look like this: truncate -s +2g /mnt/Shares/Dataset1/FileLun/FileLUN
Lastly, go back to the extent in Sharing > Block Shares (iSCSI) and make sure the Filesize is set to 0 so that the share uses the actual file size.
Connecting to and using an iSCSI share can differ between operating systems. This article provides instructions for Linux and Windows.
Fibre Channel is a TrueNAS Enterprise feature. Only TrueNAS systems licensed for Fibre Channel have the Fibre Channel Ports added to Sharing > Block Shares (iSCSI) screens.
This procedure uses an example to illustrate each step.
Add a zvol to use for the share.
a. Go to Storage > Pools.
b. Find an existing pool, click and Add zvol to create a new zvol.
Configure these iSCSI tabs in Sharing > Block Shares (iSCSI):
Initiators and Authorized Access screens only apply to iSCSI and can be ignored when configuring Fibre Channel.
a. Portals. Check for the 0.0.0.0:3260 IP and port number. If it doesn’t exist, click Add and add this portal.
b. Targets. Click Add to set up a new target. Enter the values for your uses case in the Target Name, Target Alias, and Portal Group.
Select the Target Mode option from iSCSI, Fibre Channel or Both.
The Initiator Group ID selects which existing initiator group has access to the target.
Options for the Authentication Method are None, CHAP, or Mutual CHAP.
Set Authentication Group Number to either none or an integer. This value represents the number of existing authorized accesses.
The Target Reporting tab provides Fibre Channel port bandwidth graphs.
c. Extents. Click Add to create a new extent.
d. Associated Targets. Click Add to add a new associated target.
Select values for Target and Extent.
The LUN ID is a value between 0 and 1023. Some initiators expect a value below 256. Leave this field blank to automatically assign the next available ID.
Set Fibre Channel Ports.
a. Click chevron_right to expand the option for the port you want to select.
b. Select the Mode as either Initiators or Targets. The Targets dropdown field displays on the right side of the screen.
c. Select the target from the list. A list of **Connected Initiators displays below the Targets dropdown list field.
d. Select the initiator you want to use and then click Save.
Start the iSCSI service. Go to Services and click the iSCSI toggle until the Running status message displays.
N_Port ID Virtualization (NPIV) is a Fibre Channel (FC) feature that allows multiple virtual N_Port IDs to share a single physical N_Port. An N_Port is a port that connects a Fibre Channel device, such as a server or storage array, to a Fibre Channel switch. It is responsible for establishing communication within the Fibre Channel fabric.
NPIV allows creating multiple virtual N_Ports on a single physical N_Port. This means a single physical Fibre Channel port can present multiple unique identities to the fabric, enabling different devices to share the same physical connection while maintaining separate communication channels. With NPIV, each virtual N_Port can have its own World Wide Port Name (WWPN) and can independently participate in the Fibre Channel network. This enhances resource utilization, improves management flexibility, and allows for better support of virtualization technologies. This is particularly useful in virtualized environments where you want to assign unique World Wide Names (WWNs) to each virtual machine, allowing for independent management of them on a storage area network (SAN) or on TrueNAS.
NPIV allows an administrator to use switch zoning to configure each virtual port as if it was a physical port in order to provide access control. This is important in an environment with a mix of Windows systems and virtual machines to prevent automatic or accidental reformatting of targets containing unrecognized file systems. It can also be used to segregate data; for example, to prevent the engineering department from accessing data from the human resources department. Refer to your switch documentation for details on how to configure zoning of virtual ports.
To create virtual ports on the TrueNAS system, go to System > Tunables and click ADD. Enter these options:
input hint.isp.X.vports
, where X is the number of the physical interface.In the example shown:
After creating the tunables and rebooting, the configured number of virtual ports shows on Sharing > Block Shares (iSCSI) > Fibre Channel Ports screen so they can be associated with targets, and they are also advertised to the switch so zoning can be configured on the switch.
After associating a virtual port with a target, add it to the Target tab of Reporting so you can view its bandwidth usage.
The following is a general guide on setting up NPIV with Fibre Channel in a Fibre Channel switch and a host system.
Verify that each virtual machine can see the storage devices it is zoned to access. Use monitoring tools to ensure that the NPIV setup is performing as expected and that there are no bottlenecks or connectivity issues.
Refer to the documentation for your specific hardware and software for any additional configuration steps or troubleshooting tips. By following these steps, you should be able to set up NPIV with Fibre Channel successfully. If you encounter any specific issues, consult the documentation for your hardware and software or reach out to your vendor support for help.
Creating a Network File System (NFS) share on TrueNAS makes a lot of data available for anyone with share access. Depending on the share configuration, it can restrict users to read or write privileges.
NFS treats each dataset as its own file system. When creating the NFS share on the server, the specified dataset is the location that client accesses. If you choose a parent dataset as the NFS file share location, the client cannot access any nested or child datasets beneath the parent.
If you need to create shares that include child datasets, SMB sharing is an option. Note that Windows NFS Client versions currently support only NFSv2 and NFSv3.
Before creating an NFS share, create the dataset you want the share to use for data storage.
It is best practice to use a dataset instead of a full pool for SMB or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
We recommend creating a new dataset with the Share Type set to Generic for the new NFS share.
Go to Sharing > Unix Shares (NFS) and click ADD.
Use the file browser to select the dataset to share. Enter an optional Description to help identify the share. Clicking SUBMIT creates the share. There is the option to select ENABLE SERVICE while creating the share to start the service. With this option selected, the service starts automatically after any reboots.
If you wish to create the share but not immediately enable it, select CANCEL.
See Sharing NFS Screen for more information on NFS share settings.
To edit an existing NFS share, go to Sharing > Unix Shares (NFS) and click more_vert > Edit. The options available are identical to the share creation options.
To begin sharing the data, go to Services and click the NFS toggle. If you want NFS sharing to activate immediately after TrueNAS boots, set Start Automatically.
NFS service settings can be configured by clicking (Configure).
Unless a specific setting is needed, it is recommended to use the default settings for the NFS service. When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a kerberos keytab.
The NFS share connects with various operating systems.
The recommendation is to use a Linux/Unix operating system.
Using a Linux/Unix operating system, download the nfs-common
kernel module.
Do this using the package manager of the installed distribution.
For example, on Ubuntu/Debian, enter sudo apt-get install nfs-common
in the terminal.
After installing the module, connect to an NFS share by entering sudo mount -t nfs {IPaddressOfTrueNASsystem}:{path/to/nfsShare} {localMountPoint}
, where {IPaddressOfTrueNASsystem} is the IP address of the remote TrueNAS system that contains the NFS share, {path/to/nfsShare} is the path to the NFS share on the TrueNAS system, and {localMountPoint} is a local directory on the host system configured for the mounted NFS share.
For example, sudo mount -t nfs 10.239.15.110:/mnt/pool1/photoDataset /mnt
mounts the NFS share photoDataset to the local directory /mnt
.
By default, anyone that connects to the NFS share only has the read permission. To change the default permissions, edit the share. Go to Advanced Options and change the Access settings.
ESXI 6.7 or later is required for read/write functionality with NFSv4 shares.
TrueNAS supports (WebDAV), or Web-based Distributed Authoring and Versioning. WebDAV makes it easy to share a TrueNAS dataset and its contents over the web.
To create a new share, ensure a dataset is available with all the data for sharing.
Go to Sharing > WebDAV Shares and click ADD.
Enter a name for the share in Name and use the file browser to select the dataset to share. Enter an optional description for the share in Description to help identify it. To prevent user accounts from modifying the shared data, select Read Only.
The default selection is Change User & Group Ownership. This changes the existing ownership of all files in the share to the webdav user and group accounts. The default selection simplifies WebDAV share permission. This unexpected change causes the web interface to display a warning:
Clearing the checkbox labeled Change User & Group Ownership prevents the warning from displaying. In that case, you must manually set shared file ownership to the webdav or www user and group accounts.
By default, the new WebDAV share is immediately active. To create the share but not immediately activate it, clear the checkmark in Enable. Click SUBMIT to create the share.
Creating a share immediately opens a dialog to activate the WebDAV service:
It is possible to enable or disable the WebDAV system service later. Go to Services and click the WebDAV toggle to stop the service. To automatically start the service when TrueNAS boots, select Start Automatically. Click the edit to change the service settings.
For data security, select HTTPS as the Protocol. This requires choosing an SSL certificate. The freenas_default certificate is available as an option. All Protocol options require defining a Port number. Verify that the WebDAV service port is not already in use on the network before defining a Port number.
Select either Basic or Digest as the method of HTTP Authentication. Create a new Webdav Password. This prevents unauthorized access to the shared data.
Click SAVE after making any changes.
WebDAV-shared data is accessible from a web browser.
To see the shared data, open a new browser tab and enter the following in the URL field {PROTOCOL}://{TRUENASIP}:{PORT}/{SHARENAME}
where the elements in curly brackets {} are your chosen settings from the WebDAV share and service.
Example: https://10.2.1.1:8081/newdataset
Note: The {SHARENAME}
is the name of the share you created under Sharing > WebDAV Shares and is case-sensitive!
When the Authentication WebDAV service option is configured to either Basic or Digest, the share requires a user name and password. Enter the user name webdav and the password defined in the WebDAV service.
SMB (also known as CIFS) is the native file sharing system in Windows. SMB shares can connect to any major operating system. This includes Windows, MacOS, and Linux.
TrueNAS can use SMB to share files among one or many users or devices. SMB supports a wide range of permissions and security settings. SMB can support advanced permissions (ACLs) on Windows and other systems. SMB also supports Windows Alternate Streams and Extended Metadata. SMB is suitable for the management and administration of large or small pools of data.
TrueNAS uses Samba to provide SMB services. There are many versions of the SMB protocol. During SMB session negotiation, an SMB client attempts to negotiate the highest SMB protocol. Industry-wide, the usage of the SMB1 protocol (sometimes referred to as NT1) is being deprecated for security reasons. However, most SMB clients support SMB 2 or 3 protocols, even when they are not the default protocols.
Legacy SMB clients rely on NetBIOS name resolution to discover SMB servers on a network. The NetBIOS name server (nmbd) is disabled by default in TrueNAS. You can enable it in Network > Global Configuration if this functionality is required.
MacOS clients use mDNS to discover the presence of SMB servers on the network. The mDNS server (avahi) is enabled by default on TrueNAS.
Windows clients use WS-Discovery to discover the presence of SMB servers. Check the version of the Windows client. In some versions of the Windows client, the default settings disable network discovery.
Discoverability through broadcast protocols is a convenience feature. It is not required to access an SMB server.
It is best practice to use a dataset instead of a full pool for SMB or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
For the new SMB share, the recommendation is to create a new dataset and set the Share Type to SMB.
Create the ZFS dataset with these settings:
A default Access Control List is also applied to the dataset. This default ACL is restrictive and only allows access to the dataset owner and group. You can change this ACL later according to your use case.
By default, all new local users are members of a built-in SMB group called builtin users. You can use this group to grant access to all local users on the server. You can use additional groups to fine-tune permissions to large numbers of users. User accounts built-in to TrueNAS cannot access SMB. User accounts that do not have the smb flag set cannot access SMB.
After creating a dataset and the needed accounts, determine the access requirements and adjust the dataset ACL to match. To edit the ACL, go to Storage > Pools, open the options for the new dataset, and click Edit Permissions. Many home users often add a new entry that grants this access: FULL_CONTROL to the builtin_users group with the flags set to INHERIT. See the Permissions article for more details.
To create a Windows SMB share, go to Sharing > Windows Shares (SMB) and click ADD.
The Path and Name of the SMB share define the smallest amount of information required to create a new SMB share. The Path is the directory tree on the local filesystem exported over the SMB protocol. Name is the name of the SMB share. This forms a part of the full share path name when SMB clients perform an SMB tree connect. Name must be less than or equal to 80 characters in length. Name must not contain any invalid characters. Microsoft documentation MS-FSCC section 2.1.6 lists these invalid characters. The last component of the value in Path becomes the share name if Name is blank or empty.
You can set a share Purpose to apply and lock pre-defined advanced options for the share. To keep full control over all the share Advanced Options, choose No presets.
You can specify an optional value in Description to help explain the purpose of the share.
Enabled shares this path when the SMB service is activated. Clearing Enabled disables the share without deleting the configuration.
See SMB Share Screen for more information on SMB Share settings.
Connecting to an SMB share does not work when the related system service is not activated. To make an SMB share available on the network, go to Services and click the SMB toggle to start the service. If you want the service to activate whenever TrueNAS boots, select Start Automatically.
See SMB Service Screen for more information on SMB services settings.
After creating the SMB share, additional management options are available by going to Sharing > Windows Shares (SMB) and clicking for a share entry:
Name | Description |
---|---|
Edit | Opens the share creation screen to reconfigure the share or disable it. |
Edit Share ACL | Opens a screen to configure an Access Control List (ACL) for the share. The default is open. |
Edit Share ACL
Name | Description |
---|---|
Edit Filesystem ACL | Opens a screen to configure an Access Control List (ACL) for the path defined in the share Path. |
Delete | Remove the share configuration from TrueNAS. Shared data is unaffected. |
To see the share ACL options, click more_vert > Edit Share ACL.
>
The Share Name is shown, but cannot be changed. ACL Entries are listed as a block of settings. Click ADD to register a new entry.
Name | Description |
---|---|
SID | Who this ACL entry (ACE) applies to, shown as a Windows Security Identifier. Either a SID or a Domain with Name is required for the ACL. |
Domain | Enter a domain for the user Name. Required when a SID is not entered. Local users have the SMB server NetBIOS name: truenas\smbusers. |
Permission | Dropdown list of predefined permission combinations: Select Read for read access and execute permission on the object (RX). Select Change for read access, execute permission, write access, and delete object (RXWD). Select Full for read access, execute permission, write access, delete object, change Permissions, and take ownership (RXWDPO). For more details, see smbacls(1). |
Name | Enter the name of who this ACL entry applies to, shown as a user name. Requires adding the user Domain. |
Type | Select from the dropdown list how permissions are applied to the share. Select Allowed to deny all permissions by default except those that are manually defined. Select Denied to allow all permissions by default except those that are manually defined. |
Click SAVE to store the share ACL and apply it to the share immediately.
Click more_vert > Edit Filesystem ACL to quickly return to Storage > Pools and edit the dataset ACL.
This ACL defines the user accounts or groups that own or have specific permissions to the shared dataset. The User and Group values show which accounts own, or have full permissions to the dataset. Change the default settings to your preferred primary account and group. Select the Apply checkboxes before saving any changes.
To rewrite the current ACL with a standardized preset, click SELECT AN ACL PRESET and choose an option:
To define permissions for a specific user account or group, click ADD ACL ITEM. Open the Who dropdown list, select User or Group, and select a specific user or group account. Define the settings for the account. Define the permissions to apply to that account. For example, to allow the tmoore user permission to view dataset contents but not make changes, define the ACL Type as Allow. Define Permissions for this user as Read.
TrueNAS offers the Use as Home Share option for organizations or SMEs that want to use a single SMB share to provide a personal directory to every user account.
The Use as Home Share feature is available for a single TrueNAS SMB share. You can create additional SMB shares as described in the SMB sharing article but without the Use as Home Share option enabled.
First, go to Storage > Pools and create a pool.
Next, set up the Active Directory that you want to share resources with over your network.
Go to Storage > Pools and open the more_vert next to the root dataset in the pool you just created, then click Add Dataset.
Name the dataset (this article uses Home_Share_Dataset as an example) and set the Share Type to SMB.
After creating the dataset, go to Storage > Pools and open more_vert next to the new dataset. Select Edit Permissions.
Click the Group dropdown menu and change the owning group to your Active Directory domain admins and check Apply Group.
Click Select an ACL Preset and choose HOME. Then, click SAVE.
Go to Sharing > Windows Shares (SMB) and click ADD.
Set the Path to the prepared dataset (Home_Share_Dataset for example).
The Name automatically changes to be identical to the dataset. Leave this at the default.
Set the Purpose to No presets, then click ADVANCED OPTIONS and check Use as Home Share. Click SUBMIT.
The ACL editor opens, displaying the home ACL preset values.
Click SAVE. Enable the SMB service in Services to make the share available on your network.
Go to Accounts > Users and click ADD. Create a new user name and password. By default, the user **Home Directory is titled from the user account name and added as a new subdirectory of Home_Share_Dataset.
If existing users require access to the home share, go to Accounts > Users and edit an existing account.
Adjust the user home directory to the appropriate dataset and give it a name to create their own directory.
After the user accounts have been added and permissions configured, users can log in to the share and see a folder matching their user name.
Shadow Copies, also known as the Volume Shadow Copy Service (VSS) or Previous Versions, is a Microsoft service for creating volume snapshots. Shadow copies can be used to restore previous versions of files from within Windows Explorer.
By default, all ZFS snapshots for a dataset underlying an SMB share path are presented to SMB clients through the volume shadow copy service or are accessible directly with SMB when the hidden ZFS snapshot directory is located within the path of the SMB share.
There are a few caveats about shadow copies to be aware of before activating the feature in TrueNAS:
When the Windows system is not fully patched to the latest service pack, Shadow Copies might not work. If no previous versions of files to restore are visible, use Windows Update to ensure the system is fully up-to-date.
Shadow copy support only works for ZFS pools or datasets.
Appropriate permissions must be configured on the pool or dataset shared by SMB.
Users cannot use an SMB client to delete shadow copies. Instead, the administrator uses the TrueNAS web interface to remove snapshots.
Shadow copies can be disabled for an SMB share by clearing the checkmark from Enable shadow copies for the SMB share.
This does not prevent access to the hidden
To enable Shadow Copies, go to Sharing > Windows Shares (SMB) and Edit an existing share. Open the Advanced Options, find the Other Options and select Enable Shadow Copies.
The Services screen lists all services available on the TrueNAS.
Activate or configure a service on the Services page.
Use the right slider to scroll down to the bottom of the list of services or click on page 2, or the or arrows.
To locate a service, type in the Filter Search field to narrow down the list of services.
Select Start Automatically for configured services that need to start after the system boots.
Click the toggle to start or stop the service, depending on the current state. Hover the mouse over the toggle to see the current state of that service. The toggle turns blue when it is running.
Click the edit icon to display the settings screen for a service.
Services related to data sharing or automated tasks are documented in their respective Sharing or Tasks.
ISPs often change the IP address of the system. With Dynamic Domain Name Service (DDNS) the current IP address continues to point to a domain name to provide access to TrueNAS.
DDNS requires registration with a DDNS service such as DynDNS before configuring TrueNAS. Open your specific DDNS service settings in another browser tab for reference while configuring TrueNAS. Log in to the TrueNAS web interface and go to Services > Dynamic DNS.
Your DDNS solution provides the required values for these fields. Start the DDNS service after choosing your Provider options and saving the settings.
SSH File Transfer Protocol (SFTP), is available by enabling SSH remote access to the TrueNAS system. SFTP is more secure than standard FTP as it applies SSL encryption on all transfers by default.
Go to Services, find the SSH entry, and click the edit.
Select Allow Password Authentication.
Evaluate Log in as Root with Password for your security environment: SSH with root is a security vulnerability. It allows more than SFTP transfer access. SSH with root also allows full remote control over the NAS with a terminal.
Review the remaining options and configure according to your environment or security needs.
Use the SSH screen to configure the system for SFTP. See ServicesSSH for information on SSH screen settings.
Open FileZilla or another FTP client, or command line.
This example uses FileZilla.
Using FileZilla, enter SFTP://TrueNAS IP
, username
, password
, and port 22
to connect. Where TrueNAS IP
is the IP address for your system, and username
and password
are those you use to connect to the FTP client. Or enter SFTP://'TrueNAS IP'
, 'username'
, 'password'
, and port 22
to connect.
Chroot is not 100% secure, but SFTP does not have chroot locking. The lack of chroot allows users to move up to the root directory. They can view internal system information. If this level of access is a concern, FTP with TLS may be the more secure choice.
Setting up a jail and enabling SSH is another way to allow SFTP access. This does not grant read access to other areas of the NAS itself.
FTP connections cannot share connections with other accounts, such as SMB connections. FTP connections need a new dataset and local user account.
Go to Storage > Pools to add a new dataset.
See Creating Datasets for information on how to create the dataset. After this step is completed, the new dataset appears nested beneath the pool.
Next, go to Accounts > Users > Add to create a local user on the TrueNAS.
Assign a user name and password. Link the new dataset for the FTP share as the home directory of the user. Link the new dataset for the FTP share on a per user basis, or create a global account for FTP. Example: OurOrgFTPacnt, etc.
Return to Storage > Pools, find the new dataset, and click more_vert> Edit Permissions. In the Owner fields, select the new user account as the User and Group from the dropdown list. Be sure to select Apply User and Apply Group before saving.
To configure FTP, go to the Services page, find the FTP entry, and click the edit.
Configure the options according to your environment and security considerations. See FTP Screen
Enable chroot to help confine FTP sessions to a local user home directory and allow Local User Login.
Unless necessary, do not allow anonymous or root access. For better security, enable TLS when possible. This is effectively FTPS. Enable TLS when FTP involves a WAN.
Use a browser or FTP client to connect to the TrueNAS FTP share. The images here show using FileZilla, a free option.
The user name and password are those of the local user account on the TrueNAS.
The default directory is the same as the user
Rsync is an open source cross-platform file transfer and synchronization utility. It is a fast and secure way to copy data to another system for backup or to migrate data to a new system. Use the default settings unless you require a specific change. Don’t forget to click SAVE after changing any settings.
Log in to the TrueNAS web interface and go to Services > Rsync. Click the
icon to edit the Rsync settings.Enter the TCP Port you want Rsync to listen on, then enter any rsyncd.conf(5) Auxiliary Parameters.
TrueNAS lists all created modules here.
Use this Rsync Modules list to EDIT or DELETE a module. Click to select a module to edit.
To create a new module, click ADD.
Name the module and select a Path to store it in. Select an Access Mode and fill out the rest of the fields to your needs.
When a Hosts Allow list is defined, only the IPs and hostnames on the list are able to connect to the module.
Network devices use the Link Layer Discovery Protocol (LLDP) to advertise their identity, capabilities, and neighbors on an Ethernet network. TrueNAS uses the ladvd LLDP implementation. LLDP service is often used in a local network environment with managed switches. Configuring and starting the LLDP service allows the TrueNAS system to advertise itself on the network.
To configure LLDP, go to the Services page, find the LLDP entry, and click the edit icon.
Select Interface Description and enter a Country Code. The location of the system is optional.
Click SAVE to save the current selections and return to the Services screen.
Click the toggle on the Services screen to turn the LLDP service on. The toggle turns blue when it is running.
A virtual private network (VPN) is an extension of a private network over public resources. It allows remote clients on a public network to access a private network via a secure connection. TrueNAS provides OpenVPN as a system level service that provides VPN server or client functionality. TrueNAS uses a single TCP or UDP port to act as a primary VPN server. This allows remote clients access to data stored on the system. VPN integration is possible even if the system is in a separate physical location, or only has access to public networks.
Public key infrastructure (PKI) must be in place before configuring TrueNAS as either an OpenVPN server or client. PKI utilizes certificates and certificate authorities created in or imported to TrueNAS.
The general process to configure OpenVPN (server or client) on TrueNAS is to:
Go to the Services page and find the OpenVPN Client entry. Click the edit to configure the service.
Choose the certificate to use as an OpenVPN client. This certificate must exist in TrueNAS and be in an active (unrevoked) state.
Enter the host name or IP address of the Remote OpenVPN server.
Select any other connection settings that fit with your network environment. Check for performance requirements. The Device Type must match with the OpenVPN server Device Type. Nobind prevents using a fixed port for the client. Enabled by default, it allows the OpenVPN client and server to run at the same time.
Review the Security Options and select settings that meet your network security requirements. Determine if the OpenVPN server is using TLS Encryption. If so, copy the static TLS encryption key and paste into the TLS Crypt Auth field.
Go to the Services page and find the OpenVPN Server entry. Click the edit to configure the service.
Choose a Server Certificate for this OpenVPN server. This certificate must exist in TrueNAS and be in an active (unrevoked) state.
Define a IP address and netmask for the OpenVPN. Enter these values in Server. Continue to select the remaining Connection Settings that fit with your network environment and performance requirements. When selecting TUN in Device Type, you can select a virtual addressing method for the server in Topology. Options are:
The Topology selection is automatically applied to any connected clients.
When TLS Crypt Auth Enabled is selected, TrueNAS generates a static key for the TLS Crypt Auth field after saving the options. To change this key, click RENEW STATIC KEY. Any clients connecting to the server need this key. Keys stored in the system database are included in a generated client config file. A good practice is to back up keys in a secure location.
Review the Security Options and choose settings that meet your network security requirements.
Configure and save your OpenVPN server settings.
OpenVPN client systems that are connecting to this server will need to import client configuration files. To generate client configuration files, you need the client certificate from the client system. The client certificate was previously imported to the client system. Click DOWNLOAD CLIENT CONFIG and select the Client Certificate.
See OpenVPN Screens for more information on the client and server settings.
Connecting to a private network still sends data over less secure public resources. OpenVPN includes several security features that are optional. These optional security features help protect the data sent into or out of the private network.
When finished configuring the server or client service, click SAVE. Start the service by clicking the related toggle in Services. To check the current state of the service, hover over the toggle.
Start Automatically: Selecting this option starts the OpenVPN service whenever TrueNAS completes booting. The network and data pools must be running.
S.M.A.R.T. Self-Monitoring, Analysis and Reporting Technology (SMART) is an industry standard. It performs disk monitoring and testing. Several different kinds of self-tests check disks for problems.
Click the edit in Services > S.M.A.R.T. to configure the service.
General Options
Name | Description |
---|---|
Check Interval | Enter number of minutes to determine how often the smartd daemon monitors for configured tests to be run. |
Power Mode | Select from dropdown list: Never, Sleep, Standby or Idle. Tests only run with Never. |
Difference | Enter in degrees Celsius. S.M.A.R.T. sends alerts if the temperature of a drive changes by N degrees Celsius since the last report. |
Informational | Enter in degrees Celsius. S.M.A.R.T. sends messages with a log level of LOG_INFO if the temperature exceeds the threshold. |
Critical | Enter in degrees Celsius. S.M.A.R.T. sends messages with a log level of LOG_CRIT if the temperature exceeds the threshold. |
Click SAVE when finished configuring the server or client service. Start the service by clicking the related toggle in Services. To check the current state of the service, hover over the toggle.
Selecting Start Automatically starts the service whenever TrueNAS completes booting. The network and data pools must be running.
Due to security vulnerabilities and maintainability issues, the S3 service is deprecated in TrueNAS 13.0 and removed in TrueNAS 22.12 and newer versions. Beginning in CORE 13.0-U6, the CORE web interface generates an alert when the deprecated service is either actively running or is enabled to start on boot.
TrueNAS EnterpriseBeginning in CORE 13.0-U6, Enterprise customers with the S3 service running or enabled are prevented from upgrading to the next major version.
Please contact iX Support to review options for migrating to a TrueNAS release that has Minio applications available.
Due to security vulnerabilities and maintainability issues, the S3 service is deprecated in TrueNAS 13.0 and removed in TrueNAS 22.12 and newer versions. Beginning in CORE 13.0-U6, the CORE web interface generates an alert when the deprecated service is either actively running or is enabled to start on boot.
TrueNAS EnterpriseBeginning in CORE 13.0-U6, Enterprise customers with the S3 service running or enabled are prevented from upgrading to the next major version.
Please contact iX Support to review options for migrating to a TrueNAS release that has Minio applications available.
SNMP (Simple Network Management Protocol) monitors network-attached devices for conditions that warrant administrative attention. TrueNAS uses Net-SNMP to provide SNMP. To configure SNMP, go to the Services page, find the SNMP entry, and click the edit.
See SNMP screen for information on settings.
After starting the SNMP service, port UDP 161 listens for SNMP requests.
Locate available Management Information Bases (MIBs). Go to ls /usr/local/share/snmp/mibs
.
Here is a sample of the directory contents:
The SSH service allows connections to TrueNAS with the Secure Shell Transport Layer Protocol. To use TrueNAS as an SSH server, the users in the network must use SSH client software to transfer files with SSH.
Allowing external connections to TrueNAS is a security vulnerability! Only enable SSH when there is a need for external connections. See Security Recommendations for more security considerations when using SSH.
To configure SSH, disable the service and click the edit.
Configure the options as needed to match your network environment.
See SSH Screen
Root access to the system from a remote client is never recommended. If an unavoidable critical situation requires allowing root access, it is recommended to configure two-factor authentication first. Also, disable root logins as soon as possible.
There are some additional option recommendations for the SSH service:
Re-enable the SSH service on the Services page when all configuration changes are complete. To create and store specific SSH connections and keypairs, go to the System menu section.
The Trivial File Transfer Protocol (TFTP) is a light-weight version of FTP . It is often used in a local environment. It can transfer configuration or boot files between machines, such as routers. TFTP offers a very limited set of commands and provides no authentication.
Determine the usage requirements for the TrueNAS system. If they are minimal, configure TFTP. For example, if the TrueNAS system is only used for storing images. Or if it is only used to store configuration files for network devices.
If the system has minimal usage requirements, start the service. Starting the TFTP service opens UDP port 69.
Use the TFTP screen to configure the system for SFTP.
TrueNAS uses NUT (Network UPS Tools) to provide UPS support. Connect the TrueNAS system to the UPS device. Configure the UPS service by going to Services, finding the UPS entry, and clicking edit icon.
TrueNAS EnterpriseTrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).
See UPS Screen for more information on UPS settings.
Some UPS models can be unresponsive with the default polling frequency.
This shows in TrueNAS logs as a recurring error like libusb_get_interrupt: Unknown error
.
The default polling frequency is two seconds. Decrease the polling frequency by adding an entry to Auxiliary Parameters (ups.conf): pollinterval = 10
. This should resolve the error.
upsc(8) can get status variables like the current charge and input voltage from the UPS daemon.
Run this command from the Shell using the syntax upsc ups@localhost
.
The upsc(8) manual page has other usage examples.
If the hardware supports sending the command, upscmd(8) can send commands directly to the UPS. Only users with administrative rights can administer these commands. Create these users in the Extra Users field.
The File Transfer Protocol (FTP) is a simple option for data transfers. The additional SSH options provide secure config file transfer methods. Trivial FTP options provide only simple config file transfer methods.
Options for configuring FTP, SSH, and TFTP are in the system Services. Click the edit to configure the related service.
Following the upstream FreeBSD 13.2 end-of-life, announced July 1, 2024, virtualization features (plugins, jails, and virtual machines) in TrueNAS 13.0 are now obsolete.
Enterprise users or community users with a critical need to use containers or virtualization solutions in production should migrate to the tested and supported virtualization features available in TrueNAS SCALE. TrueNAS Enterprise customers can contact iXsystems to schedule a TrueNAS 24.04 or newer deployment. See CORE to SCALE Migrations for more information.
TrueNAS CORE has an integrated update system to make it easy to keep up to date.
We recommend performing updates when the TrueNAS system is idle, with no clients connected and no scrubs or other disk activity happening. Most updates require a system reboot. Plan updates around scheduled maintenance times to avoid disrupting user activities.
The update process does not proceed unless there is enough free space in the boot pool for the new update files. If a space warning displays, go to System > Boot to remove unneeded boot environments.
The system checks daily for updates and downloads an update if one is available. An alert is issued when a new update becomes available. The automatic check and download of updates are disabled by unsetting Check for Updates Daily and Download if Available. Click (Refresh) to perform another check for updates. To change the train, use the drop-down menu to make a different selection.
The train selector does not allow downgrades. For example, you cannot select the STABLE train while booted into a Nightly boot environment or a 9.10 train while booted into an 11 boot environment. To go back to an earlier version after testing or running a more recent version, reboot and select a boot environment for that earlier version.
Information about the update displays with a link to the release notes. Alwys read the release notes before updating to determine if any of the changes in that release impact system use.
A dialog to save the system configuration file appears before installing updates.
Keep the system configuration file secure after saving it. The security information in the configuration file can grant unauthorized access to your TrueNAS system.
Ensure the system is in a low-usage state as described above in Preparing for Updates. Click DOWNLOAD UPDATES to download and install an update.
The Save Configuration dialog appears so you can save the current configuration to external media.
A confirmation window appears before installing the update. If you set Apply updates and reboot system after downloading, clicking CONTINUE downloads and applies the update, then reboots the system. The update can be downloaded for a later manual installation by unsetting Apply updates and reboot system after downloading.
APPLY PENDING UPDATE displays when an update is downloaded and ready to install. Setting Confirm and clicking CONTINUE updates and reboots the system.
Each update creates a boot environment. If the update process needs more space, it attempts to remove old boot environments. TrueNAS does not remove boot environments marked with the Keep attribute as shown in System > Boot. The upgrade fails if your system does not have space for a new boot environment. Space on the operating system device can be manually freed by going to System > Boot and removing the Keep attribute or deleting any boot environments that are no longer needed.
You can manually download and apply updates in System > Update.
You cannot use manual updates to upgrade from older major versions.
Go to https://download.freenas.org/ and find an update file of the desired version.
Manual update file names end with
Download the desired update file to your local system. Log in to the TrueNAS web interface and go to System > Update. Click INSTALL MANUAL UPDATE FILE.
The Save Configuration dialog opens. You can save a copy of the current configuration to external media for backup in case of an update problem.
After the dialog closes, the manual update screen displays.
The current version of TrueNAS displays for verification.
Select the manual update file saved to your local system using Browse. Set Reboot After Update to reboot the system after the update installs. Click APPLY UPDATE to begin the update.
Update in Progress
Starting an update shows a progress dialog. When an update is in progress, the web interface shows an animated system_update_alt icon in the top row. Dialogs also appear in every active web interface session to warn that a system update is in progress. Do not interrupt a system update.
TrueNAS EnterpriseThis is Enterprise content that specifically applies to High Availability (HA) systems with a TrueNAS Enterprise license active.
Updating a TrueNAS Enterprise system configured for High Availability (HA) has a slightly different flow from non-HA systems or TrueNAS Core. The system downloads the update to both controllers, updates and reboots the standby TrueNAS controller, and finally fails over from and updates the active TrueNAS controller.
An update usually takes between thirty minutes and an hour. The system must reboot after the update, so it is recommended to schedule updates during a maintenance window, allowing two to three hours to update, test, and possibly roll back if issues appear. On large systems, we recommend a proportionally longer maintenance window.
For individual support during an upgrade, please contact iXsystems Support to schedule your upgrade.
Scheduling at least two days ahead of a planned upgrade gives time to ensure a specialist is available for assistance. Updating from earlier than version 9.3 of TrueNAS must be scheduled with iXsystems Support.The update process will not proceed unless there is enough free space in the boot pool for the new update files. If a space warning displays, go to System > Boot and remove any unneeded boot environments.
Operating system updates only modify the OS devices and do not affect end-user data on storage drives.
An update could involve upgrading the version of ZFS installed on the storage drives. When a ZFS version upgrade is available, an notifications Alert appears in the web interface. We do not recommend upgrading the ZFS version on storage drives until you verify that you do not need to roll back to previous operating system versions or swap the storage drives with another system with an earlier ZFS version. After a ZFS version upgrade, the storage devices are not accessible by earlier TrueNAS versions.
In the web interface Dashboard, find the entry for the active TrueNAS controller and click CHECK FOR UPDATES. This button changes to UPDATES AVAILABLE when there is an available update.
Clicking the button goes to System > Update and shows the option to Download Updates or, when the system has detected and staged an update, Apply Pending Update.
When you click Download Updates or Apply Pending Update, TrueNAS gives an opportunity to save the current system configuration. We recommend backing up the system configuration before starting the update. Including the Password Secret Seed in the system configuration removes the encryption from sensitive system data, like stored passwords. When enabling this option, take extra precautions to store the downloaded system configuration file in a secure location.
After downloading the system configuration, you can continue the system update. While updating and rebooting controllers, HA and other system services are briefly unavailable.
Other users logged in to the web interface see a warning dialog. A System Updating icon displays in the top bar of the web interface while the update is in progress.
Update progress displays for both TrueNAS controllers. The standby TrueNAS controller reboots when it finishes updating. This can take several minutes. When the standby controller finishes booting, the system must fail over to update and reboot the active TrueNAS controller.
To deactivate the active TrueNAS controller and finish the update, go to the Dashboard, find the entry for the Standby controller, and click INITIATE FAILOVER.
The failover briefly interrupts TrueNAS services and availability. The browser logs out of the web interface while the active TrueNAS controller deactivates and the standby TrueNAS controller is brought online. The web interface login screen reappears when the standby TrueNAS controller finishes activating.
Log in to the web interface and check the cloud HA status in the top toolbar. This icon shows that HA is unavailable while the previously active TrueNAS controller reboots. When HA is available, a dialog asks to finish the update. Click CONTINUE to finish updating the previously active TrueNAS controller.
Verify that the update is complete by going to the Dashboard and confirming that the Version is the same on both TrueNAS controllers.
TrueNAS provides flexibility for keeping the operating system up-to-date:
The upgrade instructions instructions describe how to use an
The upgrade path for major versions of FreeNAS/TrueNAS is 9.3 > 9.10 > 11.1 > 11.3 > 12.0. We always recommend upgrading to a supported version of the software.
Be aware of these caveats before attempting a major version upgrade:
ZFS
after the upgrade, then restore the backup.
If the data resides on a UFS RAID of disks, you cannot directly import that data to the ZFS pool.
Instead, back up the data before the upgrade, create a ZFS pool after upgrading, then restore the data from the backup.Before upgrading the operating system, follow these steps:
All auxiliary parameters are subject to change between major versions of TrueNAS due to security and development issues. We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading.
To upgrade TrueNAS using an
Burn the downloaded
Insert the prepared media into the system and boot from it.
The installer waits ten seconds in the installer boot menu before booting the default option.
If needed, press Spacebar to stop the timer and choose another boot option.
After the media finishes booting into the installation menu, press Enter to select the default option 1 Install/Upgrade
.
The installer presents a screen showing all available drives.
All drives display, including boot drives and storage drives. Only choose boot drives when upgrading. Choosing the wrong drives to upgrade or install causes data loss. If you are unsure which drives contain the TrueNAS operating system, reboot and remove the install media. Log in to the TrueNAS web interface and go to System > Boot > ACTIONS > Boot Pool Status to identify the boot drives. More than one drive displays when using a mirror.
Highlight the drive where TrueNAS is installed and press Spacebar to mark it with a star. If using a mirror for the operating system, mark all the drives where the TrueNAS operating system is installed. Press Enter when done.
The installer recognizes earlier versions of FreeNAS/TrueNAS installed on the boot drives and asks to either upgrade or do a fresh install:
To perform an upgrade, press Enter to accept the default Upgrade Install. The installer displays another reminder that you should install the operating system on a disk you are not using for storage.
You can install the updated system in a new boot environment or format the entire operating system device to start fresh. Installing into a new boot environment preserves the old code, allowing a roll-back to previous versions if necessary. Formatting the boot device is usually not necessary but can reclaim space. TrueNAS preserves user data and settings when installing in a new boot environment and formatting the operating system device. Move the highlight to one of the options and press Enter to start the upgrade.
The installer unpacks the new image and checks for upgrades to the existing database file. The database file that is preserved and migrated contains your TrueNAS configuration settings.
Press Enter.
TrueNAS indicates that the upgrade is complete and a reboot is required.
Press OK, highlight 3 Reboot System
, then press Enter to reboot the system.
If the upgrade installer was booted from CD, remove the CD.
During reboot, the previous configuration database can convert to the new version.
The conversion happens during the reboot Applying database schema changes
line.
The conversion can take a long time to finish, sometimes fifteen minutes or more, and can cause the system to reboot again.
The system boots normally afterwards.
If database errors display but the web interface is accessible, log in, go to System > General, and use the UPLOAD CONFIG button to upload the configuration backup you downloaded before starting the upgrade.
There are a few adjustable interface preferences. Also included is a built-in theme editor for creating your own TrueNAS color schemes.
To access user preferences, click settings > Preferences. This page has options to adjust global settings in the web interface. There are also options to manage custom themes and create new themes.
Click the Choose Theme dropdown list to change the color appearance of the web interface. Select from a range of prebuilt or custom created themes. The High Contrast option offers the most visibility.
Select Prefer buttons with icons only when working with limited screen space. This displays icons and tooltips without text labels.
For increased security, clear the Enable Password Toggle checkbox. This removes all the visibility icons next to password fields. It prevents the actual password characters from being visible.
To create a custom theme, click CREATE NEW THEME.