{{Header}}
{{Title|title=
swap-file-creator
}}
{{#seo:
|description=Adds encrypted swap file to the system.
|image=File-swap-promo.jpg
}}
[[File:File-swap-promo.jpg|thumb|swap-file-creator logo]]
{{intro|
Adds encrypted swap file to the system.
}}
= Introduction =

<code>swap-file-creator</code> adds an encrypted swap file to the system. On every boot, it creates a new encrypted swapfile with a random password.

This is useful for systems with low RAM such as those inside virtual machines. Prevents common cases of freezing of VMs with low RAM during upgrades. <ref>
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
</ref>

It has an <code>ENOUGH_RAM</code> setting which defaults to <code>1950</code> MB. If there is more than enough RAM, it will not advice to increase RAM.

An optional option exists to shred the swapfile on shutdown but this is slow. <ref>
https://github.com/{{project_name_short}}/swap-file-creator/blob/master/etc/default/swap-file-creator
</ref>

For further information, see: https://github.com/{{project_name_short}}/swap-file-creator

= Installation =

Platform dependent.

* [[{{project_name_short}}|{{project_name_short}}]]: Available. Installed by default. Otherwise, see footnote. <ref>
{{Install Package|
package=swap-file-creator
}}
</ref>
* [[{{q project name short}}|{{q project name short}}]]: [[Unsupported]]. <ref>
Setting up swap and/or encryption of any kind is completely up to Qubes. [[Unspecific|Unspecific to {{project_name_short}}]].
</ref>

= Configuration =

The config file is located at [https://github.com/Kicksecure/swap-file-creator/blob/master/etc/default/swap-file-creator <code>/etc/default/swap-file-creator</code>]. Here you can change various parameters for the swapfile creation such as the path for where to create the swapfile at startup. <ref>
Useful in case you have a copy-on-write system like ZFS or BtrFS.
</ref>

{{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.

* {{CodeSelect|inline⁼true|code=
SWAPFILE=/var/swapfile
}}

= 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, enable swapping and display the swap usage summary.

{{CodeSelect|code=
sudo swapon -s
}}

For troubleshooting purposes, [[Troubleshooting#Daemon_Log|Check Daemon Log]] and search for unit-name: <code>swap-file-creator</code>.

= Live Mode =
<code>swap-file-creator</code> does not run if [[grub-live|live mode]] is detected. <ref>
Live mode is detected if file <code>/proc/cmdline</code> contains string <code>boot=live</code>.
</ref>

= 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 <u>not</u> break the boot process.

For example, <u>host</u> kernel versions other than the one recommended on the [[VirtualBox/Recommended Version|recommended VirtualBox version]] wiki page are are likely to break VirtualBox VMs [[Kernel#Kernel_Issues|in many ways]] if these are unsupported by VirtualBox. <ref>
https://www.virtualbox.org/ticket/17055#comment:3
</ref> 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 <u>not</u> 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: https://github.com/Kicksecure/swap-file-creator/blob/master/usr/share/swap-file-creator/swap-file-creator
* systemd unit file: https://github.com/Kicksecure/swap-file-creator/blob/master/usr/lib/systemd/system/swap-file-creator.service
* https://github.com/Kicksecure/swap-file-creator

= See Also =
* [[rads|RAM Adjusted Desktop Starter]]

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Documentation]]