Move from TrueNAS CORE 13.3

Enrol a TrueNAS CORE 13.3 system on FreeCORE and upgrade it in place.

FreeCORE carries a TrueNAS® CORE 13.3 system forward in place. Enrolment changes where 13.3 looks for operating-system updates and which FreeCORE train certificate it trusts. It does not install FreeCORE, change a storage pool, or touch user data.

Before You Begin

• This path is for TrueNAS CORE 13.3 only. The enrolment script refuses to run on another release.
• Download a configuration backup and keep it somewhere other than the system being upgraded.
• Make sure the boot pool has room for a new boot environment. System > Boot shows the current boot environments and their space use.
• Update when the system is otherwise idle, and keep a separate backup of data you cannot replace.

Enrol on the Stable Train

Open Shell from the local console menu. If root SSH access is already enabled, you can use that instead. Then run:

fetch https://freecore.org/freecore-enroll.sh && sh freecore-enroll.sh

The script displays the system version, train, update address, Update CA fingerprint, and a summary of the trust and configuration changes. Read the output before answering the confirmation prompt.

Verify the Update CA

The SHA-256 fingerprint of the FreeCORE Update CA is:

50:DF:7A:7C:49:44:58:AE:13:57:AE:90:E1:95:D0:01:53:FC:59:30:2E:50:7C:B4:E3:33:A2:FB:F6:E0:AD:08

The same certificate is published independently in the canonical Codeberg source repository as freecore-update-ca.pem. Download that copy and calculate its fingerprint with:

openssl x509 -in freecore-update-ca.pem -noout -fingerprint -sha256

The value must match both the value above and the value printed by the enrolment script.

What Enrolment Changes

The script:

• adds /usr/local/share/certs/FreeCORE-15.0-STABLE.pem; the certificates already supplied by iXsystems are left in place;
• writes /data/update.conf, pointing the updater at https://updates.freecore.org/FreeCORE;
• applies a narrow compatibility patch to the installed 13.3 update check so the change from the TrueNAS product name to FreeCORE is compared by version instead of being rejected as a downgrade;
• corrects the name 13.3 gives the new FreeCORE boot environment when the installed updater matches the known code; and
• restarts middlewared, briefly interrupting the web interface, then checks for an available update.

Original files are retained with a .pre-freecore suffix. The script downloads the Update CA only long enough to verify that the train certificate was issued by it; the CA is not installed on the 13.3 system. No update is installed until you choose to apply it from System > Update.

Undo Enrolment Before Upgrading

To point an enrolled 13.3 system back at the iXsystems updater before applying FreeCORE, run:

fetch https://freecore.org/freecore-enroll.sh && sh freecore-enroll.sh --revert

This restores the saved update configuration and compatibility files, removes the FreeCORE train certificate, and restarts middlewared when required.

--revert only undoes enrolment. It does not downgrade a system after FreeCORE 15.0 has been installed.

Apply FreeCORE 15.0

Go to System > Update, select FreeCORE-15.0-STABLE if the train selector is shown, review the available update, and apply it in the same way as another system update. The updater creates a new boot environment and migrates the configuration database on the first FreeCORE boot.

OpenVPN configuration does not migrate: FreeCORE replaces the OpenVPN server and client with WireGuard. Enterprise-licensed features are also absent. Read the FreeCORE 15.0 release notes before applying the update.

Recovery and Boot Environments

Ordinary FreeCORE updates also create boot environments. Selecting an earlier one from System > Boot or the boot menu returns to that operating-system and configuration state, but it does not rewind user data or all shared system state.

After an eligible in-place move from TrueNAS CORE 13.3, FreeCORE captures a persistent 13.3 return. It does not expire automatically. System > Update shows the origin boot environment, capture time, return availability, retained-space accounting, and the Return to 13.3 action.

The capture records the 13.3 origin boot environment together with recursive snapshots of the matching .system dataset and the complete active iocage tree. The return restores that captured set, activates the recorded origin boot environment, and reboots. The configuration stored with that boot environment returns with it. Unrelated user datasets are not rewound.

Returning is destructive to the captured areas: post-capture system state, jail and plugin changes, and data stored inside the iocage tree are discarded. Data that a jail or plugin stores in an unrelated user dataset is not restored.

There is no automatic expiry. The captured return persists until it is used, you select Remove Captured Return, or you explicitly forfeit it by confirming an incompatible pool-feature upgrade. The snapshot-space figure is a lower bound for space retained by the recorded snapshots. The pinned boot environment's deletion estimate is shown separately; it is not included in that lower bound.

Remove Captured Return destroys the recorded snapshots and releases the origin boot environment pin. It does not delete the boot environment. If cleanup is incomplete, the remaining state stays visible and Retry Cleanup tries the unfinished work again.

The action is also unavailable when the origin boot environment or a recorded snapshot is missing, or when the system dataset or active iocage dataset has moved since capture. An installer-ISO installation captures nothing because it has no 13.3 origin state. If the captured return is absent or unavailable, do not substitute manual activation of an old boot environment; restore through the backups made before the move instead.

Do not upgrade a storage pool until you are certain it no longer needs to be imported by 13.3. New ZFS feature flags can make a pool impossible for the older system to import. Keep the configuration backup and independent data backups from Before You Begin as the recovery path for this upgrade.