Documentation

How to read this page

nixram's core has NixOS and system-manager modules. You declare how much RAM the machine has. From that one declaration it configures a compressed swap device that lives in RAM (or a compressed cache in front of real disk swap), an out-of-memory watchdog, and a set of kernel memory settings.

Everything that varies by RAM size comes from the same row of the same table, so those values cannot contradict each other. The few settings that are properties of the swap medium rather than of the machine are constants, listed under Shared settings.

This page assumes you are comfortable with systemd and NixOS, and assumes nothing about kernel memory management. The words you need are defined as you meet them, and every kernel term used anywhere on this page has a plain definition in the glossary at the end.

Everything here is sourced. Each value carries a mark saying where it came from: someone else's published work, our own reasoning, or the kernel's own default left alone on purpose.

Why nixram?

The friction. Getting a Linux box to behave under memory pressure means picking a compressed swap size, then a real memory cap, then a swap priority, then a watchdog threshold, then four or five kernel settings. Each has its own blog post. None of them checks the others. A value that is right on a 512 MiB VPS is wrong on a 64 GiB server, and nothing tells you which one you are copying.

The fix. One declaration — how much RAM the machine has — indexes a table that holds every one of those values, tiered across fourteen RAM sizes, with the source of each value written down next to it.

User-session memory policy

The core module manages host-wide memory pressure. A separate Home Manager output owns the parts that belong to a logged-in account: Profile Sync Daemon configuration and user units, plus the user half of an optional device-memory foreground-session booster.

Profile Sync Daemon only runs with an explicit browser list, so it never silently adopts every supported browser it finds. On a distro-managed host, the host backend supplies PSD's command and package; the Home Manager module supplies the configuration and the user service.

The device-memory booster is deliberately narrow. It is not a general container or GPU-sharing manager. Before the system service can start, nixram checks that the current cgroup root exposes /sys/fs/cgroup/dmem.capacity; without it, the upstream daemon cannot calculate the device-memory limits it needs to apply.

The words you need first

Four definitions carry the rest of this page. Everything else is in the glossary at the end.

The two mechanisms

zram

A block of your own RAM set up as a swap device. Cold pages get compressed and stay in memory, so you fit more into the same RAM. No disk, no file and no partition is involved anywhere in the zram path.

zswap

A compressed cache that sits in front of a real disk swap partition. Pages are compressed on their way out, and cold ones are written through to the disk in the background. Once the cache is full it stops accepting, and pages go straight to disk until it drains again. It is not a swap device itself and cannot work without one behind it.

The two limits

zram-size — the ceiling

This is not disk space of any kind. It is a ceiling on how much compressed data the zram device may hold, and all of that data lives in RAM. The name is misleading, and the kernel's own name for the attribute underneath (disksize) is worse. There is no disk, no file and no partition anywhere in this path. Treat it as a number, not as storage.

zram-resident-limit — the budget

The real cap on how much actual RAM the compressed pool may ever occupy. This is the limit that protects the machine. It maps directly onto the kernel's /sys/block/zramN/mem_limit.

The model: a ceiling and a budget

Everything else on this page follows from one idea. zram is given two separate limits that do two different jobs.

The first is a ceiling: how much compressed data the device may hold. It is generous. It is also just a number — nothing is allocated because of it, and no storage of any kind is reserved.

The second is a budget: how much actual RAM the compressed pool may ever occupy. It is tight, and it is real. This is the one that protects the machine.

Because the budget does the safety work, the ceiling costs nothing. Setting it generously gives compression room to stretch on a machine whose pages happen to compress well, without exposing the machine to any risk if they do not.

        level = "4G"   ·   a machine with 4 GiB of RAM

  ┌───────────────────────────────────────────────────────────┐
  │  CEILING     zram-size = ram * 75 / 100           3 GiB   │
  │                                                           │
  │  How much compressed data the device may hold.            │
  │  A number only. No disk, no file, no partition.           │
  │  Reaching it means: the device is full, swap is full.     │
  └───────────────────────────────────────────────────────────┘
                        │
                        │  all of it actually living in
                        ▼
  ┌───────────────────────────────────────────────────────────┐
  │  BUDGET      zram-resident-limit = 25% of RAM     1 GiB   │
  │                                                           │
  │  How much real RAM the compressed pool may occupy.        │
  │  Enforced by the kernel. This is the real protection.     │
  │  Reaching it means: no more pages accepted, same as full. │
  └───────────────────────────────────────────────────────────┘

  Whichever limit is reached first is the one that stops you.
  Pages that compress well hit the ceiling. Pages that compress
  badly hit the budget. Both outcomes are bounded and safe.

What each one protects against

• The ceiling protects against unbounded swap. Without it, the kernel would keep handing pages to a device with no stated capacity. A bounded absorber followed by a timely out-of-memory decision is better than an unbounded one followed by a slow death.
• The budget protects against the compressed pool eating the machine. Compressed pages are still RAM. Without a cap, badly-compressing data could grow the pool until the thing meant to relieve memory pressure becomes the cause of it.

Is swapping to zram bad?

No. Parking cold pages in compressed RAM is the design working as intended. The instinct that swap-in-use is a red flag comes from disk swap, where every touched page costs a real disk read. zram swap is still RAM. It is closer to "this data got compressed" than to "this data left memory".

Watch stall time and the rate of out-of-memory kills. Do not watch swap-used percentage.

Quick start

1. Find your level. Run this on the machine you are configuring. It reads the real RAM total from /proc/meminfo and prints a line to paste.

nix run github:julian-corbet/nixram-corbet-ch#detect-level

2. Add the flake input.

inputs.nixram.url = "github:julian-corbet/nixram-corbet-ch";

3. Import the module and declare the level.

imports = [ inputs.nixram.nixosModules.nixram ];

nixram = {
  enable = true;
  level = "4G";
};

That is the whole configuration. There is no build-time detection and no default level: Nix builds cannot read the target machine's live memory, so the level is a fact you detect once and commit, like a disk UUID. Enabling the module without a level is a hard build error with a message pointing at the fix.

On a laptop with a swap partition you keep, or one that hibernates to it, add the zswap mode instead. It needs at least one entry in swapDevices, and it takes effect on the next boot rather than on rebuild.

nixram = {
  enable = true;
  level = "16G";
  mode = "zswap";
};

To check it came up, on a zram machine:

zramctl                       # the device, its algorithm, and what it holds
swapon --show                 # zram at priority 100, above any disk swap
systemctl status systemd-oomd # the watchdog, where the level arms it

The full level table

Fourteen anchor sizes. Every value below is an expression, not a baked-in number: ram is zram-generator's own variable for the machine's total detected RAM in MiB, evaluated against the real /proc/meminfo at boot. A machine that rounds up to a larger anchor still computes from its own true RAM.

What the marks mean

• C Cited. Taken from someone else's published work — a distribution's shipped default, upstream documentation, or the tool's own worked example — and applied as it stands. Somebody outside this project already made the case for it.
• D Stated directly. A literal figure the maintainer gave from firsthand production experience or a worked example — not derived by argument, and not this project's own inference. Applied as given.
• E Our own reasoning, not yet measured. nixram picked this value by argument, not by experiment. The argument is written down. The measurement has not been done. These are tracked as open questions and get upgraded to cited or corrected as results come in.
• K The kernel's own default, untouched. nixram deliberately sets nothing here and lets the kernel's computed or shipped value stand.

The ceiling column is now just two flat fractions, not a per-tier formula: plain ram (100% of RAM) at 256M/512M/1G, ram * 75 / 100 (75% of RAM) at every tier from 2G through 128G. It is derived, not guessed: the maintainer's own formula for the ceiling is "take the physical budget, multiply by pi, and take the nearest base-2-ish value" — meaning the nearest 3-smooth number (only 2 and 3 as prime factors: 256M, 384M, 512M, 768M, 1G, 1.5G, 2G, 3G… the sizes RAM and VPS tiers actually ship in). Because the resident-limit budget behind it ([2] below) is a fixed percentage within each tier group (30%, 25%, or 20%), and the 3-smooth grid is geometrically spaced, "nearest 3-smooth number to budget × pi" reduces to the same flat fraction for every tier in a group: 30% × pi ≈ 0.94, which rounds to exactly 1.0 (plain ram); 25% × pi ≈ 0.79 and 20% × pi ≈ 0.63 both round to 0.75. No pi()/round()/log() is evaluated live at boot — it is just the two flat percentages above. The mechanism itself is the maintainer's own, and it is checked directly against his own worked examples: 256M/512M/1G resolve to 256 MiB/512 MiB/1 GiB ("almost a GB" at 1G, his own words), and ~128G resolves to 96 GiB — his own direct correction ("96GB is better") over an earlier version of this formula that rounded down to a plain 64 GiB. The curve connecting those two endpoints, and exactly which tiers fall into which resident-limit group, is this project's own extrapolation.

Note that the watchdog being on above 256M is our own judgement, not a stated one. What is cited is the threshold it fires at (60% for 30 s), listed under Shared settings.

The values above are transcribed by hand from the module's own level table in levels.nix. Both this page and the copy in the repository documentation can drift away from it. Where they disagree, levels.nix is the source of truth.

Rounding up is safe

The detector rounds up to the next anchor, never down. That is safe because every value is an expression evaluated against the machine's real RAM at boot. A 20 GiB machine assigned to the 24G level still computes from its real 20 GiB. A machine larger than 128 GiB is assigned the 128G level, because there is nothing above it, and the expressions still compute from its real RAM.

Rounding into the 64G tier is a good example. Any machine above 32 GiB and up to 64 GiB lands there. On a 33 GiB machine that means a ceiling of about 24.75 GiB (75% of its real 33 GiB, not of the 64G anchor) and a budget of about 6.6 GiB (20% of the same real 33 GiB) — both self-correct against the machine's own true size, so there is no fixed cap to distort the picture the way an older, capped version of this formula once did.

Every anchor boundary in the current table shifts only continuous percentages — the ceiling, the budget, the reclaim threshold — which self-correct against the machine's real RAM regardless of which anchor picked them, and the same architecture pairing (zstd(level=3) alone at 256M-1G; lz4 plus zstd(level=3) recompression at 2G-128G, see why each tier is shaped this way) now applies uniformly across all three of the 256M/512M/1G tiers. A 768M anchor briefly existed earlier in this project's history, specifically to close a rounding gap between 512M and 1G while their zram architectures still differed from each other. Once 256M-1G were unified onto one architecture and one swappiness value, 512M and 1G became identical in every formula, and the anchor stopped changing anything a rounded-up box would experience — it was removed as part of the same correction, not kept around as an inert historical marker.

Why each tier is shaped this way

Read the 4G block first. Every other tier is that one with a scarcity turned up or down.

Shared settings

The zram profile

Most of these hold at every level when mode = "zram", because they are properties of the swap medium, not of the machine. vm.swappiness is the one exception: it genuinely varies by level, because how much true RAM remains and how much file cache there is to sacrifice before ever touching anonymous memory changes with RAM size, on top of the medium-cost question that doesn't. Under mode = "zswap" the swap-related settings differ, and under mode = "none" they are left alone entirely.

Where the watchdog is armed

The pressure thresholds are applied to -.slice, which covers the whole system, and user.slice, the parent of every logged-in user's session. nixram also points systemd.oomd.enable at its own oomd.enable with mkDefault, in both directions. That matters at 256M, where nixpkgs would otherwise leave the daemon running — its memory cost is the entire reason that tier disarms it.

Deliberately absent: SwapUsedLimit and ManagedOOMSwap, the triggers that fire on a swap-used percentage. Such a percentage would be measured against the generous ceiling, which is larger than the real budget on purpose. It would read "plenty of headroom" right up to the moment the real wall is hit. They are not configured at all, not even as a decorative backstop.

Protected units

oomd.protectedUnits defaults to [ "sshd.service" ] and gets two independent layers, both applied at every level regardless of whether the watchdog is enabled:

• ManagedOOMPreference = "omit" tells the userspace watchdog to leave the unit alone.
• OOMScoreAdjust = -900 tells the kernel's own last-resort killer to pick this process last. This is the layer that still protects the unit when the watchdog is off, absent, or too slow to matter.

Name only services that actually exist. A name matching nothing will materialise a skeleton unit. The .service suffix is accepted and normalised away.

The zswap profile

Two things to know before choosing this mode. It requires a real swap device — mode = "zswap" asserts that config.swapDevices is not empty, because zswap is a cache in front of disk swap, not a swap device itself. And it takes effect on the next boot only. These settings are kernel command-line parameters, off by default upstream, so nixos-rebuild switch alone does not retroactively enable zswap on a running kernel. That is a limitation of the mechanism, not a shortcut nixram took.

mode = "none"

Leaves swappiness and read-ahead untouched entirely, because there is no managed swap medium to have an opinion about. Still applies the reclaim watermarks, the MGLRU setting, the watchdog, and the protected-unit layers.

Overriding any of it

Every sysctl assignment uses mkDefault, so your own configuration can override any single one by simply assigning it — no lib.mkForce needed. sysctls.enable = false turns the whole kernel-settings layer off while keeping the swap device and watchdog wiring intact.

Option reference

All under nixram.

Also part of the surface

• Flake outputs: nixosModules.nixram and nixosModules.default, the detect-level app, and checks.
• Supported systems: x86_64-linux and aarch64-linux.

Not exposed as options

Some values are level data or hardcoded rather than user-facing: zswap.zpool and zswap.compressor (hardcoded), and the watchdog's pressure limit and duration (level data for mode = "zram": 60% for 30 s everywhere; mode = "zswap" keeps the 60% limit but overrides the duration to 3 s, matching the real production oomd config on the one machine that runs zswap).

The kernel settings themselves — vm.swappiness, vm.page-cluster, the watermark pair and MGLRU's dwell time — have no nixram option either, but all use mkDefault, so you override them directly from your own configuration instead.

One implementation note

Because level has no default, no part of the module ever indexes the level table with it directly. Everything goes through an internal value that falls back to an arbitrary valid level when it is null. A real user never sees that fallback. It exists only so that forcing unrelated parts of your configuration cannot crash evaluation before the friendly assertion gets a chance to speak.

Security

nixram runs no network service and opens no port. What it does affect is which processes survive when the machine runs out of memory, so these are the concrete guarantees:

• Your SSH daemon is protected by two independent layers, at every level, whether or not the watchdog is enabled. ManagedOOMPreference = "omit" tells the userspace watchdog to skip it; OOMScoreAdjust = -900 tells the kernel's own killer to pick it last. The second keeps working when the first is off, absent, or too slow.
• The watchdog fires on stall time, not on a percentage. A swap-used percentage measured against the generous ceiling would read "plenty of headroom" right up to the real wall, so those triggers are not configured at all.
• No daemon of nixram's own sits in the memory path. The only unit it ships is a oneshot that runs on a timer at the lowest CPU and I/O priority and then exits.
• Nothing is silently guessed. Enabling the module without a level fails the build with a message. Choosing zswap without a real swap device fails the build with a message.
• The compressed pool is bounded by the kernel, through zram-resident-limit, at every level with no exceptions — 64G and 128G included.

If you find a problem with any of this, open an issue at github.com/julian-corbet/nixram-corbet-ch/issues. There is no private disclosure channel, because there is no network surface to disclose against.

The judgement calls

What was chosen, what the alternative was, and what would change our mind.

Exceeding upstream's recommended sizing

zram-generator's own documentation recommends sizing zram to somewhere between 0.1 and 0.5 of RAM. nixram's ceiling deliberately exceeds that at every tier: plain ram, all of it, at 256M/512M/1G, and 75% of RAM from 2G all the way through 128G — a flat fraction, not a taper down to something smaller at the large end.

Why we think that is defensible. That guidance is written for setups where the ceiling is the only ceiling. nixram's default pairs it with a real memory budget that does the actual safety work. The catch: if you set zram.sizing = "virtual" you have stepped outside that net, and the 0.1–0.5 caution applies to you again in full.

Where the two flat fractions come from. The ceiling formula is the maintainer's own: "take the physical budget, multiply by pi, and take the nearest base-2-ish value" — the nearest 3-smooth number (only 2 and 3 as prime factors, the sizes RAM/VPS tiers actually ship in). Because the resident-limit budget behind it is a fixed percentage within each tier group (30%, 25%, or 20%), this reduces exactly to two flat fractions: 1.0 at the 30%-budget tiers, 0.75 at the 25%- and 20%-budget tiers. See the level table for the full derivation and the maintainer's own worked examples it was checked against.

What would change our mind: evidence that a generous ceiling causes harm even with a budget enforced behind it.

Reversed: the budget used to be unset at 64G and above

An earlier version of this design left the budget unset above 32G, reasoning that at those anchor sizes the ceiling was already small enough that a second cap looked like decoration. That reasoning was wrong: it conflated a memory-safety argument (is the ceiling already small enough) with what the budget actually bounds (how much RAM may be mid-compression-cycle at once, a CPU-tax question, not a redundant safety net). It also meant a machine that rounded up into 64G had no physical cap at all, regardless of the ceiling's own size.

Current state: every tier sets a real budget, tapering 30% (256M-1G) → 25% (2G-16G) → 20% (24G-128G). Only the two endpoints of that taper (30% at the small end, 20% at roughly 128G) are the maintainer's own stated figures; the 25% band in between, and specifically where the step down to 20% begins (24G rather than 32G or 64G), are this project's own extrapolated placement connecting those two points, not independently confirmed.

The watchdog is off at 256M

The daemon carries its own memory cost, which is a meaningfully larger fraction of a 256 MiB machine than of any larger tier. What this gives up: the early-warning layer. It does not disable the kernel's own out-of-memory killer, and the protected-unit layer still applies.

What would change our mind: a measurement of that cost. It is currently unmeasured, which is precisely why the choice is marked as our own reasoning rather than cited. Note that the reverse choice — arming the watchdog at every larger tier — is equally our own reasoning. What is cited is the threshold, not the on/off decision.

The recompression setting, and why 256M/512M/1G skip it entirely

256M, 512M, and 1G all use a dense zstd(level=3) primary with no recompression pass at all — the maintainer's own direct instruction: "everything up to a GB goes to zstd primary and done." 2G through 128G pair a cheap lz4 primary with a zstd(level=3) recompression pass instead. This is a firm pairing rule, not a size threshold: whenever the primary is already zstd(level=3), recompression is off, full stop; whenever it isn't, recompression runs behind it.

A correction worth stating plainly, not glossing over: an earlier version of this design gave 256M/512M the lz4+recompression architecture instead, reasoning that the small tiers must "lean on zram willingly" and needed a cheap primary. That over-applied a separate, much narrower instruction — a lz4-then-recompress path reserved as an uncertain exception for the weakest possible hardware, not the default for the whole small-tier band. It was a real implementation mistake, caught and reverted: 256M through 1G all share one shape now.

Where a recompression pass does run, the setting is zstd(level=3) — the same setting used as the small tiers' own primary, reused rather than a separate, denser exotic level. An earlier version of this design used zstd(level=12) here, reasoning that idle, off-the-hot-path pages could justify spending far more CPU per page. That reasoning wasn't wrong about level 12 being affordable in isolation, but it treated the recompression level as its own separate design question, when the simpler, equally defensible policy is to reuse the one dense setting already measured correct for the small tiers' primary (experiment 006: real density gain over level 1, well short of the level-6 cost cliff) — one dense reference point in the whole system, not two. Whether zstd(level=3) recovers as much absolute density as level=12 did on genuinely idle pages specifically is still open, tunable via zram.recompressionAlgorithmOverride if a future measurement argues for going denser. Never step down to level=1 as a fallback.

Why 256M-1G differ from a ~128G server, despite both containing "reluctant" tiers: the real distinguishing variable turned out not to be true-RAM headroom at all, but workload compute-boundedness, per the maintainer directly: "with 1GB RAM, you need to get whatever you can. With the big box you can wait for it later. The bigger box is also more compute bound than the smaller one." A 256M-1G-class box sees light, few-user usage with no heavy concurrent demand competing for its CPU, so paying zstd's cost synchronously, on the compress path, costs nothing that's actually needed elsewhere — and because these boxes are genuinely RAM-starved, grabbing whatever density is available immediately beats waiting for an idle window. A ~128G server runs actively compute-bound workloads — LLMs, genAI, many concurrent apps — competing hard for the very CPU a dense primary would consume, so the cheap primary protects that live demand and the expensive recompression pass is deferred to genuine idle time instead, which a machine at that scale reliably has. Placing the actual architecture boundary at 1G/2G specifically, rather than describing only the two ends the maintainer gave worked examples for, is this project's own inference — plausible, not independently confirmed tier by tier.

The two-phase recompression timer

One run repacks whatever the previous run marked as untouched and that has stayed untouched since. Then it marks the current set for the next run. Mechanically: phase one writes type=idle to the recompression control, phase two writes all to the idle control.

The alternative was a single-phase design, which would recompress the entire device every run — everything looks untouched in the instant right after being marked. The kernel clears a page's untouched flag the moment it is written again, which is what makes the dwell period real.

The timer itself fires often — every 15 minutes by default — but that's a check frequency, not a run frequency: each firing reads CPU PSI's "some" line first and only does the mark/recompress work if the last 10 seconds show genuine idleness (avg10 below 10%), otherwise it logs a line and waits for the next tick. Cadence is "whenever there is idle time," not a fixed calendar interval, on purpose: a fixed daily run either forces this work into contention on a box that's busy at exactly that moment, or wastes a box's several real idle windows by only ever taking one of them. A box under sustained, genuine load may simply never get a window to recompress at all — correct behaviour for a job whose entire premise is "only touch this when nothing else needs the CPU," not a bug.

The service runs at the lowest scheduling priority for both CPU and I/O, deliberately kept out of the way of the exact symptom it exists to prevent. The timer is persistent, so a missed run catches up.

Requirements: Linux 6.2 or newer with CONFIG_ZRAM_MULTI_COMP. The script checks for the kernel control file first. If it is absent it logs one explanatory line and exits cleanly — it does not fail the timer or the boot.

Recompression stays on at 64G and 128G

Machines at this scale are the ones the compute-boundedness reasoning above describes directly — LLMs, genAI, and many concurrent apps competing for CPU — so the cheap-primary-plus-deferred-recompression shape is the intended fit here, not just consistency for its own sake. The marginal value is still genuinely modest once the physical resident-limit budget (20% of RAM) is already large in absolute terms, even though the ceiling itself keeps scaling with RAM (75%, same as every other tier from 2G up) rather than sitting at a fixed cap. For a machine running one big workload that does not swap usefully — not actually compute-bound in the sense above — the documented alternative is mode = "none".

Non-goals

• No build-time RAM auto-detection. Nix builds cannot read the target machine's live memory, so the level is a fact you detect once and commit, like a disk UUID.
• No stacking of zram and zswap. That means compressing the same page twice, and nobody has published a measurement showing it helps.
• No swap-percentage watchdog triggers anywhere.
• No universal vm.min_free_kbytes formula.
• Not a container or cgroup memory manager. Host level only.

Open questions

Six experiments are defined in the repository. Four remain open, below. The other two — whether lz4 or lzo-rle belongs in the fast-primary slot, and whether 256M's primary should run zstd(level=1) or zstd(level=3) — have already run and closed, and their results are already folded into the table and the reasoning above: lz4 won as the uniform fast primary on every tier that also runs zstd recompression, and zstd(level=3) won as 256M/512M/1G's shared primary. Results from the remaining four feed back into the table as marker upgrades or corrections.

Being visibly unfinished where the work is unfinished is the point. A value marked as our own reasoning is not a value we are hiding — it is one we have not yet earned the right to call settled.

Glossary

Every term used on this page, in plain words. The two mechanisms and the two limits are defined near the top, where you need them first.

Tools and modules

zram-generator

The upstream systemd tool that actually creates and configures the zram device. nixram writes its configuration rather than implementing a device of its own.

zramSwap (the built-in NixOS module)

The older NixOS option set for zram. nixram deliberately does not use it. It can only set the virtual size and has no concept of a real memory budget, which is the mechanism nixram's whole model depends on. nixpkgs itself documents zram-generator as the intended successor.

What the kernel is doing

page

The fixed-size chunk the kernel moves memory around in. On the machines nixram targets it is 4 KiB.

reclaim

The kernel taking memory back from one thing so it can give it to another. Background reclaim is the kernel doing this ahead of time, quietly, before anything is actually blocked.

page fault

What happens when a process touches a page of memory that is not currently in RAM and the kernel has to fetch it back.

thrashing

The machine spending so much of its time moving pages in and out that useful work effectively stops.

OOM / the OOM killer

Out of memory. The kernel's last-resort response to running out: it picks a process and kills it. It has no idea which process you cared about.

systemd-oomd

An out-of-memory watchdog running in userspace. It watches for trouble and acts before the kernel's last-resort killer has to, which means the choice of what dies is made with more information and less panic.

PSI / pressure stall information

The kernel's own measurement of how long processes actually sat blocked waiting on memory. Stall time, in other words. It is a direct measure of the symptom you care about, unlike a percentage of some capacity.

cgroup / slice / -.slice / user.slice

The systemd hierarchy that resources are accounted against. -.slice is the root, covering the whole system. user.slice is the parent of every logged-in user's session. These are the two places nixram arms the watchdog.

The kernel settings nixram touches

sysctl

Kernel settings that can be changed at runtime. The memory ones are all named vm.something.

vm.swappiness

How eagerly the kernel moves pages to swap rather than dropping cached file data instead. Higher means swap sooner. The range now goes to 200, not 100 — the kernel explicitly sanctions values above 100 where swapping beats re-reading from disk.

vm.page-cluster

How many pages the kernel reads ahead when one swapped page is faulted back in. Its entire justification is amortising a disk seek across several pages at once.

vm.watermark_scale_factor

How much earlier the kernel starts reclaiming in the background, measured against a memory zone's free-page thresholds. Higher means start earlier and keep more headroom.

vm.watermark_boost_factor

A related setting that temporarily raises those thresholds after memory fragmentation events. nixram sets it to 0.

vm.min_free_kbytes

How much RAM the kernel keeps permanently in reserve. nixram deliberately does not touch this one.

MGLRU / multi-generational LRU

A newer kernel algorithm for deciding which pages are cold. It sorts pages into generations by age rather than one long list.

min_ttl_ms

A minimum dwell time before MGLRU is allowed to act on a generation of pages. It exists to stop the machine thrashing on pages that only just cooled down. It is not a sysctl. It lives in a kernel control file.

systemd-tmpfiles w rule

The mechanism nixram uses to write that one value, because it has no sysctl name to be set through.

boot.kernelParams

Kernel command-line settings, fixed at boot. This matters in exactly one place: zswap is configured through them, so zswap changes only take effect after a reboot.

mem_limit

The kernel control file that zram-resident-limit writes to. Only relevant if you are reading kernel documentation alongside this page.

Compression

zstd

The compression algorithm nixram uses everywhere. The fact that matters here: unpacking is essentially as fast no matter how hard the data was packed.

compression vs recompression

Compression happens on the way in, in the kernel path, while a process waits for the memory. It has to be fast. Recompression happens later, on a schedule, over pages nothing has touched, with nothing waiting on it. It can afford to be slow.

CONFIG_ZRAM_MULTI_COMP

The kernel build option that lets zram hold a second, slower compression setting alongside the fast one. Recompression needs it, plus Linux 6.2 or newer.

long-range matching / optimal parser

The techniques high zstd settings spend their extra time on. Both need a lot of surrounding data to pay off. A 4 KiB page does not give them much to work with, which is why the gain from a denser setting is modest here.

sysfs / /sys/block/zramN/

The kernel control files for a zram device. The recompression timer writes to two of them: one marks pages as untouched, the other tells the kernel to repack the marked ones.

zswap internals

max_pool_percent

The share of RAM the zswap cache is allowed to occupy.

accept_threshold_percent

Once the cache has filled up and stopped accepting pages, this is how far it must drain before it starts accepting again. It exists so the cache does not flap on and off right at the boundary.

shrinker

A zswap feature that pushes cold compressed pages out to the real disk swap early, rather than waiting for the cache to fill up and block.

zpool / zsmalloc / z3fold / zbud

The allocator zswap packs compressed pages into. Only zsmalloc still exists in current kernels. The other two have been removed, so there is no choice left to make and nixram offers none.

Nix terms

eval-time assertion

A build-time check that fails with a written message instead of producing a broken system.

mkDefault / mkForce

Nix module-system priorities. Values nixram sets with mkDefault can be overridden from your own configuration by simply assigning them, with no ceremony.

anchor level

nixram's own word for one of the fourteen RAM sizes in its table. Your machine is assigned to the nearest anchor at or above its real RAM.

the taper

nixram's own word for how the zram-resident-limit budget steps down as RAM grows: 30% at 256M-1G, 25% at 2G-16G, 20% at 24G-128G. The ceiling itself no longer tapers — it is two flat percentages, not a curve.

Contributing

nixram is MIT licensed. Corrections to the sourcing are as welcome as code — if a value here is attributed to the wrong place, that is a bug.

git clone https://github.com/julian-corbet/nixram-corbet-ch
cd nixram-corbet-ch
nix flake check

Experiment results are especially welcome. If you have run any of the four open questions above on real hardware, the numbers are worth more than the reasoning they would replace.