FreeBSD Swap Operations: Capacity, Devices, and Pressure Signals

Swap is backing capacity for virtual memory, not a way to make an undersized host behave like a larger one. A nonzero swap-usage figure can persist after a workload peak has passed, while active page-in/page-out activity under latency pressure is a stronger sign that the system is currently short of memory. Good operations distinguish installed capacity, allocated pages, and present paging churn before deciding that more swap is the repair.

This article covers ordinary FreeBSD swap partitions and the Handbook-documented file-backed option. Encrypted swap has a separate design, and ZFS-backed swap files are strongly discouraged by the current Handbook because swapping on them can hang the system. Treat the exact target provider and filesystem as safety-critical input: swapon on a data partition can overwrite its contents.

Measure current capacity and workload pressure

Begin with the running state and capture it before changing anything. swapinfo -h summarizes configured swap areas and their use; swapctl -l lists devices, and swapctl -s prints a summary on supported releases. vmstat 1 gives an interval view of memory and paging activity. Run it for long enough to capture the workload that triggers the reported problem rather than inferring a trend from one snapshot.

swapinfo -h
swapctl -l
swapctl -s
vmstat 1

Interpret the figures together. Swap capacity reports do not identify which process caused the allocation. A system may keep cold pages in swap after pressure subsides; the mere fact that Used is nonzero does not justify a reboot or swapoff. Rising paging-in/out rates coupled with response-time degradation, memory pressure, and the application’s own telemetry give stronger evidence of a current resource problem. Compare timestamps with workload, ARC, tmpfs, and process-memory behavior where relevant.

Before expanding swap, establish a capacity objective: tolerate a brief burst, permit clean application shutdown under pressure, or support a workload whose memory footprint is expected to be larger. Swap is slower than RAM and consumes storage bandwidth and device endurance. If sustained paging is part of normal operation, reduce memory demand, tune concurrency, resize the host, or move the workload before merely increasing disk-backed capacity.

Select and identify a safe swap provider

The safest operational pattern is a dedicated partition created and verified in advance. Inspect the complete partition table and stable labels before enabling it. Correlate provider identity with disk serial or virtual-disk inventory; names such as ada1p2 can change when controllers or devices enumerate differently. Never select a partition by size alone.

gpart show -lp
geom disk list
mount
zpool status
swapinfo -h

These commands help identify partition boundaries and existing consumers. They do not prove that an unused partition contains no valuable data. If a candidate provider is not a newly created, dedicated swap partition, stop and inspect its history and contents before proceeding. The Handbook explicitly warns that swapon can destroy data on a partition because it overwrites the target for use as paging space.

For a dedicated GPT swap partition already labeled swap0, a persistent /etc/fstab entry has the standard six-field form:

/dev/gpt/swap0  none  swap  sw  0  0

Replace swap0 only after confirming the actual label with glabel status and the partition table. The device path must resolve at boot, the partition must be unused for every other purpose, and the entry should not be copied into an encrypted-swap setup where the active provider is a GELI device. A label reduces dependence on changing disk indices but does not make the selected contents safe automatically.

Enable a partition with a controlled change

After independent verification of the provider and a backup of /etc/fstab, add the entry and activate the exact swap device during a maintenance window:

swapon /dev/gpt/swap0
swapinfo -h

Verify that the intended device, not a similarly named partition, appears in the output, and monitor kernel/system logs for errors. To make the entry persistent, review the final /etc/fstab line before reboot. FreeBSD reads swap entries during startup; a typo in a provider name can leave the machine without expected capacity after a restart. Do not use swapon -a as the first validation when several entries exist, because it obscures which particular entry was accepted or rejected.

Removing an entry at runtime is not equivalent to deleting the partition. swapoff must migrate pages that are resident in that area and may fail or create severe pressure if the remaining memory and swap cannot hold them. Check current use and headroom first, schedule the operation, and allow the command to complete. Never force the operation or pull the underlying storage while it is active. Only after the provider is absent from swapinfo should a storage administrator consider reusing the partition through its normal partition-management process.

Understand file-backed swap and its limits

The Handbook documents a swap file on a suitable filesystem by creating a file, setting restrictive permissions, and registering it through an md swap entry. The example below is deliberately limited to a disk-backed filesystem with adequate free space; it is not suitable for ZFS.

dd if=/dev/zero of=/usr/swap0 bs=1m count=512
chmod 0600 /usr/swap0

Then add this line to /etc/fstab:

md  none  swap  sw,file=/usr/swap0,late  0  0

The late option is part of the Handbook’s file-backed swap example. For immediate activation of the configured file entry, the documented command is swapon -aL. Check the installed release’s swapon(8) and fstab(5) before changing the form, because the swap-file option is implemented through the memory-disk path rather than treating an ordinary file as a raw partition.

Verify that the file is actually allocated, has the expected owner and mode, and that its containing filesystem has enough reserved free space for both its own use and normal system operation. Sparse-file semantics and filesystem allocation behavior matter; do not assume the dd command’s apparent length proves that physical storage is available. A full root or /usr filesystem can break unrelated services. Capacity monitoring should include the filesystem holding the backing file and the swap device list.

The current FreeBSD Handbook strongly discourages a swap file on ZFS because swapping can lead to system hangs. Do not treat that caveat as a minor performance warning. Use a dedicated swap partition or an explicitly designed encrypted swap arrangement supported by the installed release. The existing encrypted-swap guide covers its own provider lifecycle; do not combine raw and encrypted entries for the same backing partition.

Plan capacity, priority, and lifecycle deliberately

There is no universal “swap equals twice RAM” sizing rule. Capacity should follow the peak memory demand, kernel/application failure behavior, dump requirements, storage performance, and recovery target of the actual system. Use a representative workload to measure resident memory, pageable working sets, and peak page rates. A database configured to use most physical memory may require a different headroom plan from a transient batch worker. A crash-dump policy may also have requirements distinct from ordinary swap capacity; verify dumpdev(8) guidance separately instead of assuming every swap provider is suitable for dumps.

When a system has several swap areas, record why each exists, the provider identity, expected performance, and boot dependency. Avoid relying on undocumented assumptions about inter-device ordering or balancing; verify actual swapctl -l output and the current swapon(8) behavior for the target release. A faster device may be a useful design input, but adding slow network storage or an overloaded pool can make memory pressure worse rather than recover service.

Use fstab as the persistent source of truth and swapinfo/swapctl as runtime evidence. If an automated configuration tool owns fstab, change its source. Keep an approved rollback: remove the specific entry, verify other swap areas have sufficient capacity, run swapoff on the exact target in a window, and recheck the device list before partition reuse. Do not reboot just to conceal an incomplete swapoff.

Diagnose the common operational signatures

swapon refuses the provider. Confirm the path exists, is a swap partition rather than a mounted or pool member, and is not already active under another name. Inspect kernel logs and the exact error. Do not retry with alternate partition numbers until disk identity and partition layout are re-established.

Swap is nearly full. Determine whether the usage is stable historical occupancy or is increasing under active paging. Compare swapinfo, vmstat, memory dashboards, and the service’s workload timestamps. If page-out activity rises continuously, adding capacity may postpone failure but not remove the cause. If the usage is stable and no paging is occurring, investigate the application’s current behavior before changing the provider.

A swap file does not activate after reboot. Verify the md row, file= path, late option, file allocation, permissions, mount ordering, and system logs. Confirm that the backing filesystem is available when late swap activation runs. Do not silently remove late or change the filesystem to ZFS as a workaround.

swapoff stalls or fails. Stop new memory-heavy work, capture current pressure, and check that remaining RAM and other swap have room. Allow the operation time to migrate pages. If headroom is inadequate, canceling may be safer than forcing progress; defer removal and add capacity or reduce workload through a planned change.

The host becomes slow despite free swap. Free swap is not a performance guarantee. Check memory reclaim, page-in/out rate, disk latency, ARC, tmpfs, CPU saturation, and application queues. Swap may be available but too slow, or the system may be delayed by another resource entirely.

Define production acceptance and monitoring

Before adding capacity, record freebsd-version, the intended provider, disk identity, partition label, current swap list, fstab backup, memory baseline, and a rollback procedure. After activation, prove that the expected provider appears once, its capacity matches expectation, and the host continues to operate under a representative workload. Check the persistent entry during a controlled reboot before considering the change complete.

Monitor swap capacity, growth rate, active paging, filesystem free space for file-backed swap, and application latency together. Alert on sustained pressure or a failed expected swap area, not just any nonzero Used value. Preserve the exact vmstat sampling interval and swapinfo output for incident comparison. Capacity thresholds should reflect enough time to reduce workload or resize the machine; a page that fires only after the host is unresponsive is not an operational safeguard.

Finally, keep swap policy distinct from memory tuning and recovery. More swap can keep processes alive longer, but it cannot make persistent overcommit safe, restore a failed storage path, or replace an application-level memory limit. A reliable configuration has known capacity, an identified provider, safe activation and removal procedures, monitoring for real paging pressure, and a tested recovery plan for the workload that exhausted memory in the first place.

Related:

Sources: