TrueNAS SCALETrueNAS 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.

Migrating TrueNAS CORE to SCALE

Migration Overview

This article provides information and instructions for migrating non-Enterprise TrueNAS CORE to SCALE.

TrueNAS Enterprise

TrueNAS Enterprise customers should consult with iXsystems Support before attempting migrate to TrueNAS SCALE.

The process requires an extended maintenance window, requires executing steps in the correct order to prevent issues with system configuration and operation, and additional system review post-migration to catch and correct any configuration issues.

Contacting iXsystems Support

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 Portalhttps://support.ixsystems.com
Emailsupport@ixsystems.com
Telephone and Other Resourceshttps://www.ixsystems.com/support/

Migration Preparation

Review the Migration Preparation article for detailed recommendations and preparation steps before attempting to migrate from CORE to SCALE.

Depending on system configuration, migrating from CORE to SCALE can be more or less complicated.

Root is the default system administration account for CORE, SCALE Angelfish, and early Bluefin releases.

Users migrating from CORE to SCALE or from pre 22.12.3 releases must manually create an admin user account. Only fresh installations using an iso file provide the option to create the admin user during the installation process.

SCALE systems with only the root user account can log in to the TrueNAS web interface as the root user. After logging in as root, TrueNAS alerts you to create the local administrator account.

System administrators should create and begin using the admin login, and then disable the root user password.

SCALE 24.04 (Dragonfish) introduces administrators privileges and role-based administrator accounts. The root or local administrator user can create new administrators with limited privileges based on their needs. Predefined administrator roles are read only, share admin, and the default full access local administrator account.

As part of security hardening and to comply with Federal Information Processing standards (FIPS), iXsystems plans to completely disable root login in a future release.

Migration Methods

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.

Clean Install

You can migrate from CORE to SCALE with a clean install using an iso file. With a clean SCALE install, you need to reconfigure your CORE settings in SCALE and import your data. Follow the instructions in the Install articles.

When TrueNAS SCALE boots, you might need to use the Shell to configure networking interfaces to enable GUI accessibility. After logging in to the TrueNAS SCALE UI, use a system configuration file to restore the system settings to the SCALE installation and import the data storage pools.

Manual Update

Some CORE 13.0 releases can migrate using the CORE UI Upgrade function using a SCALE update file downloaded from the website. To use this method, you must upgrade to the latest maintenance release.

Earlier releases of CORE must upgrade to 13.0 and then the latest maintenance release U6.1 to use this method. If this process fails, retry using the iso file method above.

  1. Confirm that the TrueNAS CORE system is on the latest public release, 13.0-U6.1 or newer.

  2. Download the SCALE manual update file.

  3. Click CHECK FOR UPDATES in the System Information card on the Dashboard or go to System > Update.

  4. Click INSTALL MANUAL UPDATE FILE.

    SCALEManualSidegrade

  5. Click SAVE CONFIGURATION to download a backup file that can restore the system configuration in the event something goes wrong with the migration.

    SCALEConfigSidegrade

  6. Select a Temporary Storage Location (either Memory Device or a Pool) for the manual update file. Click Choose File and select the TrueNAS-SCALE.update file you downloaded.

    SCALEFileSidegrade

    Then click APPLY UPDATE.

  7. After the update completes, reboot the system if it does not reboot automatically.

    SCALESidegradeReboot

After TrueNAS SCALE reboots, sign in with the root user credentials used in CORE. Uploading the CORE config file deletes the admin user account created during a clean install and therefore requires you to recreate it.

After gaining access to the UI, you might need to use the Shell to configure the primary networking interfaces to enable GUI accessibility.

After booting and gaining access to the UI, go to System Settings > General and upload the system config file. This migrates your CORE settings, imports your pools, shares, etc. into SCALE.

After uploading the config file, review each area of the UI previously configured in CORE to validate pools imported and settings migrated correctly. Begin with your network settings.

TrueNAS SCALE automatically renames components, such as disks and interfaces, migrated from TrueNAS CORE, but does not modify the component Description. For example, the Name of an interface identified as igb0 in TrueNAS CORE is updated to eno1 after migration to TrueNAS SCALE, but the Description igb0 is retained. This difference is purely cosmetic and does not affect functionality.

See Component Naming for more information.

Use the information gathered during your preparation to migrate to restore settings, tasks, VMs, credentials, etc. not present in SCALE after uploading the config file.

Recreating the Admin User Account

All CORE systems migrating to SCALE, and all Angelfish and early Bluefin releases of SCALE upgrading to 22.12.3+ or to later SCALE major versions should create and begin using an admin user instead of the root user. After migrating or upgrading from CORE or a pre-SCALE 22.12.3 release to a later SCALE release, use this procedure to create the Local Administrator user.

Go to Credentials > Local Users and click Add.

Enter the name to use for the administrator account. For example, admin. You can create multiple admin users with any name and assign each different administration privileges.

Enter and confirm the admin user password.

Select builtin_administrators on the Auxiliary Group dropdown list.

Add the home directory for the new admin user. Enter or browse to select the location where SCALE creates the home directory. For example, /mnt/tank. If you created a dataset to use for home directories, select that dataset. Select the Read, Write, and Execute permissions for User, Group, and Other this user should have, then select Create Home Directory.

Select the shell for this admin user from the Shell dropdown list. Options are nologin, TrueNAS CLI, TrueNAS Console, sh, bash, rbash, dash, tmux, and zsh.

Select the sudo authorization permissions for this admin user. Some applications, such as Nextcloud, require sudo permissions for the administrator account. For administrator accounts generated during the initial installation process, TrueNAS SCALE sets authorization to Allow all sudo commands.

Click Save. The system adds the user to the builtin-users group after clicking Save.

Log out of the TrueNAS system and then log back in using the admin user credentials to verify that the admin user credentials work properly with your network configuration.

After adding the admin user account, disable the root user password:

Go to Credentials > Local Users, click on the root user, and select Edit. Click the Disable Password toggle to disable the password, then click Save.