Managing the System Configuration

TrueNAS allows users to manage the system configuration by uploading or downloading configurations or by resetting the system to the default configuration.

The Manage Configuration option on the System > Advanced Settings screen provides three options:

• Download File that downloads your system configuration settings to a file on your system.
• Upload File that allows you to upload a replacement configuration file.
• Reset to Defaults resets system configuration settings back to factory settings.

The Download File option downloads your TrueNAS current configuration to the local machine.

A system config file is a database file containing your settings, including accounts, directory services, networking, services, shares, storage configuration, system settings, data protection tasks, and more.

In TrueNAS 25.04 (and later), users must log in as a system administrator with full administrative access to upload or download a system configuration file. Other users, including restricted admin accounts such as a shares administrator, cannot perform database operations. See Using Administrator Logins for more information on admin account types.

When downloading the configuration (config) file, select the Export Password Secret Seed option to include the secret seed in the config file. Downloading the config file allows you to restore the system to a different operating system device where the secret seed is not already present.

Why should I save the secret seed?

The secret seed is the key TrueNAS uses to decrypt encrypted fields in the configuration database. TrueNAS encrypts these fields because they can contain sensitive information such as cryptographic certificates, service passwords, or weak hashing algorithms (for example, the NT hashes of SMB users).

When you restore a configuration file that does not include the secret seed, TrueNAS generates a new seed and cannot read the encrypted fields. Services that rely on those fields stop working. Examples are SMB access for local user accounts and apps. Always select the Export Password Secret Seed option when you download the system config file.

What happens if I do not save the secret seed?

You can still log into the web UI with your existing password. TrueNAS stores login passwords and API keys as one-way hashes rather than encrypted values, so a missing secret seed does not affect them.

TrueNAS disables SMB authentication for all local user accounts. To restore SMB access for an account, go to Credentials > Users, edit the user, and set a new password. TrueNAS requires a new password before it re-enables SMB authentication for that account.

TrueNAS deletes some encrypted items entirely, such as cloud credentials, SSH keychain credentials, and Kerberos keytabs. It empties the values of others, such as SED passwords, certificate private keys, and service passwords. Reconfigure these settings after you log in.

After you log in, recheck all system settings to verify the configurations are correct. Then test the system to verify it works as desired. When the system operates per the desired configuration, download and save the system configuration with the secret seed option selected, and keep it in a secure location.

Always save the secret seed with the system configuration file after you change the system configuration. This gives you a current backup copy to use if you need it.

Physically secure the config file with the secret seed, and any encryption key files to decrypt encrypted datasets or pools.

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

To download the configuration file:

Go to System > Advanced Settings and click on Manage Configuration. Select Download File.

The Save Configuration dialog opens.

Select Export Password Secret Seed and then click Save. The system downloads the system configuration. Keep this file in a safe location on your network where files are regularly backed up.

A downloaded configuration file always contains the full settings database. The Export Password Secret Seed option determines whether TrueNAS can restore the sensitive, encrypted fields in that database.

The secret seed (the pwenc_secret file) is the key TrueNAS uses to decrypt protected fields in the configuration database. When you restore a configuration file that does not include the secret seed, TrueNAS generates a new seed and cannot read those fields. It handles the affected settings in two ways:

• TrueNAS deletes some items entirely, such as cloud credentials, SSH keychain credentials, Kerberos keytabs, and any replication or rsync task that uses an SSH connection.
• It empties the values of others, such as SED passwords, certificate private keys, iSCSI CHAP secrets, two-factor authentication (2FA) secrets, and service passwords. The item remains, but the sensitive value it needs is blank.

TrueNAS also disables SMB authentication for all local user accounts.

In this table, Yes means the item is present and usable after a restore. TrueNAS does not store items marked Never in the configuration file, so back them up separately.

TrueNAS stores login passwords and API keys as one-way hashes rather than encrypted values, so it restores them correctly with or without the secret seed.

Only you know ZFS passphrases, and TrueNAS never writes them to the configuration file. The BMC hardware stores the IPMI/BMC password, not TrueNAS.

When you configure KMIP, the KMIP server holds SED keys and ZFS key-type encryption keys, and the configuration file does not contain them.

Always back up encryption key files and passphrases separately in a secure location.

The Upload File option gives users the ability to replace the current system configuration with any previously saved TrueNAS configuration file.

Upload a configuration file that includes the secret seed whenever possible. For details on what TrueNAS preserves with and without the seed, see Configuration Backup Contents.

Uploading a configuration file from a FreeBSD-based release wipes any existing administrative users and replaces with the original root user and password from the uploaded configuration file. To secure the system after restoring from a FreeBSD-based TrueNAS config file, log in with the original root user credentials, recreate an administrative account, and finally re-disable the root account password.

TrueNAS Enterprise

Enterprise High Availability (HA) systems should never reset their system configuration to defaults. Contact TrueNAS Enterprise Support if a system configuration reset is required.

TrueNAS Enterprise Support

Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.

TrueNAS Customer Support
Support Portal	https://support.ixsystems.com
Email	support@ixsystems.com
Telephone and Other Resources	https://www.ixsystems.com/support/

Save the current system configuration with the Download File option before resetting the configuration to default settings! If you do not save the system configuration before resetting it, you could lose data that was not backed up, and you cannot revert to the previous configuration.

The Reset to Defaults option resets the system configuration to factory settings. After the configuration resets, the system restarts, and users must set a new login password.

TrueCommand provides an easy solution for users who want to schedule an automatic remote backup of the system configuration file:

1. Set up TrueCommand.
2. Add their TrueNAS system.
3. Create and schedule the configuration file backup.