Skip to content
Documentation
State Modules
swap

swap

Manages swap space — a swapfile or a swap partition/device — together with its /etc/fstab entry and live swapon state. Idempotent: re-applying an unchanged declaration reports no change.

Category: Storage

States

StateMeaning
onThe source is an active swap area and has a matching fstab entry. A missing swapfile is created (when size is set), mkswap’d, then swapon’d.
presentThe fstab entry matches; live activation is not required (“configure now, enable later”).
offThe source is not an active swap area. The fstab entry is left untouched — use absent to remove it.
absentThe source is not active and has no fstab entry; a leftover swapfile (a regular-file source) is also removed (a device is left alone).

Parameters

ParameterTypeRequiredDescription
sizestringSwapfile size with an explicit unit, e.g. "2G", "512M", "1024K" (1024-based). State on only, and only used to create a not-yet-existing swapfile.
priorityintSwap priority, -1–32767 (-1 = swapon’s default). Becomes the swapon -p flag and the fstab pri= option. Invalid with off/absent.

Examples

Create and activate a swapfile

A missing swapfile is created at the declared size, formatted, and enabled.

swap:
  /swapfile:
    state: on
    size: "2G"
    priority: 10

Enable a swap partition 

swap:
  /dev/sda2:
    state: on

Configure now, enable later; deactivate elsewhere

present writes only the fstab entry; off deactivates without touching fstab.

swap:
  /dev/sdb1:
    state: present
    priority: 5
  /swapfile:
    state: off

Notes

  • Linux only: inspection via /proc/swaps; activation via mkswap(8)/swapon(8)/swapoff(8); a missing swapfile is created with dd(1). Other operating systems get a no-op provider.
  • The declaration name is the swap source and must be an absolute path — a swapfile (/swapfile) or a block device (/dev/sda2). UUID=/LABEL= sources are not supported (planned).
  • size governs only swapfile creation; it does not resize an existing swapfile.
  • Out of scope: custom fstab swap options (nofail, discard), fallocate-based creation, btrfs (NOCOW) swapfiles, zram / dphys-swapfile.
mountbond