Testing reverting to zram by default.

Author: bigbruno

Cargo.lock

@@ -9,7 +9,7 @@ repository = "https://github.com/biglinux/biglinux-systemd-swap"
 
 [dependencies]
 clap = { version = "4", features = ["derive"] }
-nix = { version = "0.29", features = ["fs", "process", "signal", "user", "feature"] }
+nix = { version = "0.30", features = ["fs", "process", "signal", "user"] }
 libsystemd = "0.7"
 glob = "0.3"
 libc = "0.2"

Cargo.toml

@@ -35,6 +35,7 @@ DFL_T := $(DESTDIR)$(datadir)/systemd-swap/swap-default.conf
 CNF_T := $(DESTDIR)$(sysconfdir)/systemd/swap.conf
 MAN5_T := $(DESTDIR)$(mandir)/man5/swap.conf.5
 MAN8_T := $(DESTDIR)$(mandir)/man8/systemd-swap.8
+SYSCTL_T := $(DESTDIR)$(sysconfdir)/sysctl.d/91-memory.conf
 
 .PHONY: build files dirs install uninstall clean help
 
@@ -72,6 +73,9 @@ $(MAN5_T): man/swap.conf.5
 $(MAN8_T): man/systemd-swap.8
 	install -p -Dm644 $< $@
 
+$(SYSCTL_T): include/91-memory.conf
+	install -p -Dm644 $< $@
+
 define banner
 #  This file is part of systemd-swap.\n#\n# Entries in this file show the systemd-swap defaults as\n# specified in $(datarootdir)/systemd-swap/swap-default.conf\n# You can change settings by editing this file.\n# Defaults can be restored by simply deleting this file.\n#\n# See swap.conf(5) and $(datarootdir)/systemd-swap/swap-default.conf for details.\n\n
 endef
@@ -83,15 +87,15 @@ swap.conf: include/swap-default.conf ## Generate swap.conf
 
 target/release/systemd-swap: build
 
-files: $(BIN_T) $(PRE_BIN_T) $(SVC_T) $(PRE_SVC_T) $(DFL_T) $(CNF_T) $(MAN5_T) $(MAN8_T)
+files: $(BIN_T) $(PRE_BIN_T) $(SVC_T) $(PRE_SVC_T) $(DFL_T) $(CNF_T) $(MAN5_T) $(MAN8_T) $(SYSCTL_T)
 
 install: ## Install systemd-swap
 install: build dirs files
 
 uninstall: ## Delete systemd-swap (stop systemd-swap first)
 uninstall:
 	test ! -f /run/systemd/swap/swap.conf
-	rm -v $(BIN_T) $(PRE_BIN_T) $(SVC_T) $(PRE_SVC_T) $(DFL_T) $(CNF_T) $(MAN5_T) $(MAN8_T)
+	rm -v $(BIN_T) $(PRE_BIN_T) $(SVC_T) $(PRE_SVC_T) $(DFL_T) $(CNF_T) $(MAN5_T) $(MAN8_T) $(SYSCTL_T)
 	rm -rv $(LIB_T) $(DESTDIR)$(datadir)/systemd-swap
 
 clean: ## Remove generated files

Makefile

@@ -2,25 +2,126 @@
 
 Smart dynamic swap management for Linux, written in Rust.
 
-## Overview
+Automatically detects hardware, selects the best swap strategy, and tunes the
+kernel for optimal memory management — no manual configuration required.
 
-`systemd-swap` automatically configures the best swap strategy for your system:
+## How It Works
 
--   **Auto-detection**: Smartly chooses between Zswap and Zram based on your filesystem.
--   **Zswap + SwapFC**: (Default for Btrfs/Ext4/XFS) Uses compressed RAM cache + dynamic swap files. Most efficient for desktops.
--   **Zram**: (Default for others) Uses compressed RAM block device. Good for systems without disk swap support.
--   **Dynamic Scaling**: Creates swap files on-demand, starting small and growing as needed.
+### Swap Modes
+
+| Mode | Primary | Secondary | Selection |
+|------|---------|-----------|-----------|
+| `auto` | Auto-detected | Auto-detected | **Default** — recommended |
+| `zram+swapfile` | Zram (RAM) | Swap files (disk) | btrfs / ext4 / xfs with free space |
+| `zswap+swapfile` | Zswap (kernel) | Swap files (disk) | Large disk, SSD/NVMe |
+| `zram` | Zram (RAM) | None | LiveCD, low disk, tmpfs |
+| `manual` | Explicit flags | Explicit flags | Advanced users |
+| `disabled` | — | — | Service exits cleanly |
+
+### Auto-Detection Logic
+
+In `auto` mode, the daemon checks:
+
+1. **LiveCD?** (tmpfs/squashfs/overlay root) → `zram` only
+2. **Filesystem supports swap files?** (btrfs/ext4/xfs) → if no, `zram` only
+3. **Free disk ≥ RAM?** → if no, `zram` only
+4. **Otherwise** → `zram+swapfile` (zram primary + disk overflow)
+
+### Zram Pool Architecture
+
+The daemon manages a **dynamic pool of zram devices** that expands and
+contracts based on demand:
+
+- **Initial pool**: one device per CPU core (max 8 devices)
+- **Expansion**: adds a device when pool utilization exceeds 85%
+- **Contraction**: removes idle devices when utilization drops below 20% for 120s
+- **Monitoring interval**: 5 seconds
+
+Each zram device uses:
+- **Algorithm**: zstd (level 3) — best ratio-to-speed balance
+- **Disksize**: 150% of RAM (virtual/uncompressed size)
+- **No mem_limit**: prevents write errors that block kernel fallback to disk swap
+- **Priority**: 32767 (maximum — kernel uses zram before disk swap)
+
+Physical RAM usage is naturally limited by the kernel's memory watermarks
+and the daemon's free-RAM guard (adaptive check before each expansion).
+
+**Compression ratios** (typical):
+- Desktop workloads: 3–4x
+- Server / text-heavy: 5–10x
+- Incompressible data (media, encrypted): ~1x
+
+### Swap Files (Overflow)
+
+In `zram+swapfile` mode, swap files provide emergency overflow:
+
+- **Size**: 512MB each, created on demand
+- **Maximum**: 28 files (14GB total capacity)
+- **Priority**: -1 (kernel only uses when zram is full)
+- **NOCOW**: enabled on btrfs (prevents deadlock under pressure)
+- **Created when**: free RAM < 20% or free swap < 40%
+- **Removed when**: free swap > 70%
+
+### Zswap Mode
+
+In `zswap+swapfile` mode, the kernel's zswap handles compression:
+
+- Compresses pages before writing to disk swap
+- Shrinker moves cold compressed pages to disk automatically
+- Pool limited to 45% of RAM
+- Requires disk-backed swap files as backing storage
+
+## Recommended Kernel Tuning
+
+The following kernel parameters are **not applied by the daemon** — they are
+recommendations for optimal performance with zram/zswap. Configure them
+via `/etc/sysctl.d/99-swap.conf` or your distribution's tuning service.
+
+### Memory Management
+
+| Parameter | Value | Purpose |
+|-----------|-------|---------|
+| `vm.swappiness` | 120 (zram+swapfile) / 180 (zram only) | Prefer swap over file cache (zram is in-memory, so swapping is fast) |
+| `vm.min_free_kbytes` | 3% of RAM (max 512MB) | Emergency reserve — gives kswapd headroom before OOM |
+| `vm.watermark_scale_factor` | 150 (1.5%) | Gap between min/low/high watermarks for kswapd headroom |
+| `vm.vfs_cache_pressure` | 75 | Balance between VFS cache retention and anonymous page reclaim |
+| `vm.dirty_ratio` | 10 | Max dirty pages before blocking writes (reduces memory pressure) |
+| `vm.dirty_background_ratio` | 3 | Start background writeback early |
+| `vm.page-cluster` | 0 (zram) / 2 (zswap) | Pages read per swap-in. 0 = page-at-a-time (optimal for zram) |
+
+### Memory Compaction
+
+| Parameter | Value | Purpose |
+|-----------|-------|---------|
+| `vm.compaction_proactiveness` | 20 | Background defragmentation level. Lower avoids CPU waste with zram-heavy workloads |
+| `vm.watermark_boost_factor` | 15000 | Boosts watermarks after fragmentation events for compaction recovery |
+| `vm.extfrag_threshold` | 300 | Eagerness to compact vs reclaim. Lower = more willing to compact |
+
+### Transparent Huge Pages
+
+| Parameter | Value | Purpose |
+|-----------|-------|---------|
+| THP enabled | `madvise` | Only apps requesting huge pages get them — avoids compaction stalls |
+| mTHP 64kB | `madvise` | 64kB folios via madvise — reduces swap I/O overhead |
+
+### MGLRU (Multi-Gen LRU)
+
+| Parameter | Value | Purpose |
+|-----------|-------|---------|
+| `min_ttl_ms` | 1000 | Pages younger than 1s are never reclaimed — protects working set from thrashing |
 
 ## Installation
 
-### Arch Linux / BigLinux / Manjaro...
+### Arch Linux / BigLinux / Manjaro
+
 ```bash
 cd pkgbuild
 makepkg -si
 ```
 
 ### Manual Build
-Requirements: Rust 1.70+, `btrfs-progs`, `util-linux`
+
+Requirements: Rust 1.70+, `util-linux`
 
 ```bash
 cargo build --release
@@ -30,46 +131,126 @@ sudo systemctl enable --now systemd-swap
 
 ## Usage
 
-Check status:
+### Check Status
+
 ```bash
 systemd-swap status
 ```
 
-Reload configuration:
+Shows zram pool stats (compression ratio, utilization, device count),
+swap file details, and memory breakdown.
+
+### Show Recommended Config
+
+```bash
+sudo systemd-swap autoconfig
+```
+
+Displays the auto-detected configuration for the current hardware.
+
+### Restart
+
 ```bash
 sudo systemctl restart systemd-swap
 ```
 
+### View Logs
+
+```bash
+journalctl -u systemd-swap -f
+```
+
 ## Configuration
 
-Configuration is located at `/etc/systemd/swap.conf`.
+Configuration files (in order of priority):
+
+1. `/usr/share/systemd-swap/swap-default.conf` — defaults (do not edit)
+2. `/etc/systemd/swap.conf` — user overrides
+3. `/etc/systemd/swap.conf.d/*.conf` — drop-in fragments
+
+All options support `${NCPU}` and `${RAM_SIZE}` variables, plus simple
+arithmetic with `$(( expr ))`.
 
 ### Common Options
 
-**Change Swap Mode:**
+**Change swap mode:**
+```ini
+swap_mode=zram+swapfile    # or: auto, zram, zswap+swapfile, manual, disabled
+```
+
+**Customize zram size:**
 ```ini
-# Modes: auto, zswap+swapfc, zram, manuall
-swap_mode=auto
+zram_size=200%             # Virtual disksize (% of RAM)
 ```
 
-**Customize Zram Size:**
+**Customize swap file location:**
 ```ini
-zram_size=50%
+swapfile_path=/mnt/data/swapfile
 ```
 
-**Customize Swap File Location:**
+**Adjust anti-thrashing protection:**
 ```ini
-swapfc_path=/mnt/data/swapfile
+mglru_min_ttl_ms=3000      # Higher = more protection, less reclaim
 ```
 
-See `/usr/share/systemd-swap/swap-default.conf` for all available options and defaults.
+**Customize zram pool behavior:**
+```ini
+zram_expand_threshold=90        # Expand pool above this utilization %
+zram_contract_threshold=15      # Contract pool below this utilization %
+```
+
+### Full Option Reference
+
+See `/usr/share/systemd-swap/swap-default.conf` for all available options
+with descriptions.
+
+## Architecture
+
+```
+systemd-swap (Rust daemon)
+├── main.rs          — CLI (clap), mode dispatch, kernel tuning, THP/MGLRU
+├── lib.rs           — Module declarations, global SHUTDOWN flag
+├── config.rs        — Config parser (key=value, ${VAR} expansion, arithmetic)
+├── autoconfig.rs    — Hardware detection, recommended config generation
+├── zram.rs          — Dynamic zram pool (expansion, contraction, monitoring)
+├── swapfile.rs      — Dynamic swap file management (NOCOW, loop-backed)
+├── zswap.rs         — Zswap kernel module configuration
+├── meminfo.rs       — /proc/meminfo parser, effective swap calculation
+├── systemd.rs       — Systemd unit generation, sd-notify
+└── helpers.rs       — Shared utilities (parse_size, fs detection, logging)
+```
+
+### Data Flow
+
+```
+Memory pressure (free RAM < threshold)
+  → MGLRU protects working set (pages < 1s old)
+  → Kernel swaps cold anonymous pages:
+      ├─ zram: compress with zstd level 3 → store in RAM
+      │   ├─ Pool utilization > 85% → daemon adds zram device
+      │   └─ All disksize consumed → kernel falls back to swapfiles
+      └─ zswap: compress in kernel pool → shrinker writes back to disk
+
+SwapFile monitor (1s interval):
+  ├─ free_ram < 20%  → create 512MB swap file
+  ├─ free_ram < 5%   → emergency: create immediately
+  └─ free_swap > 70% → remove unused swap file
+
+ZramPool monitor (5s interval):
+  ├─ utilization > 85% → add zram device (up to 8)
+  └─ utilization < 20% (120s stable) → remove idle device
+```
 
 ## Features
 
--   **Zero Configuration**: Works out of the box for most systems.
--   **Sparse Files**: Swap files use zero disk space until data is actually written (when using Zswap).
--   **MGLRU Support**: Integrates with Multi-Gen LRU (Kernel 6.1+) to prevent thrashing.
--   **Zram Writeback**: Can offload cold pages from Zram to disk.
+- **Zero configuration**: works out of the box for any system
+- **Dynamic scaling**: creates/removes swap resources on demand
+- **MGLRU integration**: protects working set from premature eviction (kernel 6.1+)
+- **mTHP support**: 64kB folios for efficient zram swap I/O
+- **Zswap disabled for zram**: prevents double compression per kernel docs
+- **NOCOW swap files**: safe on btrfs under memory pressure
+- **Adopt on restart**: reuses existing zram devices and swap files without swapoff
+- **Graceful shutdown**: restores all kernel parameters on stop
 
 ## License
 

README.md

@@ -0,0 +1,56 @@
+# Recommended kernel tuning for zram/zswap swap management.
+# Install to /etc/sysctl.d/91-memory.conf
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# These parameters optimize memory management for systems using
+# zram (compressed RAM swap) or zswap (compressed cache + disk swap).
+# Values are uniform — no RAM-size differentiation needed.
+#
+# NOTE: vm.min_free_kbytes is calculated dynamically by the
+# pre-systemd-swap service (3% of RAM, max 512MB).
+
+# ── Swap readahead ──
+# Pages read per swap-in operation (2^N pages).
+# 0 = page-at-a-time (optimal for zram: each page compressed individually).
+# For zswap+disk: use 2 (4 pages = 16KB) to amortize disk I/O.
+vm.page-cluster = 0
+
+# ── Swappiness ──
+vm.swappiness = 30
+
+# ── Cache reclaim ──
+# Balance VFS cache retention vs anonymous page reclaim.
+# Default 100 aggressively reclaims directory/inode caches.
+# 75 retains more VFS caches while still allowing reclaim.
+vm.vfs_cache_pressure = 75
+
+# ── Watermarks ──
+# Gap between min/low/high watermarks (in 0.01% units).
+# Default 10 (0.1%) is too tight for zram. 150 (1.5%) gives
+# kswapd enough headroom to reclaim before OOM.
+vm.watermark_scale_factor = 150
+
+# Boost watermarks after fragmentation events for compaction recovery.
+vm.watermark_boost_factor = 15000
+
+# ── Dirty page writeback ──
+# Flush dirty pages to disk early, freeing RAM before swap is needed.
+# default background_ratio=10, ratio=20. Lowering frees memory sooner.
+vm.dirty_background_ratio = 5
+vm.dirty_ratio = 15
+
+# ── Memory compaction ──
+# Background defragmentation level. Lower avoids CPU waste when
+# unmovable slab pages (zram zsmalloc, btrfs) make compaction futile.
+vm.compaction_proactiveness = 20
+
+# Eagerness to compact vs reclaim. Lower = more willing to compact.
+vm.extfrag_threshold = 300
+
+# ── Memory reserves ──
+# Reserve for root/admin logins during OOM situations.
+vm.admin_reserve_kbytes = 131072
+
+# ── OOM killer ──
+vm.oom_kill_allocating_task = 1
+vm.panic_on_oom = 0