Skip to content

Swap Ansible Role

An Ansible role to declaratively manage swap space and /etc/fstab entries on Linux systems.

Features

  • Create, resize, and remove swapfiles or enable swap partitions
  • Persist swap configuration across reboots via /etc/fstab
  • Declaratively manage any /etc/fstab entry (ext4, tmpfs, bind mounts, NFS, …)
  • Optional sysctl tuning (vm.swappiness, vm.vfs_cache_pressure)
  • Safe resize: disables swap, recreates the file, re-enables automatically
  • Secure defaults: swapfile permissions enforced as root:root 0600
  • Container-safe: swapon/swapoff calls are skipped in containers by default
  • Supports multiple swap entries (swapfiles and/or partitions) in one play

Installation

Add the following to your requirements.yml:

roles:
  - name: swap
    src: https://gitlab.com/niclas-zone/tools/ansible/roles/swap.git
    version: 1.0.0
    scm: git

Then install:

ansible-galaxy install -r requirements.yml --force

Role Variables

swap_entries

Field Default Description
path — (required) Path to swapfile or block device
state present present or absent
type file file (swapfile) or partition (block device)
size_mb — Swapfile size in MiB (required for type: file, state: present)
use_fallocate true Use fallocate(1). Set false to fall back to dd(1)
file_mode "0600" Swapfile permissions (file type only)
priority null Swap priority (-1..32767). Applied via swapon -p
persist true Add/maintain an /etc/fstab entry
fstab_opts "sw" fstab mount options (include pri=N here for boot-time priority)

swap_fstab_entries

Field Default Description
src — (required) Device, UUID=…, LABEL=…, or path
path — (required) Mount point (or none for swap/special mounts)
fstype — (required) Filesystem type (ext4, tmpfs, swap, …)
opts defaults Mount options
dump 0 Dump flag
passno 0 fsck pass number
state present present (fstab only), mounted, absent, or unmounted

General

Variable Default Description
swap_swappiness null Set vm.swappiness. null leaves the kernel default unchanged
swap_vfs_cache_pressure null Set vm.vfs_cache_pressure. null leaves it unchanged
swap_manage_in_container false Allow swapon/swapoff inside detected containers

Example Playbooks

Basic: 2 GiB swapfile with defaults

---
- hosts: servers
  become: true
  roles:
    - role: swap
      vars:
        swap_entries:
          - path: /swapfile
            size_mb: 2048

Multiple swap entries with priority and sysctl tuning

---
- hosts: servers
  become: true
  roles:
    - role: swap
      vars:
        swap_entries:
          - path: /swapfile
            size_mb: 4096
            fstab_opts: "sw,pri=10"
            priority: 10
          - path: /var/swap_secondary
            size_mb: 2048
            fstab_opts: "sw,pri=5"
            priority: 5
        swap_swappiness: 10
        swap_vfs_cache_pressure: 50

Swap partition (block device)

---
- hosts: servers
  become: true
  roles:
    - role: swap
      vars:
        swap_entries:
          - path: /dev/sdb1
            type: partition
            persist: true
            fstab_opts: "sw"

Warning: When type: partition is used and the device does not already carry a swap signature, the role runs mkswap on it — any existing data on the partition will be destroyed. Ensure the device is dedicated to swap before using this option.

Remove swap

---
- hosts: servers
  become: true
  roles:
    - role: swap
      vars:
        swap_entries:
          - path: /swapfile
            state: absent

Manage /etc/fstab entries (non-swap mounts)

---
- hosts: servers
  become: true
  roles:
    - role: swap
      vars:
        swap_fstab_entries:
          - src: "UUID=d3b07384-d9a0-4b44-8a1a-1cfbf0e3b2c7"
            path: /mnt/data
            fstype: ext4
            opts: "defaults,noatime"
            dump: 0
            passno: 2
            state: mounted
          - src: tmpfs
            path: /tmp
            fstype: tmpfs
            opts: "size=512M,mode=1777,nosuid,nodev"
          - src: /mnt/legacy
            path: /mnt/legacy
            fstype: ext4
            state: absent

Full example: swap + fstab + sysctl

---
- hosts: servers
  become: true
  roles:
    - role: swap
      vars:
        swap_entries:
          - path: /swapfile
            size_mb: 4096
            persist: true
        swap_fstab_entries:
          - src: "UUID=abc-123-def"
            path: /mnt/data
            fstype: ext4
            opts: "defaults,noatime"
            passno: 2
          - src: tmpfs
            path: /dev/shm
            fstype: tmpfs
            opts: "size=256M,mode=1777,nosuid,nodev"
        swap_swappiness: 10
        swap_vfs_cache_pressure: 50

Notes

  • Swapfile creation uses fallocate by default (fast, sparse-aware). Set use_fallocate: false to use dd instead — required on some network filesystems (NFS, BTRFS without nodatacow).
  • The role detects container environments (Docker, Podman, LXC, …) and skips swapon/swapoff calls automatically. Set swap_manage_in_container: true to override.
  • Swapfile resize is fully automated: the role disables the old swap, removes the file, creates a new one at the target size, and re-enables swap — all idempotently.
  • swap_fstab_entries uses state: present by default, which updates /etc/fstab without mounting. Use state: mounted to also mount the filesystem immediately.