Skip to content

docs: add Unraid 7.3 onboarding wizard flow #414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ljm42 wants to merge 3 commits into
base: main
Choose a base branch
from
+340 −38
Open

docs: add Unraid 7.3 onboarding wizard flow #414

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
57641b4
docs: add Unraid 7.3 onboarding wizard flow
ljm42 Mar 12, 2026
88fdb43
docs: clarify license key registration wording
ljm42 Mar 12, 2026
72ab6c9
docs: tighten 7.3 onboarding and TPM licensing copy
ljm42 Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 83 additions & 27 deletions docs/unraid-os/getting-started/set-up-unraid/deploy-and-configure-unraid-os.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ After booting Unraid OS for the first time, you'll use the %%WebGUI|web-gui%% to

:::info[Localize]

It may be easier for users to follow this guide after configuring their language settings. Check out [Multi-language support](../../using-unraid-to/customize-your-experience/multi-language-support.mdx) to make the %%WebGUI|web-gui%% more accessible in your preferred language.
It may be easier for users to follow this guide after configuring their language settings. Check out [Multi-language support](../../using-unraid-to/customize-your-experience/multi-language-support.mdx) to make the %%WebGUI|web-gui%% more accessible in your preferred language.

:::

Expand All @@ -33,12 +33,12 @@ When you access the %%WebGUI|web-gui%% for the first time, you'll be prompted to
Make sure your password is:

- Unique
- At least 8 characters long. (Although, best practice recommends 12+ for the most secure passwords!)
- At least 8 characters long. (Although, best practice recommends 12+ for the most secure passwords!)
- A mix of letters, numbers, and special characters

We recommend using a password manager for secure storage.

<div style={{ margin: 'auto', maxWidth: '300px'}}>
<div style={{ margin: "auto", maxWidth: "300px" }}>
![Set root password](/img/Set_root_password.png)
</div>

Expand All @@ -48,27 +48,83 @@ If you forget your root password, you can reset it following the [Reset your pas

:::

## Onboarding

:::note[Unraid 7.3 and later]

The onboarding wizard below applies to Unraid 7.3 and later.

:::

1. Press **Get Started** to launch the onboarding wizard. If you prefer to configure manually, select **Skip Setup**.

<div style={{ margin: "auto", maxWidth: "500px" }}>
![Step 1: Welcome to Unraid](/img/onboarding_step1.png)
</div>

To relaunch the wizard later, go to **_Settings → Onboarding Wizard_**.

2. Configure your server settings, including server name and description, time zone, language, and optional SSH and theme preferences. Then click **Next**.

<div style={{ margin: "auto", maxWidth: "500px" }}>
![Step 2: Configure Settings](/img/onboarding_step2.png)
</div>

3. Choose your boot option:
- For **flash boot**, keep the default USB/flash boot configuration and click **Next**.

<div style={{ margin: "auto", maxWidth: "500px" }}>
![Step 3: Flash Boot](/img/onboarding_step3a.png)
</div>
- For **internal boot**, choose single or mirrored boot mode, select the
device(s), and set the space reserved for the boot partition. Then click
**Next**.

<div style={{ margin: "auto", maxWidth: "500px" }}>
![Step 3: Internal Boot](/img/onboarding_step3b.png)
</div>

4. Optionally choose whether to preinstall key plugins, then click **Next**.

<div style={{ margin: "auto", maxWidth: "500px" }}>
![Step 4: Plugins](/img/onboarding_step4.png)
</div>

5. Review the summary, then click **Confirm & Apply**.

<div style={{ margin: "auto", maxWidth: "500px" }}>
![Step 5: Summary](/img/onboarding_step5.png)
</div>

6. On the **Next Steps** screen, review the recommended follow-up actions, then click:
- **Go to Dashboard** if you chose flash boot
- **Reboot** if you chose internal boot

<div style={{ margin: "auto", maxWidth: "500px" }}>
![Step 6: Next Steps](/img/onboarding_step6.png)
</div>

## Register your license key

After setting your root password, log in to your Unraid.net account to obtain a license key:
Log in to your Unraid.net account to obtain a license key:

1. In the %%WebGUI|web-gui%%, go to the **Get Started** section.

<div style={{ margin: 'auto', maxWidth: '500px'}}>
<div style={{ margin: "auto", maxWidth: "500px" }}>
![Get started](/img/Upc_get_started.png)
</div>

2. Sign in or create an account, after which a trial key will be installed automatically.

<div style={{ margin: 'auto', maxWidth: '500px'}}>
<div style={{ margin: "auto", maxWidth: "500px" }}>
![Install trial key](/img/Upc_install_trial_key.png)
</div>

This process allows you to manage your Unraid OS license keys, obtain new keys, recover lost ones, or upgrade your license.

:::important

For details on your license, visit ***Tools → Registration*** in the %%WebGUI|web-gui%%.
For details on your license, visit **_Tools → Registration_** in the %%WebGUI|web-gui%%.

:::

Expand All @@ -79,35 +135,35 @@ Before deploying Unraid OS, it's important to verify your system's BIOS and stor
<details>
<summary>Click to expand our BIOS and Storage Controller checklist</summary>

Proper BIOS and storage controller configuration is vital for a stable Unraid OS deployment. Use this checklist before your first boot.
Proper BIOS and storage controller configuration is vital for a stable Unraid OS deployment. Use this checklist before your first boot.

### Basic Settings
### Basic Settings

✅ Set the USB flash drive as the primary boot device.\
✅ Configure the storage controller to **%%AHCI|ahci%%** mode with SATA connections.\
✅ Set the controller to **%%HBA mode|hba-mode%%** (not **%%RAID|raid%%**).\
✅ Disable **Secure Boot** as it is not supported by Unraid OS.
✅ Set the USB flash drive as the primary boot device.\
✅ Configure the storage controller to **%%AHCI|ahci%%** mode with SATA connections.\
✅ Set the controller to **%%HBA mode|hba-mode%%** (not **%%RAID|raid%%**).\
✅ Disable **Secure Boot** as it is not supported by Unraid OS.

### Advanced Settings
### Advanced Settings

✅ Enable **%%hardware virtualization|hvm%%** features (e.g., **%%Intel VT-x|intel-vt-x%%** or **%%AMD-V|amd-v%%**) for **%%virtual machines (VMs)|vm%%**.\
✅ Enable **%%IOMMU|iommu%%** support (Intel VT-d or AMD-Vi) for PCI device assignment to VMs.
✅ Enable **%%hardware virtualization|hvm%%** features (e.g., **%%Intel VT-x|intel-vt-x%%** or **%%AMD-V|amd-v%%**) for **%%virtual machines (VMs)|vm%%**.\
✅ Enable **%%IOMMU|iommu%%** support (Intel VT-d or AMD-Vi) for PCI device assignment to VMs.

### Troubleshooting Tips
### Troubleshooting Tips

If Unraid OS does not boot, try:
If Unraid OS does not boot, try:

✅ Adjusting the boot order to: **Forced-FDD**, **USB-HDD**, **USB-ZIP**.\
✅ Disabling USB 2.0/3.0 support.\
✅ Toggling any Fast Boot features.\
✅ Toggling USB keyboard support.
✅ Adjusting the boot order to: **Forced-FDD**, **USB-HDD**, **USB-ZIP**.\
✅ Disabling USB 2.0/3.0 support.\
✅ Toggling any Fast Boot features.\
✅ Toggling USB keyboard support.
Comment on lines +142 to +159
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Inconsistent leading spaces in checklist items.

Some checkmark items have a leading space (lines 143-145, 150, 157-159) while others don't (lines 142, 149, 154, 156). This creates inconsistent indentation in the rendered output.

 ✅ Set the USB flash drive as the primary boot device.\
- ✅ Configure the storage controller to **%%AHCI|ahci%%** mode with SATA connections.\
- ✅ Set the controller to **%%HBA mode|hba-mode%%** (not **%%RAID|raid%%**).\
- ✅ Disable **Secure Boot** as it is not supported by Unraid OS.
+✅ Configure the storage controller to **%%AHCI|ahci%%** mode with SATA connections.\
+✅ Set the controller to **%%HBA mode|hba-mode%%** (not **%%RAID|raid%%**).\
+✅ Disable **Secure Boot** as it is not supported by Unraid OS.
 
 ### Advanced Settings
 
 ✅ Enable **%%hardware virtualization|hvm%%** features (e.g., **%%Intel VT-x|intel-vt-x%%** or **%%AMD-V|amd-v%%**) for **%%virtual machines (VMs)|vm%%**.\
- ✅ Enable **%%IOMMU|iommu%%** support (Intel VT-d or AMD-Vi) for PCI device assignment to VMs.
+✅ Enable **%%IOMMU|iommu%%** support (Intel VT-d or AMD-Vi) for PCI device assignment to VMs.
 
 ### Troubleshooting Tips
 
 If Unraid OS does not boot, try:
 
 ✅ Adjusting the boot order to: **Forced-FDD**, **USB-HDD**, **USB-ZIP**.\
- ✅ Disabling USB 2.0/3.0 support.\
- ✅ Toggling any Fast Boot features.\
- ✅ Toggling USB keyboard support.
+✅ Disabling USB 2.0/3.0 support.\
+✅ Toggling any Fast Boot features.\
+✅ Toggling USB keyboard support.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@docs/unraid-os/getting-started/set-up-unraid/deploy-and-configure-unraid-os.mdx`
around lines 142 - 159, Normalize the leading spaces for all checklist lines so
indentation is consistent: remove the extra leading spaces before "Set the USB
flash drive as the primary boot device", "Configure the storage controller to
**%%AHCI|ahci%%** mode with SATA connections", "Set the controller to **%%HBA
mode|hba-mode%%** (not **%%RAID|raid%%**)", "Disable **Secure Boot** as it is
not supported by Unraid OS", the Advanced Settings items such as "Enable
**%%hardware virtualization|hvm%%** features" and "Enable **%%IOMMU|iommu%%**
support", and the Troubleshooting Tips lines like "Adjusting the boot order to:
**Forced-FDD**, **USB-HDD**, **USB-ZIP**", ensuring every checklist line uses
the same leading whitespace (either none or one space) so rendered indentation
is uniform.


For further assistance, visit the [Unraid general support forum](https://forums.unraid.net/).
For further assistance, visit the [Unraid general support forum](https://forums.unraid.net/).

:::important
Many motherboards limit boot device selection to 12 hard drives. If your USB flash drive is recognized as a hard drive, you may not be able to boot from it after installing 12 physical hard drives. Configure the BIOS to treat the flash drive as a removable device whenever possible.
:::important
Many motherboards limit boot device selection to 12 hard drives. If your USB flash drive is recognized as a hard drive, you may not be able to boot from it after installing 12 physical hard drives. Configure the BIOS to treat the flash drive as a removable device whenever possible.

If using an add-on HBA, you may be able to disable INT 13h support to prevent its connected drives from appearing in the bootable devices list, helping to stay within the 12-drive limit.
:::
If using an add-on HBA, you may be able to disable INT 13h support to prevent its connected drives from appearing in the bootable devices list, helping to stay within the 12-drive limit.
:::

</details>
228 changes: 228 additions & 0 deletions docs/unraid-os/release-notes/7.3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,228 @@
# Version 7.3.0-beta.1 2026-03-17

This release includes internal boot support, related licensing and onboarding improvements, storage and ZFS enhancements, and a broad set of bug fixes and usability 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)?

### Known issues

For other known issues, see the [7.2.4 release notes](7.2.4.md#known-issues).

### Rolling back

If rolling back earlier than 7.2.4, also see the [7.2.4 release notes](7.2.4.md#rolling-back).

## Changes vs. [7.2.4](7.2.4.md)

### Onboarding and internal boot

New users automatically start in the onboarding wizard, where they choose language, time zone, theme, and activation code settings before selecting a boot option, including internal boot.

Existing users can go to **_Settings → Onboarding Wizard_** to review settings and migrate to internal boot.

For details, see [Onboarding](../getting-started/set-up-unraid/deploy-and-configure-unraid-os.mdx#onboarding).

### Licensing

All new and replacement keys use TPM-based licensing when possible because it is more reliable than flash-based licensing.

To proactively switch to TPM-based licensing, see [How can I move from flash-based licensing to TPM-based licensing](../troubleshooting/licensing-faq.mdx#tpm).

#### Other licensing

- Improvement: Improve handling of missing key file states

### Storage

- New: Show corrupted files in ZFS pool status
- New: Add user-facing control for ZFS ARC max size on **_Settings → Disk Settings → Tunable (zfs_arc_max)_**
- Improvement: Improve visibility into pool and drive health information
- Improvement: Improve duplicate drive detection and related messaging
- Fix: Resolve formatting-related crashes and segfaults in affected array and boot-pool scenarios
- Fix: Prevent drives from spinning down during parity copy as part of parity swap
- Fix: Correct mover availability when emptying an array disk with no pool assigned
- Fix: Correct ZFS pools waking once every 24 hours in affected cases

### WebGUI

- Improvement: Update many user-facing strings from “Flash” to “Boot”
- Improvement: Improve organization of boot-related settings
- Fix: Correct RAM display parsing after dmidecode unit label changes
- Fix: Correct time zone label and identifier issues in affected regions
- Fix: Correct Docker page tab behavior regression
- Fix: Correct Docker port mapping display for localhost-only bindings
- Fix: Correct strict proxy connectivity checks when using HTTP proxies that block CONNECT on port 80
- Fix: Correct rc.crond status typo
- Fix: Auto-restart SSH daemon after network recovery
- Fix: Correct Discord notification formatting issues
- Fix: Correct interface parsing when `ip addr` output includes peer information
- Fix: Correct read-only alerts incorrectly shown in some internal NVMe boot scenarios

### File Manager

- Improvement: Improve File Manager UI and overall performance
- Improvement: Improve same-filesystem move operations
- Improvement: Improve upload behavior
- Fix: Correct path handling issues involving `/sub/` in file paths
- Fix: Correct scrollbar interaction issues during copy or move operations
- Fix: Correct handling of double quotes in directory names
- Fix: Correct move and rename edge cases
- Fix: Preserve empty directories during affected rename operations

### Virtualization

- Improvement: Improve System Devices visibility and VM template workflows
- Improvement: Improve custom VNC port validation and defaults
- Fix: Prevent VMs created from user-defined templates from inheriting the source VM MAC address
- Fix: Correct VM snapshot commit cleanup not updating snapshot metadata correctly
- Fix: Correct libvirt startup issues encountered during testing

## Misc

- New: Add **_Settings → Tailscale_** stub page for easier plugin discovery
- Fix: Correct custom image case model handling on the login page
- Fix: Remove outdated ReiserFS warnings and stale references

### Unraid API

- dynamix.unraid.net 4.30.0 - [see changes](https://github.com/unraid/api/releases)

### Linux kernel

- version 6.18.18-Unraid

### Base distro updates

- aaa_libraries: version 15.1
- at-spi2-core: version 2.58.3
- bash: version 5.3.009
- bash-completion: version 2.17.0
- bind: version 9.20.20
- brotli: version 1.2.0
- btrfs-progs: version 6.19
- ca-certificates: version 20260212
- cifs-utils: version 7.5
- coreutils: version 9.10
- cryptsetup: version 2.8.4
- curl: version 8.18.0
- dmidecode: version 3.7
- dnsmasq: version 2.92
- docker: version 29.3.0-x86_64-1_LT
- dynamix.unraid.net: version 4.30.0
- efibootmgr: version 18
- efivar: version 20201015_cff88dd
- elfutils: version 0.194
- elogind: version 255.22
- etc: version 15.1
- ethtool: version 6.19
- exfatprogs: version 1.3.1
- file: version 5.47
- freeglut: version 3.8.0
- freetype: version 2.14.2
- gawk: version 5.4.0
- gdk-pixbuf2: version 2.44.5
- gettext: version 1.0
- gettext-tools: version 1.0
- git: version 2.53.0
- glew: version 2.3.1
- glib2: version 2.86.4
- glibc-zoneinfo: version 2026a
- gnutls: version 3.8.12
- grub: version 2.14
- harfbuzz: version 13.0.0
- icu4c: version 78.2
- iotop-c: version 1.30
- iperf3: version 3.20
- iproute2: version 6.19.0
- iptables: version 1.8.13
- jansson: version 2.15.0
- krb5: version 1.22.2
- less: version 692
- libarchive: version 3.8.5
- libcap-ng: version 0.9.1
- libdeflate: version 1.25
- libdisplay-info: version 0.3.0
- libdrm: version 2.4.131
- libevdev: version 1.13.6
- libfontenc: version 1.1.9
- libgcrypt: version 1.12.1
- libgpg-error: version 1.59
- libjpeg-turbo: version 3.1.3
- libnetfilter_conntrack: version 1.1.1
- libnftnl: version 1.3.1
- libnl3: version 3.12.0
- libnvme: version 1.16.1
- libpcap: version 1.10.6
- libpng: version 1.6.55
- libtasn1: version 4.21.0
- libunistring: version 1.4.2
- liburing: version 2.14
- libvirt: version 11.10.0-x86_64-1cf_LT
- libvirt-php: version 0.5.8_abf2ec0-x86_64-1_LT
- libX11: version 1.8.13
- libx86: version 1.1.1
- libXcomposite: version 0.4.7
- libXdamage: version 1.1.7
- libXext: version 1.3.7
- libXinerama: version 1.1.6
- libxkbcommon: version 1.13.1
- libxkbfile: version 1.2.0
- libxml2: version 2.15.2
- libXmu: version 1.3.1
- libXpm: version 3.5.18
- libXrandr: version 1.5.5
- libxslt: version 1.1.45
- libXxf86dga: version 1.1.7
- libXxf86vm: version 1.1.7
- lmdb: version 0.9.35
- lsof: version 4.99.6
- lvm2: version 2.03.38
- mcelog: version 210
- mesa: version 26.0.1
- nano: version 8.7.1
- ncurses: version 6.6
- nfs-utils: version 2.8.5
- nghttp2: version 1.68.0
- nghttp3: version 1.15.0
- noto-fonts-ttf: version 2026.03.01
- ntp: version 4.2.8p18
- nvme-cli: version 2.16
- openssl: version 3.5.5
- ovmf-stable: version 202508
- p11-kit: version 0.26.2
- pam: version 1.7.2
- pango: version 1.57.0
- pcre2: version 10.47
- php: version 8.4.15-x86_64-1_LT
- pkgtools: version 15.1
- procps-ng: version 4.0.6
- qemu: version 10.1.2-x86_64-1cf_LT
- rclone: version 1.72.0-x86_64-1_SBo_LT
- readline: version 8.3.003
- shadow: version 4.19.4
- spirv-llvm-translator: version 20260218_56778655
- sqlite: version 3.51.2
- sysstat: version 12.7.9
- talloc: version 2.4.4
- tdb: version 1.4.15
- telnet: version 0.17
- tpm2-tools: version 5.7
- tpm2-tss: version 4.1.3
- userspace-rcu: version 0.15.6
- util-linux: version 2.41.3
- virglrenderer: version 1.2.0
- virtiofsd: version 1.13.2
- wireguard-tools: version 1.0.20260223
- wireless-regdb: version 2026.02.04
- xauth: version 1.1.5
- xfsprogs: version 6.18.0
- xkbcomp: version 1.5.0
- xkeyboard-config: version 2.47
- xkill: version 1.0.7
- xorg-server: version 21.1.21
- xterm: version 407
- xz: version 5.8.2
- zfs: version 2.4.1_6.18.18_Unraid-x86_64-1_LT
- zlib: version 1.3.2
Loading