PD-1586 / 25.04 / Pd 1586 25 04 primary features upgrade notes writeup (

#3354) * Update _index.md * Update MigrateCOREHAtoSCALEHA.md * Update MigratingFromCORE.md * Update MigrateCOREtoSCALE24_04.md * Update Upgrade Paths * Update SCALEReleaseNotes.md * Update 25.04FeatureList.md * Update SCALEUpgradePaths.md * Update SCALEReleaseNotes.md * Update 25.04FeatureList.md * Update SCALEUpgradePaths.md * Update SCALEReleaseNotes.md * Update SCALEUpgradePaths.md * Update SCALEUpgradePaths.md * Update SCALEUpgradePaths.md * Apply suggestions from code review Co-authored-by: MicJ <[email protected]> * Update RESTAPIDeprecationNotice.md --------- Co-authored-by: MicJ <[email protected]>
truenas · Dec 12, 2024 · 4514bb0 · 4514bb0
1 parent 1484bdf
commit 4514bb0
Show file tree

Hide file tree

Showing 11 changed files with 108 additions and 67 deletions.
diff --git a/content/SCALE/GettingStarted/Migrate/MigrateCOREHAtoSCALEHA.md b/content/SCALE/GettingStarted/Migrate/MigrateCOREHAtoSCALEHA.md
@@ -1,6 +1,6 @@
 ---
-title: "Enterprise HA Migrations"
-description: "Discusses migrating a TrueNAS High Availability (HA) system from FreeBSD- to Linux-based TrueNAS software."
+title: "Enterprise Migrations"
+description: "Instructions for TrueNAS Enterprise users to migrate from FreeBSD- to Linux-based TrueNAS software."
 weight: 25
 aliases:
 tags:
@@ -11,6 +11,7 @@ keywords:
 - enterprise data storage solution
 - data migration
 - nas data storage
+slug: migrate-enterprise
 ---
 
 **TrueNAS Enterprise customers should consult with iXsystems Support before attempting to migrate.**

diff --git a/content/SCALE/GettingStarted/Migrate/MigratingFromCORE.md b/content/SCALE/GettingStarted/Migrate/MigratingFromCORE.md
@@ -1,6 +1,6 @@
 ---
-title: "Migrating TrueNAS"
-description: "Provides instructions on migrating from FreeBSD- to Linux-based TrueNAS versions. Migration methods include using an ISO or manual update file."
+title: "Community Migrations"
+description: "Provides instructions for TrueNAS community users to migrate from FreeBSD- to Linux-based TrueNAS versions. Migration methods include using an ISO or manual update file."
 weight: 15
 aliases:
  - /scale/gettingstarted/migratingfromcore/
@@ -13,6 +13,7 @@ keywords:
 - nas data storage
 - RAIDz
 - spinning disk
+slug: migrate-community
 ---
 
 ## Migration Overview

diff --git a/content/SCALE/GettingStarted/Migrate/_index.md b/content/SCALE/GettingStarted/Migrate/_index.md
@@ -1,6 +1,6 @@
 ---
-title: "TrueNAS Migrations"
-description: "Instructions for migrating from FreeBSD to Linux-based TrueNAS versions."
+title: "Migrating from CORE"
+description: "Instructions for migrating from FreeBSD TrueNAS CORE to Linux-based TrueNAS versions."
 geekdocCollapseSection: true
 weight: 40
 aliases:
@@ -20,7 +20,19 @@ keywords:
 - data migration
 ---
 
+On March 20, 2024, iXsystems [announced](https://www.truenas.com/blog/truenas-core-13-3-plans/) that the FreeBSD-based TrueNAS CORE platform has entered "sustaining engineering phase within the TrueNAS project."
+With this transition, TrueNAS 13.0 and 13.3 continue to receive bug fixes related to stability and security.
+New feature development and component improvement continues on Linux-based TrueNAS versions.
+
+Existing TrueNAS 13.0 and 13.3 users who are comfortable with their TrueNAS system can remain on that major version.
+Users looking for new feature development can sidegrade to the Linux-based TrueNAS platform at any time, preserving data and essential NAS functionality.
 
 {{< include file="/static/includes/MigrateCOREtoSCALE24_04.md" >}}
 
+<div class="noprint">
+
+## Contents
+
+{{< children depth="1" description="true" >}}
+
 </div>
diff --git a/content/SCALE/GettingStarted/SCALEReleaseNotes.md b/content/SCALE/GettingStarted/SCALEReleaseNotes.md
@@ -16,13 +16,21 @@ related: false
 {{< hint type="tip" title="25.04 Nightly Development Documentation" >}}
 This page tracks the latest development roadmap and notes for the future TrueNAS major version 25.04 (Fangtooth).
 
-See the stable [24.04 (Dragonfish)](https://www.truenas.com/docs/scale/24.04/gettingstarted/scalereleasenotes/) or early development [24.10 (Electric Eel)](https://www.truenas.com/docs/scale/24.10/gettingstarted/scalereleasenotes/) release notes for information relating to that version.
+See the stable [24.10 (Electric Eel)](https://www.truenas.com/docs/scale/24.10/gettingstarted/scalereleasenotes/) release notes for information relating to that version.
 {{< /hint >}}
 
 ## Features
 
 {{< include file="/static/includes/25.04FeatureList.md" >}}
 
+## Obtaining a Release
+
+{{< include file="/static/includes/EarlyReleaseWarning.md" >}}
+
+For adventurous users that want to experiment with the latest feature development, 25.04 (Fangtooth) nightly images are available from the [the TrueNAS downloads server](https://download.truenas.com/truenas-scale-fangtooth-nightly/).
+
+More details are available from [Software Releases]({{< relref "/TrueNASUpgrades/_index.md" >}}).
+
 ## Release Schedule
 
 {{< include file="/static/includes/ReleaseScheduleWarning.md" >}}
@@ -34,23 +42,6 @@ See the stable [24.04 (Dragonfish)](https://www.truenas.com/docs/scale/24.04/get
 {{< include file="/static/includes/SoftwareStatusPage.md" >}}
 {{< /expand >}}
 
-## 25.04 Nightly Development Changelog
-
-Coming soon
-
-{{< include file="/static/includes/RESTAPIDeprecationNotice.md" >}}
-
-<!--
-## Obtaining a Release
-
-{{< include file="/static/includes/EarlyReleaseWarning.md" >}}
-
-25.04 (Fangtooth) early releases (BETA and RC) are available from the [TrueNAS download page](https://www.truenas.com/download-truenas-scale/).
-
-For adventurous users that want to experiment with the latest feature development, nightly build [.iso](https://download.truenas.com/truenas-scale-electriceel-nightly/) and [.update](https://update.sys.truenas.net/scale/TrueNAS-SCALE-ElectricEel-Nightlies/) files are available.
-
-More details are available from [Software Releases]({{< relref "/TrueNASUpgrades/_index.md" >}}).
-
 ## Upgrade Notes
 
 * TrueNAS is an appliance built from specific Linux packages.
@@ -60,18 +51,23 @@ More details are available from [Software Releases]({{< relref "/TrueNASUpgrades
   We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading as these settings can result in SMB share failures after an upgrade.
 
 * {{< include file="/static/includes/UpgradeClearCache.md" >}}
-  
-### Upgrade Paths (Anticipated)
 
+* {{< include file="/static/includes/RESTAPIDeprecationNotice.md" >}}
+
+* The default libvirt account UID and GID is changed to to avoid possible clashes with user created Active Directory (AD) users. TrueNAS automatically updates libvirt UID and GIDs when upgraded to 25.04. Users attempting revert to 24.10 or an earlier release must manually review and update libvirt-qemu user and group IDs back to the values that were default in that version (64055:64055 for 24.10).
+
+
+### Upgrade Paths (Anticipated)
+<!--
 {{< include file="/static/includes/25.04UpgradeMethods.md" >}}
 
 See the <a href="https://www.truenas.com/software-status/" target="_blank">TrueNAS Software Status</a> page for recommendations about which software version to use based on your user type.
+-->
 
-Update the system to the latest maintenance release of the installed major version before attempting to upgrade to a new TrueNAS major version.
-
-include file="/static/includes/SCALEUpgradePaths.md" 
+{{< include file="/static/includes/SCALEUpgradePaths.md" >}}
 
-### TrueNAS Migrations
+<!--
+### Migrating from TrueNAS CORE
 
 {{< include file="/_includes/MigrateCOREtoSCALEWarning.md" >}}
 
@@ -90,15 +86,17 @@ See the [Migration articles]({{< relref "/SCALE/GettingStarted/Migrate/_index.md
 
 You must either clean install using an <file>iso</file> or use an upgrade file to migrate a FreeBSD-based TrueNAS system to TrueNAS 25.04 (Fangtooth).
 Enterprise customers should [contact Support](https://www.truenas.com/docs/scale/gettingstarted/migrate/migratecorehatoscaleha/#expand-1-Enterprise%20HA%20Migrations) for assistance with migration.
+-->
 
 ## Component Versions
 Click the component version number to see the latest release notes for that component.
 
 {{< truetable >}}
 | Component | Version |
 |-----------|-------------|
-| Linux Kernel | [_._.__](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tag/?h=v_._.__) |
-| OpenZFS | [_._.__](https://github.com/openzfs/zfs/tree/zfs-_._.__) |
+| Linux Kernel | [6.12](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tag/?h=v6.12) |
+| OpenZFS | [2.3.0-2](https://github.com/openzfs/zfs/tree/zfs-2.3.0-rc3) |
+| Docker Engine | [27.3.1](https://docs.docker.com/engine/release-notes/27/#2731) |
 {{< /truetable >}}
 
 ### OpenZFS Feature Flags
@@ -108,12 +106,21 @@ Any new feature flags introduced since the previous OpenZFS version that was int
 {{< truetable >}}
 | Feature Flag | GUID | Notes |
 |--------------|------|-------|
-|  | [org.openzfs:raidz_expansion](https://openzfs.github.io/openzfs-docs/man/master/7/zpool-features.7.html#raidz_expansion) |  |
-|  | [com.delphix:redaction_list_spill](https://openzfs.github.io/openzfs-docs/man/master/7/zpool-features.7.html#redaction_list_spill) | |
+| fast deduplication | [com.klarasystems:fast_dedup](https://openzfs.github.io/openzfs-docs/man/master/7/zpool-features.7.html#fast_dedup) | This flag is present in 24.10, but is now generally available through the TrueNAS UI. |
 {{< /truetable >}}
 
 For more details on feature flags, see [OpenZFS Feature Flags](https://openzfs.github.io/openzfs-docs/Basic%20Concepts/Feature%20Flags.html) and [OpenZFS zpool-feature.7](https://openzfs.github.io/openzfs-docs/man/7/zpool-features.7.html).
 
+## 25.04 Nightly Development Changelog
+
+* The TrueNAS REST API is deprecated in TrueNAS 25.04 and replaced by the [TrueNAS websocket client](https://github.com/truenas/api_client). Full removal of the REST API is planned for a future release.
+* The default libvirt account UID & GID is changed to a less common value to avoid clashing with user created UID/GIDs. See Upgrade Notes above for more information ([NAS-131695](https://ixsystems.atlassian.net/browse/NAS-131695)).
+* Improved API key mechanism with support for user-linked API keys ([NAS-131396](https://ixsystems.atlassian.net/browse/NAS-131396)).
+  Existing API keys created via the TrueNAS API (not UI or TrueCommand) that specify an allow list with white-listed API methods are revoked upon upgrade because there is no clean way to migrate to the new system.
+  Legacy API keys from TrueNAS 24.10 or earlier migrate to the root, admin, or truenas_admin account, depending on server configuration
+
+<!--
+
 ## 25.04-BETA.1 Changelog
 
 {{< hint type=warning title="Early Release Software" >}}

diff --git a/content/TrueNASUpgrades/_index.md b/content/TrueNASUpgrades/_index.md
@@ -62,8 +62,6 @@ See the [Documentation Archive](https://www.truenas.com/docs/archive/) for conte
 
 {{< include file="/static/includes/SCALEUpgradePaths.md" >}}
 
-{{< include file="/static/includes/COREUpgradePaths.md" >}}
-
 ## Release Schedules
 
 **The release names and dates provided here are tentative and can change at any time.**

diff --git a/data/properties/scale-downloads.yaml b/data/properties/scale-downloads.yaml
@@ -1,8 +1,8 @@
 ---
-id: "scale-downloads"
-img: "/images/truenas_scale-logo-full-color-rgb.png"
+id: "truenas-downloads"
+img: "/images/tn-openstorage-logo.png"
 product: "TrueNAS"
-title: "SCALE&trade; | Enterprise&trade;"
+title: "TrueNAS<sup>&reg;</sup> | Enterprise&trade;"
 majorVersions:
   - lifecycle: "Archive"
     majorVersions: 

diff --git a/data/properties/scale-releases.yaml b/data/properties/scale-releases.yaml
@@ -1,8 +1,8 @@
 ---
 id: "scale-schedule"
-img: "/images/truenas_scale-logo-full-color-rgb.png"
+img: "/images/tn-openstorage-logo.png"
 product: "TrueNAS"
-title: "TrueNAS&trade; | Enterprise&trade;"
+title: "TrueNAS<sup>&reg;</sup> | Enterprise&trade;"
 majorVersions:
   - lifecycle: "Previous"
     name: "TrueNAS 24.04 - Dragonfish"

diff --git a/static/includes/25.04FeatureList.md b/static/includes/25.04FeatureList.md
@@ -1,21 +1,24 @@
 &NewLine;
 
-This page is being updated to follow development changes for TrueNAS 25.04 (Fangtooth).
-Check back soon for updates.
-
-<!--
-
-&NewLine;
-
 25.04 (Fangtooth) will bring many new features and improvements to the TrueNAS experience:
 
 {{< columns >}}
-* 
+* RDMA support for NFS (Enterprise Feature) ([NAS-129977](https://ixsystems.atlassian.net/browse/NAS-129977))
+
+* iSCSI Fibre Channel support (Enterprise Feature)
+
+* Versioned TrueNAS API
+
+* Improved UI Login Experience ([NAS-130810](https://ixsystems.atlassian.net/browse/NAS-130810)).
 
 <--->
 
-<!--
-* 
+* Improved STIG Compliance and Security Focus ([NAS-127235](https://ixsystems.atlassian.net/browse/NAS-127235))
+
+* Containers (Sandboxes) with Incus (Experimental Community Feature) ([NAS-130251](https://ixsystems.atlassian.net/browse/NAS-130251))
+
+* Enable support for ZFS Fast Deduplication ([NAS-127088](https://ixsystems.atlassian.net/browse/NAS-127088))
+
+* Improvements to the TrueNAS apps service
 
 {{< /columns >}}
--->
diff --git a/static/includes/MigrateCOREtoSCALE24_04.md b/static/includes/MigrateCOREtoSCALE24_04.md
@@ -1,6 +1,6 @@
 &NewLine;
 
-TrueNAS users wanting to migrate from 13.0-U6 (latest) or 13.3 to TrueNAS 24.10 or later can migrate to 24.04 and earlier using the UI, but must clean install if migrating to later releases.
-Attempting to migrate directly to 24.10 or later releases fail and cannot be done.
+TrueNAS users wanting to migrate from the latest FreeBSD-based 13.0-U6 or 13.3 CORE release to the Linux-based TrueNAS version 24.10 or later can migrate to 24.04 and earlier using the UI, but must clean install if migrating to later releases.
+Attempting to migrate directly to 24.10 or later releases using the UI is not supported.
 
-Download a copy of the <file>iso</file> for the latest maintenance release of 24.10 or earlier, then follow the migration instructions in this Getting Started section of the TrueNAS Documentation Hub to move from the FreeBSD-based version of TrueNAS to the Linux Debian-based version of TrueNAS.
+Download a copy of the <file>iso</file> for the latest maintenance release of 24.10 or later, then follow the migration instructions in this Getting Started section of the TrueNAS Documentation Hub to move from the FreeBSD-based to the Linux-based version of TrueNAS.
diff --git a/static/includes/RESTAPIDeprecationNotice.md b/static/includes/RESTAPIDeprecationNotice.md
@@ -1,7 +1,7 @@
 &NewLine;
 
 {{< hint type="info" title="REST API Deprecation Notice" >}}
-The TrueNAS REST API is deprecated in TrueNAS 25.04 and replaced by the [TrueNAS API Client](https://github.com/truenas/api_client).
+The TrueNAS REST API is deprecated in TrueNAS 25.04 and replaced by the [TrueNAS websocket client](https://github.com/truenas/api_client).
 Full removal of the REST API is planned for a future release.
 
 This new API Client is not the deprecated TrueNAS CLI (midcli).

diff --git a/static/includes/SCALEUpgradePaths.md b/static/includes/SCALEUpgradePaths.md
@@ -41,19 +41,35 @@
 }
 </style>
 
+The chart below shows recommended paths for upgrading from earlier TrueNAS versions.
+
+Update the system to the latest maintenance release of the installed major version before attempting to upgrade to a new major version.
+
+Permitted upgrade methods are:
+* **update**: apply an automatic update using the **Update** screen in the TrueNAS UI or install a manual update file. Some upgrade paths do not support these options (see chart).
+* **ISO install**: save a current TrueNAS configuration file, perform a fresh install using an <file>.iso</file> file for the target version, and then upload the previously saved configuration.
+
+Users can skip major versions with a fresh ISO install followed by a configuration file upload.
+Carefully review release notes for each skipped major version before upgrading, noting any service deprecations or significant changes that impact the previous configuration.
+Consider stopping at major versions with significant impacts to address changes before continuing the upgrade path or be prepared to manually reconfigure incompatibilities on the latest target version.
+
 <div class="section-box" id="scale-upgrade-paths" style="padding: 0 40px 40px 40px; margin-bottom: 20px;">
     <div class="upgrade-paths-container">
       <img src="/images/tn-openstorage-logo.png" style="box-shadow: none; max-width: 225px; padding-bottom: 20px; padding-top: 40px;" title="TrueNAS" alt="TrueNAS">
       <div class="scroll-container" id="scrollContainer1">
         <div class="chart-wrapper">
           {{< mermaid class="mermaid_sizing" >}}
           flowchart LR
-            A["22.02.4 (Angelfish)"] -->|update| C
-            B["13.0-U6.2<br><br>13.3-RELEASE"] -->|ISO install| E
-            C["22.12.4.2 (Bluefin)"] -->|update| D
-            D["23.10.2 (Cobia)"] -->|update| E
-            E["24.04.2.5 (Dragonfish)"] -->|update| H
-            H["24.10.0.2 (Electric Eel)"]
+            A["11.3-U5"] -->|update| B["12.0-U8.1"]
+            B -->|"update<br><br>ISO install"| C["13.0-U6.3<br><br>13.3-U1"]
+            C -->|ISO install| H
+            C -->|"(anticipated)"| I
+            D["22.02.4 (Angelfish)"] -->|update| E
+            E["22.12.4.2 (Bluefin)"] -->|update| F
+            F["23.10.2 (Cobia)"] -->|update| G
+            G["24.04.2.5 (Dragonfish)"] -->|update| H
+            H["24.10.0.2 (Electric Eel)"] -->|"(anticipated)"| I
+            I["25.04.0 (Fangtooth)"]
           {{< /mermaid >}}
         </div>
       </div>
@@ -64,11 +80,14 @@
         <div class="chart-wrapper">
           {{< mermaid class="mermaid_sizing" >}}
           flowchart LR
-            A["13.0-U6.2"] -->|ISO install| D
-            B["Current 23.10 (Cobia) release"] -->|update| C
-            C["23.10.2 (Cobia)"] -->|update| D
-            D["24.04.2.5 (Dragonfish)"]  -->|"(anticipated)"| E
-            E["24.10.0.2 (Electric Eel)"]
+            A["11.3-U5"] -->|update| B
+            B["12.0-U8.1"] -->|update| C
+            C["13.0-U6.3"] -->|"(anticipated)"| F
+            C["13.0-U6.3"] -->|"(anticipated)"| G
+            D["23.10.2 (Cobia)"] -->|update| E
+            E["24.04.2.5 (Dragonfish)"]  -->|"(anticipated)"| F
+            F["24.10.0.2 (Electric Eel)"] -->|"(anticipated)"| G
+            G["25.04.0 (Fangtooth)"]
           {{< /mermaid >}}
         </div>
       </div>