nixos/modules/tasks/filesystems/overlayfs.nix

   1 { config, lib, pkgs, utils, ... }:
   2
   3 let
   4   # The scripted initrd contains some magic to add the prefix to the
   5   # paths just in time, so we don't add it here.
   6   sysrootPrefix = fs:
   7     if config.boot.initrd.systemd.enable && (utils.fsNeededForBoot fs) then
   8       "/sysroot"
   9     else
  10       "";
  11
  12   # Returns a service that creates the required directories before the mount is
  13   # created.
  14   preMountService = _name: fs:
  15     let
  16       prefix = sysrootPrefix fs;
  17
  18       escapedMountpoint = utils.escapeSystemdPath (prefix + fs.mountPoint);
  19       mountUnit = "${escapedMountpoint}.mount";
  20
  21       upperdir = prefix + fs.overlay.upperdir;
  22       workdir = prefix + fs.overlay.workdir;
  23     in
  24     lib.mkIf (fs.overlay.upperdir != null)
  25       {
  26         "rw-${escapedMountpoint}" = {
  27           requiredBy = [ mountUnit ];
  28           before = [ mountUnit ];
  29           unitConfig = {
  30             DefaultDependencies = false;
  31             RequiresMountsFor = "${upperdir} ${workdir}";
  32           };
  33           serviceConfig = {
  34             Type = "oneshot";
  35             ExecStart = "${pkgs.coreutils}/bin/mkdir -p -m 0755 ${upperdir} ${workdir}";
  36           };
  37         };
  38       };
  39
  40   overlayOpts = { config, ... }: {
  41
  42     options.overlay = {
  43
  44       lowerdir = lib.mkOption {
  45         type = with lib.types; nullOr (nonEmptyListOf (either str pathInStore));
  46         default = null;
  47         description = ''
  48           The list of path(s) to the lowerdir(s).
  49
  50           To create a writable overlay, you MUST provide an upperdir and a
  51           workdir.
  52
  53           You can create a read-only overlay when you provide multiple (at
  54           least 2!) lowerdirs and neither an upperdir nor a workdir.
  55         '';
  56       };
  57
  58       upperdir = lib.mkOption {
  59         type = lib.types.nullOr lib.types.str;
  60         default = null;
  61         description = ''
  62           The path to the upperdir.
  63
  64           If this is null, a read-only overlay is created using the lowerdir.
  65
  66           If you set this to some value you MUST also set `workdir`.
  67         '';
  68       };
  69
  70       workdir = lib.mkOption {
  71         type = lib.types.nullOr lib.types.str;
  72         default = null;
  73         description = ''
  74           The path to the workdir.
  75
  76           This MUST be set if you set `upperdir`.
  77         '';
  78       };
  79
  80     };
  81
  82     config = lib.mkIf (config.overlay.lowerdir != null) {
  83       fsType = "overlay";
  84       device = lib.mkDefault "overlay";
  85       depends = map (x: "${x}") (config.overlay.lowerdir ++ lib.optionals (config.overlay.upperdir != null) [
  86         config.overlay.upperdir
  87         config.overlay.workdir
  88       ]);
  89
  90       options =
  91         let
  92           prefix = sysrootPrefix config;
  93
  94           lowerdir = map (s: prefix + s) config.overlay.lowerdir;
  95           upperdir = prefix + config.overlay.upperdir;
  96           workdir = prefix + config.overlay.workdir;
  97         in
  98         [
  99           "lowerdir=${lib.concatStringsSep ":" lowerdir}"
 100         ] ++ lib.optionals (config.overlay.upperdir != null) [
 101           "upperdir=${upperdir}"
 102           "workdir=${workdir}"
 103         ];
 104     };
 105
 106   };
 107 in
 108
 109 {
 110
 111   options = {
 112
 113     # Merge the overlay options into the fileSystems option.
 114     fileSystems = lib.mkOption {
 115       type = lib.types.attrsOf (lib.types.submodule [ overlayOpts ]);
 116     };
 117
 118   };
 119
 120   config =
 121     let
 122       overlayFileSystems = lib.filterAttrs (_name: fs: (fs.overlay.lowerdir != null)) config.fileSystems;
 123       initrdFileSystems = lib.filterAttrs (_name: utils.fsNeededForBoot) overlayFileSystems;
 124       userspaceFileSystems = lib.filterAttrs (_name: fs: (!utils.fsNeededForBoot fs)) overlayFileSystems;
 125     in
 126     {
 127
 128       boot.initrd.availableKernelModules = lib.mkIf (initrdFileSystems != { }) [ "overlay" ];
 129
 130       assertions =
 131         lib.concatLists (
 132           lib.mapAttrsToList (_name: fs: [
 133             {
 134               assertion = (fs.overlay.upperdir == null) == (fs.overlay.workdir == null);
 135               message = "You cannot define a `lowerdir` without a `workdir` and vice versa for mount point: ${fs.mountPoint}";
 136             }
 137             {
 138               assertion =
 139                 (fs.overlay.lowerdir != null && fs.overlay.upperdir == null)
 140                 -> (lib.length fs.overlay.lowerdir) >= 2;
 141               message = "A read-only overlay (without an `upperdir`) requires at least 2 `lowerdir`s: ${fs.mountPoint}";
 142             }
 143           ]) overlayFileSystems
 144         )
 145         ++ lib.mapAttrsToList (_: fs: {
 146           assertion = fs.overlay.upperdir == null -> config.boot.initrd.systemd.enable;
 147           message = ''
 148             Stage 1 overlay file system ${fs.mountPoint} has no upperdir,
 149             which is not supported with scripted initrd. Please enable
 150             'boot.initrd.systemd.enable'.
 151           '';
 152         }) initrdFileSystems;
 153
 154       boot.initrd.systemd.services = lib.mkMerge (lib.mapAttrsToList preMountService initrdFileSystems);
 155       systemd.services = lib.mkMerge (lib.mapAttrsToList preMountService userspaceFileSystems);
 156
 157     };
 158
 159 }