pyrox.dev
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
5This 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
10When 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.
11Whereas for many web servers, applications, it is possible to work with a Nix store only disk image and is faster to build.
12
13NixOS 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
17For reference, read the function signature source code for documentation on arguments: <https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-disk-image.nix>.
18Features 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
42Images 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
48A `deterministic` flag is available for best efforts determinism.
49
50## Usage {#sec-make-disk-image-usage}
51
52To produce a Nix-store only image:
53```nix
54let
55 pkgs = import <nixpkgs> {};
56 lib = pkgs.lib;
57 make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
58in
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
74Some arguments can be left out, they are shown explicitly for the sake of the example.
75
76Building this derivation will provide a QCOW2 disk image containing only the Nix store and its registration information.
77
78To produce a NixOS installation image disk with UEFI and bootloader installed:
79```nix
80let
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>;
85in
86 make-disk-image {
87 inherit pkgs lib;
88 config = evalConfig {
89 modules = [
90 {
91 fileSystems."/" = { device = "/dev/vda"; fsType = "ext4"; autoFormat = true; };
92 boot.grub.device = "/dev/vda";
93 }
94 ];
95 };
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```
107
108