From ec6c53b5ba40e358e5b211c86e4847f9501b0ba7 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 11:02:22 -0400 Subject: [PATCH 01/15] docs(unraid-os): add release type guide - Purpose: document the public Unraid OS release levels users see when choosing updates. - Before: the upgrade guide mentioned Stable and Next, but did not explain Stable, Beta, RC, patch, or withdrawn prerelease meanings in one place. - Problem: users evaluating prerelease builds had to infer risk, license impact, and reporting expectations from scattered release notes and FAQ text. - Change: add a dedicated release types page under Maintain and update, covering release readiness, Update OS channels, eligibility notes, and prerelease reporting guidance. - Implementation: link the new page from the Upgrading Unraid guide and keep validation scoped to targeted MDX lint rather than the full build. --- .../maintain-and-update/release-types.mdx | 104 ++++++++++++++++++ .../maintain-and-update/upgrading-unraid.mdx | 2 + 2 files changed, 106 insertions(+) create mode 100644 docs/unraid-os/system-administration/maintain-and-update/release-types.mdx diff --git a/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx b/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx new file mode 100644 index 00000000000..8f84ffbae6c --- /dev/null +++ b/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx @@ -0,0 +1,104 @@ +--- +sidebar_position: 1 +sidebar_label: Release types +--- + +# Unraid OS release types + +Unraid OS releases are published at different levels of readiness. Understanding the difference helps you decide whether to update a production server, test a future release, or wait for a later build. + +For most servers, use the latest **Stable** release. Use **Beta** or **Release Candidate (RC)** releases only when you are comfortable testing prerelease software and reading release notes carefully. + +## Release types at a glance + +| Release type | Example version | Best for | What to expect | +| --- | --- | --- | --- | +| **Stable** | `7.2.5` | Production servers | General availability release recommended for normal use. Stable releases may still receive later bug-fix or security patch releases. | +| **Patch release** | `7.2.5` after `7.2.4` | Users already on that stable series | A stable update in the same major/minor series. Patch releases usually focus on bug fixes, security updates, and compatibility fixes rather than new feature work. | +| **Release Candidate (RC)** | `7.3.0-rc.1` | Final validation on test systems | A prerelease that is expected to be close to stable, but may still include unresolved issues or last-minute changes. | +| **Beta** | `7.3.0-beta.2` | Early testing and feedback | A prerelease used to test new features, platform changes, fixes, and upgrade paths before the release is ready for stable use. | +| **Withdrawn prerelease** | Varies | Moving off an unavailable test build | A beta or RC that is no longer enabled for regular use. Update to the latest stable release unless the release notes say otherwise. | + +## Stable releases + +A stable release is the version most users should install. Stable releases are intended for regular use and are the safest choice for servers that store important data, host services, or need predictable uptime. + +Stable release notes explain major changes, upgrade warnings, known issues, and rollback notes. Before updating, read the release notes for the version you plan to install, then follow the [standard upgrade process](./upgrading-unraid.mdx). + +Stable releases can include: + +- **Feature releases**, such as `7.2.0`, which start a new release series. +- **Patch releases**, such as `7.2.5`, which update an existing stable series. + +Patch releases are still stable releases. They usually exist to resolve defects, address security issues, improve compatibility, or backport important fixes without starting a new feature series. + +## Beta releases + +Beta releases are public prereleases for users who want to help test upcoming Unraid OS changes. They can include new features, larger platform changes, dependency updates, and fixes that need broader hardware and workflow coverage before stable release. + +Install beta releases only on test or non-production systems where you can tolerate downtime, rollback work, and troubleshooting. A beta can contain regressions that are not present in the current stable release. + +Before installing a beta: + +- Back up your boot device. +- Read the full release notes, especially known issues and rollback notes. +- Confirm that your plugins and critical containers are compatible. +- Be prepared to report issues with diagnostics and reproduction steps. +- Avoid making irreversible storage or pool-format changes unless the release notes say the rollback path is safe. + +## Release candidate releases + +A release candidate is a prerelease that is closer to the intended stable version than a beta. RC builds are used to validate final fixes, packaging, upgrade behavior, and regressions before stable release. + +An RC is still prerelease software. Treat it with the same caution as a beta unless the release notes for that specific version say otherwise. + +RC releases are useful when: + +- You want to test whether a beta issue is fixed before stable release. +- You rely on hardware or plugins that need validation against the next stable version. +- You can provide useful feedback if something breaks. + +## Channels in the Update OS tool + +In the WebGUI, open ***Tools -> Update OS*** or use **Check for Update** from the top-right menu. + +- Choose **Stable** for stable releases. +- Choose **Next** for available beta and RC releases. + +The available channels and releases can change over time. If a prerelease is available, review the prerelease disclaimer, changelog, and release notes before continuing. + +## License and update eligibility + +Your license remains valid even if your update eligibility expires. Update eligibility only affects access to new OS updates. + +For prereleases: + +- Beta and RC versions are for testing and may contain bugs. +- Support for a prerelease ends when the corresponding stable version is released. +- Your license must be eligible for OS updates on the stable release date to receive that stable version. +- If your update eligibility expires before the stable release, you must extend your license to upgrade to that stable version or roll back to a supported stable version that your license allows. + +For more detail, see [What happens with pre-releases](../../troubleshooting/licensing-faq.mdx#pre-release-policy) in the licensing FAQ. + +## Choosing the right release + +Use this general rule: + +- Use **Stable** for production systems, important data, remote servers, and systems you do not want to troubleshoot. +- Use **RC** when you want to validate the next stable release and can handle prerelease risk. +- Use **Beta** when you want early access to new work and are prepared to test, report issues, and potentially roll back. +- Move off old beta or RC releases when a newer prerelease or stable release is available. + +If you are unsure, stay on the latest stable release. + +## Reporting prerelease issues + +Good prerelease feedback helps turn beta and RC builds into better stable releases. When reporting an issue, include: + +- The exact Unraid OS version. +- Whether the issue started after upgrading. +- Diagnostics from ***Tools -> Diagnostics***. +- Steps to reproduce the issue. +- Any relevant plugin, Docker, VM, network, or storage configuration details. + +For current prerelease feedback, see [Unraid OS Prerelease (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback). For stable release discussions and announcements, see the [Unraid announcements forum](https://forums.unraid.net/forum/7-announcements/). diff --git a/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx b/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx index d2cabc1f0d3..e727d78ea7f 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx +++ b/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx @@ -16,6 +16,8 @@ import ManualDowngradeCommandLine from "./partials/manual-downgrade-command-line Upgrading Unraid OS ensures that you have the latest features, security updates, and hardware support. This page outlines the standard upgrade process, along with troubleshooting tips and manual upgrade options. +For help deciding between Stable, Beta, and Release Candidate (RC) builds, see [Unraid OS release types](./release-types.mdx). + :::note[Prerequisites] Before you start upgrading, make sure to create a complete backup of your boot device. For more details, refer to [Backing up your boot device](../maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). From d0c25d1ca8d98303dff230adbc99f36d209e35e6 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 11:10:54 -0400 Subject: [PATCH 02/15] docs(unraid-os): add update landing page - Purpose: turn the update-related docs into a guided user journey. - Before: Release types, Upgrading Unraid, and Version history were connected only by narrow point-to-point links. - Problem: users deciding what to install still had to assemble the update flow from separate pages. - Change: add an Updating Unraid landing page that summarizes preparation, release choice, WebGUI update steps, version history usage, prerelease cautions, and support next steps. - Implementation: reposition the maintain-and-update pages, link Version history back to the update journey, and tighten the old beta/RC guidance. - Validation: ran targeted remark lint across the touched MDX files. --- docs/unraid-os/download_list.mdx | 2 + .../changing-the-flash-device.mdx | 2 +- .../maintain-and-update/release-types.mdx | 4 +- .../maintain-and-update/updating-unraid.mdx | 67 +++++++++++++++++++ .../maintain-and-update/upgrading-unraid.mdx | 4 +- 5 files changed, 74 insertions(+), 5 deletions(-) create mode 100644 docs/unraid-os/system-administration/maintain-and-update/updating-unraid.mdx diff --git a/docs/unraid-os/download_list.mdx b/docs/unraid-os/download_list.mdx index 5d8d5f8a7fb..bfa2e185044 100644 --- a/docs/unraid-os/download_list.mdx +++ b/docs/unraid-os/download_list.mdx @@ -7,6 +7,8 @@ import {VersionsTable} from '@site/src/components/VersionsTable'; # Version history +Use this page to find release notes and download links for Unraid OS versions. If you are deciding what to install, start with [Updating Unraid](./system-administration/maintain-and-update/updating-unraid.mdx) and [Unraid OS release types](./system-administration/maintain-and-update/release-types.mdx). + Need the USB Creator? [Getting Started With Unraid](https://unraid.net/getting-started) diff --git a/docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx b/docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx index 020b5e95b01..f49c071a5f6 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx +++ b/docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 sidebar_label: Changing the boot device --- diff --git a/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx b/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx index 8f84ffbae6c..03ab5fc93a1 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx +++ b/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 2 sidebar_label: Release types --- @@ -87,7 +87,7 @@ Use this general rule: - Use **Stable** for production systems, important data, remote servers, and systems you do not want to troubleshoot. - Use **RC** when you want to validate the next stable release and can handle prerelease risk. - Use **Beta** when you want early access to new work and are prepared to test, report issues, and potentially roll back. -- Move off old beta or RC releases when a newer prerelease or stable release is available. +- Do not remain on old beta or RC releases. When a newer prerelease or stable release is available, update or roll back to a supported stable version. If you are unsure, stay on the latest stable release. diff --git a/docs/unraid-os/system-administration/maintain-and-update/updating-unraid.mdx b/docs/unraid-os/system-administration/maintain-and-update/updating-unraid.mdx new file mode 100644 index 00000000000..d2778572730 --- /dev/null +++ b/docs/unraid-os/system-administration/maintain-and-update/updating-unraid.mdx @@ -0,0 +1,67 @@ +--- +sidebar_position: 1 +sidebar_label: Updating Unraid +--- + +# Updating Unraid + +Keeping Unraid OS current gives you the latest fixes, security updates, hardware support, and features. Most users should update through the %%WebGUI|web-gui%% using the latest **Stable** release. + +Use this page as the starting point for update decisions. It connects the release type guidance, the update procedure, and the version archive in one place. + +## Before you update + +1. Back up your boot device. +2. Read the release notes for the version you plan to install. +3. Update plugins before updating Unraid OS. +4. Confirm that your critical Docker containers, %%VMs|vm%%, and plugins are compatible. +5. Make sure you understand any rollback warnings in the release notes. + +If you use %%ZFS|zfs%% pools, encrypted pools, internal boot, TPM-based licensing, or other newer platform features, read the release notes especially carefully. Some storage, boot, and pool-format changes can affect downgrade paths. + +## Choose the right release + +For most systems, choose the latest **Stable** release. + +| If you want to... | Use this | +| --- | --- | +| Keep a production server reliable | Latest **Stable** release | +| Apply bug fixes in your current release series | Latest stable **patch release** | +| Validate the next stable release before general availability | **Release Candidate (RC)** on a test or non-production system | +| Test new features early and provide feedback | **Beta** on a test or non-production system | +| Recover from an old or unavailable prerelease | Update to a newer prerelease or roll back to a supported stable release | + +For more detail, see [Unraid OS release types](./release-types.mdx). + +## Update through the WebGUI + +For Unraid 7.x and later: + +1. Open the %%WebGUI|web-gui%%. +2. Select **Check for Update** from the top-right menu, or go to ***Tools -> Update OS***. +3. Choose **Stable** for stable releases, or **Next** for available beta and RC releases. +4. Review the changelog and release notes. +5. Confirm the update. +6. Reboot when prompted. + +For the complete procedure, including legacy update paths and troubleshooting, see [Upgrading Unraid](./upgrading-unraid.mdx). + +## Find release notes and older versions + +Use [Version history](../../download_list.mdx) when you need release notes, download links, or a previous Unraid OS ZIP file. + +Version history is a reference page. Before installing an older release, read the release notes for both the version you are leaving and the version you are installing. Pay special attention to **Rolling back**, **Known issues**, and storage-related warnings. + +## Prerelease reminders + +Beta and RC releases are for testing. They may contain bugs, incomplete fixes, or upgrade paths that change before stable release. + +Do not remain on old beta or RC releases. When a newer prerelease or stable release is available, update or roll back to a supported stable version. + +Your license remains valid even if update eligibility expires, but update eligibility affects access to new OS updates. If your update eligibility expires before a prerelease becomes stable, you may need to extend your license to install the stable release or roll back to a supported stable version. For more detail, see the [licensing FAQ](../../troubleshooting/licensing-faq.mdx#pre-release-policy). + +## If something goes wrong + +Start with the release notes for the version you installed. Many release notes include version-specific known issues, rollback steps, and compatibility warnings. + +If you need help, gather diagnostics from ***Tools -> Diagnostics*** and include the exact Unraid OS version, the version you upgraded from, and any relevant plugin, Docker, VM, storage, or network details. diff --git a/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx b/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx index e727d78ea7f..c1471e24a2f 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx +++ b/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 sidebar_label: Upgrading Unraid --- @@ -16,7 +16,7 @@ import ManualDowngradeCommandLine from "./partials/manual-downgrade-command-line Upgrading Unraid OS ensures that you have the latest features, security updates, and hardware support. This page outlines the standard upgrade process, along with troubleshooting tips and manual upgrade options. -For help deciding between Stable, Beta, and Release Candidate (RC) builds, see [Unraid OS release types](./release-types.mdx). +For the full update journey, start with [Updating Unraid](./updating-unraid.mdx). For help deciding between Stable, Beta, and Release Candidate (RC) builds, see [Unraid OS release types](./release-types.mdx). :::note[Prerequisites] From 6186855fa7b5da07686d2530d3c130082fa6c5a4 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 11:15:55 -0400 Subject: [PATCH 03/15] docs(unraid-os): make update guide category root - Purpose: make Updating Unraid the root page for the maintain-and-update category instead of a separate child page. - Before: the section used Docusaurus generated-index behavior and listed Updating Unraid as another page alongside supporting docs. - Problem: the update journey was structurally weaker than the intended root-page-and-subpages IA. - Change: rename the landing page to the category index, remove the generated-index override, and update links to the index page. - Implementation: use Docusaurus category index convention so Release types, Upgrading Unraid, and related pages remain subpages. - Validation: ran targeted remark lint across the touched MDX files. --- docs/unraid-os/download_list.mdx | 2 +- .../maintain-and-update/_category_.json | 7 ++----- .../maintain-and-update/{updating-unraid.mdx => index.mdx} | 0 .../maintain-and-update/upgrading-unraid.mdx | 2 +- 4 files changed, 4 insertions(+), 7 deletions(-) rename docs/unraid-os/system-administration/maintain-and-update/{updating-unraid.mdx => index.mdx} (100%) diff --git a/docs/unraid-os/download_list.mdx b/docs/unraid-os/download_list.mdx index bfa2e185044..3f7e380cb9d 100644 --- a/docs/unraid-os/download_list.mdx +++ b/docs/unraid-os/download_list.mdx @@ -7,7 +7,7 @@ import {VersionsTable} from '@site/src/components/VersionsTable'; # Version history -Use this page to find release notes and download links for Unraid OS versions. If you are deciding what to install, start with [Updating Unraid](./system-administration/maintain-and-update/updating-unraid.mdx) and [Unraid OS release types](./system-administration/maintain-and-update/release-types.mdx). +Use this page to find release notes and download links for Unraid OS versions. If you are deciding what to install, start with [Updating Unraid](./system-administration/maintain-and-update/index.mdx) and [Unraid OS release types](./system-administration/maintain-and-update/release-types.mdx). Need the USB Creator? [Getting Started With Unraid](https://unraid.net/getting-started) diff --git a/docs/unraid-os/system-administration/maintain-and-update/_category_.json b/docs/unraid-os/system-administration/maintain-and-update/_category_.json index 00221b87b61..ee0c1dada9c 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/_category_.json +++ b/docs/unraid-os/system-administration/maintain-and-update/_category_.json @@ -1,7 +1,4 @@ { "label": "Maintain and update", - "position": 2, - "link": { - "type": "generated-index" - } - } \ No newline at end of file + "position": 2 + } diff --git a/docs/unraid-os/system-administration/maintain-and-update/updating-unraid.mdx b/docs/unraid-os/system-administration/maintain-and-update/index.mdx similarity index 100% rename from docs/unraid-os/system-administration/maintain-and-update/updating-unraid.mdx rename to docs/unraid-os/system-administration/maintain-and-update/index.mdx diff --git a/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx b/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx index c1471e24a2f..cb9c50f3d46 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx +++ b/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx @@ -16,7 +16,7 @@ import ManualDowngradeCommandLine from "./partials/manual-downgrade-command-line Upgrading Unraid OS ensures that you have the latest features, security updates, and hardware support. This page outlines the standard upgrade process, along with troubleshooting tips and manual upgrade options. -For the full update journey, start with [Updating Unraid](./updating-unraid.mdx). For help deciding between Stable, Beta, and Release Candidate (RC) builds, see [Unraid OS release types](./release-types.mdx). +For the full update journey, start with [Updating Unraid](./index.mdx). For help deciding between Stable, Beta, and Release Candidate (RC) builds, see [Unraid OS release types](./release-types.mdx). :::note[Prerequisites] From 08e119f5b90c2de0ca0f555484a753673ad527ad Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 11:57:05 -0400 Subject: [PATCH 04/15] docs(unraid-os): move update guidance to root section - Purpose: make Updating Unraid a first-class Unraid OS category instead of burying it under system administration. - Before: update guidance lived under System administration > Maintain and update, mixing OS update decisions with boot-device maintenance. - Problem: updates are a core lifecycle path and should read like a root-level user journey, while boot-device replacement is maintenance. - Change: move Updating Unraid, Release types, Upgrading Unraid, and update/downgrade partials into a root-level Updating Unraid category. - Implementation: relabel the old section as Maintenance, adjust root category ordering, update internal links, and add redirects from old update URLs to the new location. - Validation: ran targeted remark lint for moved/edited Markdown and pnpm run check-case-sensitivity. --- .../advanced-configurations/_category_.json | 4 ++-- docs/unraid-os/download_list.mdx | 4 ++-- docs/unraid-os/release-notes/7.2.0.md | 2 +- docs/unraid-os/release-notes/7.2.1.md | 2 +- docs/unraid-os/release-notes/7.2.2.md | 2 +- docs/unraid-os/release-notes/7.2.3.md | 2 +- docs/unraid-os/release-notes/7.2.4.md | 2 +- docs/unraid-os/release-notes/7.2.5.md | 2 +- docs/unraid-os/release-notes/7.3.0.md | 2 +- docs/unraid-os/release-notes/_category_.json | 2 +- .../system-administration/_category_.json | 4 ++-- .../maintain-and-update/_category_.json | 2 +- docs/unraid-os/troubleshooting/_category_.json | 4 ++-- docs/unraid-os/updating-unraid/_category_.json | 4 ++++ .../index.mdx | 4 ++-- .../partials/manual-downgrade-command-line.mdx | 2 +- .../partials/manual-downgrade-simplest.mdx | 2 +- .../partials/upgrade-legacy-611-612.mdx | 0 .../partials/upgrade-modern.mdx | 0 .../release-types.mdx | 2 +- .../upgrading-unraid.mdx | 6 +++--- docs/unraid-os/using-unraid-to/_category_.json | 4 ++-- .../community-applications.mdx | 2 +- docusaurus.config.ts | 16 ++++++++++++++-- 24 files changed, 46 insertions(+), 30 deletions(-) create mode 100644 docs/unraid-os/updating-unraid/_category_.json rename docs/unraid-os/{system-administration/maintain-and-update => updating-unraid}/index.mdx (94%) rename docs/unraid-os/{system-administration/maintain-and-update => updating-unraid}/partials/manual-downgrade-command-line.mdx (95%) rename docs/unraid-os/{system-administration/maintain-and-update => updating-unraid}/partials/manual-downgrade-simplest.mdx (94%) rename docs/unraid-os/{system-administration/maintain-and-update => updating-unraid}/partials/upgrade-legacy-611-612.mdx (100%) rename docs/unraid-os/{system-administration/maintain-and-update => updating-unraid}/partials/upgrade-modern.mdx (100%) rename docs/unraid-os/{system-administration/maintain-and-update => updating-unraid}/release-types.mdx (97%) rename docs/unraid-os/{system-administration/maintain-and-update => updating-unraid}/upgrading-unraid.mdx (92%) diff --git a/docs/unraid-os/advanced-configurations/_category_.json b/docs/unraid-os/advanced-configurations/_category_.json index 408047b45f8..48b491b2dfc 100644 --- a/docs/unraid-os/advanced-configurations/_category_.json +++ b/docs/unraid-os/advanced-configurations/_category_.json @@ -1,7 +1,7 @@ { "label": "Advanced configurations", - "position": 4, + "position": 5, "link": { "type": "generated-index" } - } \ No newline at end of file + } diff --git a/docs/unraid-os/download_list.mdx b/docs/unraid-os/download_list.mdx index 3f7e380cb9d..521c0583242 100644 --- a/docs/unraid-os/download_list.mdx +++ b/docs/unraid-os/download_list.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 title: Version history --- @@ -7,7 +7,7 @@ import {VersionsTable} from '@site/src/components/VersionsTable'; # Version history -Use this page to find release notes and download links for Unraid OS versions. If you are deciding what to install, start with [Updating Unraid](./system-administration/maintain-and-update/index.mdx) and [Unraid OS release types](./system-administration/maintain-and-update/release-types.mdx). +Use this page to find release notes and download links for Unraid OS versions. If you are deciding what to install, start with [Updating Unraid](./updating-unraid/index.mdx) and [Unraid OS release types](./updating-unraid/release-types.mdx). Need the USB Creator? [Getting Started With Unraid](https://unraid.net/getting-started) diff --git a/docs/unraid-os/release-notes/7.2.0.md b/docs/unraid-os/release-notes/7.2.0.md index 4b0ac3f7aa9..5e2e6e14b6d 100644 --- a/docs/unraid-os/release-notes/7.2.0.md +++ b/docs/unraid-os/release-notes/7.2.0.md @@ -6,7 +6,7 @@ Note that some plugins may have visual issues in this release; please give plugi ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](../../unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? +For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.1.md b/docs/unraid-os/release-notes/7.2.1.md index fa346044f3c..2520bf310a3 100644 --- a/docs/unraid-os/release-notes/7.2.1.md +++ b/docs/unraid-os/release-notes/7.2.1.md @@ -4,7 +4,7 @@ This is a small update with some great fixes and improvements. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](../../unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? +For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.2.md b/docs/unraid-os/release-notes/7.2.2.md index 60177c9f35c..f897ad8addb 100644 --- a/docs/unraid-os/release-notes/7.2.2.md +++ b/docs/unraid-os/release-notes/7.2.2.md @@ -8,7 +8,7 @@ If you are on 7.2.0 or earlier you can skip straight to 7.2.2. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](../../unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? +For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.3.md b/docs/unraid-os/release-notes/7.2.3.md index 52e8df73654..42c732d7877 100644 --- a/docs/unraid-os/release-notes/7.2.3.md +++ b/docs/unraid-os/release-notes/7.2.3.md @@ -4,7 +4,7 @@ This is a security and bugfix release, recommended for all users. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](../../unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? +For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.4.md b/docs/unraid-os/release-notes/7.2.4.md index 03f5837e9f5..2e0d4b76c9b 100644 --- a/docs/unraid-os/release-notes/7.2.4.md +++ b/docs/unraid-os/release-notes/7.2.4.md @@ -6,7 +6,7 @@ This release includes critical security updates and bug fixes. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/system-administration/maintain-and-update/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? +For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.5.md b/docs/unraid-os/release-notes/7.2.5.md index 652f5a2b23f..fd445fd300d 100644 --- a/docs/unraid-os/release-notes/7.2.5.md +++ b/docs/unraid-os/release-notes/7.2.5.md @@ -8,7 +8,7 @@ This release is recommended for all 7.2.x users. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/system-administration/maintain-and-update/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? +For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.3.0.md b/docs/unraid-os/release-notes/7.3.0.md index 3f5c6606f1c..cbf5d612762 100644 --- a/docs/unraid-os/release-notes/7.3.0.md +++ b/docs/unraid-os/release-notes/7.3.0.md @@ -6,7 +6,7 @@ This is RELEASE CANDIDATE software. Please use on test servers only. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/system-administration/maintain-and-update/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? +For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? ### Known issues diff --git a/docs/unraid-os/release-notes/_category_.json b/docs/unraid-os/release-notes/_category_.json index 4e9fe407582..bd9c8d64db6 100644 --- a/docs/unraid-os/release-notes/_category_.json +++ b/docs/unraid-os/release-notes/_category_.json @@ -1,6 +1,6 @@ { "label": "Release notes", - "position": 6, + "position": 7, "link": { "type": "generated-index", "description": "Unraid Release Notes" diff --git a/docs/unraid-os/system-administration/_category_.json b/docs/unraid-os/system-administration/_category_.json index 4a8cbe116c4..22e74c00abf 100644 --- a/docs/unraid-os/system-administration/_category_.json +++ b/docs/unraid-os/system-administration/_category_.json @@ -1,7 +1,7 @@ { "label": "System administration", - "position": 3, + "position": 4, "link": { "type": "generated-index" } - } \ No newline at end of file + } diff --git a/docs/unraid-os/system-administration/maintain-and-update/_category_.json b/docs/unraid-os/system-administration/maintain-and-update/_category_.json index ee0c1dada9c..f931c8aeb65 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/_category_.json +++ b/docs/unraid-os/system-administration/maintain-and-update/_category_.json @@ -1,4 +1,4 @@ { - "label": "Maintain and update", + "label": "Maintenance", "position": 2 } diff --git a/docs/unraid-os/troubleshooting/_category_.json b/docs/unraid-os/troubleshooting/_category_.json index 04a750cf02f..d151979b62c 100644 --- a/docs/unraid-os/troubleshooting/_category_.json +++ b/docs/unraid-os/troubleshooting/_category_.json @@ -1,4 +1,4 @@ { "label": "Troubleshooting", - "position": 5 -} \ No newline at end of file + "position": 6 +} diff --git a/docs/unraid-os/updating-unraid/_category_.json b/docs/unraid-os/updating-unraid/_category_.json new file mode 100644 index 00000000000..316eed29df6 --- /dev/null +++ b/docs/unraid-os/updating-unraid/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Updating Unraid", + "position": 2 +} diff --git a/docs/unraid-os/system-administration/maintain-and-update/index.mdx b/docs/unraid-os/updating-unraid/index.mdx similarity index 94% rename from docs/unraid-os/system-administration/maintain-and-update/index.mdx rename to docs/unraid-os/updating-unraid/index.mdx index d2778572730..c54a9f7a16a 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/index.mdx +++ b/docs/unraid-os/updating-unraid/index.mdx @@ -48,7 +48,7 @@ For the complete procedure, including legacy update paths and troubleshooting, s ## Find release notes and older versions -Use [Version history](../../download_list.mdx) when you need release notes, download links, or a previous Unraid OS ZIP file. +Use [Version history](../download_list.mdx) when you need release notes, download links, or a previous Unraid OS ZIP file. Version history is a reference page. Before installing an older release, read the release notes for both the version you are leaving and the version you are installing. Pay special attention to **Rolling back**, **Known issues**, and storage-related warnings. @@ -58,7 +58,7 @@ Beta and RC releases are for testing. They may contain bugs, incomplete fixes, o Do not remain on old beta or RC releases. When a newer prerelease or stable release is available, update or roll back to a supported stable version. -Your license remains valid even if update eligibility expires, but update eligibility affects access to new OS updates. If your update eligibility expires before a prerelease becomes stable, you may need to extend your license to install the stable release or roll back to a supported stable version. For more detail, see the [licensing FAQ](../../troubleshooting/licensing-faq.mdx#pre-release-policy). +Your license remains valid even if update eligibility expires, but update eligibility affects access to new OS updates. If your update eligibility expires before a prerelease becomes stable, you may need to extend your license to install the stable release or roll back to a supported stable version. For more detail, see the [licensing FAQ](../troubleshooting/licensing-faq.mdx#pre-release-policy). ## If something goes wrong diff --git a/docs/unraid-os/system-administration/maintain-and-update/partials/manual-downgrade-command-line.mdx b/docs/unraid-os/updating-unraid/partials/manual-downgrade-command-line.mdx similarity index 95% rename from docs/unraid-os/system-administration/maintain-and-update/partials/manual-downgrade-command-line.mdx rename to docs/unraid-os/updating-unraid/partials/manual-downgrade-command-line.mdx index 52eff50a9b8..3bc53388c8d 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/partials/manual-downgrade-command-line.mdx +++ b/docs/unraid-os/updating-unraid/partials/manual-downgrade-command-line.mdx @@ -4,7 +4,7 @@ This method should only be used if you are comfortable with the Linux command li ::: -1. Copy the URL of the desired Unraid version ZIP file from the [Version History](../../../download_list.mdx). +1. Copy the URL of the desired Unraid version ZIP file from the [Version History](../../download_list.mdx). 2. Log in via %%SSH|ssh%% or console. 3. Execute the following commands *one at a time* (replace `` with the copied link): diff --git a/docs/unraid-os/system-administration/maintain-and-update/partials/manual-downgrade-simplest.mdx b/docs/unraid-os/updating-unraid/partials/manual-downgrade-simplest.mdx similarity index 94% rename from docs/unraid-os/system-administration/maintain-and-update/partials/manual-downgrade-simplest.mdx rename to docs/unraid-os/updating-unraid/partials/manual-downgrade-simplest.mdx index 143111e1535..ebb0e1ca3fd 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/partials/manual-downgrade-simplest.mdx +++ b/docs/unraid-os/updating-unraid/partials/manual-downgrade-simplest.mdx @@ -1,4 +1,4 @@ -1. Download the Unraid version ZIP file from the [Version History](../../../download_list.mdx). +1. Download the Unraid version ZIP file from the [Version History](../../download_list.mdx). 2. Unzip the file on your computer. 3. Access the `flash` network share (your boot volume; the share name may still be `flash` even when the UI says **Boot device**) or connect the USB boot device to your computer. 4. Create a `previous` directory if it doesn't already exist. diff --git a/docs/unraid-os/system-administration/maintain-and-update/partials/upgrade-legacy-611-612.mdx b/docs/unraid-os/updating-unraid/partials/upgrade-legacy-611-612.mdx similarity index 100% rename from docs/unraid-os/system-administration/maintain-and-update/partials/upgrade-legacy-611-612.mdx rename to docs/unraid-os/updating-unraid/partials/upgrade-legacy-611-612.mdx diff --git a/docs/unraid-os/system-administration/maintain-and-update/partials/upgrade-modern.mdx b/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx similarity index 100% rename from docs/unraid-os/system-administration/maintain-and-update/partials/upgrade-modern.mdx rename to docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx diff --git a/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx b/docs/unraid-os/updating-unraid/release-types.mdx similarity index 97% rename from docs/unraid-os/system-administration/maintain-and-update/release-types.mdx rename to docs/unraid-os/updating-unraid/release-types.mdx index 03ab5fc93a1..635a625259c 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/release-types.mdx +++ b/docs/unraid-os/updating-unraid/release-types.mdx @@ -78,7 +78,7 @@ For prereleases: - Your license must be eligible for OS updates on the stable release date to receive that stable version. - If your update eligibility expires before the stable release, you must extend your license to upgrade to that stable version or roll back to a supported stable version that your license allows. -For more detail, see [What happens with pre-releases](../../troubleshooting/licensing-faq.mdx#pre-release-policy) in the licensing FAQ. +For more detail, see [What happens with pre-releases](../troubleshooting/licensing-faq.mdx#pre-release-policy) in the licensing FAQ. ## Choosing the right release diff --git a/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx b/docs/unraid-os/updating-unraid/upgrading-unraid.mdx similarity index 92% rename from docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx rename to docs/unraid-os/updating-unraid/upgrading-unraid.mdx index cb9c50f3d46..5fc292f32e5 100644 --- a/docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx +++ b/docs/unraid-os/updating-unraid/upgrading-unraid.mdx @@ -20,7 +20,7 @@ For the full update journey, start with [Updating Unraid](./index.mdx). For help :::note[Prerequisites] -Before you start upgrading, make sure to create a complete backup of your boot device. For more details, refer to [Backing up your boot device](../maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). +Before you start upgrading, make sure to create a complete backup of your boot device. For more details, refer to [Backing up your boot device](../system-administration/maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). ::: @@ -49,7 +49,7 @@ Before you start upgrading, make sure to create a complete backup of your boot d :::caution[ZFS pool upgrade warnings] -When upgrading to Unraid 7.x, you may see warnings about [%%ZFS|zfs%%](../../advanced-configurations/optimize-storage/zfs-storage.mdx) pool feature upgrades during boot or in the %%WebGUI|web-gui%%. These warnings are not a sign of a problem; they simply indicate that your %%ZFS|zfs%% pool is using features from an older version of ZFS. +When upgrading to Unraid 7.x, you may see warnings about [%%ZFS|zfs%%](../advanced-configurations/optimize-storage/zfs-storage.mdx) pool feature upgrades during boot or in the %%WebGUI|web-gui%%. These warnings are not a sign of a problem; they simply indicate that your %%ZFS|zfs%% pool is using features from an older version of ZFS. Upgrading your pool isn't urgent, but if you do decide to upgrade, keep in mind that it may not work with previous versions of Unraid. This means you may not be able to revert to a previous Unraid version after making the upgrade. @@ -143,7 +143,7 @@ If you don't see the option to downgrade under **Tools → Downgrade OS**, use t ### Manual downgrade or upgrade -Manual downgrades are only needed if you can't access the %%WebGUI|web-gui%% or if the downgrade option isn't available. Before proceeding, it's important to back up your boot device. For more details, see [Backing up your boot device](../maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). +Manual downgrades are only needed if you can't access the %%WebGUI|web-gui%% or if the downgrade option isn't available. Before proceeding, it's important to back up your boot device. For more details, see [Backing up your boot device](../system-administration/maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). diff --git a/docs/unraid-os/using-unraid-to/_category_.json b/docs/unraid-os/using-unraid-to/_category_.json index b7725209325..55110b0bb89 100644 --- a/docs/unraid-os/using-unraid-to/_category_.json +++ b/docs/unraid-os/using-unraid-to/_category_.json @@ -1,7 +1,7 @@ { "label": "Using Unraid to", - "position": 2, + "position": 3, "link": { "type": "generated-index" } - } \ No newline at end of file + } diff --git a/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx index 8725f9d4a3e..27ed32c6f14 100644 --- a/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx +++ b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx @@ -106,7 +106,7 @@ The **Action Center** is located within the **Apps** tab in the %%WebGUI|web-gui - **Incompatible applications**: Applications that may not work with your current Unraid version - **Blacklisted applications**: Applications that have been removed from the catalog for security or compatibility reasons -When you access the Action Center, you'll see alerts for any applications requiring attention. To update an application, click on Actions for the app that needs updating, and then select **Update** to run the update script. Regular updates are essential for maintaining the security, stability, and compatibility of your Unraid installation. See [Upgrading Unraid](../../system-administration/maintain-and-update/upgrading-unraid.mdx) for more information. +When you access the Action Center, you'll see alerts for any applications requiring attention. To update an application, click on Actions for the app that needs updating, and then select **Update** to run the update script. Regular updates are essential for maintaining the security, stability, and compatibility of your Unraid installation. See [Upgrading Unraid](../../updating-unraid/upgrading-unraid.mdx) for more information. --- diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 39f7ad70c7e..cdd1c79a0ee 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -345,6 +345,18 @@ const config: Config = { from: "/category/zfs/", to: "/unraid-os/advanced-configurations/optimize-storage/zfs-storage/", }, + { + from: "/unraid-os/system-administration/maintain-and-update/", + to: "/unraid-os/updating-unraid/", + }, + { + from: "/unraid-os/system-administration/maintain-and-update/release-types/", + to: "/unraid-os/updating-unraid/release-types/", + }, + { + from: "/unraid-os/system-administration/maintain-and-update/upgrading-unraid/", + to: "/unraid-os/updating-unraid/upgrading-unraid/", + }, // Connect redirects { from: "/connect/", to: "/unraid-connect/overview-and-setup/" }, @@ -616,7 +628,7 @@ const config: Config = { { from: "/unraid-os/manual/tools/", to: "/category/advanced-tools/" }, { from: "/unraid-os/manual/upgrade-instructions/", - to: "/unraid-os/system-administration/maintain-and-update/upgrading-unraid/", + to: "/unraid-os/updating-unraid/upgrading-unraid/", }, { from: "/unraid-os/manual/users/", @@ -980,7 +992,7 @@ const config: Config = { { from: "/go/troubleshooting/", to: "/unraid-os/troubleshooting/" }, { from: "/go/upgrade-instructions/", - to: "/unraid-os/system-administration/maintain-and-update/upgrading-unraid/", + to: "/unraid-os/updating-unraid/upgrading-unraid/", }, { from: "/go/upgrading-a-vm-to-windows-11/", From 66c43d38d5e433ac3dabd3b16cb7041f40e652b6 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 12:45:48 -0400 Subject: [PATCH 05/15] docs(connect): align remote access guide with UI - Purpose: correct the Unraid Connect remote access guide so it matches the current Unraid 7.2.x settings UI. - Before: the guide described dynamic remote access choices and dashboard activation steps that are not exposed by the current settings form. - Problem: users on Unraid 7.2.4 only see Disabled/Always plus Static/UPnP forwarding, so the guide sent them looking for options that do not exist. - Change: document the current Allow Remote Access, Forward Type, and WAN Port controls, and clarify that on-demand dynamic remote access is not currently exposed. - How: replace the dynamic/static tabbed setup with current 7.2.x setup guidance and remove the overview claim about dynamic remote access. --- docs/unraid-connect/overview-and-setup.mdx | 2 +- docs/unraid-connect/remote-access.mdx | 72 ++++++++-------------- 2 files changed, 26 insertions(+), 48 deletions(-) diff --git a/docs/unraid-connect/overview-and-setup.mdx b/docs/unraid-connect/overview-and-setup.mdx index c79f86de00d..808ffe1f783 100644 --- a/docs/unraid-connect/overview-and-setup.mdx +++ b/docs/unraid-connect/overview-and-setup.mdx @@ -21,7 +21,7 @@ With Unraid Connect, you can: - Monitor real-time server health and resource usage, including storage, network, and Docker container status. - Perform and schedule secure online flash backups to protect your configuration and licensing information. - Receive notifications about server health, storage status, and critical events. -- Use dynamic remote access and server deep linking to navigate to specific management pages or troubleshoot issues quickly. +- Use remote access links and server deep linking to navigate to specific management pages or troubleshoot issues quickly. - Manage multiple servers from a single dashboard, making it perfect for users with more than one Unraid system. Unraid Connect is more than just an add-on; it's an essential extension of the Unraid platform, designed to maximize the value, security, and convenience of your Unraid OS investment. diff --git a/docs/unraid-connect/remote-access.mdx b/docs/unraid-connect/remote-access.mdx index d25cc5d4004..112e79828a2 100644 --- a/docs/unraid-connect/remote-access.mdx +++ b/docs/unraid-connect/remote-access.mdx @@ -3,14 +3,9 @@ sidebar_position: 3 sidebar_label: Remote access --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import RemoteAccessDynamic from './partials/remote-access/dynamic.mdx'; -import RemoteAccessStatic from './partials/remote-access/static.mdx'; - # Remote access -Unlock secure, browser-based access to your Unraid %%WebGUI|web-gui%% from anywhere with remote access. This feature is ideal for managing your server when you're away from home - no complicated networking or %%VPN Tunnel|vpn-tunnel%% setup is required. For more advanced needs, such as connecting to Docker containers or accessing network drives, a %%VPN Tunnel|vpn-tunnel%% remains the recommended solution. +Unlock secure, browser-based access to your Unraid %%WebGUI|web-gui%% from anywhere with remote access. This feature is ideal for managing your server when you're away from home, but it does require either %%UPnP|upnp%% or a manual port forwarding rule on your router. For more advanced needs, such as connecting to Docker containers or accessing network drives, a %%VPN Tunnel|vpn-tunnel%% remains the recommended solution. :::important[Security reminder] @@ -20,9 +15,9 @@ Before enabling remote access, ensure your root password is strong and unique. U Remote access through Unraid Connect provides: -- **Convenience** - Quickly access your server’s management interface from anywhere, using a secure, cloud-managed connection. -- **Security** - Dynamic access modes limit exposure by only allowing access to the internet when necessary, which helps reduce risks from automated attacks. -- **Simplicity** - No need for manual port forwarding or VPN client setup for basic management tasks. +- **Convenience** - Quickly access your server’s management interface from anywhere, using a trusted Unraid Connect URL. +- **Security** - Your %%WebGUI|web-gui%% traffic is encrypted when SSL/TLS is configured correctly. +- **Simplicity** - %%UPnP|upnp%% can create the required port mapping automatically when your router supports it. :::tip @@ -45,45 +40,32 @@ Your Unraid server will be ready to accept secure remote connections via the %%W --- -## Choosing a remote access type - -Unraid Connect offers two modes: - - - - - - - - - - +## Choosing a remote access configuration -| Feature | Dynamic remote access | Static remote access | -| ------------------------------------ | --------------------------- | ------------------------- | -| %%WebGUI\|web-gui%% open to internet | Only when enabled | Always | -| Attack surface | Minimized | Maximized | -| Automation | Auto open/close via Connect | Manual setup, always open | -| %%UPnP\|upnp%% support | Yes | Yes | -| | **Recommended for most** | | +In current Unraid 7.2.x releases, the Unraid API settings page exposes these remote access controls: -## Dynamic remote access setup +- **Allow Remote Access** - Choose whether remote access is **Disabled** or **Always** available. +- **Remote Access Forward Type** - Choose **Static** for manual port forwarding, or **UPnP** to let your router create the port mapping automatically. +- **Remote Access WAN Port** - Choose the WAN port to forward when using **Static** forwarding. -To set up dynamic remote access: +When remote access is set to **Always**, your %%WebGUI|web-gui%% is continuously reachable from the internet on the configured WAN port. Use a strong root password, keep Unraid OS updated, and disable remote access when you do not need it. -1. In ***Settings → Management Access → Unraid API***, select a dynamic option from the Remote Access dropdown: - - **Dynamic - UPnP:** Uses %%UPnP|upnp%% to open and close a random port automatically (requires %%UPnP|upnp%% enabled on your router). - - **Dynamic - Manual port forward:** Requires you to forward the selected port on your router manually. +Dynamic, on-demand remote access is not currently exposed in the Unraid API settings page. If you need remote management without keeping the %%WebGUI|web-gui%% exposed through port forwarding, use [Tailscale](../unraid-os/system-administration/secure-your-server/tailscale.mdx) or another %%VPN Tunnel|vpn-tunnel%%. -2. Navigate to [Unraid Connect](https://connect.myunraid.net/), and go to the management or server details page. +## Enable remote access -3. The **Dynamic remote access** card will show a button if your server isn’t currently accessible from your location. - -4. Click the button to enable WAN access. If using %%UPnP|upnp%%, a new port forward lease is created (typically for 30 minutes) and auto-renewed while active. +To enable remote access: -5. The card will display the current status and %%UPnP|upnp%% state. +1. In the Unraid %%WebGUI|web-gui%%, navigate to ***Settings → Management Access*** and open the **Unraid API Settings** tab. +2. Set **Allow Remote Access** to **Always**. +3. Choose a **Remote Access Forward Type**: + - **UPnP:** Lets Unraid ask your router to create the WAN port mapping automatically. This requires %%UPnP|upnp%% support and %%UPnP|upnp%% enabled on your router. + - **Static:** Requires you to create the port forwarding rule manually on your router. +4. If you choose **Static**, enter the **Remote Access WAN Port** you want to use. +5. Click **Apply**. +6. Log in to [Unraid Connect](https://connect.myunraid.net/) and click the **Manage** link to connect to your server remotely. -6. After 10 minutes of inactivity - or if you click **Disable remote access** - internet access is automatically revoked. %%UPnP|upnp%% leases are removed as well. +If the **Manage** link does not work, use the relevant forwarding section below to verify that the WAN port reaches your server's HTTPS port. --- @@ -100,13 +82,11 @@ To configure %%UPnP|upnp%%: Navigate to ***Settings → Management Access*** and change **Use %%UPnP|upnp%%** to **Yes**. 3. **Select %%UPnP|upnp%% in Unraid Connect.** - On the Unraid Connect settings page, choose the remote access option as %%UPnP|upnp%% (select either Dynamic or Always On) and then click **Apply**. + On the Unraid API settings page, set **Allow Remote Access** to **Always**, set **Remote Access Forward Type** to **UPnP**, and then click **Apply**. -4. **Verify port forwarding (Always On only).** +4. **Verify port forwarding.** Click the **Check** button. If successful, you'll see the message, "Your Unraid Server is reachable from the Internet." - For Dynamic forwarding, you need to click **Enable Dynamic Remote Access** in [Unraid Connect](https://connect.myunraid.net/) to allow access. - :::caution[Troubleshooting] If the setting changes from %%UPnP|upnp%% to Manual Port Forward upon reloading, Unraid might not be able to communicate with your router. Double-check that %%UPnP|upnp%% is enabled and consider updating your router's firmware. @@ -129,9 +109,7 @@ To configure manual port forwarding: Some routers may require the WAN port and HTTPS port to match. If so, use the same high random number for both. -4. **Verify port forwarding (Always On only):** Press the **Check** button. If everything is correct, you’ll see “Your Unraid Server is reachable from the Internet.” - - For dynamic forwarding, ensure to click **Enable Dynamic Remote Access** in [Unraid Connect](https://connect.myunraid.net/) to enable access. +4. **Verify port forwarding:** Press the **Check** button. If everything is correct, you’ll see “Your Unraid Server is reachable from the Internet.” 5. **Access your server:** Log in to [Unraid Connect](https://connect.myunraid.net/) and click the **Manage** link to connect to your server remotely. From 34e1ecc036895d231eaeb0365d8669d2dd9347fc Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 12:46:45 -0400 Subject: [PATCH 06/15] Revert "docs(connect): align remote access guide with UI" This reverts commit ea48ddee164da7bd3fa258288753b158dd85158e. --- docs/unraid-connect/overview-and-setup.mdx | 2 +- docs/unraid-connect/remote-access.mdx | 72 ++++++++++++++-------- 2 files changed, 48 insertions(+), 26 deletions(-) diff --git a/docs/unraid-connect/overview-and-setup.mdx b/docs/unraid-connect/overview-and-setup.mdx index 808ffe1f783..c79f86de00d 100644 --- a/docs/unraid-connect/overview-and-setup.mdx +++ b/docs/unraid-connect/overview-and-setup.mdx @@ -21,7 +21,7 @@ With Unraid Connect, you can: - Monitor real-time server health and resource usage, including storage, network, and Docker container status. - Perform and schedule secure online flash backups to protect your configuration and licensing information. - Receive notifications about server health, storage status, and critical events. -- Use remote access links and server deep linking to navigate to specific management pages or troubleshoot issues quickly. +- Use dynamic remote access and server deep linking to navigate to specific management pages or troubleshoot issues quickly. - Manage multiple servers from a single dashboard, making it perfect for users with more than one Unraid system. Unraid Connect is more than just an add-on; it's an essential extension of the Unraid platform, designed to maximize the value, security, and convenience of your Unraid OS investment. diff --git a/docs/unraid-connect/remote-access.mdx b/docs/unraid-connect/remote-access.mdx index 112e79828a2..d25cc5d4004 100644 --- a/docs/unraid-connect/remote-access.mdx +++ b/docs/unraid-connect/remote-access.mdx @@ -3,9 +3,14 @@ sidebar_position: 3 sidebar_label: Remote access --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import RemoteAccessDynamic from './partials/remote-access/dynamic.mdx'; +import RemoteAccessStatic from './partials/remote-access/static.mdx'; + # Remote access -Unlock secure, browser-based access to your Unraid %%WebGUI|web-gui%% from anywhere with remote access. This feature is ideal for managing your server when you're away from home, but it does require either %%UPnP|upnp%% or a manual port forwarding rule on your router. For more advanced needs, such as connecting to Docker containers or accessing network drives, a %%VPN Tunnel|vpn-tunnel%% remains the recommended solution. +Unlock secure, browser-based access to your Unraid %%WebGUI|web-gui%% from anywhere with remote access. This feature is ideal for managing your server when you're away from home - no complicated networking or %%VPN Tunnel|vpn-tunnel%% setup is required. For more advanced needs, such as connecting to Docker containers or accessing network drives, a %%VPN Tunnel|vpn-tunnel%% remains the recommended solution. :::important[Security reminder] @@ -15,9 +20,9 @@ Before enabling remote access, ensure your root password is strong and unique. U Remote access through Unraid Connect provides: -- **Convenience** - Quickly access your server’s management interface from anywhere, using a trusted Unraid Connect URL. -- **Security** - Your %%WebGUI|web-gui%% traffic is encrypted when SSL/TLS is configured correctly. -- **Simplicity** - %%UPnP|upnp%% can create the required port mapping automatically when your router supports it. +- **Convenience** - Quickly access your server’s management interface from anywhere, using a secure, cloud-managed connection. +- **Security** - Dynamic access modes limit exposure by only allowing access to the internet when necessary, which helps reduce risks from automated attacks. +- **Simplicity** - No need for manual port forwarding or VPN client setup for basic management tasks. :::tip @@ -40,32 +45,45 @@ Your Unraid server will be ready to accept secure remote connections via the %%W --- -## Choosing a remote access configuration +## Choosing a remote access type -In current Unraid 7.2.x releases, the Unraid API settings page exposes these remote access controls: +Unraid Connect offers two modes: -- **Allow Remote Access** - Choose whether remote access is **Disabled** or **Always** available. -- **Remote Access Forward Type** - Choose **Static** for manual port forwarding, or **UPnP** to let your router create the port mapping automatically. -- **Remote Access WAN Port** - Choose the WAN port to forward when using **Static** forwarding. + + + + -When remote access is set to **Always**, your %%WebGUI|web-gui%% is continuously reachable from the internet on the configured WAN port. Use a strong root password, keep Unraid OS updated, and disable remote access when you do not need it. + + + + -Dynamic, on-demand remote access is not currently exposed in the Unraid API settings page. If you need remote management without keeping the %%WebGUI|web-gui%% exposed through port forwarding, use [Tailscale](../unraid-os/system-administration/secure-your-server/tailscale.mdx) or another %%VPN Tunnel|vpn-tunnel%%. +| Feature | Dynamic remote access | Static remote access | +| ------------------------------------ | --------------------------- | ------------------------- | +| %%WebGUI\|web-gui%% open to internet | Only when enabled | Always | +| Attack surface | Minimized | Maximized | +| Automation | Auto open/close via Connect | Manual setup, always open | +| %%UPnP\|upnp%% support | Yes | Yes | +| | **Recommended for most** | | -## Enable remote access +## Dynamic remote access setup -To enable remote access: +To set up dynamic remote access: + +1. In ***Settings → Management Access → Unraid API***, select a dynamic option from the Remote Access dropdown: + - **Dynamic - UPnP:** Uses %%UPnP|upnp%% to open and close a random port automatically (requires %%UPnP|upnp%% enabled on your router). + - **Dynamic - Manual port forward:** Requires you to forward the selected port on your router manually. + +2. Navigate to [Unraid Connect](https://connect.myunraid.net/), and go to the management or server details page. -1. In the Unraid %%WebGUI|web-gui%%, navigate to ***Settings → Management Access*** and open the **Unraid API Settings** tab. -2. Set **Allow Remote Access** to **Always**. -3. Choose a **Remote Access Forward Type**: - - **UPnP:** Lets Unraid ask your router to create the WAN port mapping automatically. This requires %%UPnP|upnp%% support and %%UPnP|upnp%% enabled on your router. - - **Static:** Requires you to create the port forwarding rule manually on your router. -4. If you choose **Static**, enter the **Remote Access WAN Port** you want to use. -5. Click **Apply**. -6. Log in to [Unraid Connect](https://connect.myunraid.net/) and click the **Manage** link to connect to your server remotely. +3. The **Dynamic remote access** card will show a button if your server isn’t currently accessible from your location. -If the **Manage** link does not work, use the relevant forwarding section below to verify that the WAN port reaches your server's HTTPS port. +4. Click the button to enable WAN access. If using %%UPnP|upnp%%, a new port forward lease is created (typically for 30 minutes) and auto-renewed while active. + +5. The card will display the current status and %%UPnP|upnp%% state. + +6. After 10 minutes of inactivity - or if you click **Disable remote access** - internet access is automatically revoked. %%UPnP|upnp%% leases are removed as well. --- @@ -82,11 +100,13 @@ To configure %%UPnP|upnp%%: Navigate to ***Settings → Management Access*** and change **Use %%UPnP|upnp%%** to **Yes**. 3. **Select %%UPnP|upnp%% in Unraid Connect.** - On the Unraid API settings page, set **Allow Remote Access** to **Always**, set **Remote Access Forward Type** to **UPnP**, and then click **Apply**. + On the Unraid Connect settings page, choose the remote access option as %%UPnP|upnp%% (select either Dynamic or Always On) and then click **Apply**. -4. **Verify port forwarding.** +4. **Verify port forwarding (Always On only).** Click the **Check** button. If successful, you'll see the message, "Your Unraid Server is reachable from the Internet." + For Dynamic forwarding, you need to click **Enable Dynamic Remote Access** in [Unraid Connect](https://connect.myunraid.net/) to allow access. + :::caution[Troubleshooting] If the setting changes from %%UPnP|upnp%% to Manual Port Forward upon reloading, Unraid might not be able to communicate with your router. Double-check that %%UPnP|upnp%% is enabled and consider updating your router's firmware. @@ -109,7 +129,9 @@ To configure manual port forwarding: Some routers may require the WAN port and HTTPS port to match. If so, use the same high random number for both. -4. **Verify port forwarding:** Press the **Check** button. If everything is correct, you’ll see “Your Unraid Server is reachable from the Internet.” +4. **Verify port forwarding (Always On only):** Press the **Check** button. If everything is correct, you’ll see “Your Unraid Server is reachable from the Internet.” + + For dynamic forwarding, ensure to click **Enable Dynamic Remote Access** in [Unraid Connect](https://connect.myunraid.net/) to enable access. 5. **Access your server:** Log in to [Unraid Connect](https://connect.myunraid.net/) and click the **Manage** link to connect to your server remotely. From 48ada0d3ff09ea1a2ff92fa42b64d6c0f128cd01 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 12:47:07 -0400 Subject: [PATCH 07/15] docs(unraid-os): move update section near release notes - Move the root-level Updating Unraid category below Troubleshooting and above Release notes. - Restore the surrounding Unraid OS categories to their prior relative order so the update journey no longer interrupts the main topic flow. - Shift Version history after Release notes to preserve the release-reference ordering. --- docs/unraid-os/advanced-configurations/_category_.json | 2 +- docs/unraid-os/download_list.mdx | 2 +- docs/unraid-os/release-notes/_category_.json | 2 +- docs/unraid-os/system-administration/_category_.json | 2 +- docs/unraid-os/troubleshooting/_category_.json | 2 +- docs/unraid-os/updating-unraid/_category_.json | 2 +- docs/unraid-os/using-unraid-to/_category_.json | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/unraid-os/advanced-configurations/_category_.json b/docs/unraid-os/advanced-configurations/_category_.json index 48b491b2dfc..ffa6edba2af 100644 --- a/docs/unraid-os/advanced-configurations/_category_.json +++ b/docs/unraid-os/advanced-configurations/_category_.json @@ -1,6 +1,6 @@ { "label": "Advanced configurations", - "position": 5, + "position": 4, "link": { "type": "generated-index" } diff --git a/docs/unraid-os/download_list.mdx b/docs/unraid-os/download_list.mdx index 521c0583242..dc8a3e8e09b 100644 --- a/docs/unraid-os/download_list.mdx +++ b/docs/unraid-os/download_list.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 title: Version history --- diff --git a/docs/unraid-os/release-notes/_category_.json b/docs/unraid-os/release-notes/_category_.json index bd9c8d64db6..aa96f9ecd1b 100644 --- a/docs/unraid-os/release-notes/_category_.json +++ b/docs/unraid-os/release-notes/_category_.json @@ -1,6 +1,6 @@ { "label": "Release notes", - "position": 7, + "position": 8, "link": { "type": "generated-index", "description": "Unraid Release Notes" diff --git a/docs/unraid-os/system-administration/_category_.json b/docs/unraid-os/system-administration/_category_.json index 22e74c00abf..5edef43eef4 100644 --- a/docs/unraid-os/system-administration/_category_.json +++ b/docs/unraid-os/system-administration/_category_.json @@ -1,6 +1,6 @@ { "label": "System administration", - "position": 4, + "position": 3, "link": { "type": "generated-index" } diff --git a/docs/unraid-os/troubleshooting/_category_.json b/docs/unraid-os/troubleshooting/_category_.json index d151979b62c..d4489573a50 100644 --- a/docs/unraid-os/troubleshooting/_category_.json +++ b/docs/unraid-os/troubleshooting/_category_.json @@ -1,4 +1,4 @@ { "label": "Troubleshooting", - "position": 6 + "position": 5 } diff --git a/docs/unraid-os/updating-unraid/_category_.json b/docs/unraid-os/updating-unraid/_category_.json index 316eed29df6..ab6b61d79dd 100644 --- a/docs/unraid-os/updating-unraid/_category_.json +++ b/docs/unraid-os/updating-unraid/_category_.json @@ -1,4 +1,4 @@ { "label": "Updating Unraid", - "position": 2 + "position": 7 } diff --git a/docs/unraid-os/using-unraid-to/_category_.json b/docs/unraid-os/using-unraid-to/_category_.json index 55110b0bb89..40737c43165 100644 --- a/docs/unraid-os/using-unraid-to/_category_.json +++ b/docs/unraid-os/using-unraid-to/_category_.json @@ -1,6 +1,6 @@ { "label": "Using Unraid to", - "position": 3, + "position": 2, "link": { "type": "generated-index" } From 08dc9df1746e236b5b5847f289139313da36c339 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 12:53:03 -0400 Subject: [PATCH 08/15] docs(sidebar): nest release references under update guide - Render Release notes and Version history inside the Updating Unraid sidebar category. - Keep the underlying document files in place so existing release-note and version-history URLs do not change. - Preserve the existing semver grouping for release-note entries after they are nested. --- sidebar-semver-sort.js | 59 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 2 deletions(-) diff --git a/sidebar-semver-sort.js b/sidebar-semver-sort.js index 44f07e538bb..e6a8c80ab05 100644 --- a/sidebar-semver-sort.js +++ b/sidebar-semver-sort.js @@ -20,10 +20,61 @@ function addItemTitle(item) { }; } +function itemLabel(item) { + return item.label?.toLowerCase(); +} + +function isVersionHistoryDoc(item) { + return item.type === "doc" && item.id === "unraid-os/download_list"; +} + +function groupReleaseReferencesUnderUpdatingUnraid(items) { + const updatingIndex = items.findIndex((item) => + item.type === "category" && itemLabel(item) === "updating unraid" + ); + + if (updatingIndex === -1) { + return items; + } + + const releaseNotes = []; + const versionHistory = []; + const remainingItems = []; + + items.forEach((item, index) => { + if (index === updatingIndex) { + remainingItems.push(item); + } else if (item.type === "category" && itemLabel(item) === "release notes") { + releaseNotes.push(item); + } else if (isVersionHistoryDoc(item)) { + versionHistory.push(item); + } else { + remainingItems.push(item); + } + }); + + if (releaseNotes.length === 0 && versionHistory.length === 0) { + return items; + } + + const updatedUpdatingCategory = { + ...items[updatingIndex], + items: [ + ...(items[updatingIndex].items || []), + ...releaseNotes, + ...versionHistory, + ], + }; + + return remainingItems.map((item) => + item === items[updatingIndex] ? updatedUpdatingCategory : item + ); +} + function sortSidebarItems(items, sortBySemver = false) { - const result = items.map((item) => { + let result = items.map((item) => { if (item.type === "category") { - if (item.label.toLowerCase() === "release notes") { + if (itemLabel(item) === "release notes") { return { ...item, items: sortSidebarItems(item.items, true) }; } else { return { ...item, items: sortSidebarItems(item.items, false) }; @@ -32,6 +83,10 @@ function sortSidebarItems(items, sortBySemver = false) { return item; }); + if (!sortBySemver) { + result = groupReleaseReferencesUnderUpdatingUnraid(result); + } + if (sortBySemver) { const subfolderArrays = result.reduce((acc, item) => { const semverCompare = getSemverFromId(item.id); From 0554642474758a234a68a38f5f6f894ce52e2136 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 13:01:41 -0400 Subject: [PATCH 09/15] docs(unraid-os): simplify update landing page - Keep the Updating Unraid index focused as a short navigation hub. - Move detailed release-type and procedure content behind the dedicated Release types and Upgrading Unraid pages. - Link to the release-notes category instead of a specific version so the page stays current. --- docs/unraid-os/updating-unraid/index.mdx | 60 +++++++----------------- 1 file changed, 18 insertions(+), 42 deletions(-) diff --git a/docs/unraid-os/updating-unraid/index.mdx b/docs/unraid-os/updating-unraid/index.mdx index c54a9f7a16a..b8c9156432c 100644 --- a/docs/unraid-os/updating-unraid/index.mdx +++ b/docs/unraid-os/updating-unraid/index.mdx @@ -5,60 +5,36 @@ sidebar_label: Updating Unraid # Updating Unraid -Keeping Unraid OS current gives you the latest fixes, security updates, hardware support, and features. Most users should update through the %%WebGUI|web-gui%% using the latest **Stable** release. +Keeping Unraid OS current gives you the latest fixes, security updates, hardware support, and features. Most users should install the latest **Stable** release through the %%WebGUI|web-gui%%. -Use this page as the starting point for update decisions. It connects the release type guidance, the update procedure, and the version archive in one place. +Use this section to choose the right release, run the update, review release notes, and find older versions when needed. -## Before you update +## Start here -1. Back up your boot device. -2. Read the release notes for the version you plan to install. -3. Update plugins before updating Unraid OS. -4. Confirm that your critical Docker containers, %%VMs|vm%%, and plugins are compatible. -5. Make sure you understand any rollback warnings in the release notes. - -If you use %%ZFS|zfs%% pools, encrypted pools, internal boot, TPM-based licensing, or other newer platform features, read the release notes especially carefully. Some storage, boot, and pool-format changes can affect downgrade paths. +- [Release types](./release-types.mdx): Understand Stable, patch, beta, and Release Candidate (RC) releases. +- [Upgrading Unraid](./upgrading-unraid.mdx): Follow the standard update, downgrade, and manual recovery procedures. +- [Release notes](/category/release-notes/): Review version-specific changes, known issues, and rollback notes. +- [Version history](../download_list.mdx): Find release notes and download links for current and older versions. -## Choose the right release +## Which release should you install? For most systems, choose the latest **Stable** release. -| If you want to... | Use this | -| --- | --- | -| Keep a production server reliable | Latest **Stable** release | -| Apply bug fixes in your current release series | Latest stable **patch release** | -| Validate the next stable release before general availability | **Release Candidate (RC)** on a test or non-production system | -| Test new features early and provide feedback | **Beta** on a test or non-production system | -| Recover from an old or unavailable prerelease | Update to a newer prerelease or roll back to a supported stable release | - -For more detail, see [Unraid OS release types](./release-types.mdx). - -## Update through the WebGUI - -For Unraid 7.x and later: +Use beta and RC releases only when you are comfortable testing prerelease software, ideally on a test or non-production server. Do not remain on old beta or RC releases after a newer prerelease or stable release is available. -1. Open the %%WebGUI|web-gui%%. -2. Select **Check for Update** from the top-right menu, or go to ***Tools -> Update OS***. -3. Choose **Stable** for stable releases, or **Next** for available beta and RC releases. -4. Review the changelog and release notes. -5. Confirm the update. -6. Reboot when prompted. +For the full breakdown, see [Unraid OS release types](./release-types.mdx). -For the complete procedure, including legacy update paths and troubleshooting, see [Upgrading Unraid](./upgrading-unraid.mdx). +## Before updating -## Find release notes and older versions +Before updating, make sure you: -Use [Version history](../download_list.mdx) when you need release notes, download links, or a previous Unraid OS ZIP file. - -Version history is a reference page. Before installing an older release, read the release notes for both the version you are leaving and the version you are installing. Pay special attention to **Rolling back**, **Known issues**, and storage-related warnings. - -## Prerelease reminders - -Beta and RC releases are for testing. They may contain bugs, incomplete fixes, or upgrade paths that change before stable release. - -Do not remain on old beta or RC releases. When a newer prerelease or stable release is available, update or roll back to a supported stable version. +1. Back up your boot device. +2. Read the release notes for the version you plan to install. +3. Update plugins before updating Unraid OS. +4. Confirm that critical Docker containers, %%VMs|vm%%, and plugins are compatible. +5. Review any rollback warnings before installing the update. -Your license remains valid even if update eligibility expires, but update eligibility affects access to new OS updates. If your update eligibility expires before a prerelease becomes stable, you may need to extend your license to install the stable release or roll back to a supported stable version. For more detail, see the [licensing FAQ](../troubleshooting/licensing-faq.mdx#pre-release-policy). +If you use %%ZFS|zfs%% pools, encrypted pools, internal boot, TPM-based licensing, or other newer platform features, read the release notes especially carefully. Some storage, boot, and pool-format changes can affect downgrade paths. ## If something goes wrong From 93758f0d39468f3b7c9d22dc1b724c3ff9dba822 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 16:37:02 -0400 Subject: [PATCH 10/15] docs(unraid-os): link release types from 7.3.0 notes - Purpose: add a prominent path from the 7.3.0 release candidate notes to the release types guide. - Before: readers saw the release candidate warning without an inline explanation of Stable, Beta, and RC terminology. - Problem: users curious about prerelease labels had to discover the release types page elsewhere. - Now: the top of the 7.3.0-rc.1 changelog links directly to the Unraid OS release types guide. - How: add one short sentence beneath the release candidate warning using the existing docs route. --- docs/unraid-os/release-notes/7.3.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/unraid-os/release-notes/7.3.0.md b/docs/unraid-os/release-notes/7.3.0.md index cbf5d612762..6a31a98d8cb 100644 --- a/docs/unraid-os/release-notes/7.3.0.md +++ b/docs/unraid-os/release-notes/7.3.0.md @@ -4,6 +4,8 @@ This release candidate includes onboarding and internal boot, TPM-based licensin This is RELEASE CANDIDATE software. Please use on test servers only. +Curious about what our different release types are? See [Unraid OS release types](/unraid-os/updating-unraid/release-types/). + ## Upgrading For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? From a5c3701c0885f3277904a8026ac558a2ac3d4b9a Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 16:43:56 -0400 Subject: [PATCH 11/15] docs(unraid-os): simplify update guide navigation - Purpose: align the PR with account app terminology and remove redundant update navigation. - Before: new release-type content used prerelease while the account app says pre-release, and Updating Unraid contained a nested Upgrading Unraid page. - Problem: the spelling mismatch created inconsistent product language, and the update/upgrading hierarchy was hard to scan in the sidebar. - Now: new source docs use pre-release wording, the Updating Unraid category links directly to the update guide, and the old nested guide path redirects to the category root. - How: move the update procedure into updating-unraid/index.mdx, delete upgrading-unraid.mdx, update internal links, and preserve redirects for old URLs. --- docs/unraid-os/release-notes/7.2.0.md | 2 +- docs/unraid-os/release-notes/7.2.1.md | 2 +- docs/unraid-os/release-notes/7.2.2.md | 2 +- docs/unraid-os/release-notes/7.2.3.md | 2 +- docs/unraid-os/release-notes/7.2.4.md | 2 +- docs/unraid-os/release-notes/7.2.5.md | 2 +- docs/unraid-os/release-notes/7.3.0.md | 10 +- .../unraid-os/updating-unraid/_category_.json | 6 +- docs/unraid-os/updating-unraid/index.mdx | 157 +++++++++++++++--- .../partials/upgrade-modern.mdx | 2 +- .../updating-unraid/release-types.mdx | 32 ++-- .../updating-unraid/upgrading-unraid.mdx | 156 ----------------- .../community-applications.mdx | 2 +- docusaurus.config.ts | 10 +- 14 files changed, 176 insertions(+), 211 deletions(-) delete mode 100644 docs/unraid-os/updating-unraid/upgrading-unraid.mdx diff --git a/docs/unraid-os/release-notes/7.2.0.md b/docs/unraid-os/release-notes/7.2.0.md index 5e2e6e14b6d..fd6706f9148 100644 --- a/docs/unraid-os/release-notes/7.2.0.md +++ b/docs/unraid-os/release-notes/7.2.0.md @@ -6,7 +6,7 @@ Note that some plugins may have visual issues in this release; please give plugi ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? +For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.1.md b/docs/unraid-os/release-notes/7.2.1.md index 2520bf310a3..545377e4688 100644 --- a/docs/unraid-os/release-notes/7.2.1.md +++ b/docs/unraid-os/release-notes/7.2.1.md @@ -4,7 +4,7 @@ This is a small update with some great fixes and improvements. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? +For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.2.md b/docs/unraid-os/release-notes/7.2.2.md index f897ad8addb..451e75e401e 100644 --- a/docs/unraid-os/release-notes/7.2.2.md +++ b/docs/unraid-os/release-notes/7.2.2.md @@ -8,7 +8,7 @@ If you are on 7.2.0 or earlier you can skip straight to 7.2.2. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? +For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.3.md b/docs/unraid-os/release-notes/7.2.3.md index 42c732d7877..107b2cc858f 100644 --- a/docs/unraid-os/release-notes/7.2.3.md +++ b/docs/unraid-os/release-notes/7.2.3.md @@ -4,7 +4,7 @@ This is a security and bugfix release, recommended for all users. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? +For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.4.md b/docs/unraid-os/release-notes/7.2.4.md index 2e0d4b76c9b..7ea4ed88c79 100644 --- a/docs/unraid-os/release-notes/7.2.4.md +++ b/docs/unraid-os/release-notes/7.2.4.md @@ -6,7 +6,7 @@ This release includes critical security updates and bug fixes. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? +For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.2.5.md b/docs/unraid-os/release-notes/7.2.5.md index fd445fd300d..cdc335d48a6 100644 --- a/docs/unraid-os/release-notes/7.2.5.md +++ b/docs/unraid-os/release-notes/7.2.5.md @@ -8,7 +8,7 @@ This release is recommended for all 7.2.x users. ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? +For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? ### Known issues diff --git a/docs/unraid-os/release-notes/7.3.0.md b/docs/unraid-os/release-notes/7.3.0.md index 6a31a98d8cb..f0fbf01e108 100644 --- a/docs/unraid-os/release-notes/7.3.0.md +++ b/docs/unraid-os/release-notes/7.3.0.md @@ -8,11 +8,11 @@ Curious about what our different release types are? See [Unraid OS release types ## Upgrading -For step-by-step instructions, see [Upgrading Unraid](/unraid-os/updating-unraid/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? +For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)? ### Known issues -See [Unraid OS Prerelease (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback) for issues reported by other testers. +See [Unraid OS Pre-release (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback) for issues reported by other testers. - During internal boot setup, the WebGUI may show **Array Offline** while internal boot configures. **DO NOT** manually restart or remove your flash drive during this process. - Internal boot requires boot storage that can be accessed by in-tree Linux drivers during startup. Devices that require third-party drivers or post-boot configuration cannot be used for internal boot. @@ -24,10 +24,10 @@ See [Unraid OS Prerelease (Bugs & Feedback)](https://product.unraid.net/b/unraid ### Rolling back -- If you already enabled internal boot or switched to TPM-based licensing while testing the 7.3 prerelease, you can roll back to `7.3.0-beta.1` without issue. +- If you already enabled internal boot or switched to TPM-based licensing while testing the 7.3 pre-release, you can roll back to `7.3.0-beta.1` without issue. - Do not roll back to `7.2.4` or earlier after enabling internal boot or TPM-based licensing. - If you upgrade ZFS pool features, earlier Unraid releases may not be able to import those pools. -- If you need to roll back, follow the normal prerelease rollback process before moving between builds. +- If you need to roll back, follow the normal pre-release rollback process before moving between builds. If you are considering any rollback path below `7.3.0-beta.1`, also see the [7.2.4 release notes](/unraid-os/release-notes/7.2.4/). @@ -160,7 +160,7 @@ To proactively switch to TPM-based licensing, see [How can I move from flash-bas - xfsprogs: version 6.18.0 - zfs: version 2.4.1 -## Prerelease tester notes +## Pre-release tester notes ### CHANGES FROM BETA.2 diff --git a/docs/unraid-os/updating-unraid/_category_.json b/docs/unraid-os/updating-unraid/_category_.json index ab6b61d79dd..431532f2630 100644 --- a/docs/unraid-os/updating-unraid/_category_.json +++ b/docs/unraid-os/updating-unraid/_category_.json @@ -1,4 +1,8 @@ { "label": "Updating Unraid", - "position": 7 + "position": 7, + "link": { + "type": "doc", + "id": "unraid-os/updating-unraid/index" + } } diff --git a/docs/unraid-os/updating-unraid/index.mdx b/docs/unraid-os/updating-unraid/index.mdx index b8c9156432c..85040c78a70 100644 --- a/docs/unraid-os/updating-unraid/index.mdx +++ b/docs/unraid-os/updating-unraid/index.mdx @@ -3,41 +3,154 @@ sidebar_position: 1 sidebar_label: Updating Unraid --- + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import UpgradeModern from "./partials/upgrade-modern.mdx"; +import UpgradeLegacy611612 from "./partials/upgrade-legacy-611-612.mdx"; +import ManualDowngradeSimplest from "./partials/manual-downgrade-simplest.mdx"; +import ManualDowngradeCommandLine from "./partials/manual-downgrade-command-line.mdx"; + # Updating Unraid -Keeping Unraid OS current gives you the latest fixes, security updates, hardware support, and features. Most users should install the latest **Stable** release through the %%WebGUI|web-gui%%. +Updating Unraid OS ensures that you have the latest features, security updates, and hardware support. This page outlines the standard update process, along with troubleshooting tips and manual update options. + +For help deciding between Stable, Beta, and Release Candidate (RC) builds, see [Unraid OS release types](./release-types.mdx). + +:::note[Prerequisites] + +Before you start updating, make sure to create a complete backup of your boot device. For more details, refer to [Backing up your boot device](../system-administration/maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). + +::: + +:::tip[Best practices before updating] + +1. **Make a backup** of your boot device and any important data. +2. **Read the Release Notes** for the version you plan to install. +3. **Update all plugins** to their latest versions. +4. **Optionally, stop the array** before proceeding. +5. **Update Unraid OS** using the ***Tools → Update OS*** page. +6. **Reboot** your server to complete the upgrade. + +::: + +## Standard update process + + + + + + + + + + + +:::caution[ZFS pool upgrade warnings] + +When upgrading to Unraid 7.x, you may see warnings about [%%ZFS|zfs%%](../advanced-configurations/optimize-storage/zfs-storage.mdx) pool feature upgrades during boot or in the %%WebGUI|web-gui%%. These warnings are not a sign of a problem; they simply indicate that your %%ZFS|zfs%% pool is using features from an older version of ZFS. + +Upgrading your pool isn't urgent, but if you do decide to upgrade, keep in mind that it may not work with previous versions of Unraid. This means you may not be able to revert to a previous Unraid version after making the upgrade. + +As always, remember to back up your data before upgrading your %%ZFS|zfs%% pools. + +::: + +--- + +## Troubleshooting upgrade issues + +If you run into problems after upgrading, check the relevant section below for assistance. + +
+ Array or docker containers are slow to start after upgrade - Click to expand/collapse -Use this section to choose the right release, run the update, review release notes, and find older versions when needed. + A one-time migration may be necessary for Docker containers after certain upgrades. This process can take time, especially if you have many images. Be patient during this process; performance should normalize after the initial start. -## Start here +
-- [Release types](./release-types.mdx): Understand Stable, patch, beta, and Release Candidate (RC) releases. -- [Upgrading Unraid](./upgrading-unraid.mdx): Follow the standard update, downgrade, and manual recovery procedures. -- [Release notes](/category/release-notes/): Review version-specific changes, known issues, and rollback notes. -- [Version history](../download_list.mdx): Find release notes and download links for current and older versions. +
+ Docker containers are not working correctly after upgrade - Click to expand/collapse -## Which release should you install? + If you encounter errors like *"layers from manifest don't match image configuration,"* you may need to rebuild your Docker image file. Here’s how: -For most systems, choose the latest **Stable** release. + 1. Go to ***Settings → Docker*** and stop the Docker service. + 2. Check the box to delete the Docker image and click the delete button. + 3. Restart Docker to recreate the image. + 4. Navigate to the **Apps** tab, **Previous Apps** and check off what you wish to reinstall and click **"Install xx Applications"**. -Use beta and RC releases only when you are comfortable testing prerelease software, ideally on a test or non-production server. Do not remain on old beta or RC releases after a newer prerelease or stable release is available. +
+ +
+ VMs show "cannot get interface MTU" or network errors - Click to expand/collapse + + If you've used a custom bridge name for %%VM|vm%% networking, update all %%VMs|vm%% to use the default `br0` bridge by following these steps: + + 1. Go to the **VMs** tab and edit each %%VM|vm%% (make sure to enable **Advanced View**). + 2. Set the network bridge to `br0` and click **Apply**. + 3. Navigate to ***Settings → VM Manager*** (in **Advanced View**) and set the default bridge to `br0`. + +
+ +
+ VNC access to VMs is not working or is slow - Click to expand/collapse + + For older %%VMs|vm%%, you may need to update the %%VNC|vnc-session%% video driver: + + 1. Edit the %%VM|vm%% from the **VMs** tab (select **Advanced View**). + 2. Set the **%%VNC|vnc-session%% Video Driver** to **QXL** (recommended). Try **Cirrus** or **vmvga** if you have limited success with QXL. + 3. Click **Apply** to save the changes. + +
+ +
+ VM will not boot (EFI shell appears) - Click to expand/collapse + + If you have %%OVMF|ovmf%%-based %%VMs|vm%% created in older Unraid versions, you might encounter an EFI shell. You can boot the %%VM|vm%% by entering the following commands: + + 1. Type `fs0:`. + 2. Then type `cd efi/boot`. + 3. Finally, type `bootx64.efi`. + + If `fs0:` doesn't work, you can try `fs1:` instead. If you continue to have issues, please visit the [Unraid forums](https://forums.unraid.net/) for assistance. + +
+ +
+ Trying to start my VM gives an "Invalid machine type" error - Click to expand/collapse + + To resolve this, edit the %%VM|vm%% in the %%WebGUI|web-gui%% and click **Apply** without making any changes. This action will update the machine type to the latest supported version. + +
+ +
+ Poor VM performance after upgrading - Click to expand/collapse + + If your %%VM|vm%% is slow after an upgrade, go to the %%VM|vm%% settings (in **Advanced View**) and update the **Machine** type version to the latest revision (e.g., change from `i440fx-2.5` to `i440fx-2.7`). Make sure not to change the prefix (for example, don't switch from `i440fx` to `Q35`). + +
+ +--- -For the full breakdown, see [Unraid OS release types](./release-types.mdx). +## Downgrading Unraid -## Before updating +Before downgrading, be sure to read the release notes for the version you are downgrading from. Look for the section titled "Rolling back," as it contains any important steps you need to take. -Before updating, make sure you: +If you have access to the WebGUI, you can go to **Tools → Downgrade OS.** This option allows you to downgrade to your previously installed version without downloading a zip file from the Version History page. -1. Back up your boot device. -2. Read the release notes for the version you plan to install. -3. Update plugins before updating Unraid OS. -4. Confirm that critical Docker containers, %%VMs|vm%%, and plugins are compatible. -5. Review any rollback warnings before installing the update. +If you don't see the option to downgrade under **Tools → Downgrade OS**, use the manual method described below. This usually means that the files for the previous version are not on your boot device. -If you use %%ZFS|zfs%% pools, encrypted pools, internal boot, TPM-based licensing, or other newer platform features, read the release notes especially carefully. Some storage, boot, and pool-format changes can affect downgrade paths. +### Manual downgrade or upgrade -## If something goes wrong +Manual downgrades are only needed if you can't access the %%WebGUI|web-gui%% or if the downgrade option isn't available. Before proceeding, it's important to back up your boot device. For more details, see [Backing up your boot device](../system-administration/maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). -Start with the release notes for the version you installed. Many release notes include version-specific known issues, rollback steps, and compatibility warnings. + + + + -If you need help, gather diagnostics from ***Tools -> Diagnostics*** and include the exact Unraid OS version, the version you upgraded from, and any relevant plugin, Docker, VM, storage, or network details. + + + + diff --git a/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx b/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx index 811cd5f4366..3089ed077b0 100644 --- a/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx +++ b/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx @@ -1,4 +1,4 @@ -Upgrading Unraid is done using the new **Update OS tool** with a user-friendly interface: +Updating Unraid is done using the new **Update OS tool** with a user-friendly interface: 1. In the %%WebGUI|web-gui%%, click the top-right dropdown menu and select **Check for Update** or navigate to ***Tools → Update OS***. 2. Choose the **Stable** channel for stable releases, or the **Next** channel for betas and RCs. diff --git a/docs/unraid-os/updating-unraid/release-types.mdx b/docs/unraid-os/updating-unraid/release-types.mdx index 635a625259c..7141231c627 100644 --- a/docs/unraid-os/updating-unraid/release-types.mdx +++ b/docs/unraid-os/updating-unraid/release-types.mdx @@ -7,7 +7,7 @@ sidebar_label: Release types Unraid OS releases are published at different levels of readiness. Understanding the difference helps you decide whether to update a production server, test a future release, or wait for a later build. -For most servers, use the latest **Stable** release. Use **Beta** or **Release Candidate (RC)** releases only when you are comfortable testing prerelease software and reading release notes carefully. +For most servers, use the latest **Stable** release. Use **Beta** or **Release Candidate (RC)** releases only when you are comfortable testing pre-release software and reading release notes carefully. ## Release types at a glance @@ -15,15 +15,15 @@ For most servers, use the latest **Stable** release. Use **Beta** or **Release C | --- | --- | --- | --- | | **Stable** | `7.2.5` | Production servers | General availability release recommended for normal use. Stable releases may still receive later bug-fix or security patch releases. | | **Patch release** | `7.2.5` after `7.2.4` | Users already on that stable series | A stable update in the same major/minor series. Patch releases usually focus on bug fixes, security updates, and compatibility fixes rather than new feature work. | -| **Release Candidate (RC)** | `7.3.0-rc.1` | Final validation on test systems | A prerelease that is expected to be close to stable, but may still include unresolved issues or last-minute changes. | -| **Beta** | `7.3.0-beta.2` | Early testing and feedback | A prerelease used to test new features, platform changes, fixes, and upgrade paths before the release is ready for stable use. | -| **Withdrawn prerelease** | Varies | Moving off an unavailable test build | A beta or RC that is no longer enabled for regular use. Update to the latest stable release unless the release notes say otherwise. | +| **Release Candidate (RC)** | `7.3.0-rc.1` | Final validation on test systems | A pre-release that is expected to be close to stable, but may still include unresolved issues or last-minute changes. | +| **Beta** | `7.3.0-beta.2` | Early testing and feedback | A pre-release used to test new features, platform changes, fixes, and upgrade paths before the release is ready for stable use. | +| **Withdrawn pre-release** | Varies | Moving off an unavailable test build | A beta or RC that is no longer enabled for regular use. Update to the latest stable release unless the release notes say otherwise. | ## Stable releases A stable release is the version most users should install. Stable releases are intended for regular use and are the safest choice for servers that store important data, host services, or need predictable uptime. -Stable release notes explain major changes, upgrade warnings, known issues, and rollback notes. Before updating, read the release notes for the version you plan to install, then follow the [standard upgrade process](./upgrading-unraid.mdx). +Stable release notes explain major changes, upgrade warnings, known issues, and rollback notes. Before updating, read the release notes for the version you plan to install, then follow the [standard update process](./index.mdx). Stable releases can include: @@ -34,7 +34,7 @@ Patch releases are still stable releases. They usually exist to resolve defects, ## Beta releases -Beta releases are public prereleases for users who want to help test upcoming Unraid OS changes. They can include new features, larger platform changes, dependency updates, and fixes that need broader hardware and workflow coverage before stable release. +Beta releases are public pre-releases for users who want to help test upcoming Unraid OS changes. They can include new features, larger platform changes, dependency updates, and fixes that need broader hardware and workflow coverage before stable release. Install beta releases only on test or non-production systems where you can tolerate downtime, rollback work, and troubleshooting. A beta can contain regressions that are not present in the current stable release. @@ -48,9 +48,9 @@ Before installing a beta: ## Release candidate releases -A release candidate is a prerelease that is closer to the intended stable version than a beta. RC builds are used to validate final fixes, packaging, upgrade behavior, and regressions before stable release. +A release candidate is a pre-release that is closer to the intended stable version than a beta. RC builds are used to validate final fixes, packaging, upgrade behavior, and regressions before stable release. -An RC is still prerelease software. Treat it with the same caution as a beta unless the release notes for that specific version say otherwise. +An RC is still pre-release software. Treat it with the same caution as a beta unless the release notes for that specific version say otherwise. RC releases are useful when: @@ -65,16 +65,16 @@ In the WebGUI, open ***Tools -> Update OS*** or use **Check for Update** from th - Choose **Stable** for stable releases. - Choose **Next** for available beta and RC releases. -The available channels and releases can change over time. If a prerelease is available, review the prerelease disclaimer, changelog, and release notes before continuing. +The available channels and releases can change over time. If a pre-release is available, review the pre-release disclaimer, changelog, and release notes before continuing. ## License and update eligibility Your license remains valid even if your update eligibility expires. Update eligibility only affects access to new OS updates. -For prereleases: +For pre-releases: - Beta and RC versions are for testing and may contain bugs. -- Support for a prerelease ends when the corresponding stable version is released. +- Support for a pre-release ends when the corresponding stable version is released. - Your license must be eligible for OS updates on the stable release date to receive that stable version. - If your update eligibility expires before the stable release, you must extend your license to upgrade to that stable version or roll back to a supported stable version that your license allows. @@ -85,15 +85,15 @@ For more detail, see [What happens with pre-releases](../troubleshooting/licensi Use this general rule: - Use **Stable** for production systems, important data, remote servers, and systems you do not want to troubleshoot. -- Use **RC** when you want to validate the next stable release and can handle prerelease risk. +- Use **RC** when you want to validate the next stable release and can handle pre-release risk. - Use **Beta** when you want early access to new work and are prepared to test, report issues, and potentially roll back. -- Do not remain on old beta or RC releases. When a newer prerelease or stable release is available, update or roll back to a supported stable version. +- Do not remain on old beta or RC releases. When a newer pre-release or stable release is available, update or roll back to a supported stable version. If you are unsure, stay on the latest stable release. -## Reporting prerelease issues +## Reporting pre-release issues -Good prerelease feedback helps turn beta and RC builds into better stable releases. When reporting an issue, include: +Good pre-release feedback helps turn beta and RC builds into better stable releases. When reporting an issue, include: - The exact Unraid OS version. - Whether the issue started after upgrading. @@ -101,4 +101,4 @@ Good prerelease feedback helps turn beta and RC builds into better stable releas - Steps to reproduce the issue. - Any relevant plugin, Docker, VM, network, or storage configuration details. -For current prerelease feedback, see [Unraid OS Prerelease (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback). For stable release discussions and announcements, see the [Unraid announcements forum](https://forums.unraid.net/forum/7-announcements/). +For current pre-release feedback, see [Unraid OS Pre-release (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback). For stable release discussions and announcements, see the [Unraid announcements forum](https://forums.unraid.net/forum/7-announcements/). diff --git a/docs/unraid-os/updating-unraid/upgrading-unraid.mdx b/docs/unraid-os/updating-unraid/upgrading-unraid.mdx deleted file mode 100644 index 5fc292f32e5..00000000000 --- a/docs/unraid-os/updating-unraid/upgrading-unraid.mdx +++ /dev/null @@ -1,156 +0,0 @@ ---- -sidebar_position: 3 -sidebar_label: Upgrading Unraid ---- - - - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; -import UpgradeModern from "./partials/upgrade-modern.mdx"; -import UpgradeLegacy611612 from "./partials/upgrade-legacy-611-612.mdx"; -import ManualDowngradeSimplest from "./partials/manual-downgrade-simplest.mdx"; -import ManualDowngradeCommandLine from "./partials/manual-downgrade-command-line.mdx"; - -# Upgrading Unraid - -Upgrading Unraid OS ensures that you have the latest features, security updates, and hardware support. This page outlines the standard upgrade process, along with troubleshooting tips and manual upgrade options. - -For the full update journey, start with [Updating Unraid](./index.mdx). For help deciding between Stable, Beta, and Release Candidate (RC) builds, see [Unraid OS release types](./release-types.mdx). - -:::note[Prerequisites] - -Before you start upgrading, make sure to create a complete backup of your boot device. For more details, refer to [Backing up your boot device](../system-administration/maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). - -::: - -:::tip[Best practices before upgrading] - -1. **Make a backup** of your boot device and any important data. -2. **Read the Release Notes** for the version you plan to install. -3. **Update all plugins** to their latest versions. -4. **Optionally, stop the array** before proceeding. -5. **Update Unraid OS** using the ***Tools → Update OS*** page. -6. **Reboot** your server to complete the upgrade. - -::: - -## Standard upgrade process - - - - - - - - - - - -:::caution[ZFS pool upgrade warnings] - -When upgrading to Unraid 7.x, you may see warnings about [%%ZFS|zfs%%](../advanced-configurations/optimize-storage/zfs-storage.mdx) pool feature upgrades during boot or in the %%WebGUI|web-gui%%. These warnings are not a sign of a problem; they simply indicate that your %%ZFS|zfs%% pool is using features from an older version of ZFS. - -Upgrading your pool isn't urgent, but if you do decide to upgrade, keep in mind that it may not work with previous versions of Unraid. This means you may not be able to revert to a previous Unraid version after making the upgrade. - -As always, remember to back up your data before upgrading your %%ZFS|zfs%% pools. - -::: - ---- - -## Troubleshooting upgrade issues - -If you run into problems after upgrading, check the relevant section below for assistance. - -
- Array or docker containers are slow to start after upgrade - Click to expand/collapse - - A one-time migration may be necessary for Docker containers after certain upgrades. This process can take time, especially if you have many images. Be patient during this process; performance should normalize after the initial start. - -
- -
- Docker containers are not working correctly after upgrade - Click to expand/collapse - - If you encounter errors like *"layers from manifest don't match image configuration,"* you may need to rebuild your Docker image file. Here’s how: - - 1. Go to ***Settings → Docker*** and stop the Docker service. - 2. Check the box to delete the Docker image and click the delete button. - 3. Restart Docker to recreate the image. - 4. Navigate to the **Apps** tab, **Previous Apps** and check off what you wish to reinstall and click **"Install xx Applications"**. - -
- -
- VMs show "cannot get interface MTU" or network errors - Click to expand/collapse - - If you've used a custom bridge name for %%VM|vm%% networking, update all %%VMs|vm%% to use the default `br0` bridge by following these steps: - - 1. Go to the **VMs** tab and edit each %%VM|vm%% (make sure to enable **Advanced View**). - 2. Set the network bridge to `br0` and click **Apply**. - 3. Navigate to ***Settings → VM Manager*** (in **Advanced View**) and set the default bridge to `br0`. - -
- -
- VNC access to VMs is not working or is slow - Click to expand/collapse - - For older %%VMs|vm%%, you may need to update the %%VNC|vnc-session%% video driver: - - 1. Edit the %%VM|vm%% from the **VMs** tab (select **Advanced View**). - 2. Set the **%%VNC|vnc-session%% Video Driver** to **QXL** (recommended). Try **Cirrus** or **vmvga** if you have limited success with QXL. - 3. Click **Apply** to save the changes. - -
- -
- VM will not boot (EFI shell appears) - Click to expand/collapse - - If you have %%OVMF|ovmf%%-based %%VMs|vm%% created in older Unraid versions, you might encounter an EFI shell. You can boot the %%VM|vm%% by entering the following commands: - - 1. Type `fs0:`. - 2. Then type `cd efi/boot`. - 3. Finally, type `bootx64.efi`. - - If `fs0:` doesn't work, you can try `fs1:` instead. If you continue to have issues, please visit the [Unraid forums](https://forums.unraid.net/) for assistance. - -
- -
- Trying to start my VM gives an "Invalid machine type" error - Click to expand/collapse - - To resolve this, edit the %%VM|vm%% in the %%WebGUI|web-gui%% and click **Apply** without making any changes. This action will update the machine type to the latest supported version. - -
- -
- Poor VM performance after upgrading - Click to expand/collapse - - If your %%VM|vm%% is slow after an upgrade, go to the %%VM|vm%% settings (in **Advanced View**) and update the **Machine** type version to the latest revision (e.g., change from `i440fx-2.5` to `i440fx-2.7`). Make sure not to change the prefix (for example, don't switch from `i440fx` to `Q35`). - -
- ---- - -## Downgrading Unraid - -Before downgrading, be sure to read the release notes for the version you are downgrading from. Look for the section titled "Rolling back," as it contains any important steps you need to take. - -If you have access to the WebGUI, you can go to **Tools → Downgrade OS.** This option allows you to downgrade to your previously installed version without downloading a zip file from the Version History page. - -If you don't see the option to downgrade under **Tools → Downgrade OS**, use the manual method described below. This usually means that the files for the previous version are not on your boot device. - -### Manual downgrade or upgrade - -Manual downgrades are only needed if you can't access the %%WebGUI|web-gui%% or if the downgrade option isn't available. Before proceeding, it's important to back up your boot device. For more details, see [Backing up your boot device](../system-administration/maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). - - - - - - - - - - diff --git a/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx index 27ed32c6f14..d5a10446621 100644 --- a/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx +++ b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx @@ -106,7 +106,7 @@ The **Action Center** is located within the **Apps** tab in the %%WebGUI|web-gui - **Incompatible applications**: Applications that may not work with your current Unraid version - **Blacklisted applications**: Applications that have been removed from the catalog for security or compatibility reasons -When you access the Action Center, you'll see alerts for any applications requiring attention. To update an application, click on Actions for the app that needs updating, and then select **Update** to run the update script. Regular updates are essential for maintaining the security, stability, and compatibility of your Unraid installation. See [Upgrading Unraid](../../updating-unraid/upgrading-unraid.mdx) for more information. +When you access the Action Center, you'll see alerts for any applications requiring attention. To update an application, click on Actions for the app that needs updating, and then select **Update** to run the update script. Regular updates are essential for maintaining the security, stability, and compatibility of your Unraid installation. See [Updating Unraid](../../updating-unraid/index.mdx) for more information. --- diff --git a/docusaurus.config.ts b/docusaurus.config.ts index cdd1c79a0ee..b2269ec37f8 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -355,7 +355,11 @@ const config: Config = { }, { from: "/unraid-os/system-administration/maintain-and-update/upgrading-unraid/", - to: "/unraid-os/updating-unraid/upgrading-unraid/", + to: "/unraid-os/updating-unraid/", + }, + { + from: "/unraid-os/updating-unraid/upgrading-unraid/", + to: "/unraid-os/updating-unraid/", }, // Connect redirects @@ -628,7 +632,7 @@ const config: Config = { { from: "/unraid-os/manual/tools/", to: "/category/advanced-tools/" }, { from: "/unraid-os/manual/upgrade-instructions/", - to: "/unraid-os/updating-unraid/upgrading-unraid/", + to: "/unraid-os/updating-unraid/", }, { from: "/unraid-os/manual/users/", @@ -992,7 +996,7 @@ const config: Config = { { from: "/go/troubleshooting/", to: "/unraid-os/troubleshooting/" }, { from: "/go/upgrade-instructions/", - to: "/unraid-os/updating-unraid/upgrading-unraid/", + to: "/unraid-os/updating-unraid/", }, { from: "/go/upgrading-a-vm-to-windows-11/", From cdfffdcfd076c7ceb9dc3c5d31f9b182f6f92f20 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 21:42:37 -0400 Subject: [PATCH 12/15] docs(release-types): clarify stable release series - Purpose: Clarify how Stable releases cover both minor releases and patch releases. - Before: Patch release appeared as a separate release type beside Stable, which made it look like a separate readiness category. - Problem: Readers could miss that patch releases are still Stable releases and that Unraid minor releases usually carry the larger series-level changes. - New behavior: The Stable row now shows a typical .0-to-patch sequence, and the Stable section explains what Unraid minor and patch releases typically contain. - Implementation: Removed the separate Patch release row, renamed feature releases to minor releases, and added concise lifecycle guidance for .0 and later patch releases. --- docs/unraid-os/updating-unraid/release-types.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/unraid-os/updating-unraid/release-types.mdx b/docs/unraid-os/updating-unraid/release-types.mdx index 7141231c627..ac2b35bfa20 100644 --- a/docs/unraid-os/updating-unraid/release-types.mdx +++ b/docs/unraid-os/updating-unraid/release-types.mdx @@ -13,8 +13,7 @@ For most servers, use the latest **Stable** release. Use **Beta** or **Release C | Release type | Example version | Best for | What to expect | | --- | --- | --- | --- | -| **Stable** | `7.2.5` | Production servers | General availability release recommended for normal use. Stable releases may still receive later bug-fix or security patch releases. | -| **Patch release** | `7.2.5` after `7.2.4` | Users already on that stable series | A stable update in the same major/minor series. Patch releases usually focus on bug fixes, security updates, and compatibility fixes rather than new feature work. | +| **Stable** | `7.2.0`, then `7.2.1`, `7.2.2`, and later patches | Production servers | General availability release recommended for normal use. A stable series often begins with a `.0` minor release, then receives patch releases with fixes and compatibility updates. | | **Release Candidate (RC)** | `7.3.0-rc.1` | Final validation on test systems | A pre-release that is expected to be close to stable, but may still include unresolved issues or last-minute changes. | | **Beta** | `7.3.0-beta.2` | Early testing and feedback | A pre-release used to test new features, platform changes, fixes, and upgrade paths before the release is ready for stable use. | | **Withdrawn pre-release** | Varies | Moving off an unavailable test build | A beta or RC that is no longer enabled for regular use. Update to the latest stable release unless the release notes say otherwise. | @@ -27,10 +26,12 @@ Stable release notes explain major changes, upgrade warnings, known issues, and Stable releases can include: -- **Feature releases**, such as `7.2.0`, which start a new release series. +- **Minor releases**, such as `7.2.0`, which start a new stable series. - **Patch releases**, such as `7.2.5`, which update an existing stable series. -Patch releases are still stable releases. They usually exist to resolve defects, address security issues, improve compatibility, or backport important fixes without starting a new feature series. +At Unraid, minor releases usually contain the larger stable changes for a series. These can include new or changed WebGUI behavior, storage, Docker, VM, networking, security, driver, kernel, and package updates, plus upgrade-path changes that need broader validation before the stable release is published. + +After a typical `.0` stable release, later patch releases in the same series may follow. For example, `7.2.1`, `7.2.2`, and `7.2.5` are all patch releases in the `7.2` series. Patch releases are still stable releases, but they usually focus on resolving defects, addressing security issues, improving hardware or plugin compatibility, updating bundled components, and backporting important fixes without starting a new feature series. ## Beta releases From 89343683f3a7296418cdc4ece6a4ecda6fa5568d Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 21:49:24 -0400 Subject: [PATCH 13/15] docs(updates): clarify release branch selection - Purpose: Explain that release branch selection is managed through the Unraid account app. - Before: The docs told users to choose Stable or Next in the Update OS tool, implying the branch could be changed from within the OS. - Problem: Users cannot switch release branches directly inside the OS, so the guidance pointed them at the wrong control surface. - New behavior: The release-types page and modern update steps now say Update OS shows updates for the server's current branch, and branch changes happen through Manage Unraid.net Account in the account app. - Implementation: Renamed the channels section, added Account app guidance, and changed the update procedure to apply the selected release rather than assuming a stable update. --- .../updating-unraid/partials/upgrade-modern.mdx | 6 +++--- docs/unraid-os/updating-unraid/release-types.mdx | 10 ++++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx b/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx index 3089ed077b0..9c56e861353 100644 --- a/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx +++ b/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx @@ -1,13 +1,13 @@ Updating Unraid is done using the new **Update OS tool** with a user-friendly interface: 1. In the %%WebGUI|web-gui%%, click the top-right dropdown menu and select **Check for Update** or navigate to ***Tools → Update OS***. -2. Choose the **Stable** channel for stable releases, or the **Next** channel for betas and RCs. +2. Review the update shown for your server's current release branch. 3. Click **View Changelog to Start Update**. The Changelog will appear for you to review before hitting **Continue**. -4. Click **Confirm and start update** to apply the latest stable release. +4. Click **Confirm and start update** to apply the selected release. 5. When prompted, reboot your server to complete the upgrade. :::note -You may need to log into your Unraid account to access updates, especially for "Next" branch releases. +To change between the **Stable** and **Next** release branches, open the top-right account menu and choose **Manage Unraid.net Account**. Release branches are managed in the Unraid account app, not directly in the OS. ::: diff --git a/docs/unraid-os/updating-unraid/release-types.mdx b/docs/unraid-os/updating-unraid/release-types.mdx index ac2b35bfa20..b7ad9c22ead 100644 --- a/docs/unraid-os/updating-unraid/release-types.mdx +++ b/docs/unraid-os/updating-unraid/release-types.mdx @@ -59,14 +59,16 @@ RC releases are useful when: - You rely on hardware or plugins that need validation against the next stable version. - You can provide useful feedback if something breaks. -## Channels in the Update OS tool +## Release branches and the Update OS tool In the WebGUI, open ***Tools -> Update OS*** or use **Check for Update** from the top-right menu. -- Choose **Stable** for stable releases. -- Choose **Next** for available beta and RC releases. +The Update OS tool shows updates for the release branch your server is already using. To change release branches, open the top-right account menu and choose **Manage Unraid.net Account** to manage the server in the [Unraid account app](../../unraid-account/server-management.mdx). You cannot switch release branches directly from inside the OS. -The available channels and releases can change over time. If a pre-release is available, review the pre-release disclaimer, changelog, and release notes before continuing. +- Use the **Stable** branch for stable releases. +- Use the **Next** branch for available beta and RC releases. + +The available branches and releases can change over time. If a pre-release is available on your selected branch, review the pre-release disclaimer, changelog, and release notes before continuing. ## License and update eligibility From f476eb5940e915d8f3bb949e22f1417ac810f283 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 21:51:09 -0400 Subject: [PATCH 14/15] docs(versions): rename version archive page - Purpose: Rename the version listing page from Version history to Version Archive. - Before: The page title and heading used Version history, and the intro only pointed users toward update decision pages. - Problem: The page is an archive of releases and downloads, while users looking to install or update need clearer direction to the right tool. - New behavior: The page is labeled Version Archive and its intro directs existing servers to the built-in updater, new boot devices to USB Creator, and release selection questions to release types. - Implementation: Updated the page front matter title, H1, intro copy, USB Creator link, and updater link to the standard update process anchor. --- docs/unraid-os/download_list.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/unraid-os/download_list.mdx b/docs/unraid-os/download_list.mdx index dc8a3e8e09b..1ee577d1aba 100644 --- a/docs/unraid-os/download_list.mdx +++ b/docs/unraid-os/download_list.mdx @@ -1,14 +1,14 @@ --- sidebar_position: 9 -title: Version history +title: Version Archive --- import {VersionsTable} from '@site/src/components/VersionsTable'; -# Version history +# Version Archive -Use this page to find release notes and download links for Unraid OS versions. If you are deciding what to install, start with [Updating Unraid](./updating-unraid/index.mdx) and [Unraid OS release types](./updating-unraid/release-types.mdx). +Use this archive to find release notes and download links for Unraid OS versions. To update an existing server, use the built-in updater; see the [standard update process](./updating-unraid/index.mdx#standard-update-process) for steps. To create a new boot device, use the [Unraid USB Creator](https://unraid.net/download). -Need the USB Creator? [Getting Started With Unraid](https://unraid.net/getting-started) +If you are deciding which release to install, start with [Unraid OS release types](./updating-unraid/release-types.mdx). From aeff74dd05c6f53058f5414f56b6f27349fed5d5 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Wed, 22 Apr 2026 21:57:53 -0400 Subject: [PATCH 15/15] docs(feedback): link product trackers - Purpose: Make it clear where users should report bugs and request features. - Before: Release type guidance only linked to the pre-release feedback board and the footer did not expose the Product Unraid tracker. - Problem: Users with stable-release bugs or feature ideas lacked a direct path from the docs to the right tracker. - New behavior: The release-types page links stable bug reports, pre-release feedback, and feature requests, while the footer includes one compact Feature and Bug Tracker link. - Implementation: Updated the reporting section in release-types.mdx and added a Product Unraid link under the Community footer group. --- docs/unraid-os/updating-unraid/release-types.mdx | 12 +++++++++--- docusaurus.config.ts | 4 ++++ 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/unraid-os/updating-unraid/release-types.mdx b/docs/unraid-os/updating-unraid/release-types.mdx index b7ad9c22ead..86e2023b691 100644 --- a/docs/unraid-os/updating-unraid/release-types.mdx +++ b/docs/unraid-os/updating-unraid/release-types.mdx @@ -94,9 +94,9 @@ Use this general rule: If you are unsure, stay on the latest stable release. -## Reporting pre-release issues +## Reporting issues and feature requests -Good pre-release feedback helps turn beta and RC builds into better stable releases. When reporting an issue, include: +Good feedback helps turn beta and RC builds into better stable releases and helps improve stable releases over time. When reporting an issue, include: - The exact Unraid OS version. - Whether the issue started after upgrading. @@ -104,4 +104,10 @@ Good pre-release feedback helps turn beta and RC builds into better stable relea - Steps to reproduce the issue. - Any relevant plugin, Docker, VM, network, or storage configuration details. -For current pre-release feedback, see [Unraid OS Pre-release (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback). For stable release discussions and announcements, see the [Unraid announcements forum](https://forums.unraid.net/forum/7-announcements/). +Use the relevant Product Unraid tracker: + +- For stable release bugs, use [Unraid OS Bug Reports](https://product.unraid.net/b/unraid-os-bugs). +- For beta or RC feedback, use [Unraid OS Pre-release (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback). +- For product ideas and enhancements, use [Unraid OS Feature Requests](https://product.unraid.net/b/unraid-os-feature-requests). + +For stable release discussions and announcements, see the [Unraid announcements forum](https://forums.unraid.net/forum/7-announcements/). diff --git a/docusaurus.config.ts b/docusaurus.config.ts index b2269ec37f8..e5cbb9fc963 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -242,6 +242,10 @@ const config: Config = { items: [ { label: "Forums", href: "https://forums.unraid.net" }, { label: "Discord", href: "https://discord.unraid.net/" }, + { + label: "Feature and Bug Tracker", + href: "https://product.unraid.net/", + }, ], }, {