TrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Preparing to Migrate

13 minute read.

Last Modified 2024-03-21 15:56 EDT

Migrating TrueNAS from CORE to SCALE is a one-way operation. Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-U6.1 (or later) release before attempting to migrate from CORE to SCALE.

What can or cannot migrate?

Although TrueNAS attempts to keep most of your CORE configuration data when upgrading to SCALE, some CORE-specific items do not transfer. These are the items that don’t migrate from CORE:

Microsoft OneDrive Cloud Sync credentials and tasks. OneDrive compatibility is not available in TrueNAS SCALE.
FreeBSD GELI encryption. If you have GELI-encrypted pools on your system that you plan to import into SCALE, you must migrate your data from the GELI pool to a non-GELI encrypted pool before migrating to SCALE.
Malformed certificates. TrueNAS SCALE validates the system certificates when a CORE system migrates to SCALE. When a malformed certificate is found, SCALE generates a new self-signed certificate to ensure system accessibility.
CORE plugins and jails. Save the configuration information for your plugin and back up any stored data. After completing the SCALE install, add the equivalent SCALE application using the Apps option. If your CORE plugin is not listed as an available application in SCALE, use the Launch Docker Image option to add it as an application and import data from the backup into a new SCALE dataset for the application.
NIS data.
System tunables.
ZFS boot environments.
AFP shares also do not transfer, but migrate into an SMB share with AFP compatibility enabled.
CORE netcli utility. A new CLI utility is used for the Console Setup Menu and other commands issued in a CLI. By default, any TrueNAS user account with netcli as the chosen Shell updates to use the nologin option instead. See the Users Screens reference article for descriptions of all Shell options.
SAS multipath is not supported in TrueNAS SCALE.
TrueNAS CORE account names beginning with a number are not supported in TrueNAS SCALE. Usernames in SCALE must begin with a letter or an underscore. Before attempting a CORE to SCALE migration, review the local user accounts and rename or replace any accounts that begin with a numeric character (0-9).

VM storage and its basic configuration transfer over during a migration, but you need to double-check the VM configuration and the network interface settings specifically before starting the VM.

Init/shutdown scripts transfer, but can break. Review them before use.

Preparing for Migration

Read this article before you attempt to migrate your CORE system to a SCALE major version.

We strongly recommend not using USB flash drives or USB-attached drives for backups as these can have issues, including with recovering backed up files. For more information on using USB drives and devices in general, read the CORE Hardware Guide. If you must use a USB type device, verify you can access files on the device before you upgrade/migrate to SCALE.

TrueNAS Enterprise
CORE Enterprise customers are encouraged to contact Support for assistance with the process of moving from CORE to SCALE, especially customers with HA systems.

Upgrade your CORE system to the most recent publicly-available CORE major maintenace release version. TrueNAS systems on 12.0x or earlier should upgrade to the latest CORE 13.0 release (e.g 13.0-U6.1 or newer) prior to migrating to SCALE. CORE systems at the latest 13.0 release can use the iso upgrade method to migrate to SCALE.
Migrate GELI-encrypted pools to a non-GELI-encrypted pool before upgrading from CORE 12.0x or earlier releases!
Verify the root user is not locked. Go to Accounts > Users, select the root user and click Edit to view current settings and confirm Lock User is not selected.
Write down, copy, or take screenshots of settings to use in the event of a post-upgrade/migration issue or to duplicate in SCALE. Use the checklist below to guide you through this step:
System dataset - Identify your system dataset. If you want to use the same dataset for the system dataset in SCALE, note the pool and system dataset. When you set up the first required pool on SCALE import this pool first.
Deprecated services - Record the settings for services deprecated in SCALE.
VMs - If you have virtual machines configured in CORE, write down or screenshot network and other setting information.
Plugins or jails - Plugins and jails do not migrate. Record settings for each plugin/jail and back up the data associated with each.
CAs, certificates, CSRs - If you added certificate authorities, certificates, or certificate signing requests to CORE, they should migrate with the system config file, but as a precaution against possible malformed certificates copy private and public certificate keys and save each, then copy or screenshot all CA, certificate, and CSR setting. Make sure you have backed-up copies of certificates used in CORE to import or configure in SCALE.
Usernames beginning with (0-9) - Review local user account names and rename or replace these with a letter or underscore before migrating.
Tunables on CORE - SCALE does not use Tunables the way CORE does. SCALE allows adding script configurations on the System Settings > Advanced screen, using the Sysctl widget.
Init/shutdown scripts - If using init/shutdown scripts in CORE, copy them or take a screenshot to add them to SCALE.
Cron jobs - If configured in CORE, copy or use screenshots of cron job scripts if you want to add the same jobs in SCALE.
Global self-encrypting drive (SED) Password - Unlock these drives in CORE before you clean install SCALE. Write down the SED password configured in CORE to use in SCALE.
Credentials - Copy or write down the credentials for SSH connections and keypairs, and any cloud service backup providers configured in CORE if you do not have the credential settings saved in other files kept secured outside of CORE.
Data protection tasks - Write down or take screenshots of replication, periodic snapshot, cloud sync, or other task settings to reconfigure these in SCALE if you want to duplicate these tasks.
Write down or take screenshots of your network configuration information. Capture the global network settings, interfaces (LAGG, VLAN, bridge settings), static IP addresses, and aliases.
FreeBSD and Linux use different nomenclature for network interfaces, bridges, LAGGs, and VLANs. Because of the difference, network settings can either get lost or not transfer which means you have no network connectivity. You can find interface names in the CORE UI on the Network > Interfaces screen.
When using a TrueNAS Enterprise system from iXsystems, refer to the network port ID manuals of your TrueNAS Systems to find the network port assignments in TrueNAS SCALE. When using custom hardware for TrueNAS, refer to the manual or documentation provided with your system or locate this information on your server hardware and take note of it.
If there are issues after a clean install of SCALE from an iso file or you are not using DHCP for network and interface configuration, use the information from your CORE settings to configure your SCALE network settings and to reconfigure your static IPs or aliases.
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address, or you can assign a static IP address. You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
- DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed.
- DNS name sever IP addresses in your network (SCALE can accommodate up to three name server IP addresses).
- IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network.
- Main domain name or the domain name for the portion of your network where the TrueNAS SCALE server is deployed.
- Host name you want to use if not using the default-assigned host name in SCALE (truenas is the default host name in SCALE).
- IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP).
- IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.
Migrate the deprecated S3 MinIO service (if in use). See services deprecated in SCALE. This is a lenthy process depending on the amount of data stored while using the S3 service. Read and follow instructions in Migrating from MinIO S3! Make sure S3 MinIO data is backed up as a precaution. The migrating from the S3 service requires installing SCALE 22.12.3 (Bluefin). This version of SCALE provides access to both the S3 service and the MinIO app you migrate to.
If you need to do a clean install with the SCALE iso file, you can import your data pools into SCALE. Verify you can access your backed up files before you upgrade/migrate to SCALE.
Back up any critical data.
Download your system configuration file and a debug file. After updating to the latest publicly-available release of CORE and making any changes to CORE user accounts or any other settings download these files and keep them in a safe place and where you can access them if you need to revert to CORE with a clean install using the CORE iso file.

After completing the steps that apply to your CORE system listed above, download the SCALE ISO file and save it to your computer. Burn the iso to a USB drive (see Installing on Physical Hardware in Installing SCALE) when upgrading a physical system.

Deprecated Services in SCALE

The built-in services listed in this section are available in CORE, but deprecated in SCALE 22.12.3 (Bluefin) and removed in later SCALE releases. They require attention before attempting to migrate to SCALE.

Each of the sections has information that can help you determine the best steps forward to secure any critical data before attempting to migrate from CORE to SCALE. They provide details on transitioning from that service to an application with the functionality of the deprecated service.

TrueNAS SCALE has apps you can deploy as replacements for these services. SCALE 24.04 provides the option to force an upgrade without converting deprecated services to apps. The force option is not recommended for the S3 service as forcing the upgrade results in losing access to and the ability to recover the MinIO S3 data. If migrating the S3 service in Bluefin, you can also transition the other deprecated services to the applications that replace them before you upgrade to the latest major release of SCALE.

See SCALE Bluefin Deprecated Services for more information.

Migrating from DDNS Service

Review and write down or take screenshots of your Dynamic DNS service provider, domain, IP address, port number, URL, and credential (username and password) settings to use when you reconfigure in a replacement app. If establishing a new provider, create the user account before proceeding. Otherwise, use the existing provider details.

To grant access to a specific user (and group) other than using the default admin user UID and GID, add a new non-root administrative user. Note the UID and GID for this new user to enter in the application configuration screen.

Install a replacement application such as DDNS-Updater using the CORE service settings from your notes. SCALE suggests other applications to consider other than DDNS-Updater application.

Migrating from OpenVPN Service

Review your OpenVPN client and server service settings. Take note of all certificate, device type, port, protocol, TLS crypt authentication, and additional parameter settings to use in a replacement app.

A certificate configured on CORE should migrate to SCALE, but as a precaution, record the certificate authority (CA) and certificate settings, and make a copy of the the private and public keys the CA and certificate uses.

Install a replacement application such as WG Easy using the CORE service settings from your notes. SCALE suggests other applications to consider other than the WG Easy VPN application.

Migrating from Rsync Service

Review your rsync and module service settings. Take note of all host path, access mode type, number of simultaneous connections, user and group IDs, allow and deny host addresses, and any auxiliary parameter settings.

Before you configure a new rsync application like Rsync Daemon (Rsync-d), validate that it is needed. When rsync is configured externally with SSH or using an rsync task in Data Protection > Rsync Tasks, and when Rsync Mode is set to SSH, the deprecated rsync service is not used or necessary for rsync to function.

Install a replacement application such as Rsync Daemon using the CORE service settings from your notes. SCALE suggests other applications to consider other than the Rsync Daemon application.

Migrating from S3 MinIO

You must migrate your S3 service and data before you upgrade or migrate from CORE to SCALE!

If you have S3 service MinIO configured in CORE you must first clean install or upgrade to SCALE 22.12.3 (Bluefin). The deprecated S3 service is based on the MinIO-deprecated and de-supported Filesystem platform. MinIO requires you to upgrade and migrate to a MinIO Client (MC) release. After completing this process you can upgrade to SCALE 24.04 (Dragonfish). SCALE 22.12.3 includes both the deprecated S3 service and the replacement MinIO app you migrate to. Failing to migrate the S3 service results in losing access to and the ability to compile your MinIO data.

Review your S3 service settings. Take note of the credentials (Access Key and Secret Key), and data storage volume and host path.

If a certificate other than the default freenas_default is used, take note. A certificate configured on CORE should migrate to SCALE, but as a precaution, record the certificate authority (CA) and certificate settings, especially any private and public keys the certificate uses.

Follow the migration instructions provided in Migrating from MinIO S3. This is an involved and time-consuming process with specific requirements. The amount of data being migrated determines how long this process takes.

Migrating from TFTP Service

Review your TFTP service settings. Take note of all directory, host, auxiliary parameter, permission, and credential (username and password) settings.

To grant access to a specific user (and group) other than using the default admin user UID and GID, add the new non-root administrative user. Note the UID and GID for this new user to enter in the application configuration screen.

To use a specific dataset or storage volume for files, create any new dataset in Bluefin before installing the application. Install the replacement application such as TFTP Server (TFTP-HPA) using the CORE service settings from your notes. SCALE suggests other applications to consider other than the TFTP Server (TFTP-HPA) application.

Migrating from WebDAV Service and Shares

Disable both the WebDAV share and service. Also disable the Start Automatically option to prevent the service from re-enabling after a system restart.

Review any existing WebDAV service authentication settings. Take note of all IP addresses, port numbers, URLs and credentials (username and password).

Remove any existing WebDAV shares. Go to Shares > WebDAV and use Edit to view any existing configurations. Take note of the share name, path, and read only settings. Delete the WebDAV share configuration.

In SCALE Bluefin: To grant access to a specific user (and group) other than using the default admin user UID and GID, add a new non-root administrative user for the share(s). Note the UID and GID for this new user to enter in the application configuration screen.

After disabling the WebDAV service and clearing any existing share configurations from the Shares > WebDAV screen in Bluefin, install the WebDAV application to recreate your shares using the CORE service settings from your notes. Use the webdav user and group in control, and the UID and GID (666) in the application.

Have more questions?

For further discussion or assistance, see these resources:

Found content that needs an update? You can suggest content changes directly! To request changes to this content, click the Feedback button located on the middle-right side of the page (might require disabling ad blocking plugins).

Preparing to Migrate

What can or cannot migrate?

Preparing for Migration

Deprecated Services in SCALE

Related Content