██████ ▓██   ██▓  ██████ ▄▄▄█████▓ █    ██  ███▄    █ ▓█████  ██▀███  
▒██    ▒  ▒██  ██▒▒██    ▒ ▓  ██▒ ▓▒ ██  ▓██▒ ██ ▀█   █ ▓█   ▀ ▓██ ▒ ██▒
░ ▓██▄     ▒██ ██░░ ▓██▄   ▒ ▓██░ ▒░▓██  ▒██░▓██  ▀█ ██▒▒███   ▓██ ░▄█ ▒
  ▒   ██▒  ░ ▐██▓░  ▒   ██▒░ ▓██▓ ░ ▓▓█  ░██░▓██▒  ▐▌██▒▒▓█  ▄ ▒██▀▀█▄  
▒██████▒▒  ░ ██▒▓░▒██████▒▒  ▒██▒ ░ ▒▒█████▓ ▒██░   ▓██░░▒████▒░██▓ ▒██▒
▒ ▒▓▒ ▒ ░   ██▒▒▒ ▒ ▒▓▒ ▒ ░  ▒ ░░   ▒▒▓▒ ▒ ▒ ░ ▒░   ▒ ▒ ░░ ▒░ ░░ ▒▓ ░▒▓░
░ ░▒  ░ ░ ▓██ ░▒░ ░ ░▒  ░ ░    ░    ░ ▒░ ░ ░ ░ ░░   ░ ▒░ ░ ░  ░  ░▒ ░ ▒░
░  ░  ░   ▒ ▒ ░░  ░  ░  ░    ░        ░░ ░ ░    ░   ░ ░    ░     ░░   ░ 
      ░   ░ ░           ░              ░              ░    ░  ░   ░     
          ░ ░                                                           

Dynamic Linux Responsiveness, I/O Latency and Memory Tuner

Overview • Features • Quick Start • CLI Reference • Tuning Profiles • Documentation

---

Overview

On standard Linux installations, default memory management settings rely on percentage-based dirty ratios (vm.dirty_ratio = 20%, vm.dirty_background_ratio = 10%). On modern workstations with 16 GB to 64 GB+ RAM, this allows 3 GB to 13 GB of uncommitted dirty memory to accumulate before writeback throttling occurs.

When sustained disk I/O occurs (such as large file transfers, package updates, or builds), the kernel forces synchronous writeback, causing UI freezes, audio dropouts, and mouse lag.

Systuner inspects hardware metrics directly from /proc and /sys (RAM capacity, swap configuration, ZRAM presence, storage drive rotational status, and battery state) and computes fixed-byte sysctl parameters to maintain deterministic I/O latency and desktop responsiveness.

---

Features

• Hardware Inspection: Direct querying of /proc/meminfo, /proc/swaps, /sys/block, and /sys/class/power_supply without external subprocess overhead.
• Fixed-Byte Dirty Buffers: Replaces ratio-based dirty thresholds with explicit byte ceilings (vm.dirty_bytes, vm.dirty_background_bytes).
• Metadata Cache Retention: Tunes vm.vfs_cache_pressure to keep directory and inode structures resident in memory.
• Medium-Aware Swappiness: Configures vm.swappiness according to whether swap is backed by ZRAM, solid-state drives, or rotational disks.
• Zero-Latency Swap Clustering: Disables sequential page clustering (vm.page-cluster = 0) on non-rotational storage and ZRAM.
• Multi-Mode CLI: Supports stdout configuration generation, live kernel application (--apply), diff tables (--status), and JSON output (--json).
• Library Architecture: Core logic is packaged into libsystuner.so and libsystuner.a for integration into custom tools and system installers.

---

Quick Start

Build and Test

git clone https://github.com/parchlinux/systuner.git
cd systuner
make && make test

Install

sudo make install

---

CLI Reference

1. Generate Configuration to Standard Output

$ systuner
# Configuration generated by Systuner 0.1.0
# Target Profile : desktop | RAM: 15.30 GiB | Storage: Non-rotational (NVMe/SSD)

vm.dirty_background_bytes = 67108864
vm.dirty_bytes = 268435456
vm.dirty_expire_centisecs = 3000
vm.dirty_writeback_centisecs = 500
vm.swappiness = 10
vm.vfs_cache_pressure = 50
vm.page-cluster = 0
vm.max_map_count = 1048576

2. Inspect Difference Between Kernel and Recommended Values

$ systuner --status
+---------------------------------+-----------------+-----------------+----------+
| Sysctl Parameter                | Current Value   | Recommended     | Status   |
+---------------------------------+-----------------+-----------------+----------+
| vm.dirty_background_bytes       |        67108864 |        67108864 | OK       |
| vm.dirty_bytes                  |       268435456 |       268435456 | OK       |
| vm.dirty_expire_centisecs       |            3000 |            3000 | OK       |
| vm.dirty_writeback_centisecs    |             500 |             500 | OK       |
| vm.swappiness                   |              10 |              10 | OK       |
| vm.vfs_cache_pressure           |              50 |              50 | OK       |
| vm.page-cluster                 |               3 |               0 | CHANGE   |
| vm.max_map_count                |         1048576 |         1048576 | OK       |
+---------------------------------+-----------------+-----------------+----------+

3. Apply Live or Persist

# Apply parameters directly to /proc/sys (requires root)
sudo systuner --apply

# Persist configuration to /etc/sysctl.d/99-systuner.conf (requires root)
sudo systuner --write

---

Tuning Profiles

Profile	Scenario	Flush Timers	Swappiness	Max Map Count
desktop (default on AC)	Interactive desktop and workstation use	30s expire / 5s writeback	10 (SSD) / 100 (ZRAM)	1,048,576
gaming	Low-latency gaming (Steam, Wine, Proton)	15s expire / 2.5s writeback	5 (SSD) / 60 (ZRAM)	2,147,483,642
laptop (auto on battery)	Battery life preservation and disk sleep	60s expire / 15s writeback	10	1,048,576
server	High-throughput batch processing	30s expire / 5s writeback	20	1,048,576
low-memory	Embedded or legacy systems (RAM < 2 GB)	16 MB / 64 MB tight buffers	10 (VFS pressure 150)	262,144

systuner -p gaming --diff

---

Documentation

• Kernel Tuning Technical Guide: Analysis of memory writeback, swap mechanics, and kernel internals.
• C Library API Reference: Header documentation and code examples for libsystuner.
• Architecture and Design: Internal subsystem layout and memory model.
• Manual Page: Command line reference manual (man systuner).

---

License and Copyright

Copyright (C) 2026 Parch GNU/Linux
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).