debianito-post-install/docs/swap.md

Option 9: Swap

1. What does this component do?

This module is responsible for the secure management of disk-based swap space within the debianito environment. Unlike standard Linux tools that might overwrite existing configurations or conflict with memory compression features (like ZRAM), this script operates as a priority-aware, persistent swap manager.

Its primary functions include:

• Dynamic Allocation: Creating and resizing swapfiles based on detected RAM capacity without requiring physical partition changes.
• Priority Integration: Explicitly setting the swap priority (pri=10) to ensure it sits below ZRAM (which uses priority=100). This prevents the system from using disk I/O for memory swapping until compressed RAM is exhausted, optimizing performance.
• Persistence Management: Safely editing /etc/fstab with a unique tag (# debianito-managed-swap) to ensure swap survives reboots without corrupting manual entries.
• Safety Locking: Prevents concurrent operations using file locking mechanisms to avoid race conditions during active system usage.

2. How does it work?

The script leverages several advanced Linux subsystems and safety protocols:

1. File System Detection: It identifies the filesystem type of the target partition (e.g., ext4, btrfs). For Btrfs, it applies specific flags (chattr +C for copy-on-write optimization) to prevent performance degradation during swap operations.
2. Allocation Strategy: It prefers fallocate for instant space reservation on supported filesystems, falling back to dd if=/dev/zero for compatibility or zeroing requirements (like Btrfs).
3. Fstab Validation: Before writing changes to /etc/fstab, it creates a temporary file and validates the syntax using findmnt --verify. If validation fails, the script aborts and restores the original state.
4. Concurrency Control: It utilizes flock on /run/lock/debianito-swap.lock. This ensures that if another process is modifying swap settings (e.g., a system update), this script will wait or exit gracefully to prevent filesystem corruption.
5. Swappiness Tuning: It configures vm.swappiness via both runtime (sysctl -w) and persistent (/etc/sysctl.d/99-swappiness-debianito.conf) mechanisms, defaulting to values that favor RAM usage over disk swapping (e.g., 10-20).

3. The Logical Decision Tree (Step by Step)

The execution flow follows a strict logical tree designed for safety and idempotency:

1. Initialization & Locking:

   • The manage_swap() function attempts to acquire an exclusive lock (flock -n). If the lock is held by another process, it immediately exits with a "Busy" message to prevent conflicts.

2. Menu Selection Loop:

   • Enters a continuous loop presenting options (Status, Create, Remove, Swappiness).
   • Breaks only when the user selects "Back to main menu".

3. Action Execution Paths:

   • Path A: Status Check (_swap_current_status)
     • Reads active swap entries via swapon --show.
     • Reads current swappiness from /proc/sys/vm/swappiness.
     • Parses /etc/fstab for managed tags.
   • Path B: Create/Resize (_swap_create_file)
     • Recommendation: Calculates optimal size based on RAM (e.g., 2GB for >16GB RAM, 4GB for 8-16GB).
     • Btrfs Check: If the filesystem is Btrfs, it warns about nodatacow requirements and hibernation limitations.
     • Existence Check: If /swapfile exists, it prompts to confirm recreation (deleting old data first via swapoff).
     • Allocation: Uses fallocate or dd to zero the file. Sets permissions (chmod 600) and initializes swap (mkswap).
     • Persistence: Attempts to write the new entry to /etc/fstab. If validation fails, it cleans up (removes file) before exiting.
   • Path C: Remove (_swap_remove_file)
     • Checks for the unique SWAP_FSTAB_TAG in fstab.
     • Confirms user intent to delete.
     • Executes swapoff, removes the fstab line, and deletes the physical file.
   • Path D: Swappiness (_swap_set_swappiness)
     • Validates input (0-100 integer).
     • Writes a temporary sysctl config file.
     • Applies changes immediately via sysctl -w.

4. What does each menu item do and what does it mean?

Each option in the swap management submenu serves a specific technical purpose:

• Option 1: Show current swap & swappiness

  • Technical Action: Aggregates data from /proc/swaps, /proc/sys/vm/swappiness, and /etc/fstab.
  • Significance: Provides an audit trail of the current memory management state. It verifies if ZRAM is active (implied by priority check) and how much disk swap is currently in use.

• Option 2: Create / resize swapfile

  • Technical Action: Allocates a new block device file (/swapfile) or expands an existing one. Sets the pri=10 flag to ensure it acts as a secondary memory layer after ZRAM fills up.
  • Significance: Essential for systems with low RAM that need overflow protection without installing physical partitions. The "Resize" capability allows adapting to new hardware configurations dynamically.

• Option 3: Remove swapfile

  • Technical Action: Disables the swapfile (swapoff), removes it from /etc/fstab, and deletes the file from disk.
  • Significance: Useful for troubleshooting, freeing up disk space (e.g., on SSDs where write cycles are a concern), or migrating to ZRAM-only configurations if RAM is sufficient.

• Option 4: Change swappiness

  • Technical Action: Modifies the kernel parameter vm.swappiness.
  • Significance: Controls the "aggressiveness" of swapping. A lower value (e.g., 10) tells the kernel to keep data in RAM longer, only using swap as a last resort. This is critical for desktop performance and battery life on laptops.

• Option 5: Back to main menu

  • Technical Action: Releases the file lock (exec 9>&-) and terminates the submenu loop.
  • Significance: Returns control to the user, ensuring no swap operations are running in the background before they navigate to other system configurations.