Sign in Subscribe
Guides

Ultimate Guide to ZFS on Unraid: Cache vs Array

The Tech Monk's Ultimate Guide to ZFS on Unraid: Cache vs Array

Namaste, fellow system administrators. The path to optimal Unraid performance often leads us to the powerful realm of ZFS. While traditionally Unraid relies on its unique parity-protected array, integrating ZFS, particularly for the cache pool, can drastically improve speeds, especially for write-heavy workloads and demanding applications. This guide will illuminate the differences between utilizing ZFS for the cache pool versus the main array, and provide a step-by-step walkthrough to setting it up.

This is not a beginner's guide. A foundational understanding of Unraid concepts, file systems, and basic command-line operations is assumed. But fear not, I will guide you step-by-step towards enlightenment.

Introduction: Why ZFS on Unraid?

Unraid's native array relies on a copy-on-write mechanism which allows for different sized drives to be used. The parity drive provides data redundancy, but writing involves calculating parity, which can be a performance bottleneck, especially with smaller or slower drives.

ZFS, on the other hand, is a transactional file system renowned for its data integrity, advanced features like snapshots and checksums, and, importantly, performance. Integrating ZFS into your Unraid setup can provide several key advantages:

  • Improved Write Performance: By utilizing a ZFS cache pool, data can be written to the faster SSD pool first, and then moved to the slower array in the background.
  • Data Integrity: ZFS's checksumming mechanism ensures that data corruption is detected and corrected.
  • Advanced Features: ZFS offers features like snapshots, which allow you to easily revert to previous states in case of data loss or corruption.
  • Application Performance: Applications like Docker containers and VMs benefit greatly from the speed and reliability of a ZFS pool.

However, there are considerations. ZFS requires more RAM than the Unraid array. Generally, 1GB of RAM per 1TB of storage is recommended, although this can vary depending on workload. Furthermore, expanding a ZFS pool in Unraid can be more complex than expanding the standard array.

Prerequisites

Before embarking on this journey, ensure you have the following:

  • Unraid Server: A functional Unraid server, preferably running the latest stable version.
  • Hardware:
    • Sufficient RAM (consider 1GB per 1TB of storage in your ZFS pool)
    • SATA SSD (256GB or larger): This is essential for a functional ZFS cache pool. While NVMe drives offer even faster performance, a SATA SSD provides a good balance of speed and affordability. A second SSD is required for RAID1 mirror configuration.
    • Hard Drives: For the Unraid array itself.
  • Backup: Always back up your critical data before making significant changes to your storage system.
  • Understanding: A grasp of basic command-line operations (SSH access).
  • Patience: This process may take some time, especially if you're migrating data.

Step-by-Step Instructions: Creating a ZFS Cache Pool

This section assumes you are creating a ZFS cache pool. Creating a ZFS pool for the array is possible, but requires significantly more knowledge and consideration due to the way Unraid handles parity. We will focus on the more common and manageable cache pool scenario.

  1. Identify Your SSD:

    • Log into your Unraid web interface.
    • Go to "Main" and identify the drive(s) you want to use for your ZFS cache pool. Note their serial numbers (e.g., WDC-ABCDEFG12345). We'll need these later.
    • If the drives are currently assigned to the array, unassign them and stop the array.

  2. Create the ZFS Pool:

    • Go to "Pools" and click "Add Pool".
    • Enter a name for your pool (e.g., cache).
    • Select "ZFS" as the file system.
    • Under "Devices," select the SSD(s) you identified earlier.
      • RAID Configuration: Select a RAID configuration:
        • single (no redundancy - NOT recommended)
        • mirror (RAID1 – provides redundancy - Recommended)
        • raidz1 (Similar to RAID5 - requires at least 3 drives)
        • raidz2 (Similar to RAID6 - requires at least 4 drives)
        • raidz3 (Requires at least 5 drives)
        • For a cache pool, mirror is the most common and recommended choice for data redundancy and decent performance with two drives.
    • Click "Create". Unraid will format the drive(s) and create the ZFS pool.

  3. Configure the Cache Pool:

    • Go to "Settings" -> "Global Share Settings".
    • Set the "Use cache pool" setting to "Yes".
    • Set the "Mover action" to either:
      • "Cache yes": Data is written to the cache pool first, and then moved to the array during the scheduled mover process.
      • "Prefer": Attempts to write directly to the cache pool if space is available; otherwise, writes to the array.
    • Click "Apply".

  4. Configure Individual Shares:

    • Go to "Shares".
    • Edit each share that you want to utilize the cache pool.
    • Set the "Use cache pool" setting for each share to "Yes", "Prefer", or "Only", depending on your requirements.
      • Yes: The share will use the cache pool and be moved to the array.
      • Prefer: The share will attempt to use the cache pool, and if it is full, write directly to the array.
      • Only: The share will ONLY reside on the cache pool. DO NOT use "Only" for shares that require long term storage or that need to survive a failure of the cache pool.
    • Click "Apply".

  5. Start the Array:

    • Go back to the "Main" page and start the array.

  6. Run the Mover:

    • Go to "Main" and click the "Mover" button to manually initiate the mover process. This will move data from the array to the cache pool (or vice versa, depending on your settings).

Troubleshooting

  • Pool Creation Errors: Double-check that the drives you selected are not already part of the array or another pool. Ensure the drives are detected correctly in the BIOS.
  • Performance Issues: Monitor the performance of your ZFS pool using the zpool iostat command in the terminal. High I/O wait times may indicate a bottleneck. Consider upgrading your SSDs or adding more RAM.
  • Data Loss: In the event of a drive failure in a mirrored ZFS pool, replace the failed drive and resilver the pool using the zpool replace command (refer to the ZFS documentation for specific instructions). Ensure you have proper backups!
  • ZFS Errors: Check the Unraid system log for ZFS-related errors. These errors often provide clues to the underlying problem.
  • Mover not working: Verify the shares have the "use cache pool" setting properly configured to "yes" or "prefer". Ensure the scheduled mover is enabled in "settings" -> "scheduler".

ZFS on the Array: A Word of Caution

While technically possible, using ZFS directly on the Unraid array is generally not recommended for beginners. Unraid's parity calculations are tightly integrated with its own storage system, and mixing ZFS with the parity layer can lead to data corruption or performance issues. The Unraid OS relies on XFS being directly formatted on the drives for parity to work correctly. Only very advanced users with a deep understanding of both Unraid and ZFS should attempt this. This guide focuses exclusively on using ZFS for the cache pool, which is a much safer and more practical approach for most users.

Conclusion

By following these steps, you've successfully created a ZFS cache pool on your Unraid server, unlocking improved performance and data integrity for your applications and data. Remember to monitor your pool's health and performance regularly, and always keep your backups up to date.

Now, go forth and enjoy the speed and reliability of ZFS! May your streams be buffer-free and your downloads swift.

Before you begin, consider investing in a quality SATA SSD, such as a Samsung 870 EVO, Crucial MX500, or WD Blue. A reliable SSD is critical for the smooth operation and longevity of your ZFS cache pool. Upgrade today and experience the difference!


Check Price: SATA SSD (256GB or larger)

Read next