Files
nixpkgs/nixos/doc/manual/configuration/overlayfs.section.md
Dark Steveneq 646b892680
Some checks failed
Periodic Merges (6h) / master → staging-nixos (push) Failing after 12m50s
Periodic Merges (6h) / master → staging-next (push) Failing after 12m54s
Periodic Merges (24h) / merge-base(master,staging) → haskell-updates (push) Failing after 11m54s
Periodic Merges (6h) / staging-next → staging (push) Failing after 12m13s
Periodic Merges (24h) / staging-next-25.05 → staging-25.05 (push) Failing after 13m24s
Periodic Merges (24h) / release-25.05 → staging-next-25.05 (push) Failing after 14m28s
push sheeet
2025-10-09 14:15:47 +02:00

734 B

Overlayfs

NixOS offers a convenient abstraction to create both read-only as well writable overlays.

{
  fileSystems = {
    "/writable-overlay" = {
      overlay = {
        lowerdir = [ writableOverlayLowerdir ];
        upperdir = "/.rw-writable-overlay/upper";
        workdir = "/.rw-writable-overlay/work";
      };
      # Mount the writable overlay in the initrd.
      neededForBoot = true;
    };
    "/readonly-overlay".overlay.lowerdir = [
      writableOverlayLowerdir
      writableOverlayLowerdir2
    ];
  };
}

If upperdir and workdir are not null, they will be created before the overlay is mounted.

To mount an overlay as read-only, you need to provide at least two lowerdirs.