Get a Quote     (408) 943-4100   TrueNAS Discord VendOp_Icon_15x15px Enterprise Support
TrueNAS.com Software Systems Company Community Security iX Portal Download
TrueNAS Enterprise TrueNAS SCALE TrueNAS CORE Compare Editions TrueCommand Software Status FreeNAS
Compare Systems F-Series M-Series H-Series R-Series Mini Series
About iXsystems Our Clients Reviews Careers Awards iX Blog & News iX Website Contact Us
Community Forum Discord TrueNAS GitHub TrueNAS Merch Store
Use Cases Analytics Backup and Archival Cloud Data Mobility File Sharing iX Storj Media Creation Surveillance Virtualization
Industry Automotive Education Gaming Government Healthcare MSP Manufacturing Research & AI Media & Entertainment
Download TrueNAS SCALE Download TrueNAS CORE Get TrueNAS Enterprise Compare TrueNAS Editions Contact an Enterprise Specialist
  1. Documentation Hub
  2. /
  3. TrueNAS 25.04 (Early)
  4. /
  5. Getting Started
  6. /
  7. TrueNAS Migrations
  8. /
  9. Preparing to Migrate
Edit page
TrueNASTrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.

Preparing to Migrate

  12 minute read.

Migrating TrueNAS from FreeBSD- to Linux-based versions is a one-way operation. Attempting to activate or roll back to a FreeBSD-based TrueNAS boot environment can break the system.

Upgrade your FreeBSD-based TrueNAS system to the latest publicly-available release version, 13.0-U6.2 (or 13.3 for community users), before attempting to migrate. See Software Releases for current recommended update paths to make sure you download and migrate to the correct version.

What can or cannot migrate?

Although TrueNAS attempts to keep most of your configuration data when migrating, some items do not transfer. These are the items that do not migrate:

  • Microsoft OneDrive Cloud Sync credentials and tasks. OneDrive compatibility is not available in TrueNAS.
  • FreeBSD GELI encryption. If you have GELI-encrypted pools on your system that you plan to import, you must migrate your data from the GELI pool to a non-GELI encrypted pool before migrating.
  • Malformed certificates. TrueNAS validates the system certificates when a system migrates. When a malformed certificate is found, TrueNAS generates a new self-signed certificate to ensure system accessibility.
  • Plugins and jails. Save the configuration information for your plugin and back up any stored data. After migrating, add the equivalent application using the Apps option. If your plugin is not listed as an available application, use the Custom App option to add it and import data from the backup into a new dataset for the application.
  • NIS data.
  • System tunables.
  • ZFS boot environments.
  • SMB auxiliary parameters. As of TrueNAS 23.10 (Cobia), the Auxiliary Parameters option is no longer available in the UI as a configurable option. We recommend removing any auxiliary parameter settings before migrating.
  • AFP shares also do not transfer, but migrate into an SMB share with AFP compatibility enabled.
  • 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.
  • TrueNAS 13 account names beginning with a number are not supported in TrueNAS 24.04. Usernames must begin with a letter or an underscore. Before attempting 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.

If VMs need to access local NAS storage, you need to create a network bridge and assign it to the VM. Applications or sandboxes that need access to local storage within the container must use a bridge or mount a local storage location as a host path for the application.

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

Preparing for Migration

Read this article before you attempt to migrate your FreeBSD-based system to a Linux-based TrueNAS 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 Hardware Guide. If you must use a USB type device, verify you can access files on the device before you migrate.
TrueNAS Enterprise
Enterprise customers are encouraged to contact Support for assistance with the process of moving from a FreeBSD-based (13.3 or earlier) to a Linux-based (22.12 or newer) TrueNAS version, especially customers with HA systems.

  1. Upgrade your system to either the latest 13.0 or 13.3 release. TrueNAS Enterprise-licensed (or community systems that haven’t switched to 13.3) systems on 12.0x or earlier should upgrade to the latest 13.0 release (e.g 13.0-U6.2 or newer) prior to migration. Community users with 13.3 installed should update to the latest maintenance release of that version prior to migration. Either major version can use the iso upgrade method for migration.

  2. Migrate GELI-encrypted pools to a non-GELI-encrypted pool before upgrading from TrueNAS 12.0x or earlier releases! If you do not migrate from GELI to ZFS encryption before upgrading to 13.0-U6.2 (or newer) or migrating to TrueNAS 24.04, you permanently lose access to the data in the GELI encrypted pool(s).

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

  4. Write down, copy, or take screenshots of settings to duplicate after migrating or use in the event of a post-upgrade/migration issue. 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 after migrating, note the pool and system dataset. When you set up the first required pool after migrating import this pool first.

    Deprecated services - Record the settings for services deprecated in newer TrueNAS versions.

    VMs - If you have virtual machines configured, 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, 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 to import or configure after migrating.

    Usernames beginning with (0-9) - Review local user account names and rename or replace these with a letter or underscore before migrating.

    Tunables - Linux-based TrueNAS (22.12 or newer) does not use Tunables in the same way. Copy script configurations to add on the System > Advanced Settings screen, using the Sysctl widget, after migrating.

    Init/shutdown scripts - If using init/shutdown scripts, copy them or take a screenshot to add them after migrating.

    Cron jobs - If configured, copy or use screenshots of cron job scripts if you want to add the same jobs after migrating.

    Global self-encrypting drive (SED) Password - Unlock these drives before migrating. Write down the SED password to use after migrating.

    Credentials - Copy or write down the credentials for SSH connections and keypairs, and any configured cloud service backup providers if you do not have the credential settings saved in other files kept secured outside of TrueNAS.

    Data protection tasks - Write down or take screenshots of replication, periodic snapshot, cloud sync, or other task settings to reconfigure these after migrating.

  5. Remove all SMB auxiliary parameter settings before migrating. In TrueNAS 23.10 (Cobia) or newer, the SMB Auxiliary Parameters option is not available in the UI. Attempting to migrate with these settings can result in broken SMB shares post upgrade that require CLI access to fix.

  6. 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. See Component Naming for more information.

    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. 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 from an iso file, or if you are not using DHCP for network and interface configuration, use the recorded information from your previous settings to configure your network settings and reconfigure your static IPs or aliases after migrating.

    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 (TrueNAS 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 server is deployed.
    • Host name you want to use if not using the default-assigned host name in TrueNAS (truenas).
    • 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.

  7. Offline the deprecated S3 MinIO service (if in use). This might require a manual data backup and restore strategy. Enterprise customers can contact iX Support to discuss migration and backup strategies.

  8. Back up any critical data.

  9. Download your system configuration file and a debug file. After updating to the latest publicly-available release of TrueNAS 13.0 (or 13.3 for community users) and making any changes to 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 with a clean install using the TrueNAS 13.0 or 13.3 iso file.

After completing the steps listed above that apply to your existing system, download the latest TrueNAS 24.04 ISO file and save it to your computer. See Software Releases for current recommended update paths to make sure you download and migrate to and from the correct TrueNAS versions. Burn the iso to a USB drive (see Installing on Physical Hardware) when upgrading a physical system.

Deprecated Services

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

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 13.0 to 24.04. They provide details on transitioning from that service to an application with the functionality of the deprecated service.

TrueNAS has apps you can deploy as replacements for these services. 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.

See 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 service settings from your notes.

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 configured certificate should migrate, 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 service settings from your notes.

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 Rsyncd, 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 13.0 service settings from your notes. TrueNAS 24.10 suggests other applications to consider other than the Rsync Daemon application.

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 before installing the application. Install the replacement application, such as TFTP Server (TFTP-HPA), using the service settings from your notes.

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 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 service settings from your notes. Use the webdav user and group in control, and the UID and GID (666) in the application.

Related Content

Getting Started
Tutorials
Solutions

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