{{Header}} {{Title|title= swap-file-creator }} {{#seo: |description=Creates a swap file on LUKS-encrypted systems, optionally on unencrypted disks. |image=File-swap-promo.jpg }} [[File:File-swap-promo.jpg|thumb|swap-file-creator logo]] {{intro| Creates a swap file on LUKS-encrypted systems. Useful for systems with low RAM, such as virtual machines. }} = Introduction = swap-file-creator adds a swap file on a LUKS-encrypted disk to the system. On every boot, it creates a new swapfile if the disk is LUKS-encrypted. No swapfile will be created by default on unencrypted disks. Optional: Create a swap file on an unencrypted disk. This is useful for systems with low RAM such as those inside virtual machines. It prevents common cases of freezing of VMs with low RAM during upgrades. Such as during Linux kernel module building (VirtualBox guest additions) as well as kernel header package upgrades. * https://forums.whonix.org/t/swap-swap-file-whonix-gateway-freezing-during-apt-get-dist-upgrade-encrypted-swap-file-creator/8317 * https://forums.whonix.org/t/whonix-xfce-for-virtualbox-users-ram-increase-required/8993 * https://forums.whonix.org/t/default-ram-setting/12312 It has an ENOUGH_RAM setting which defaults to 1950 MB. If there is more than enough RAM, it will not advise to increase RAM. (This setting only controls whether a low-RAM warning is shown; it does not disable swap creation.) An optional option exists to shred the swapfile on shutdown but this is slow. {{Github_link|repo=swap-file-creator|path=/blob/master/etc/default/swap-file-creator}} Earlier versions created an encrypted swap file with an ephemeral key using dm-crypt. Due to a Linux kernel bug, this is no longer supported in Debian trixie and later; current versions instead create a regular swap file on top of LUKS full-disk encryption. https://lore.kernel.org/lkml/20251111231835.1232ad8f@kf-m2g5/T/#u For further information, see: {{Github_link|repo=swap-file-creator|path=}} = Installation = Platform dependent. * [[{{project_name_short}}|{{project_name_short}}]]: Available. Installed by default. Otherwise, see footnote. {{Install Package| package=swap-file-creator }} * [[{{q project name short}}|{{q project name short}}]]: [[Unsupported]]. Setting up swap and/or encryption of any kind is completely up to Qubes. [[Unspecific|Unspecific to {{project_name_short}}]]. Opt-in available. = Configuration = The config file is located at [https://github.com/Kicksecure/swap-file-creator/blob/master/etc/default/swap-file-creator /etc/default/swap-file-creator]. Here you can change various parameters for the swapfile creation such as the path for where to create the swapfile at startup. This might be useful in case you have a copy-on-write system like ZFS or BtrFS. {{Open with root rights|filename= /etc/default/swap-file-creator }} For example, to set a custom swap file size of 1024 MB, add. {{CodeSelect|code= SWAP_FILE_SIZE_CUSTOM_MB=1024 }} Save. Done. Settings will be applied after reboot (or when swap-file-creator is restarted). Other configuration options include (see /etc/default/swap-file-creator for the full list): * {{CodeSelect|inline=true|code= SWAPFILE=/var/swapfile }} : Path where the swap file is created. * {{CodeSelect|inline=true|code= ENOUGH_RAM=1950 }} : RAM threshold in MB after which no low-RAM advice is shown. Does not disable swap-file-creator. * {{CodeSelect|inline=true|code= DO_PRE_CHECK=yes }} : When yes (default), swap-file-creator only creates a swap file if the target path is on a LUKS-encrypted device. Set to no to allow creating a swap file on unencrypted disks ('''not recommended''' for privacy). * {{CodeSelect|inline=true|code= SHRED_ON_STOP=no }} : When set to yes, the swap file is shredded before deletion when stopping the service. * {{CodeSelect|inline=true|code= SWAPON_EXTRA= }} : Extra options passed to swapon. * {{CodeSelect|inline=true|code= MKSWAP_EXTRA= }} : Extra options passed to mkswap. = Check Swap File Size = {{CodeSelect|code= sudo du -sh /var/swapfile }} = Functionality Test = To check it is working correctly, check the amount of free and used memory in the system. {{CodeSelect|code= free -m }} Next, display the swap usage summary. {{CodeSelect|code= sudo swapon -s }} For troubleshooting purposes, [[Troubleshooting#Daemon_Log|Check Daemon Log]] and search for unit-name: swap-file-creator. = Live Mode = swap-file-creator does not run if [[grub-live|live mode]] is detected. Live mode is detected via the helper-scripts live mode detection mechanism /usr/libexec/helper-scripts/live-mode.sh, which sets a live_status_detected flag used by swap-file-creator. = Debugging = Only required in case of issues. Otherwise the user can skip this wiki chapter. == Error States == In case swap-file-creator is failing at boot time, it does not break the boot process. For example, host kernel versions other than the one recommended on the [[VirtualBox/Recommended Version|recommended VirtualBox version]] wiki page are likely to break VirtualBox VMs [[Kernel#Kernel_Issues|in many ways]] if these are unsupported by VirtualBox. https://www.virtualbox.org/ticket/17055#comment:3 In this case, swap-file-creator might [https://forums.whonix.org/t/solved-swap-file-creator-breaks-with-whonix-16-for-virtualbox-and-newer-linux-host-kernel-version-5-18/13799 be broken] and this being the only [https://forums.whonix.org/uploads/default/original/2X/6/694af8fb74342a848d9fae832ba028c481e18a72.png visible] error, but this still does not break the boot process. However, when using kernel versions unsupported by VirtualBox, many other things will be broken and the system will be unbootable anyhow. == Manual Swap File Creation == TODO: document = Disable = {{CodeSelect|code= sudo systemctl stop swap-file-creator }} {{CodeSelect|code= sudo systemctl disable swap-file-creator }} {{CodeSelect|code= sudo rm -f /var/swapfile }} = Development = * main source code file: {{Github_link|repo=swap-file-creator|path=/blob/master/usr/share/swap-file-creator/swap-file-creator}} * systemd unit file: {{Github_link|repo=swap-file-creator|path=/blob/master/usr/lib/systemd/system/swap-file-creator.service}} * {{Github_link|repo=swap-file-creator|path=}} = See Also = * [[rads|RAM Adjusted Desktop Starter]] = Footnotes = {{reflist|close=1}} {{Footer}} [[Category:Documentation]]