doc/build-helpers/images/makediskimage.section.md

   1 # `<nixpkgs/nixos/lib/make-disk-image.nix>` {#sec-make-disk-image}
   2
   3 `<nixpkgs/nixos/lib/make-disk-image.nix>` is a function to create _disk images_ in multiple formats: raw, QCOW2 (QEMU), QCOW2-Compressed (compressed version), VDI (VirtualBox), VPC (VirtualPC).
   4
   5 This function can create images in two ways:
   6
   7 - using `cptofs` without any virtual machine to create a Nix store disk image,
   8 - using a virtual machine to create a full NixOS installation.
   9
  10 When testing early-boot or lifecycle parts of NixOS such as a bootloader or multiple generations, it is necessary to opt for a full NixOS system installation.
  11 Whereas for many web servers, applications, it is possible to work with a Nix store only disk image and is faster to build.
  12
  13 NixOS tests also use this function when preparing the VM. The `cptofs` method is used when `virtualisation.useBootLoader` is false (the default). Otherwise the second method is used.
  14
  15 ## Features {#sec-make-disk-image-features}
  16
  17 For reference, read the function signature source code for documentation on arguments: <https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-disk-image.nix>.
  18 Features are separated in various sections depending on if you opt for a Nix-store only image or a full NixOS image.
  19
  20 ### Common {#sec-make-disk-image-features-common}
  21
  22 - arbitrary NixOS configuration
  23 - automatic or bound disk size: `diskSize` parameter, `additionalSpace` can be set when `diskSize` is `auto` to add a constant of disk space
  24 - multiple partition table layouts: EFI, legacy, legacy + GPT, hybrid, none through `partitionTableType` parameter
  25 - OVMF or EFI firmwares and variables templates can be customized
  26 - root filesystem `fsType` can be customized to whatever `mkfs.${fsType}` exist during operations
  27 - root filesystem label can be customized, defaults to `nix-store` if it's a Nix store image, otherwise `nixpkgs/nixos`
  28 - arbitrary code can be executed after disk image was produced with `postVM`
  29 - the current nixpkgs can be realized as a channel in the disk image, which will change the hash of the image when the sources are updated
  30 - additional store paths can be provided through `additionalPaths`
  31
  32 ### Full NixOS image {#sec-make-disk-image-features-full-image}
  33
  34 - arbitrary contents with permissions can be placed in the target filesystem using `contents`
  35 - a `/etc/nixpkgs/nixos/configuration.nix` can be provided through `configFile`
  36 - bootloaders are supported
  37 - EFI variables can be mutated during image production and the result is exposed in `$out`
  38 - boot partition size when partition table is `efi` or `hybrid`
  39
  40 ### On bit-to-bit reproducibility {#sec-make-disk-image-features-reproducibility}
  41
  42 Images are **NOT** deterministic, please do not hesitate to try to fix this, source of determinisms are (not exhaustive) :
  43
  44 - bootloader installation have timestamps
  45 - SQLite Nix store database contain registration times
  46 - `/etc/shadow` is in a non-deterministic order
  47
  48 A `deterministic` flag is available for best efforts determinism.
  49
  50 ## Usage {#sec-make-disk-image-usage}
  51
  52 To produce a Nix-store only image:
  53 ```nix
  54 let
  55   pkgs = import <nixpkgs> {};
  56   lib = pkgs.lib;
  57   make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
  58 in
  59   make-disk-image {
  60     inherit pkgs lib;
  61     config = {};
  62     additionalPaths = [ ];
  63     format = "qcow2";
  64     onlyNixStore = true;
  65     partitionTableType = "none";
  66     installBootLoader = false;
  67     touchEFIVars = false;
  68     diskSize = "auto";
  69     additionalSpace = "0M"; # Defaults to 512M.
  70     copyChannel = false;
  71   }
  72 ```
  73
  74 Some arguments can be left out, they are shown explicitly for the sake of the example.
  75
  76 Building this derivation will provide a QCOW2 disk image containing only the Nix store and its registration information.
  77
  78 To produce a NixOS installation image disk with UEFI and bootloader installed:
  79 ```nix
  80 let
  81   pkgs = import <nixpkgs> {};
  82   lib = pkgs.lib;
  83   make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
  84   evalConfig = import <nixpkgs/nixos/lib/eval-config.nix>;
  85 in
  86   make-disk-image {
  87     inherit pkgs lib;
  88     inherit (evalConfig {
  89       modules = [
  90         {
  91           fileSystems."/" = { device = "/dev/vda"; fsType = "ext4"; autoFormat = true; };
  92           boot.grub.device = "/dev/vda";
  93         }
  94       ];
  95     }) config;
  96     format = "qcow2";
  97     onlyNixStore = false;
  98     partitionTableType = "legacy+gpt";
  99     installBootLoader = true;
 100     touchEFIVars = true;
 101     diskSize = "auto";
 102     additionalSpace = "0M"; # Defaults to 512M.
 103     copyChannel = false;
 104     memSize = 2048; # Qemu VM memory size in megabytes. Defaults to 1024M.
 105   }
 106 ```