ZRAM Compressed Memory — Tiered Swap Manager

A smart swap manager for Unraid that combines compressed RAM (ZRAM) with optional disk overflow protection. Helps memory-constrained servers avoid OOM crashes.

How It Works

Tier 1: ZRAM Swap (always active)
  Compressed in RAM — fast, ~3:1 ratio
  8 GB server → effectively ~20 GB usable memory

Tier 2: Disk Swap File (optional)
  Overflow to a writable disk when ZRAM fills (NVMe/SSD recommended)
  Prevents OOM — the kernel handles overflow automatically via priority

Features

• Auto-Sizing: Automatically sizes ZRAM to a percentage of your RAM (configurable 25-75%, default 50%).
• Live Dashboard Card: Real-time stats — RAM saved, compression ratio, CPU load, and a 1-hour history chart.
• Disk Overflow Protection: Optional swap file on any allowed mount (NVMe/SSD recommended; HDD permitted with a warning) for when ZRAM fills up. Includes a drive picker with smart media detection.
• Device Isolation: Labels all managed devices. Only shows its own ZRAM — won't interfere with other plugins that use ZRAM.
• Safe Operations: OOM evacuation checks before removing swap. Atomic config writes. CSRF protection on all actions.
• Boot Persistence: Automatically recreates your swap configuration on every boot.
• Compression Choice: Support for all kernel-supported algorithms (zstd, lz4, lzo, etc.).

Installation

Community Applications (Recommended)

Search for "ZRAM Compressed Memory" in the Apps tab.

Manual URL

Copy and paste into Plugins > Install Plugin: https://github.com/johnpwhite/unraid-plugin-zram/raw/main/unraid-zram-card.plg

Settings Guide

Tier 1: ZRAM Swap

• Size: Auto (percentage of RAM) or a fixed size like 4G.
• Auto Size Slider: 25-75% of physical RAM. Default 50%. Shows calculated size in real-time.
• Algorithm: zstd recommended (best compression ratio with good speed).
• Swappiness: 0-200 (kernel 5.8+ range). Default 150, recommended for ZRAM systems — tells the kernel that compressed-RAM swap is cheaper than dropping page cache. Use 100 for legacy parity, 180+ for aggressive zram with disk swap as fallback.

Tier 2: Disk Swap File

• Drive Picker: Shows eligible mounted filesystems with smart classification:
  • NVMe: Recommended (green)
  • SATA SSD: OK (green)
  • HDD: Not recommended (orange warning)
  • USB/Removable: Hidden
  • Btrfs RAID: Warned (swap files not supported on multi-device btrfs)
• Size: Configurable. 16 GB default.
• Priority: Automatically set to 10 (ZRAM is 100). Kernel uses ZRAM first, overflows to the disk tier only when needed.
• On and off: The disk swap turns off when the array stops, and turns on at boot and when the array starts. Nothing turns it on in the background at other times: if you turn it off yourself (swapoff), it stays off until you click ACTIVATE, or until the next boot or array start. REMOVE turns it off and deletes the swap file.

Plugin Settings

• Refresh Interval: Dashboard update frequency (default 3000ms).
• Collection Interval: Background history recording frequency (default 3s).
• Debug Mode: Detailed logging for troubleshooting.
• Command Console: Real-time log of all plugin actions.

Requirements

• Unraid 6.12.1 or newer (optimized for Unraid 7.2+).
• ZRAM kernel module (standard in Unraid).
• For Tier 2: A writable mount under /mnt/cache or /mnt/disks with a supported filesystem (XFS, ext4, or single-device btrfs). NVMe/SSD recommended; HDD permitted but slower.

Created by John White