nixos/modules/config/swap.nix

   1 { config, lib, pkgs, utils, ... }:
   2
   3 let
   4   inherit (lib) mkIf mkOption types;
   5
   6   randomEncryptionCoerce = enable: { inherit enable; };
   7
   8   randomEncryptionOpts = { ... }: {
   9
  10     options = {
  11
  12       enable = mkOption {
  13         default = false;
  14         type = types.bool;
  15         description = ''
  16           Encrypt swap device with a random key. This way you won't have a persistent swap device.
  17
  18           WARNING: Don't try to hibernate when you have at least one swap partition with
  19           this option enabled! We have no way to set the partition into which hibernation image
  20           is saved, so if your image ends up on an encrypted one you would lose it!
  21
  22           WARNING #2: Do not use /dev/disk/by-uuid/… or /dev/disk/by-label/… as your swap device
  23           when using randomEncryption as the UUIDs and labels will get erased on every boot when
  24           the partition is encrypted. Best to use /dev/disk/by-partuuid/…
  25         '';
  26       };
  27
  28       cipher = mkOption {
  29         default = "aes-xts-plain64";
  30         example = "serpent-xts-plain64";
  31         type = types.str;
  32         description = ''
  33           Use specified cipher for randomEncryption.
  34
  35           Hint: Run "cryptsetup benchmark" to see which one is fastest on your machine.
  36         '';
  37       };
  38
  39       keySize = mkOption {
  40         default = null;
  41         example = "512";
  42         type = types.nullOr types.int;
  43         description = ''
  44           Set the encryption key size for the plain device.
  45
  46           If not specified, the amount of data to read from `source` will be
  47           determined by cryptsetup.
  48
  49           See `cryptsetup-open(8)` for details.
  50         '';
  51       };
  52
  53       sectorSize = mkOption {
  54         default = null;
  55         example = "4096";
  56         type = types.nullOr types.int;
  57         description = ''
  58           Set the sector size for the plain encrypted device type.
  59
  60           If not specified, the default sector size is determined from the
  61           underlying block device.
  62
  63           See `cryptsetup-open(8)` for details.
  64         '';
  65       };
  66
  67       source = mkOption {
  68         default = "/dev/urandom";
  69         example = "/dev/random";
  70         type = types.str;
  71         description = ''
  72           Define the source of randomness to obtain a random key for encryption.
  73         '';
  74       };
  75
  76       allowDiscards = mkOption {
  77         default = false;
  78         type = types.bool;
  79         description = ''
  80           Whether to allow TRIM requests to the underlying device. This option
  81           has security implications; please read the LUKS documentation before
  82           activating it.
  83         '';
  84       };
  85     };
  86
  87   };
  88
  89   swapCfg = {config, options, ...}: {
  90
  91     options = {
  92
  93       device = mkOption {
  94         example = "/dev/sda3";
  95         type = types.nonEmptyStr;
  96         description = "Path of the device or swap file.";
  97       };
  98
  99       label = mkOption {
 100         example = "swap";
 101         type = types.str;
 102         description = ''
 103           Label of the device.  Can be used instead of {var}`device`.
 104         '';
 105       };
 106
 107       size = mkOption {
 108         default = null;
 109         example = 2048;
 110         type = types.nullOr types.int;
 111         description = ''
 112           If this option is set, ‘device’ is interpreted as the
 113           path of a swapfile that will be created automatically
 114           with the indicated size (in megabytes).
 115         '';
 116       };
 117
 118       priority = mkOption {
 119         default = null;
 120         example = 2048;
 121         type = types.nullOr types.int;
 122         description = ''
 123           Specify the priority of the swap device. Priority is a value between 0 and 32767.
 124           Higher numbers indicate higher priority.
 125           null lets the kernel choose a priority, which will show up as a negative value.
 126         '';
 127       };
 128
 129       randomEncryption = mkOption {
 130         default = false;
 131         example = {
 132           enable = true;
 133           cipher = "serpent-xts-plain64";
 134           source = "/dev/random";
 135         };
 136         type = types.coercedTo types.bool randomEncryptionCoerce (types.submodule randomEncryptionOpts);
 137         description = ''
 138           Encrypt swap device with a random key. This way you won't have a persistent swap device.
 139
 140           HINT: run "cryptsetup benchmark" to test cipher performance on your machine.
 141
 142           WARNING: Don't try to hibernate when you have at least one swap partition with
 143           this option enabled! We have no way to set the partition into which hibernation image
 144           is saved, so if your image ends up on an encrypted one you would lose it!
 145
 146           WARNING #2: Do not use /dev/disk/by-uuid/… or /dev/disk/by-label/… as your swap device
 147           when using randomEncryption as the UUIDs and labels will get erased on every boot when
 148           the partition is encrypted. Best to use /dev/disk/by-partuuid/…
 149         '';
 150       };
 151
 152       discardPolicy = mkOption {
 153         default = null;
 154         example = "once";
 155         type = types.nullOr (types.enum ["once" "pages" "both" ]);
 156         description = ''
 157           Specify the discard policy for the swap device. If "once", then the
 158           whole swap space is discarded at swapon invocation. If "pages",
 159           asynchronous discard on freed pages is performed, before returning to
 160           the available pages pool. With "both", both policies are activated.
 161           See swapon(8) for more information.
 162         '';
 163       };
 164
 165       options = mkOption {
 166         default = [ "defaults" ];
 167         example = [ "nofail" ];
 168         type = types.listOf types.nonEmptyStr;
 169         description = ''
 170           Options used to mount the swap.
 171         '';
 172       };
 173
 174       deviceName = mkOption {
 175         type = types.str;
 176         internal = true;
 177       };
 178
 179       realDevice = mkOption {
 180         type = types.path;
 181         internal = true;
 182       };
 183
 184     };
 185
 186     config = {
 187       device = mkIf options.label.isDefined
 188         "/dev/disk/by-label/${config.label}";
 189       deviceName = lib.replaceStrings ["\\"] [""] (utils.escapeSystemdPath config.device);
 190       realDevice = if config.randomEncryption.enable then "/dev/mapper/${config.deviceName}" else config.device;
 191     };
 192
 193   };
 194
 195 in
 196
 197 {
 198
 199   ###### interface
 200
 201   options = {
 202
 203     swapDevices = mkOption {
 204       default = [];
 205       example = [
 206         { device = "/dev/hda7"; }
 207         { device = "/var/swapfile"; }
 208         { label = "bigswap"; }
 209       ];
 210       description = ''
 211         The swap devices and swap files.  These must have been
 212         initialised using {command}`mkswap`.  Each element
 213         should be an attribute set specifying either the path of the
 214         swap device or file (`device`) or the label
 215         of the swap device (`label`, see
 216         {command}`mkswap -L`).  Using a label is
 217         recommended.
 218       '';
 219
 220       type = types.listOf (types.submodule swapCfg);
 221     };
 222
 223   };
 224
 225   config = mkIf ((lib.length config.swapDevices) != 0) {
 226     assertions = lib.map (sw: {
 227       assertion = sw.randomEncryption.enable -> builtins.match "/dev/disk/by-(uuid|label)/.*" sw.device == null;
 228       message = ''
 229         You cannot use swap device "${sw.device}" with randomEncryption enabled.
 230         The UUIDs and labels will get erased on every boot when the partition is encrypted.
 231         Use /dev/disk/by-partuuid/… instead.
 232       '';
 233     }) config.swapDevices;
 234
 235     warnings =
 236       lib.concatMap (sw:
 237         if sw.size != null && lib.hasPrefix "/dev/" sw.device
 238         then [ "Setting the swap size of block device ${sw.device} has no effect" ]
 239         else [ ])
 240       config.swapDevices;
 241
 242     system.requiredKernelConfig = [
 243       (config.lib.kernelConfig.isYes "SWAP")
 244     ];
 245
 246     # Create missing swapfiles.
 247     systemd.services =
 248       let
 249         createSwapDevice = sw:
 250           let realDevice' = utils.escapeSystemdPath sw.realDevice;
 251           in lib.nameValuePair "mkswap-${sw.deviceName}"
 252           { description = "Initialisation of swap device ${sw.device}";
 253             # The mkswap service fails for file-backed swap devices if the
 254             # loop module has not been loaded before the service runs.
 255             # We add an ordering constraint to run after systemd-modules-load to
 256             # avoid this race condition.
 257             after = [ "systemd-modules-load.service" ];
 258             wantedBy = [ "${realDevice'}.swap" ];
 259             before = [ "${realDevice'}.swap" "shutdown.target"];
 260             conflicts = [ "shutdown.target" ];
 261             path = [ pkgs.util-linux pkgs.e2fsprogs ]
 262               ++ lib.optional sw.randomEncryption.enable pkgs.cryptsetup;
 263
 264             environment.DEVICE = sw.device;
 265
 266             script =
 267               ''
 268                 ${lib.optionalString (sw.size != null) ''
 269                   currentSize=$(( $(stat -c "%s" "$DEVICE" 2>/dev/null || echo 0) / 1024 / 1024 ))
 270                   if [[ ! -b "$DEVICE" && "${toString sw.size}" != "$currentSize" ]]; then
 271                     # Disable CoW for CoW based filesystems like BTRFS.
 272                     truncate --size 0 "$DEVICE"
 273                     chattr +C "$DEVICE" 2>/dev/null || true
 274
 275                     echo "Creating swap file using dd and mkswap."
 276                     dd if=/dev/zero of="$DEVICE" bs=1M count=${toString sw.size} status=progress
 277                     ${lib.optionalString (!sw.randomEncryption.enable) "mkswap ${sw.realDevice}"}
 278                   fi
 279                 ''}
 280                 ${lib.optionalString sw.randomEncryption.enable ''
 281                   cryptsetup plainOpen -c ${sw.randomEncryption.cipher} -d ${sw.randomEncryption.source} \
 282                   ${lib.concatStringsSep " \\\n" (lib.flatten [
 283                     (lib.optional (sw.randomEncryption.sectorSize != null) "--sector-size=${toString sw.randomEncryption.sectorSize}")
 284                     (lib.optional (sw.randomEncryption.keySize != null) "--key-size=${toString sw.randomEncryption.keySize}")
 285                     (lib.optional sw.randomEncryption.allowDiscards "--allow-discards")
 286                   ])} ${sw.device} ${sw.deviceName}
 287                   mkswap ${sw.realDevice}
 288                 ''}
 289               '';
 290
 291             unitConfig.RequiresMountsFor = [ "${dirOf sw.device}" ];
 292             unitConfig.DefaultDependencies = false; # needed to prevent a cycle
 293             serviceConfig = {
 294               Type = "oneshot";
 295               RemainAfterExit = sw.randomEncryption.enable;
 296               UMask = "0177";
 297               ExecStop = lib.optionalString sw.randomEncryption.enable "${pkgs.cryptsetup}/bin/cryptsetup luksClose ${sw.deviceName}";
 298             };
 299             restartIfChanged = false;
 300           };
 301
 302       in lib.listToAttrs (lib.map createSwapDevice (lib.filter (sw: sw.size != null || sw.randomEncryption.enable) config.swapDevices));
 303
 304   };
 305
 306 }