Swap - Revision history

Axodentally: Clarify swap on zvol situation. Add notes to zram (recommendation to use userspace oom-killer, zswap instead of zram with writeback). Expand zswap section.

2026-03-26T19:46:45Z

Clarify swap on zvol situation. Add notes to zram (recommendation to use userspace oom-killer, zswap instead of zram with writeback). Expand zswap section.

← Older revision		Revision as of 19:46, 26 March 2026
Line 47:		Line 47:

	It is an alternative or complementary approach to swap disks, suitable for systems with enough RAM. In the event the system needs to swap it will move uncompressed RAM contents into the compressed area, saving RAM space while effectively increasing the available RAM at the cost of computational power for compression and decompression.		It is an alternative or complementary approach to swap disks, suitable for systems with enough RAM. In the event the system needs to swap it will move uncompressed RAM contents into the compressed area, saving RAM space while effectively increasing the available RAM at the cost of computational power for compression and decompression.

			{{Note\|When using zram for swap, it is highly recommended to enable a userspace OOM killer such as systemd-oomd (via {{nixos:option\|systemd.oomd.enable}}). Because zram acts as a block device with a hard capacity limit in RAM, the kernel's native OOM killer can sometimes fail to trigger in time under heavy memory pressure, leading to severe system lockups.<ref name="ChrisDown-zswapVsZram">https://chrisdown.name/2026/03/24/zswap-vs-zram-when-to-use-what.html</ref>}}

	See [https://search.nixos.org/options?query=zramSwap zramSwap] for a full list of available options and their descriptions.		See [https://search.nixos.org/options?query=zramSwap zramSwap] for a full list of available options and their descriptions.
Line 53:		Line 55:

	Zram supports writeback functionality, allowing idle or incompressible pages to be moved to a backing storage device rather than keeping it in memory. Currently, writeback can only use block storage devices (such as partitions) and does not support swap files. The backing partition must be manually created first, but does not require formatting.		Zram supports writeback functionality, allowing idle or incompressible pages to be moved to a backing storage device rather than keeping it in memory. Currently, writeback can only use block storage devices (such as partitions) and does not support swap files. The backing partition must be manually created first, but does not require formatting.

			{{Note\|While zram writeback allows moving incompressible or idle pages to disk, it is not fully integrated into the kernel's memory management subsystem. If your goal is to have compressed RAM that automatically spills over to a physical disk when full, [[#Zswap swap cache\|zswap]] is generally the better and more robust tool for the job <ref name="ChrisDown-zswapVsZram"/>.}}

	An example configuration:		An example configuration:
Line 82:		Line 86:
	== Zswap swap cache ==		== Zswap swap cache ==

	[https://docs.kernel.org/admin-guide/mm/zswap.html Zswap] is a compressed RAM cache for swap pages. It acts as a middle layer between system memory and a traditional disk-based swap device, storing compressed pages in RAM before optionally writing them out to disk-based swap if necessary. ~~It acts as an LRU cache~~.		[https://docs.kernel.org/admin-guide/mm/zswap.html Zswap] is a compressed RAM cache for swap pages. It acts as a middle layer between system memory and a traditional disk-based swap device, storing compressed pages in RAM before optionally writing them out to disk-based swap if necessary. Because zswap integrates directly into the kernel's memory management subsystem, it automatically and dynamically evicts the coldest pages to your backing disk when memory pressure rises. This graceful degradation provides a significant architectural advantage over zram for systems that have physical disk swap.

	Unlike zram, zswap requires a disk-based swap device or file to back it.		Unlike zram, zswap requires a disk-based swap device or file to back it.
Line 102:		Line 106:

	You can verify zswap's runtime status via <code>cat /sys/module/zswap/parameters/enabled</code> and inspect usage statistics with <code># grep -r . /sys/kernel/debug/zswap/</code>		You can verify zswap's runtime status via <code>cat /sys/module/zswap/parameters/enabled</code> and inspect usage statistics with <code># grep -r . /sys/kernel/debug/zswap/</code>

			A proper zswap configuration module is [https://github.com/NixOS/nixpkgs/pull/470366 currently under review].

	== Disable swap ==		== Disable swap ==
Line 206:		Line 212:
	== Adjusting swap usage behaviour ==		== Adjusting swap usage behaviour ==

	[https://docs.kernel.org/admin-guide/sysctl/vm.html#swappiness Swappiness] controls how aggressively swap space is used, specifically how to free up memory when needed. By default, Linux uses a swappiness value of 60. Higher values will make the kernel prefer swapping out idle processes over dropping caches. Conversely lower values will try to avoid swapping as much as possible, keeping processes in RAM unless absolutely necessary. An optimal value is workload dependent and ~~will~~ will require experimentation.		[https://docs.kernel.org/admin-guide/sysctl/vm.html#swappiness Swappiness] controls how aggressively swap space is used, specifically how to free up memory when needed. By default, Linux uses a swappiness value of 60. Higher values will make the kernel prefer swapping out idle processes over dropping caches. Conversely lower values will try to avoid swapping as much as possible, keeping processes in RAM unless absolutely necessary. An optimal value is workload dependent and will require experimentation.

	{{file\|/etc/nixos/configuration.nix\|nix\|		{{file\|/etc/nixos/configuration.nix\|nix\|
Line 222:		Line 228:
	== ZFS and swap ==		== ZFS and swap ==

	OpenZFS does not support swap on zvols ~~nor do they~~ support ~~swap files~~ on a ZFS ~~dataset~~.		OpenZFS does not support swap files on a ZFS dataset. Swap on zvols is technically supported, but does not support resume from hibernation and can lead to system lockup in high memory pressure situation and is thus not recommended (see [https://github.com/openzfs/zfs/issues/7734 OpenZFS issue #7734] and the [https://wiki.archlinux.org/title/ZFS#Swap_volume arch wiki on Swap Volumes in ZFS]).

	Instead you should set up a swap partition or swap file on a non-ZFS filesystem.<ref>https://utcc.utoronto.ca/~cks/space/blog/solaris/ZFSForSwapMyViews</ref>		Instead, you should set up a swap partition or swap file on a non-ZFS filesystem.<ref>https://utcc.utoronto.ca/~cks/space/blog/solaris/ZFSForSwapMyViews</ref>

	== Using swap files on Btrfs ==		== Using swap files on Btrfs ==

Malix: Undo revision 30906 by Malix (talk) ; confused zswap and zram swap

2026-03-20T15:03:32Z

Undo revision 30906 by Malix (talk) ; confused zswap and zram swap

← Older revision		Revision as of 15:03, 20 March 2026
Line 79:		Line 79:

	This is probably because the writeback device has already been mounted elsewhere (e.g. as swap). To avoid this you need to do as the [[#Disable swap]] section says and make sure your writeback device is not being mounted as swap (this can happen due to <code>systemd-gpt-auto-generator(8)</code>). Do note that zram writeback does ''not'' respect the swap on-disk format and will destroy your existing swap header.		This is probably because the writeback device has already been mounted elsewhere (e.g. as swap). To avoid this you need to do as the [[#Disable swap]] section says and make sure your writeback device is not being mounted as swap (this can happen due to <code>systemd-gpt-auto-generator(8)</code>). Do note that zram writeback does ''not'' respect the swap on-disk format and will destroy your existing swap header.

			== Zswap swap cache ==

			[https://docs.kernel.org/admin-guide/mm/zswap.html Zswap] is a compressed RAM cache for swap pages. It acts as a middle layer between system memory and a traditional disk-based swap device, storing compressed pages in RAM before optionally writing them out to disk-based swap if necessary. It acts as an LRU cache.

			Unlike zram, zswap requires a disk-based swap device or file to back it.

			Zswap is controlled by kernel parameters and can be enabled in your NixOS configuration by setting appropriate options through <code>boot.kernelParams</code>.

			{{file\|/etc/nixos/configuration.nix\|nix\|
			<nowiki>
			boot.kernelParams = [
			"zswap.enabled=1" # enables zswap
			"zswap.compressor=lz4" # compression algorithm
			"zswap.max_pool_percent=20" # maximum percentage of RAM that zswap is allowed to use
			"zswap.shrinker_enabled=1" # whether to shrink the pool proactively on high memory pressure
			];
			</nowiki>
			}}

			{{note\|If you use the <code>lz4</code> algorithm, you will also need to set {{nixos:option\|boot.initrd.systemd.enable}} to true}}

			You can verify zswap's runtime status via <code>cat /sys/module/zswap/parameters/enabled</code> and inspect usage statistics with <code># grep -r . /sys/kernel/debug/zswap/</code>

	== Disable swap ==		== Disable swap ==

Malix: /* Zswap swap cache */ deprecate (reason: duplicate)

2026-03-20T14:58:36Z

Zswap swap cache: deprecate (reason: duplicate)

← Older revision		Revision as of 14:58, 20 March 2026
Line 79:		Line 79:

	This is probably because the writeback device has already been mounted elsewhere (e.g. as swap). To avoid this you need to do as the [[#Disable swap]] section says and make sure your writeback device is not being mounted as swap (this can happen due to <code>systemd-gpt-auto-generator(8)</code>). Do note that zram writeback does ''not'' respect the swap on-disk format and will destroy your existing swap header.		This is probably because the writeback device has already been mounted elsewhere (e.g. as swap). To avoid this you need to do as the [[#Disable swap]] section says and make sure your writeback device is not being mounted as swap (this can happen due to <code>systemd-gpt-auto-generator(8)</code>). Do note that zram writeback does ''not'' respect the swap on-disk format and will destroy your existing swap header.

	~~== Zswap swap cache ==~~

	[https://docs.kernel.org/admin-guide/mm/zswap.html Zswap] is a compressed RAM cache for swap pages. It acts as a middle layer between system memory and a traditional disk-based swap device, storing compressed pages in RAM before optionally writing them out to disk-based swap if necessary. It acts as an LRU cache.

	~~Unlike zram, zswap requires a disk-based swap device or file to back it.~~

	~~Zswap is controlled by kernel parameters and can be enabled in your NixOS configuration by setting appropriate options through <code>boot.kernelParams</code>.~~

	~~{{file\|/etc/nixos/configuration.nix\|nix\|~~
	~~<nowiki>~~
	~~boot.kernelParams = [~~
	~~"zswap.enabled=1" # enables zswap~~
	~~"zswap.compressor=lz4" # compression algorithm~~
	~~"zswap.max_pool_percent=20" # maximum percentage of RAM that zswap is allowed to use~~
	~~"zswap.shrinker_enabled=1" # whether to shrink the pool proactively on high memory pressure~~
	];
	~~</nowiki>~~
	}}

	~~{{note\|If you use the <code>lz4</code> algorithm, you will also need to set {{nixos:option\|boot.initrd.systemd.enable}} to true}}~~

	~~You can verify zswap's runtime status via <code>cat /sys/module/zswap/parameters/enabled</code> and inspect usage statistics with <code># grep -r . /sys/kernel/debug/zswap/</code>~~

	== Disable swap ==		== Disable swap ==

Hasnep: Change GB to GiB and MB to MiB

2026-03-17T02:58:42Z

Change GB to GiB and MB to MiB

← Older revision		Revision as of 02:58, 17 March 2026
Line 23:		Line 23:
	swapDevices = [{		swapDevices = [{
	device = "/var/lib/swapfile";		device = "/var/lib/swapfile";
	size = 16*1024; # 16 GB		size = 16*1024; # 16 GiB
	}];		}];
	</nowiki>		</nowiki>
	}}		}}

	This will create a 16GB swapfile at <code>/var/lib/swapfile</code>. The <code>size</code> value [https://search.nixos.org/options?show=swapDevices.*.size is specified in ~~megabytes~~]. This will cause a swap file to be generated and an entry to be set up in <code>/etc/fstab</code>.		This will create a 16GB swapfile at <code>/var/lib/swapfile</code>. The <code>size</code> value [https://search.nixos.org/options?show=swapDevices.*.size is specified in mebibytes]. This will cause a swap file to be generated and an entry to be set up in <code>/etc/fstab</code>.

	== Swap partition ==		== Swap partition ==

Hasnep: Fix typo in URL

2026-03-17T02:50:33Z

Fix typo in URL

← Older revision		Revision as of 02:50, 17 March 2026
Line 218:		Line 218:
	You can see your current swappiness level by <code>cat /proc/sys/vm/swappiness</code>. The lowest accepted value is 0 while the maximum value is 200. The lowest sane value is 1 (0 causes the system to not scan for unused anonymous pages, i.e. memory freed by processes, at all).		You can see your current swappiness level by <code>cat /proc/sys/vm/swappiness</code>. The lowest accepted value is 0 while the maximum value is 200. The lowest sane value is 1 (0 causes the system to not scan for unused anonymous pages, i.e. memory freed by processes, at all).

	For more on tuning the swap, start with [https://wiki.archlinux.org/title/Swap#~~swappiness~~ ArchWiki]'s description.		For more on tuning the swap, start with [https://wiki.archlinux.org/title/Swap#Swappiness ArchWiki]'s description.

	== ZFS and swap ==		== ZFS and swap ==

Turnipjs: /* Adjusting swap usage behaviour */ fix typo

2026-02-12T23:41:21Z

Adjusting swap usage behaviour: fix typo

← Older revision		Revision as of 23:41, 12 February 2026
Line 206:		Line 206:
	== Adjusting swap usage behaviour ==		== Adjusting swap usage behaviour ==

	[https://docs.kernel.org/admin-guide/sysctl/vm.html#swappiness Swappiness] controls how ~~aggressibely~~ swap space is used, specifically how to free up memory when needed. By default, Linux uses a swappiness value of 60. Higher values will make the kernel prefer swapping out idle processes over dropping caches. Conversely lower values will try to avoid swapping as much as possible, keeping processes in RAM unless absolutely necessary. An optimal value is workload dependent and will will require experimentation.		[https://docs.kernel.org/admin-guide/sysctl/vm.html#swappiness Swappiness] controls how aggressively swap space is used, specifically how to free up memory when needed. By default, Linux uses a swappiness value of 60. Higher values will make the kernel prefer swapping out idle processes over dropping caches. Conversely lower values will try to avoid swapping as much as possible, keeping processes in RAM unless absolutely necessary. An optimal value is workload dependent and will will require experimentation.

	{{file\|/etc/nixos/configuration.nix\|nix\|		{{file\|/etc/nixos/configuration.nix\|nix\|

Httpdev: Added section on separately encrypted swap partition.

2026-01-05T22:22:50Z

Added section on separately encrypted swap partition.

@@ Line 153: / Line 153: @@
 By encrypting the swap with a random key kept in memory, we make sure that the contents of the swap become unreadable as soon as the data in memory has been lost. NixOS contains a handy helper to help you do this, generating a new key on each boot:
-<syntaxhighlight lang="nix">
+<syntaxhighlight lang="nix">swapDevices = [{
    device = "/dev/disk/by-partuuid/aaaaaaaaa-bbbb-cccc-dddd-0123456789ab";
    randomEncryption.enable = true;
-}];
+}];</syntaxhighlight>
-The selected device will have all its content made unusuable at every boot. Using a partuuid or partlabel is recommended because it is less subject to change when the overall partition scheme changes.
+The selected device will have all its content made unusable at every boot. Using a partuuid or partlabel is recommended because it is less subject to change when the overall partition scheme changes.
 If you want to use TRIM, set <code>randomEncryption.allowDiscards</code> in addition to the <code>options</code>. This has the security implication of:
@@ Line 168: / Line 166: @@
 You will need to weigh between the two.
-Using a random key makes hibernation impossible. If you want to use hibernation, use a regular [[Full Disk Encryption]] (or partial disk encryption with LUKS) scheme with an unchanging key.
+'''Warning:''' On some NixOS versions, if <code>randomEncryption.enable = true</code> and the <code>swap</code> is a file (rather than a partition) located on an encrypted LUKS partition, [https://discourse.nixos.org/t/swap-file-on-luks-partition/72234 the system can freeze as soon as the swap is used.]
 == Adjusting swap usage behaviour ==

Jopejoe1: add closing bracket

2025-11-06T18:13:35Z

add closing bracket

← Older revision		Revision as of 18:13, 6 November 2025
Line 61:		Line 61:
	enable = true;		enable = true;
	writebackDevice = "/dev/sda1"		writebackDevice = "/dev/sda1"
			};
	</nowiki>		</nowiki>
	}}		}}

Artoria2e5: /* Encrypt swap with random key */ ~

2025-07-10T11:06:17Z

Encrypt swap with random key: ~

← Older revision		Revision as of 11:06, 10 July 2025
Line 167:		Line 167:
	You will need to weigh between the two.		You will need to weigh between the two.

	Using a random key makes hibernation impossible. If you want to use hibernation, use a regular [[Full Disk Encryption]] scheme with an unchanging key.		Using a random key makes hibernation impossible. If you want to use hibernation, use a regular [[Full Disk Encryption]] (or partial disk encryption with LUKS) scheme with an unchanging key.

	== Adjusting swap usage behaviour ==		== Adjusting swap usage behaviour ==

Artoria2e5: /* Encrypt swap with random key */ ~

2025-07-10T11:05:46Z

Encrypt swap with random key: ~

← Older revision		Revision as of 11:05, 10 July 2025
Line 167:		Line 167:
	You will need to weigh between the two.		You will need to weigh between the two.

	Using a random key makes hibernation impossible. If you want to use hibernation, use a regular [[Full Disk Encryption]] scheme with an unchanging key. ~~(If you change the range of the LVM pool somewhat you can get partial disk encryption.)~~		Using a random key makes hibernation impossible. If you want to use hibernation, use a regular [[Full Disk Encryption]] scheme with an unchanging key.

	== Adjusting swap usage behaviour ==		== Adjusting swap usage behaviour ==