File systems
Selecting a file system type
Selecting the right file system for your Unraid array or cache pool is crucial. It helps you achieve a balance between performance, data protection, and advanced features. Unraid supports several modern Linux file systems, each with its own unique strengths and specific use cases:
File System | Data Protection | Space Efficiency | Advanced Features | Best Use Case |
---|---|---|---|---|
XFS | No built-in redundancy | 100% | Robust against corruption | Default for array drives; high reliability |
ZFS | RAIDZ1/RAIDZ2/RAIDZ3, mirrors, etc. | Varies by RAID level | Checksums, Snapshots, RAID | Multi-device pools, VMs, Docker, advanced users |
BTRFS | RAID 0/1/10/5/6, mirrors | Varies by RAID level | Checksums, Snapshots, RAID | Multi-device pools, mixed SSD/HDD, flexible pools |
- XFS
- ZFS
- BTRFS
XFS is the default file system for array drives in Unraid. It’s known for its robustness and ability to recover from corruption after unexpected shutdowns or crashes. Each drive formatted with XFS acts as a self-contained file system, making data recovery straightforward on any Linux system.
ZFS is a modern file system that comes with advanced features such as checksums to detect bit rot, snapshots for backups, and native RAID support options like RAIDZ1/RAIDZ2/RAIDZ3 and mirrors. ZFS can be utilized for both single-device and multi-device pools in Unraid 6.12 and later.
- Data protection: Supports various RAID levels for redundancy.
- Performance: Excellent, particularly for multi-device pools.
- Best for: High-performance environments, virtual machines, Docker, or when advanced features like snapshots are required.
For a deep dive into ZFS features, configuration, and best practices, check out our dedicated section on ZFS storage.
BTRFS provides flexible RAID support, checksums for data integrity, and efficient management of mixed-size drives in pools. It serves as the default file system for cache pools and supports both single-device and multi-device configurations.
- Mixing different file system types in your Unraid system is perfectly acceptable; the Unraid parity system works independently of the file system used.
- Always format and partition drives within Unraid to ensure compatibility.
- Linux systems can read these file systems natively; however, Windows and macOS will require additional software for access.
- You can encrypt drives for enhanced security, but keep in mind that encrypted drives might pose challenges for recovery if corruption occurs.
- For transfer drives or external devices, it's recommended to use the Unassigned Devices plugin, which supports additional file systems.
- For array drives: XFS is generally the best choice for most users.
- For high-performance or advanced features: Choose ZFS or BTRFS for cache pools or multi-device setups.
- For mixed or expanding pools: BTRFS is ideal if you want to use different drive sizes or easily add or remove devices.
If you're uncertain, starting with the defaults is a good approach: use XFS for array drives and BTRFS for cache pools.
Setting a file system type
When adding a new drive to Unraid, you can select the file system type that works best for your needs. The file system determines how data is organized and protected on the disk.
To set the file system type:
-
Set the default globally:
- Navigate to Settings → Disk Settings to set the default file system for new array drives only.
- Unraid defaults to XFS for array drives.
- Note: There is currently no global default setting for cache pools. They will always default to BTRFS if left to "auto".
-
Set the file system for an individual drive:
- Stop the array.
- Click on the drive in the Main tab.
- Choose your desired file system type from the drop-down menu.
- If you select auto, Unraid will use the global default.
- For multi-device cache pools, only BTRFS or ZFS are supported.
Creating a file system (formatting)
Before using a new disk in Unraid, you must format it with the selected file system. Remember, formatting will erase all existing content on the drive.
To begin with formatting:
- Start the array.
- Identify unmountable drives: Drives that are not recognized will appear as unmountable.
- Verify drive selection: Verify that all unmountable drives are the ones you want to format.
- Confirm and format: Check the box to confirm, read the warning dialog carefully, and click Format.
- Monitor the process: The format process will begin. For new disks, Unraid will first rewrite the partition table.
- Wait for completion: Formatting usually takes a few minutes. If you don't see progress, refresh the Main tab.
Once formatting is complete, the drive is ready to store files.
Changing a file system type
You may want to change the file system type on a specific drive to take advantage of new features or to ensure compatibility with your other drives.
Changing the file system type will erase all existing data on the drive. Always back up any important files before proceeding.
To change the file system type on a particular drive:
- Stop the array: Begin by stopping your array to ensure no operations are occurring during the change.
- Select the drive: In the Main tab, click on the drive that you want to change the format for.
- Choose the new file system: From the drop-down menu, select the desired file system format. If you have multiple drives to change, repeat this step for each one.
- Start the array: Once you have selected the new file systems, start your array again.
- Format unmountable drives: The Main tab will display an option to format unmountable drives. Take a moment to check the list and ensure that only the drives you intend to change are included.
- Confirm and format: Check the confirmation box to acknowledge the change, then click the Format button to proceed.
- Wait for the process to finish: Formatting usually takes just a few minutes. If you notice that the status isn't updating, you can refresh the Main tab to check the progress.
If you encounter any issues, feel free to visit the Unraid forums. Attach your system diagnostics zip file (found under Tools → Diagnostics) for assistance.
Converting to a new file system type
If you want to change the file system type on a drive but keep its data, you must migrate the contents before reformatting. This process is especially common for users moving away from the deprecated ReiserFS (used in older Unraid versions) to XFS or BTRFS, but it applies to any file system conversion.
This process requires temporarily moving your data to another location. Make sure you have enough free space elsewhere in your array or on an external device before you begin.
To safely convert to a new file system type:
- Copy all data off the drive: Move your files to another location. This could be another drive in your array, a cache pool, or an external backup.
- If you're converting multiple drives, do so one at a time to minimize risk and space requirements.
- Many users schedule conversions after adding a new drive to the array to create the needed free space.
- Change the file system type: Follow the procedure for changing a file system type. This will format the drive and erase all content, leaving you with a blank drive in the new format.
- Copy your data back: Move the saved files back to the newly formatted drive.
- Repeat as needed: If you have more than one drive to convert, repeat these steps for each drive, transferring data as needed.
The process can take several hours, depending on the amount of data and the speed of your drives. Most of the time is spent copying files, which can run unattended.
If you are migrating from ReiserFS, this is the safest way to preserve your data since support for ReiserFS is being removed from Unraid and the Linux kernel.
Reformatting a drive
Reformatting a drive in Unraid will erase all of your data and create a new, empty file system. This process is useful for resolving persistent file system errors or starting fresh with a new format.
Reformatting will permanently erase all data on the drive. Always back up any important files before you begin.
To safely reformat your drive:
- Stop the array.
- Change the file system type:
- (Optional) Change back to your original file system type:
This simple process ensures that the drive is fully wiped and formatted as you desire. The formatting process usually takes just a few minutes.
Reformatting a cache drive
Sometimes, you'll need to reformat a cache drive for the following reasons:
- To change the file system type (for example, from BTRFS to XFS or vice versa)
- To fix persistent file system errors
- To start fresh for new workloads
Recommended procedure for reformatting a cache drive
- Stop the array.
- Disable Docker and VM services under Settings.
- Start the array (this will prevent the Docker and VM tabs from appearing).
To move data off the cache:
- Set share storage and Mover action (cache → array): For each share that has files in the cache, set Primary storage to the source cache pool and Secondary storage to the array. Set Mover action to cache → array.
- Note down any shares you change and their original settings.
- Run Mover: Run Mover from the Main tab. Wait for it to finish and ensure that the cache is empty.
- If any files remain, stop and check the forums for help.
To reformat the cache drive:
- Stop the array.
- Set the cache drive format (choose between XFS or BTRFS).
- Start the array.
- Format the cache drive:
- Confirm that only the cache drive is listed as unmountable.
- Proceed to format the drive.
To restore data and settings:
- Restore share settings: For each share you changed, set Primary storage and Secondary storage back to their original values.
- Move data back (array → cache): Set Primary storage to the destination cache pool and Secondary storage to the array for each share you changed. Set Mover action to array → cache, then run the Mover again to move your data back to the cache.
- Stop the array.
- Re-enable Docker and VM services.
- Start the array.
The time it takes to move data with the Mover and format the drive can vary from several minutes to several hours, depending on the amount of data and the speed of the drive.
BTRFS operations
Maintaining your BTRFS pools in Unraid is essential for keeping them running well and ensuring your data stays safe. Two key tools you’ll want to use regularly are Balance and Scrub. These operations help solve space allocation problems, optimize your storage use, and protect your data from hidden corruption.
Let’s break down what each operation does and when to use them:
- Balance
- Scrub
The Balance operation redistributes data and metadata chunks across your BTRFS pool. This process helps free up space, resolves allocation issues, and can fix “no space left on device” errors even when space seems available.
When to run Balance
- When you encounter “no space left on device” errors but have free space.
- After adding or removing drives in a pool.
- To optimize space usage and improve performance.
How to run Balance
- Access the pool: In the WebGUI, click on the pool in the Main tab and select Balance.
- Add parameters (optional): Optionally, add parameters for advanced use (refer to Unraid Help for details).
- Start the process: Click Start to begin the process.
Balance operations can take a few minutes to several hours, depending on the pool size and amount of data.
The Scrub operation reads all data and metadata, checks the integrity of checksums, and repairs any corrupt blocks using available redundant copies. Scrubbing helps identify and fix silent data corruption, known as “bit rot,” before it becomes a significant issue.
When to run Scrub
- As part of routine maintenance (see recommended schedule below).
- After unclean shutdowns or if you suspect corruption.
- More frequently on high-usage pools.
Recommended schedule
- High-usage pools: Once a week
- All other pools: Once a month
How to run Scrub
- Access the pool: In the WebGUI, click on the pool in the Main tab and select Scrub.
- Start the process: Click Start to initiate the process.
Scrub operations are usually quicker than a full disk scan because they only check allocated data. Based on pool size and usage, expect this to take anywhere from a few minutes to a few hours.
Both Balance and Scrub can be performed while the system is online, but keep in mind that performance may be affected during these operations. You can monitor the progress in the WebGUI.
For more details on advanced BTRFS features, check out the official BTRFS documentation.
Unassigned drives
Unassigned drives are storage devices connected to your Unraid server that aren't part of the main array or any cache pool. You can use these drives to transfer files, create backups, or provide fast storage for virtual machines.
Common uses for unassigned drives
- Connect removable drives for easy file transfers or backups.
- Use dedicated drives for high-performance tasks like running virtual machines or temporary data storage.
Using the Unassigned Devices plugins
To make the most of your unassigned drives, consider installing the following plugins from the Apps tab:
-
Unassigned Devices: This plugin allows you to mount, share, and manage drives with file systems that Unraid supports, like XFS, BTRFS, or NTFS.
-
Unassigned Devices Plus: This extension broadens your options by supporting additional file systems, including ExFAT and HFS+.
These plugins enable:
- Easily mounting and unmounting drives from the Unraid web interface.
- Sharing your unassigned drives over the network.
- Automating the mounting process when the server boots up.
- Formatting or erasing drives for future use.
- Safely disconnecting USB or external drives without hassle.
For more details on installing and managing plugins, check out Plugins.
Troubleshooting
Drive shows as unmountable
If you see that a drive in Unraid is unmountable, it could be due to one of two main reasons:
-
New drive added: If you just added a new drive to your setup, it will show as unmountable until you format it. Formatting creates a file system that allows the drive to store files. You can find the steps to format a drive here.
-
File system problems: If a drive that was previously working suddenly shows as unmountable, it likely has a file system issue. This can happen due to unexpected shutdowns, problems while writing data, or if the drive has been marked as disabled (which appears as a red 'x' in the WebGUI).
Do not format an unmountable drive unless you are okay with losing all the data on it. Formatting will erase everything and update the parity information, making recovery impossible. Always try to fix the file system first.
If your drive is unmountable:
- Identify the situation: Determine if it's a new drive or a previously working drive.
- For new drives: Format the drive to create a new file system (check the formatting steps).
- For previously working drives: Perform a file system check or repair (see Checking a file system). Avoid formatting if you want to keep the data.
If a drive is both unmountable and disabled (red 'x'), first run the file system check/repair on the emulated drive. If the emulated drive is also unmountable and you attempt to rebuild it, the new drive will also be unmountable.
Fixing the file system typically takes less time than rebuilding the drive, allowing you to access your data without losing anything. Remember, rebuilding a drive does not fix file system issues; it merely ensures that the physical drive matches the emulated one, carrying over any existing problems.
While parity helps recover a failed drive, it cannot fix file system problems. If the file system is corrupted, parity will simply replicate that corruption to the new drive.
If you’re unsure:
- Download your system logs by navigating to Tools → Diagnostics.
- For expert help, post your issue along with the diagnostics on the Unraid forums.
- Only format unmountable drives if they are brand new or if you want to erase all data.
- Use the file system check/repair for fixing corrupt files; don’t rely on parity to solve these issues.
- For cache pools with multiple drives, consider using either BTRFS or ZFS.
- Always double-check before formatting or repairing drives to avoid accidental loss of data.
Checking a file system
If a disk that previously mounted without issues now shows as unmountable, it typically indicates file system corruption. This may result from an unclean shutdown, a failed write operation, or the disk being marked as disabled in the WebGUI. Checking and repairing the file system is generally quicker and safer than performing a rebuild, so it's advisable to try this before formatting or rebuilding the disk.
Preparing to check or repair
-
Identify the file system type:
-
Start the array in the correct mode:
- For XFS, start the array in Maintenance Mode.
- For BTRFS, start the array in Normal mode for a scrub or Maintenance Mode for a repair.
- For ZFS, refer to the ZFS section below.
-
Handle emulated disks: If the disk is disabled and being emulated, run the check/repair on the emulated disk before attempting a rebuild. If the emulated disk is unmountable, the rebuilt disk will also be unmountable.
Common error messages
Message | Meaning / Action |
---|---|
Superblock has bad magic number | Severe corruption; attempt a file system repair. |
Filesystem is dirty | Unclean shutdown; execute a file system check. |
Metadata corruption detected | File system structures are damaged; initiate a repair. |
No valid BTRFS found | Disk may not belong to a valid pool; check pool assignments. |
Mount: wrong fs type, bad option, etc. | Incorrect file system selection or disk is unformatted. |
Cannot mount /dev/mdX: Structure needs cleaning | File system is corrupted; perform a repair. |
Via the WebGUI
- Start the array: Start the array in the correct mode (refer to the steps above).
- Select the disk: Go to the Main tab and select the disk you wish to check.
- Access check options: Scroll to Check Filesystem Status.
- For XFS (Unraid 7.0+): You will see a CHECK button without any options to enter. The system automatically determines the necessary actions based on the check results.
- For other file systems: Enter any necessary options (for details, see Help in the upper right).
- Start the check: Click Check to initiate the process.
- Monitor progress: Monitor the progress in the output box. Use Refresh if required.
- Review results: Review the results. If uncertain, copy the output and post it on the forums for advice.
XFS Automatic Repair Workflow (Unraid 7.0+)
Starting with Unraid 7.0, XFS file system repair is now fully automated through the WebGUI:
- Initial Check: Click the CHECK button (no options to enter)
- Check Results:
- No corruption detected: Shows "no filesystem corruption detected" and the CHECK button remains
- Corruption detected: Shows "filesystem corruption detected" and a FIX button appears
- Repair Process: Click FIX to automatically repair the file system
- Additional Actions: If needed, a ZERO LOG button may appear
- Completion: Shows "filesystem repaired" when the process is complete
This automated system eliminates the need for users to manually enter repair options and ensures the correct repair sequence is followed.
Via the command line
- XFS
- BTRFS
- ZFS
To check an XFS file system via command line:
- Start the array in Maintenance Mode.
- Run the following command:
xfs_repair -v /dev/mdXp1
- Replace
X
with the disk number (e.g.,/dev/md1p1
). - For encrypted XFS, use
/dev/mapper/mdXp1
. - For drives not in the array:
xfs_repair -v /dev/sdX1
- Ensure you are using the correct device identifier.
Running this command on an array disk outside of Maintenance Mode will invalidate parity.
To check a BTRFS file system via command line:
- To perform a scrub (which checks and repairs many errors automatically), start the array in Normal mode and run:
btrfs scrub start /mnt/diskX
- For a read-only check, start the array in Maintenance Mode and run:
btrfs check --readonly /dev/mdXp1
- Replace
X
with the disk number. - For drives not in the array:
btrfs check --readonly /dev/sdX1
Running this command on an array disk outside of Maintenance Mode will invalidate parity.
To check a ZFS file system via the command line:
Recommended method
ZFS uses scrubbing instead of traditional filesystem checks like fsck
. A scrub examines all data in the pool to verify checksums and automatically repairs any corruption found on redundant configurations.
- Start the array in Normal mode and run:
zpool scrub poolname
- Replace
poolname
with your actual ZFS pool name.
- Replace
Check pool status
To view the current health and any ongoing scrub progress, use the command:zpool status -v poolname
This command shows detailed information about pool health, any errors, and scrub progress.
Additional ZFS commands
- To pause a scrub:
zpool scrub -p poolname
- To stop a scrub:
zpool scrub -s poolname
- To list all pools:
zpool list
For comprehensive guidance on ZFS file systems, check out the dedicated ZFS storage section.
- File system repairs are generally faster than a complete rebuild and can restore access without data loss.
- Rebuilding a disk does not resolve file system corruption; always run a check or repair first.
- If you have doubts, post your diagnostics and error messages on the Unraid forums for expert assistance.
Repairing a file system
If a check of your file system finds errors, you might need to run a repair to get access to your data again. Repairs typically take less time than a full rebuild, but it's important to read the output carefully and reach out for help on the forums if you're unsure about anything.
Repairs can take anywhere from several minutes to several hours, especially for larger or heavily corrupted file systems. Progress might seem slow, but you can check on the activity by looking at the read/write statistics on the Main page.
Preparing to repair
-
Identify the file system type: Go to the Main tab, click on the disk, and find out what type of file system it is (XFS, BTRFS, or ZFS).
-
Start the array in the correct mode:
- For XFS: Use Maintenance Mode.
- For BTRFS: Use Normal mode for a scrub; use Maintenance Mode for a repair.
- For ZFS: Use Normal mode and run a scrub to check for errors. See the ZFS storage page for guidance on ZFS pool maintenance and repair procedures.
-
Handle emulated disks: If the disk is disabled and being emulated, run the repair on the emulated disk before trying to do a rebuild.
Via the WebGUI
- Start the array: Start the array in the correct mode (refer to the section above).
- Select the disk: Go to the Main tab and click on the disk you want to repair.
- Access repair options: Scroll down to Check Filesystem Status.
- For XFS (Unraid 7.0+): The repair process is fully automated. Click CHECK, then FIX if corruption is detected, and ZERO LOG if prompted.
- For other file systems: Remove any options that would run the process in check-only mode (like
--readonly
for BTRFS). - Add suggested options: If prompted, add the suggested options as indicated in the check output.
- Start the repair: Click on Check to begin the repair.
- Monitor progress: Keep an eye on the progress in the output box. Use Refresh if needed.
- Check for lost files: If you notice a
lost+found
folder after the repair, it may contain files or folders that couldn't be fully recovered. Use backups or the Linuxfile
command to identify the contents if necessary.
If you're uncertain about the output, copy and share it on the Unraid forums for expert help. Use the code formatting option to keep it readable.
Via the command line
- XFS
- BTRFS
- ZFS
- Start the array in Maintenance Mode.
- Run the following command:
xfs_repair /dev/mdXp1
. ReplaceX
with the disk number (e.g.,/dev/md1p1
). - For encrypted XFS, use:
/dev/mapper/mdXp1
. - If you're prompted to use
-L
, re-run the command like this:xfs_repair -L /dev/mdXp1
. This is usually safe and necessary to complete the repair. - For drives that are not part of the array:
xfs_repair /dev/sdX1
.
Running this command on an array disk outside of Maintenance Mode will invalidate parity.
- To perform a scrub (which detects and repairs many errors automatically), start the array in Normal mode and run:
btrfs scrub start /mnt/diskX
. - For a full repair, start the array in Maintenance Mode and run:
btrfs check --repair /dev/mdXp1
. Only use--repair
if advised by the forums or documentation, as it can sometimes lead to further issues.
--repair
with cautionThe --repair
option can sometimes cause data loss or make corruption worse if used incorrectly. Only use it when:
- You've consulted the Unraid forums for your specific error
- You have a recent backup of your data
- You understand the risks involved
For most BTRFS issues, try running a scrub
first (which is safer) or seek expert advice before attempting repairs.
ZFS pools offer built-in integrity checking and self-healing capabilities, which often eliminate the need for traditional file system repairs.
For ZFS pools
- Check pool health: Use the command
zpool status poolname
to see the status of your pool. - Run a scrub: Execute
zpool scrub poolname
. This command detects and repairs any corruption automatically. - Clear errors: After addressing any underlying issues, run
zpool clear poolname
to clear the error state.
For ZFS disks in the array
- Check dataset health: Use
zfs list -o name,health
to check the health of your datasets. - Run a scrub: You can also run
zpool scrub poolname
for any disks belonging to a specific pool.
ZFS automatically identifies and fixes data corruption when redundancy is available, such as in mirrors or RAIDZ1/RAIDZ2/RAIDZ3 configurations. Unlike traditional file systems, ZFS typically does not require manual repair commands because it continuously monitors data integrity with checksums.
For a comprehensive understanding of ZFS management, troubleshooting, and advanced repair scenarios, refer to the dedicated ZFS storage page for detailed guides and best practices.
- Stop and restart the array in Normal mode.
- The drive should now mount and be accessible.
- If you see a
lost+found
folder, check its contents for any important files.
If you don't understand the repair output or if the process fails, share your diagnostics and repair log on the Unraid forums for further assistance.