Adding swap space

How to create a swap file on a server with little memory, how to tune it, and when an upgrade is the better choice.

Swap is disk space that Linux uses as backup memory when RAM fills up. This guide shows how to create a swap file, tune it and remove it. You run all the commands on the server, in an SSH session as root (Connecting to your server over SSH (Windows, macOS, Linux)). You can see how much RAM your plan has in the app.blackbox.md panel: on the server card in “My Servers”, in the “Spec” field.

Available to: the server owner, with SSH access as root. The commands are the same on all the Linux systems available to order: Ubuntu, Debian, AlmaLinux and CentOS Stream. AlmaLinux and CentOS Stream need one extra step, marked in the text.

When swap helps

Swap helps if:

the server has 1–2 GB of RAM;
memory fills up only now and then, for example during a traffic spike or a scheduled job;
you install or compile packages (system updates, composer, npm) that need a lot of memory for a short time.

Without swap, when memory runs out, the Linux kernel forcibly stops a process (the OOM killer), usually the largest one: the database or the web server. With swap, the server slows down, but processes keep running, as long as the swap does not fill up too.

Plan	RAM	Disk	Recommended swap
Basic XS	1 GB	20 GB	1 GB
Standard S	2 GB	20 GB	1 GB
CPU S	2 GB	30 GB	1 GB
Basic S	2 GB	50 GB	2 GB

On plans with 4 GB of RAM or more, swap is usually not needed. A 1 GB file can stay as a reserve for rare spikes.

Important Swap does not replace RAM: the disk is many times slower than memory. If the server uses swap all the time, it needs a plan with more RAM. You'll find the signs below, in the section “When you need an upgrade”.

Check memory and existing swap

free -h
swapon --show

Example on a server without swap:

               total        used        free      shared  buff/cache   available
Mem:           1.9Gi       1.2Gi       118Mi        12Mi       640Mi       560Mi
Swap:             0B          0B          0B

If the Swap: row shows 0B and swapon --show prints nothing, the server has no swap. BLACKBOX does not add swap when it installs the server, so this is usually what you'll see on a new server.
The available column shows how much more memory applications can use.
In the Mem: row, total is slightly lower than the plan's RAM: the system reserves part of it.

If swapon --show already lists a file or a partition, do not create another one. To change the size of the existing swap, see the frequently asked questions at the end.

Also check the free disk space. The Avail column must show much more than the size of the swap you are creating:

df -h /

Create the swap file

These commands create a 2 GB file named /swapfile. For 1 GB, write 1G instead of 2G.

Reserve the disk space:
```
fallocate -l 2G /swapfile
```
Allow only root to access the file:
```
chmod 600 /swapfile
```
Set the file up as swap:
```
mkswap /swapfile
```
Only on AlmaLinux and CentOS Stream, where SELinux is active, apply the SELinux label intended for /swapfile:
```
restorecon -v /swapfile
```
Turn on swap:
```
swapon /swapfile
```
Check with swapon --show. The output looks like this, and in free -h the Swap: row no longer shows 0B:
```
NAME      TYPE SIZE USED PRIO
/swapfile file   2G   0B   -2
```

Swap stays active until the next reboot. To have it turn on automatically at every boot, add it to /etc/fstab (next section).

If fallocate does not work

If fallocate prints Operation not supported or swapon rejects the file (it appears to have holes or Invalid argument), create the file with dd. It takes longer, but dd writes the whole file to disk and works even where fallocate does not. count is the size in MB: 2048 for 2 GB, 1024 for 1 GB.

rm -f /swapfile
dd if=/dev/zero of=/swapfile bs=1M count=2048 status=progress

Then continue with steps 2–6 above.

Turn on swap at every boot

Make a copy of the /etc/fstab file:
```
cp /etc/fstab /etc/fstab.bak
```
Check that there is no line for /swapfile yet. The command must print nothing:
```
grep swapfile /etc/fstab
```

Add the line at the end of the file:

echo '/swapfile none swap sw 0 0' >> /etc/fstab

Reload the systemd configuration:
```
systemctl daemon-reload
```
Test the line without rebooting: turn swap off, then turn it on again from /etc/fstab. If /swapfile appears in the output, the line is correct.
```
swapoff /swapfile
swapon -a
swapon --show
```

If you made a mistake in /etc/fstab, restore the copy before any reboot:

cp /etc/fstab.bak /etc/fstab

Warning In step 3, type two >> signs. With a single >, the command replaces the entire contents of /etc/fstab, and the server may no longer boot correctly. Customers have no web console, so you would not be able to fix the file after a reboot. If you lose access, write to us: How to contact BLACKBOX support.

Tune swappiness

The vm.swappiness parameter controls how readily the kernel moves data from RAM to swap. The default value is usually 60. With a value of 10, the kernel keeps applications in RAM as long as possible and moves data to swap mostly when memory is almost full.

See the current value:
```
cat /proc/sys/vm/swappiness
```
Set the value to 10 right away:
```
sysctl vm.swappiness=10
```
To keep the setting after a reboot, write it to a new file in /etc/sysctl.d/. Here a single > is correct, because the file is new:
```
echo 'vm.swappiness=10' > /etc/sysctl.d/99-swappiness.conf
```
Check the file. The output must be vm.swappiness = 10:
```
sysctl -p /etc/sysctl.d/99-swappiness.conf
```

When you need an upgrade

Swap helps with rare spikes. If memory is short all the time, the solution is more RAM. The signs are:

in free -h, used in the Swap: row grows and stays high, while available in the Mem: row is close to zero;
the server responds slowly, even though the processor is not busy;
in the output of the command below, the si and so columns (data read from swap and written to swap, per second) are greater than 0 in almost every measurement:
```
vmstat 1 5
```
the kernel log shows processes stopped because of a lack of memory (the command shows the messages since the last boot):
```
journalctl -k | grep -i "out of memory"
```

What to do:

Find out which process is using the memory and whether you can tune it: Diagnosing server load (CPU, RAM, disk, network).
If the application needs more memory, move to a larger plan in the same family with the “Upgrade” button on the server card: Server upgrade: moving to a larger plan.

Current plan	Next plan in the family	RAM	Disk
Basic XS	Basic S	1 → 2 GB	20 → 50 GB
Basic S	Basic M	2 → 4 GB	50 → 100 GB
Standard S	Standard M	2 → 4 GB	20 → 40 GB
CPU S	CPU M	2 → 4 GB	stays at 30 GB

The prices of all plans are in VPS plans: how to choose. The swap file stays on the server after the upgrade: you can keep it as a reserve or remove it.

If the server has the Monitoring add-on service, the “RAM usage (%)” chart in the “Trends” block of the “Monitoring” page shows memory usage over time. The chart does not include swap: check swap on the server with free -h. Details: The “Monitoring” page.

Swap and disk space

The swap file takes up its full size on the disk, even when it is not in use: 2 GB of swap means 2 GB less for your data.
On 20–30 GB disks (Basic XS, Standard S and the CPU family), do not go above 1 GB. In the CPU (30 GB) and High-Frequency Compute (50 GB) families, the disk stays the same even after an upgrade.
Exclude /swapfile from your backups: its contents are of no use after a reboot.
If the disk fills up, shrink or remove the swap and follow The server's disk is full.

Remove swap

Check the memory. available in the Mem: row must be greater than used in the Swap: row; otherwise the data in swap has nowhere to go:
```
free -h
```
Turn off swap. If swap holds a lot of data, the command may take a few minutes:
```
swapoff /swapfile
```
Delete the line from /etc/fstab. The command keeps a copy of the file in /etc/fstab.bak:
```
sed -i.bak '/^\/swapfile /d' /etc/fstab
```
Check that the line is gone (the first command must print nothing) and reload the configuration:
```
grep swapfile /etc/fstab
systemctl daemon-reload
```
Delete the file:
```
rm /swapfile
```
If you set swappiness, delete its file too. The default value comes back at the next reboot:
```
rm /etc/sysctl.d/99-swappiness.conf
```

Common error messages

Message	What it means	What to do
`fallocate: fallocate failed: Operation not supported`	The file system does not support `fallocate`.	Create the file with `dd`.
`swapon: /swapfile: skipping - it appears to have holes.` or `swapon: /swapfile: swapon failed: Invalid argument`	The file is not fully written to disk, or the file system does not accept a file created with `fallocate`.	Delete it and create it with `dd`.
`swapon: /swapfile: insecure permissions 0644, 0600 suggested.`	Other users can also read the file.	Run `chmod 600 /swapfile`.
`swapon: /swapfile: swapon failed: Device or resource busy`	Swap is already active.	Check with `swapon --show`. Nothing more needs to be done.
`No space left on device` (with `fallocate` or `dd`)	There is not enough free space on the disk.	Choose a smaller size or free up space.
`swapoff: /swapfile: swapoff failed: Cannot allocate memory`	There is not enough free RAM for the data in swap.	Temporarily stop large applications and try again. Otherwise, delete the line from `/etc/fstab`, reboot the server, and then delete the file.

Frequently asked questions

What swap size should I choose? 1 GB on 20–30 GB disks and 2 GB on other servers with 1–2 GB of RAM. More swap rarely helps: if the server needs more memory, choose a plan with more RAM.

How do I change the swap size? Turn off swap, delete the file and create it again with the new size (1 GB in the example). On AlmaLinux and CentOS Stream, also run restorecon -v /swapfile before swapon. The line in /etc/fstab stays the same.

swapoff /swapfile
rm /swapfile
fallocate -l 1G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

Does swap slow down the server? Not as long as it is used rarely. The slowdown starts when the server moves data to swap all the time. Then you need more RAM, not more swap.