diff --git a/docs/API/how-to-use-the-api.mdx b/docs/API/how-to-use-the-api.mdx index 05852b74fc..33665b1319 100644 --- a/docs/API/how-to-use-the-api.mdx +++ b/docs/API/how-to-use-the-api.mdx @@ -29,6 +29,8 @@ The Apollo GraphQL Studio provides a comprehensive view of all available queries ::: +### WebGUI method (recommended) + Using the %%WebGUI|web-gui%% is the easiest way to enable the %%GraphQL|graphql%% sandbox: 1. Navigate to ***Settings → Management Access → Developer Options*** diff --git a/docs/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx b/docs/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx index b8e5695a9e..5ca68387f2 100644 --- a/docs/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx +++ b/docs/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx @@ -388,7 +388,7 @@ If you're running a traditional Unraid %%array|array%% and want to add %%ZFS|zfs - **Drive size mismatch in RAIDZ:** %%ZFS|zfs%% treats all disks in a RAIDZ vdev as the size of the smallest one. To ensure the best efficiency, always use identically sized drives within each vdev. -- **Expanding RAIDZ vdevs via the %%WebGUI|web-gui%%:** RAIDZ expansion is available via the %%WebGUI|web-gui%% in Unraid 7.2 and later. Earlier versions (7.1.x) supported expansion via CLI only. +- **Expanding RAIDZ vdevs via the %%WebGUI|web-gui%%:** RAIDZ expansion is available via the %%WebGUI|web-gui%% in Unraid 7.2 and later. Earlier versions (7.1.x) supported expansion via CLI only. For step-by-step instructions, see [RAIDZ expansion](../../using-unraid-to/manage-storage/cache-pools.mdx#raidz-expansion). - **%%ZFS|zfs%% disk vs. full zpool:** A single %%ZFS|zfs%%-formatted disk in the Unraid %%array|array%% does not offer the redundancy or features of a dedicated %%ZFS|zfs%% pool. To leverage advanced functionality, use standalone pools. diff --git a/docs/unraid-os/getting-started/set-up-unraid/customize-unraid-settings.mdx b/docs/unraid-os/getting-started/set-up-unraid/customize-unraid-settings.mdx index b18cbbf1fc..f888a604ca 100644 --- a/docs/unraid-os/getting-started/set-up-unraid/customize-unraid-settings.mdx +++ b/docs/unraid-os/getting-started/set-up-unraid/customize-unraid-settings.mdx @@ -19,11 +19,11 @@ Unraid OS automatically functions but allows further customization of settings s Don't forget - the %%WebGUI|web-gui%% includes built-in help. To access help for a specific field, click the prompt next to it, or use the **Help** icon ![Help icon](/img/helpicon.png) at the top right of the interface to toggle help for all fields. -## System Settings +## System settings **System Settings** enable you to configure key functionalities like network, share, %%VM|vm%%, and disk settings. -### CPU Pinning +### CPU pinning %%CPU Pinning|cpu-pinning%% allows you to assign specific CPU cores to %%VMs|vm%% (Virtual Machines) or Docker containers. This is particularly important for performance-sensitive workloads, such as gaming %%VMs|vm%%. Even if you manually assign Docker containers to avoid conflicts with your gaming %%VM|vm%%, the host operating system may still utilize those cores for tasks like managing the %%WebGUI|web-gui%%, running a %%parity check|parity-check%%, or performing %%BTRFS|btrfs%% operations. @@ -31,7 +31,7 @@ Don't forget - the %%WebGUI|web-gui%% includes built-in help. To access help for - When you isolate a core, it becomes dedicated to the %%VM|vm%% or container and is no longer accessible to Unraid OS. - You can pin cores without needing to restart your server, but applying CPU isolation changes does require a system restart. -### Date & Time +### Date & time On this page, you can set your time zone and toggle the use of up to four NTP servers. You should adjust Unraid to match your time zone for accurate timekeeping. @@ -39,7 +39,7 @@ On this page, you can set your time zone and toggle the use of up to four NTP se ![Toolbar - Settings](/img/date-time.png) -### Disk Settings +### Disk settings You can modify additional settings for your disk devices on this page. Enable your %%array|array%% to start automatically on boot, adjust disk %%spin-down timers|spin-down-timers%%, and even change advanced driver settings like %%SMART polling frequency|smart-polling%%. @@ -69,7 +69,7 @@ Unraid defaults to the hostname `tower`, but you can change it here. You can als ![Settings - Identification](/img/settings-identification.png) -### Management Access +### Management access You can configure various access settings for your Unraid server, including enabling Telnet or %%SSH|ssh%%, setting ports for %%SSL|ssl%%/%%TLS|tls%%, HTTP, and HTTPS, and defining the default landing page for Unraid. For detailed information about securing your %%WebGUI|web-gui%% with %%SSL|ssl%% certificates, see [Securing your connection](../../system-administration/secure-your-server/securing-your-connection.mdx). @@ -77,7 +77,7 @@ You can configure various access settings for your Unraid server, including enab ![Settings - Management Access](/img/settings-management-access.png) -### Network Settings +### Network settings By default, Unraid tries to obtain an IP address from a DHCP server on your local network, usually provided by your router. On this page, you can configure a static IP address, set up %%bonding|nic-bonding%%, %%bridging|nic-bridging%%, or explore other options. While setting a static IP is recommended, it is not necessary to use Unraid. @@ -85,7 +85,89 @@ By default, Unraid tries to obtain an IP address from a DHCP server on your loca ![Network Settings](/img/settings-network.png) -### Power Mode +#### WiFi setup + +Unraid supports WiFi connectivity for situations where a wired network connection isn't practical or available. While a wired connection is generally recommended for better stability and performance, a wireless setup can be a suitable alternative when running a cable isn't an option. + +:::important[Initial setup requirements] + +For the initial WiFi setup, you'll need either: + +- A local keyboard and monitor connected to your server (boot into GUI mode), or +- A temporary wired connection to access the %%WebGUI|web-gui%% + +Once WiFi is configured, you can remove the wired connection and manage your server wirelessly. + +::: + +##### Setting up WiFi + +1. Access the %%WebGUI|web-gui%% and go to ***Settings → Network Settings → Wireless wlan0***. +2. Enable WiFi by toggling the **Enable WiFi** option. +3. Configure the **Regulatory Region**: + - In most cases, it’s best to leave this set to **Automatic**. + - If your preferred network isn't appearing in the scan results, set it to your specific location (country/region). +4. Scan for available networks: + - Available WiFi networks should be listed. + - Click the **Connect to WiFi network** (ᯤ) icon next to your preferred network. +5. Enter your network credentials: + - Type your WiFi password. + - Review and adjust any additional settings if needed. + - Click **Join this network** to connect. + +:::tip[Docker containers and WiFi] + +If you plan to use Docker containers with WiFi, ensure to unplug any wired connections **before** starting the Docker service. This helps prevent network configuration conflicts that can occur when both interfaces are active simultaneously. + +::: + +##### Supported WiFi features + +Unraid's WiFi implementation supports the following: + +- **WPA2** and **WPA3 security protocols**, including WPA2/WPA3 Enterprise networks. If both WPA2 and WPA3 are available, Unraid will automatically use WPA3 for enhanced security. +- **Modern WiFi adapters** that have Linux in-kernel driver support. Older adapters may not be compatible. + +:::info[USB WiFi adapters] + +If you're using a USB WiFi adapter, check this list of [USB WiFi adapters supported with Linux in-kernel drivers](https://github.com/morrownr/USB-WiFi/blob/main/home/USB_WiFi_Adapters_that_are_supported_with_Linux_in-kernel_drivers.md) to ensure compatibility. + +If your WiFi adapter isn't detected, please start a new thread on the [Unraid forums](https://forums.unraid.net/) and provide your diagnostics for investigation. + +::: + +##### WiFi limitations + +WiFi has some limitations compared to wired networking: + +- You can only connect to **one WiFi network** at a time. +- Only one wireless NIC is supported - `wlan0`. If your system has multiple wireless adapters (`wlan1`, `wlan2`, etc.), only `wlan0` will be used. +- Unlike wired connections, you **cannot combine multiple wireless connections** to improve reliability. +- **`wlan0` cannot participate in a bond**. You cannot combine WiFi and Ethernet connections in a bond configuration. +- It's best to use either a wired connection or WiFi, but **not both at the same time**. If you need to temporarily connect or disconnect a network cable while using WiFi, your server should automatically adjust to use the active connection within about a minute. For important information about Docker containers when switching between connection types, see the **Docker and virtual machine considerations** section below. + +##### Docker and virtual machine considerations + +When using WiFi, there are specific considerations for Docker containers and %%virtual machines|vm%%: + +###### Docker containers + +- On ***Settings → Docker***, when WiFi is enabled, the system automatically uses **ipvlan** for custom networks (macvlan is not supported with WiFi). +- Host access to custom networks must be disabled in ***Settings → Docker***. +- Container **Network Type** cannot use `br0`, `bond0`, or `eth0`. + +:::caution + +Docker cannot participate in two networks sharing the same subnet. If you switch between wired and wireless connections, you will need to restart Docker and reconfigure all existing containers to use the new interface. This network configuration change requires container reconfiguration. It's strongly recommended to choose either wired or wireless and not switch between them. +::: + +###### Virtual machines + +It's recommended to set your %%VM|vm%% **Network Source** to **virbr0** (Private NAT). This mode works with any number of %%VMs|vm%% and provides network access through %%NAT|nat%%. Note that mDNS does not work through NAT, so the %%VM|vm%% will need to access other local network devices by IP address, not hostname. You can add IP addresses and hostnames to the hosts file on the %%VM|vm%% operating system to allow access by hostname. The %%VMs|vm%% won't be directly accessible from other devices on your LAN, but you can still access them via %%VNC|vnc-session%% through the host. + +For more information about %%VM|vm%% networking, see [Overview and system prep](../../using-unraid-to/create-virtual-machines/overview-and-system-prep.mdx). + +### Power mode The **Power Mode** setting allows you to optimize your Unraid server for energy efficiency, balanced operation, or maximum performance. You can choose from available modes - **Best power efficiency**, **Balanced operation**, or **Best performance** - to match your workload and energy preferences. Adjusting Power Mode can help reduce power consumption, lower system temperatures, or provide additional resources for demanding tasks. @@ -95,7 +177,7 @@ Changes take effect immediately and do not require a system restart. ![Power Mode](/img/settings-powermode.png) -### Global Share Settings +### Global share settings %%User shares|user-share%% can greatly simplify the organization and access of content across multiple disks in the %%array|array%%. You have the option to specify which disks are allowed to participate in %%user shares|user-share%% through global inclusion or exclusion settings. @@ -103,7 +185,7 @@ Changes take effect immediately and do not require a system restart. ![Global Share Settings](/img/settings-globalshare.png) -### UPS Settings +### UPS settings Unraid can be connected to an APC (or compatible) UPS (Uninterruptible Power Supply) to allow the system to safely shut down during a power loss while still receiving battery power. You can configure the UPS connection and set policies for the shutdown command on this page. @@ -111,19 +193,19 @@ Unraid can be connected to an APC (or compatible) UPS (Uninterruptible Power Sup ![UPS Settings](/img/settings-ups.png) -### VM Manager +### VM manager -**Virtual machines** (VMs) can turn your server into a desktop or media player, and run applications not designed for Linux. For details on managing %%VMs|vm%% on Unraid, see [VM setup](../../using-unraid-to/create-virtual-machines/vm-setup.mdx). +**Virtual machines** can turn your server into a desktop or media player, and run applications not designed for Linux. For details on managing %%VMs|vm%% on Unraid, see [VM setup](../../using-unraid-to/create-virtual-machines/vm-setup.mdx).
![VM Manager](/img/settings-vmmanager.png)
-## Network Services +## Network services **Network Services** let you configure network communication protocols on your Unraid server, which are essential for user and disk shares. You can also enable an %%FTP|ftp%% server, a logging server, and set up a %%VPN|vpn-tunnel%% for secure remote access. -### NFS (Network File System) +### NFS (Network file system) NFSv4 support is available in Unraid. You can enable or disable it for %%user shares|user-share%% and adjust the `fuse_remember` tunable to help resolve *NFS Stale File Handle* errors. @@ -131,7 +213,7 @@ NFSv4 support is available in Unraid. You can enable or disable it for %%user sh ![NFS](/img/settings-nfs.png) -### SMB (Server Message Block) +### SMB (Server message block) The SMB protocol is used by Microsoft Windows clients. From this page, you can enable it, define a workgroup, or join an Active Directory domain. @@ -139,7 +221,7 @@ The SMB protocol is used by Microsoft Windows clients. From this page, you can e ![SMB](/img/settings-smb.png) -### FTP (File Transfer Protocol) +### FTP (File transfer protocol) Users can connect via %%FTP|ftp%% only if they are added to the **FTP users** field on this page. If no users are added, the %%FTP|ftp%% service will not start. @@ -147,7 +229,7 @@ Users can connect via %%FTP|ftp%% only if they are added to the **FTP users** fi ![FTP](/img/settings-ftp.png) -### Syslog Server +### Syslog server The %%Syslog server|syslog-server%% permanently stores your system log, which is useful for troubleshooting since Unraid clears the log after each reboot. @@ -171,7 +253,7 @@ You can also configure your server as a %%Subnet Router|subnet-routing%% for loc ![Tailscale Settings](/img/settings-tailscale.png) -### VPN Manager +### VPN manager You can establish a %%VPN|vpn-tunnel%% connection to your Unraid server using [%%Wireguard|wireguard%%](https://www.wireguard.com/) for secure internet connections. @@ -179,7 +261,7 @@ You can establish a %%VPN|vpn-tunnel%% connection to your Unraid server using [% ![VPN Manager](/img/settings-vpnmanager.png) -## User Preferences +## User preferences User Preferences allow you to configure various aspects of your interactions with Unraid OS, including notifications, display settings, UI customization, and the %%Mover|mover%% schedule. @@ -191,7 +273,7 @@ You can enable/disable the requirement for confirmations when performing various ![Confirmations](/img/settings-confirmations.png) -### Console Settings +### Console settings Allows you to customize the local system console. You can select the keyboard layout, adjust the screen blanking timeout, and enable or disable persistent Bash history across reboots. These options enhance your experience when using Unraid with a connected monitor and keyboard. @@ -199,7 +281,7 @@ Allows you to customize the local system console. You can select the keyboard la ![Console Settings](/img/settings-console.png) -### Display Settings +### Display settings Customize the Unraid %%WebGUI|web-gui%% appearance on this page by adjusting the date and time format, number format, and toggling between tabbed and non-tabbed views. You can also select the temperature unit and choose from different themes for the user interface. @@ -207,7 +289,7 @@ Customize the Unraid %%WebGUI|web-gui%% appearance on this page by adjusting the ![Display Settings](/img/settings-display.png) -### Notification Settings +### Notification settings Unraid can send you notifications about important system events, updates, and alerts through your browser, email, or third-party notification services. The Notification Settings page allows you to control how and when you receive these notifications. @@ -255,11 +337,11 @@ Enable **Browser** notifications for immediate visibility when using the %%WebGU ::: -#### SMTP Settings +#### SMTP settings To receive email notifications, you need to configure your email server settings. Unraid supports many email providers including Gmail, Outlook, and custom SMTP servers. -The SMTP Settings can be found at ***Settings → User Preferences → Notification Settings → SMTP Settings***. +The SMTP settings can be found at ***Settings → User Preferences → Notification Settings → SMTP Settings***. **Basic configuration:** @@ -325,7 +407,7 @@ Always use app passwords instead of your main Gmail password. App passwords can ::: -#### Notification Agents +#### Notification agents Notification agents allow you to send alerts to third-party services and mobile apps. Unraid includes built-in support for many popular notification services. @@ -370,7 +452,7 @@ You can enable multiple agents simultaneously. For example, you might use Discor The Scheduler settings page allows you to easily configure the frequency for automated tasks including %%parity checks|parity-check%%, the cache %%Mover|mover%%, and %%TRIM/Discard|trim-discard%% operations for SSDs. -## User Utilities +## User utilities Third-party plugins are displayed here, enhancing Unraid’s functionality and giving you more control over your server. For example, the [Community Applications plugin](../../using-unraid-to/run-docker-containers/community-applications.mdx) is included. Other plugins offer features for system monitoring, maintenance, storage management, and `appdata` backups. diff --git a/docs/unraid-os/release-notes/7.2.0.md b/docs/unraid-os/release-notes/7.2.0.md index 75907c154d..346c75d034 100644 --- a/docs/unraid-os/release-notes/7.2.0.md +++ b/docs/unraid-os/release-notes/7.2.0.md @@ -29,7 +29,7 @@ If rolling back earlier than 7.1.4, also see the [7.1.4 release notes](7.1.4.md# #### ZFS RAIDZ expansion -You can now expand your single-vdev RAIDZ1/2/3 pools, one drive at a time: +You can now expand your single-vdev RAIDZ1/2/3 pools, one drive at a time. For detailed instructions, see [RAIDZ expansion](../../using-unraid-to/manage-storage/cache-pools.mdx#raidz-expansion). - With the array running, on **_Main → Pool Devices_**, select the pool name to view the details - In the **Pool Status** area, check for an **Upgrade Pool** button. If one exists, you'll need to click that before continuing. Note that upgrading the pool will limit your ability to downgrade to earlier releases of Unraid (7.1 should be OK, but not 7.0) diff --git a/docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx b/docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx index 3267de77ca..9215c8a316 100644 --- a/docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx +++ b/docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx @@ -148,7 +148,7 @@ This displays RAM usage in a human-readable format. The `-h` flag means sizes wi :::tip[Understand the output] -A low "available" memory reading doesn’t necessarily indicate a problem—Linux aggressively caches data for performance. +A low "available" memory reading doesn't necessarily indicate a problem—Linux aggressively caches data for performance. ::: diff --git a/docs/unraid-os/troubleshooting/common-issues/unclean-shutdowns.mdx b/docs/unraid-os/troubleshooting/common-issues/unclean-shutdowns.mdx index fe5c98bdaa..f5c9d87d9c 100644 --- a/docs/unraid-os/troubleshooting/common-issues/unclean-shutdowns.mdx +++ b/docs/unraid-os/troubleshooting/common-issues/unclean-shutdowns.mdx @@ -117,7 +117,7 @@ To enable VM hibernation: - 1. **Install %%QEMU|qemu%% %%Guest Agent|guest-agent%%:** + 1. **Install %%QEMU|qemu%% %%Guest Agent|guest-agent%%:** ```bash # Ubuntu/Debian sudo apt install qemu-guest-agent @@ -179,7 +179,6 @@ In this section, we’ll cover how to configure timeouts for various systems and :::tip[When to increase timeouts] If you're experiencing unclean shutdowns or containers that crash during shutdown, consider increasing the general shutdown timeout to **180 seconds** (or **300+ seconds** if you have multiple %%VMs|vm%%). This gives services more time to shut down gracefully. - ::: ### Shutdown sequence @@ -226,11 +225,11 @@ This section provides in-depth information about configuring timeouts for differ Configure VM shutdown timeouts in **_Settings → VM Manager → VM Shutdown_** (enable Advanced view). -**How it works:** + **How it works:** -- %%VMs|vm%% go through three shutdown stages, each consuming the full VM timeout -- All %%VMs|vm%% in each stage are processed simultaneously -- Total VM shutdown time = VM timeout × 3 + - %%VMs|vm%% go through three shutdown stages, each consuming the full VM timeout + - All %%VMs|vm%% in each stage are processed simultaneously + - Total VM shutdown time = VM timeout × 3 **Common issues:** @@ -248,9 +247,7 @@ Configure VM shutdown timeouts in **_Settings → VM Manager → VM Shutdown_** ::: :::warning[No safe timeout without hibernation] - Without hibernation and %%QEMU|qemu%% %%Guest Agent|guest-agent%%, there isn't a truly safe timeout for Windows %%VMs|vm%%. Dialog boxes or ongoing update installations could render any timeout inadequate, leading to forced shutdowns and data corruption risk. - ::: #### Docker timeouts diff --git a/docs/unraid-os/troubleshooting/faq.mdx b/docs/unraid-os/troubleshooting/faq.mdx index c68ebcc860..c6b89588f8 100644 --- a/docs/unraid-os/troubleshooting/faq.mdx +++ b/docs/unraid-os/troubleshooting/faq.mdx @@ -90,9 +90,7 @@ If you had [Unraid Connect](../../unraid-connect/overview-and-setup.mdx) enabled Refer to [Reset your password](../system-administration/secure-your-server/user-management.mdx#reset-your-password). :::note - If you're using encrypted drives and forget the encryption password, data recovery isn't possible - there is no backdoor. - :::
@@ -110,7 +108,6 @@ If you're using encrypted drives and forget the encryption password, data recove 7. Wipe existing filesystems from each data drive: :::danger[Critical: Destructive Operation] - **This step will permanently erase ALL data on the specified drive(s) and is IRREVERSIBLE!** - **Verify you have backups** of any data you need before proceeding @@ -126,7 +123,6 @@ wipefs /dev/sdX ``` Replace `X` with the correct drive letter (e.g., sda, sdb, sdc) - ::: @@ -235,16 +231,13 @@ Unraid features a unique storage architecture that distinguishes it from traditi marginTop: "1.5rem", }} > - Why convert from MBR to GPT? MBR (Master Boot Record) partitioning supports disks up to 2TB and only allows a maximum of four primary partitions. On the other hand, GPT (%%GUID|guid%% Partition Table) can handle much larger disks and nearly unlimited partitions. Converting to GPT is advisable if you work with larger drives or want better partition management. :::important[Use **Maintenance Mode**] - Before starting the conversion process, put your %%array|array%% into **Maintenance Mode**. This step ensures no writes occur during the conversion, protecting your data. - :::
- Conversion process
@@ -294,9 +286,7 @@ This process keeps your data safe while changing the partitioning style. Yes. The **br0** bridge is a Linux network bridge allowing Docker containers and %%VM|vm%%s to connect directly to your local area network (LAN) with their IP addresses. It acts as a virtual network switch that connects your physical network interface to the virtual interfaces used by containers and %%VM|vm%%s. :::note - Disabling br0 means that %%VMs|vm%% and Docker containers will not have direct access to the LAN and may lose some advanced networking features. - :::
@@ -385,9 +375,7 @@ If problems persist, try accessing the %%WebGUI|web-gui%% from another browser o If you need more time with your [30-day free trial](https://unraid.net/download) of Unraid, you can extend it. Once your original trial expires, stop the %%array|array%% and go to the **Registration** page. You should see a button that allows you to request a 15-day extension. You can do this twice for a total of 60 days before you need to purchase a license. :::important - You must use the same USB flash device to continue your trial. Changing the flash device will require starting a new trial from scratch. - :::
diff --git a/docs/unraid-os/using-unraid-to/create-virtual-machines/vm-setup.mdx b/docs/unraid-os/using-unraid-to/create-virtual-machines/vm-setup.mdx index ca06a92dfd..1456ee776d 100644 --- a/docs/unraid-os/using-unraid-to/create-virtual-machines/vm-setup.mdx +++ b/docs/unraid-os/using-unraid-to/create-virtual-machines/vm-setup.mdx @@ -341,7 +341,6 @@ BIOS type can only be set when creating a new %%VM|vm%%. - See [%%QEMU|qemu%% 9p documentation](http://wiki.qemu.org/Documentation/9psetup) for details. **Network settings:** - - Modify the **Network MAC address** or select an alternate **Network Bridge**. - Click the refresh symbol to auto-generate a new MAC address. - Add additional virtual network interfaces as needed. @@ -537,7 +536,7 @@ The %%VM|vm%% should now continue booting into your OS. :::tip -If this happens frequently, check your VM’s boot order and ensure the correct %%vDisk|vdisk%% or ISO is set as the primary boot device in the VM settings. +If this happens frequently, check your VM's boot order and ensure the correct %%vDisk|vdisk%% or ISO is set as the primary boot device in the VM settings. ::: @@ -585,7 +584,7 @@ This error typically indicates %%IOMMU|iommu%% group conflicts or missing interr :::note -For detailed %%IOMMU|iommu%% group explanations, we recommend checking out [Alex Williamson’s blog](http://vfio.blogspot.com/2014/08/iommu-groups-inside-and-out.html). +For detailed %%IOMMU|iommu%% group explanations, we recommend checking out [Alex Williamson's blog](http://vfio.blogspot.com/2014/08/iommu-groups-inside-and-out.html). ::: diff --git a/docs/unraid-os/using-unraid-to/manage-storage/array/overview.mdx b/docs/unraid-os/using-unraid-to/manage-storage/array/overview.mdx index d6c33498c2..9438e6c922 100644 --- a/docs/unraid-os/using-unraid-to/manage-storage/array/overview.mdx +++ b/docs/unraid-os/using-unraid-to/manage-storage/array/overview.mdx @@ -170,7 +170,7 @@ When using Unraid, the speed at which you can read files is mainly determined by | **Read speed** | SSD: 400–550 MB/s, NVMe: 250–7,000 MB/s\* | SSD: 400–550 MB/s, NVMe: 250–7,000 MB/s\* | HDD: 70–250 MB/s (per disk) | | **Write speed** | SSD: 400–550 MB/s, NVMe: 250–7,000 MB/s\* | SSD: 400–550 MB/s, NVMe: 250–7,000 MB/s\* | 20–120 MB/s (parity mode dependent) | | **Data protection** | %%RAID 1\|raid1%%/%%RAID 10\|raid10%%; %%RAID 5\|raid5%%/%%RAID 6\|raid6%% (experimental, not for critical data) | %%RAID 1\|raid1%%/%%RAID 10\|raid10%%; %%RAIDZ1\|raidz1%%/%%RAIDZ2\|raidz2%%/%%RAIDZ3\|raidz3%% (stable, production-ready) | Parity-based, file system agnostic | -| **Expansion** | Mix drive sizes; add/remove devices dynamically | Limited add/remove device support; cannot remove from RAIDZ; single-device add to expand single-vdev RAIDZ in Unraid 7.2 | Add drives, but no striping or performance scaling | +| **Expansion** | Mix drive sizes; add/remove devices dynamically | Limited add/remove device support; cannot remove from RAIDZ; single-device add to expand single-vdev RAIDZ in Unraid 7.2 (see [RAIDZ expansion](../cache-pools.mdx#raidz-expansion)) | Add drives, but no striping or performance scaling | | **Recovery complexity** | Higher risk of data loss; %%BTRFS\|btrfs%% tools required | Higher risk of data loss; %%ZFS\|zfs%% tools required | Easier parity-based rebuilds | | **Best for** | Apps, VMs, frequent writes | Apps, VMs, frequent writes, enterprise workloads | Bulk storage, media libraries | diff --git a/docs/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx b/docs/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx index 839300cf2a..d46ce0d966 100644 --- a/docs/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx +++ b/docs/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx @@ -81,7 +81,7 @@ To convert a pool to BTRFS or ZFS: ### Adding drives to create a multi-device pool -Once your pool is formatted as %%BTRFS|btrfs%% or %%ZFS|zfs%%, you can add more drives for redundancy and to expand storage. +Once your pool is formatted as %%BTRFS|btrfs%% or %%ZFS|zfs%%, you can add more drives for redundancy and to expand storage. For detailed instructions on adding disks to existing pools, see [Adding disks to a pool](#adding-disks-to-a-pool). To add more drives for redundancy: @@ -110,14 +110,61 @@ If you want to add disks to your pool, make sure your pool is already formatted ::: -To add a disk to a pool: +### BTRFS pools + +To add a disk to a %%BTRFS|btrfs%% pool: 1. Stop the %%array|array%%. 2. In the **Main** tab, open the pool. -3. In the Pool Devices section, set **Slots** to the exact number of additional devices. +3. In the **Pool Devices** section, set **Slots** to the exact number of additional devices. 4. Assign the new devices to the available slots. 5. Start the %%array|array%% to enable the changes. +:::note + +After starting the %%array|array%%, %%BTRFS|btrfs%% automatically begins a **Balance** operation to redistribute data across all devices in the pool. This process may take several hours or even days, depending on the size of your pool and the amount of data stored. During this time, your pool may appear busy, but you can continue using it normally. You can monitor the Balance progress in the **Main** tab by clicking the first pool device and checking **Balance Status**. + +::: + +### ZFS pools + +Expanding %%ZFS|zfs%% pools depends on your type of pool configuration: + +- **Single-vdev RAIDZ1/2/3 pools:** A pool with one group of drives in a RAIDZ configuration. Can be expanded one drive at a time. See [RAIDZ expansion](#raidz-expansion) below. +- **Mirrored pools:** A pool where drives are paired together in mirrors. Can add additional mirror pairs to increase capacity. +- **Multi-vdev pools:** A pool with multiple groups of drives (e.g., multiple RAIDZ groups or multiple mirror pairs). Cannot be expanded by adding individual drives to existing groups. + +:::important + +Not all %%ZFS|zfs%% pools can be expanded by adding devices. Only single-vdev RAIDZ1/2/3 pools allow for one-drive-at-a-time expansion. Other pool configurations require you to add complete vdevs, such as adding a new mirror pair to a mirrored pool or adding a new vdev of the same width to a RAIDZ pool. + +::: + +:::tip[Planning for future expansion] + +If you're creating a new two-device %%ZFS|zfs%% pool and plan to expand it later by adding drives one at a time, choose **RAIDZ1** during initial setup instead of the default mirrored configuration. While two-device pools default to mirrored (which provides redundancy), choosing RAIDZ1 allows you to expand the pool incrementally in the future without migrating your data. If you're not planning to expand beyond two drives, the default mirrored configuration is recommended for its simplicity and performance. + +::: + +#### RAIDZ expansion + +Starting with Unraid 7.2, you can expand single-vdev RAIDZ1/2/3 pools one drive at a time. This feature allows you to grow your pool capacity incrementally without rebuilding the entire pool. + +To expand a single-vdev RAIDZ pool: + +1. With the %%array|array%% running, on ***Main → Pool Devices***, select the pool name to view the details. +2. In the **Pool Status** area, check for an **Upgrade Pool** button. If one exists, you'll need to click that before continuing. Note that upgrading the pool will limit your ability to downgrade to earlier releases of Unraid. +3. Stop the %%array|array%%. +4. On ***Main → Pool Devices***, add a slot to the pool. +5. Select the appropriate drive (must be at least as large as the smallest drive in the pool). +6. Start the %%array|array%%. + +:::caution + +If you see an "invalid expansion" warning, the pool needs to be upgraded first using the **Upgrade Pool** button mentioned in step 2. + +::: + --- ## Removing disks from a pool @@ -134,7 +181,7 @@ Removing a disk from a %%BTRFS|btrfs%% or %%ZFS|zfs%% multi-device %%cache pool| ### Changing pool RAID levels -%%BTRFS|btrfs%% provides the ability to change %%RAID|raid%% levels for %%cache pools|cache-pool%% dynamically, allowing you to adjust settings without stopping the %%array|array%% or losing any data. This flexibility lets you optimize for performance, redundancy, or storage efficiency as your requirements change. +%%BTRFS|btrfs%% provides the ability to change %%RAID|raid%% levels for %%cache pools|cache-pool%% dynamically, allowing you to adjust settings without stopping the %%array|array%% or losing any data. This flexibility lets you optimize for performance, redundancy, or storage efficiency as your requirements change. For information on adding disks to %%BTRFS|btrfs%% pools, see [BTRFS pools](#btrfs-pools).

Supported %%RAID|raid%% Levels

diff --git a/docs/unraid-os/using-unraid-to/manage-storage/file-systems.mdx b/docs/unraid-os/using-unraid-to/manage-storage/file-systems.mdx index adf946e683..77dbbd5baa 100644 --- a/docs/unraid-os/using-unraid-to/manage-storage/file-systems.mdx +++ b/docs/unraid-os/using-unraid-to/manage-storage/file-systems.mdx @@ -98,7 +98,7 @@ For more details on adding existing drives, see the [release notes](../../releas - **For array drives:** %%XFS|xfs%% is generally the best choice for most users. EXT4 is also a solid option if you prefer a more traditional Linux file system. - **For high-performance or advanced features:** Choose %%ZFS|zfs%% or %%BTRFS|btrfs%% for %%cache pools|cache-pool%% or multi-device setups. See the [ZFS storage](../../advanced-configurations/optimize-storage/zfs-storage.mdx) page for detailed %%ZFS|zfs%% guidance. -- **For mixed or expanding pools:** %%BTRFS|btrfs%% is ideal if you want to use different drive sizes or easily add or remove devices. +- **For mixed or expanding pools:** %%BTRFS|btrfs%% is ideal if you want to use different drive sizes or easily add or remove devices. See [BTRFS pools](../cache-pools.mdx#btrfs-pools) for details on adding disks to %%BTRFS|btrfs%% pools. - **For existing drives:** Use NTFS or exFAT only when adding existing drives with data; add them before adding parity. If you're uncertain, starting with the defaults is a good approach: use %%XFS|xfs%% for %%array|array%% drives and %%BTRFS|btrfs%% for %%cache pools|cache-pool%%. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx b/i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx index 04e308a752..5662da3f98 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx +++ b/i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx @@ -138,7 +138,7 @@ The hybrid %%ZFS|zfs%%-in-array approach is helpful for specific backup or repli 5. 在 **文件系统** 下，选择 `zfs` 或 `zfs-encrypted`。
- ![](./assets/zfs9.png) + ![](./assets/zfs10.png)
6. 点击 **应用**。