masfl

macOS auto swap for linux

background

macOS dynamically creates and removes swap files so users never have to think about swap configuration. Linux requires manual setup. masfl is a systemd service that monitors memory pressure via PSI and automatically manages swap files.

requirements

• Linux 4.20+ (for PSI support; MemAvailable fallback works on older kernels)
• util-linux — provides fallocate, mkswap, swapon, swapoff

install

from release

Download the latest binary from releases and install:

tar xzf masfl-x86_64-linux.tar.gz
sudo install -m 755 masfl /usr/local/bin/masfl
sudo install -m 644 masfl.service /etc/systemd/system/masfl.service
sudo systemctl daemon-reload
sudo systemctl enable --now masfl

from source

git clone https://github.com/pgray/masfl.git
cd masfl
make install
sudo systemctl enable --now masfl

usage

masfl [OPTIONS]

Options:
    --swap-dir <PATH>                  directory for swap files [default: /var/lib/masfl]
    --max-swap-files <N>               maximum swap files to manage [default: 4]
    --swap-size <SIZE>                 size per swap file, e.g. 1G, 512M [default: 1G]
    --poll-interval <SECONDS>          seconds between checks [default: 3]
    --pressure-threshold <THRESHOLD>   PSI some avg10 threshold to create swap [default: 10]
    --mem-threshold-low <PERCENT>      MemAvailable % to create swap (PSI fallback) [default: 15]
    --mem-threshold-high <PERCENT>     MemAvailable % to remove excess swap (PSI fallback) [default: 50]
    --dry-run                          log actions without making changes

dry run

masfl --dry-run

custom configuration

masfl --swap-size 2G --max-swap-files 8 --pressure-threshold 30.0

To customize the systemd service, use a drop-in override:

sudo systemctl edit masfl

[Service]
ExecStart=
ExecStart=/usr/local/bin/masfl --swap-size 2G --pressure-threshold 30.0

how it works

Swap files are created with mode 0600 (root-only read/write) for security.

masfl uses Linux's Pressure Stall Information (PSI) to detect memory pressure. PSI is a kernel feature (Linux 4.20+) that tracks how much time processes spend stalled waiting for memory resources. The kernel exposes this at /proc/pressure/memory:

some avg10=0.00 avg60=0.00 avg300=0.00 total=0
full avg10=0.00 avg60=0.00 avg300=0.00 total=0

• some — percentage of time at least one task is stalled on memory
• full — percentage of time all tasks are stalled on memory
• avg10/avg60/avg300 — averages over 10s, 60s, and 300s windows

masfl pre-allocates one swap file at startup so there's always a buffer available. It then watches the some avg10 value. When it crosses --pressure-threshold (default 10), masfl creates additional swap files (up to --max-swap-files). When pressure drops below 20% of the threshold and swap usage is under 5%, masfl removes excess swap files (but always keeps at least the initial one).

This is the same signal the kernel itself uses for memory reclaim decisions, making it a more reliable trigger than simple free memory thresholds.

PSI availability: PSI is disabled by default on some distros (e.g. Ubuntu, Debian). If /proc/pressure/memory is not available, masfl automatically falls back to a MemAvailable percentage check: swap is created when available memory drops below --mem-threshold-low (default 15%) and excess swap is removed when it rises above --mem-threshold-high (default 50%). To enable PSI, add psi=1 to your kernel boot parameters.

uninstall

make uninstall
# or manually:
sudo systemctl stop masfl
sudo systemctl disable masfl
sudo rm -f /usr/local/bin/masfl /etc/systemd/system/masfl.service
sudo systemctl daemon-reload

development

make          # list targets
make ready    # fmt, lint, test
make build    # debug build
make release  # release build

license

GPL-2.0-only