pyrox.dev
1# vmTools {#sec-vm-tools}
2
3A set of VM related utilities, that help in building some packages in more advanced scenarios.
4
5## `vmTools.createEmptyImage` {#vm-tools-createEmptyImage}
6
7A bash script fragment that produces a disk image at `destination`.
8
9### Attributes {#vm-tools-createEmptyImage-attributes}
10
11* `size`. The disk size, in MiB.
12* `fullName`. Name that will be written to `${destination}/nix-support/full-name`.
13* `destination` (optional, default `$out`). Where to write the image files.
14
15## `vmTools.runInLinuxVM` {#vm-tools-runInLinuxVM}
16
17Run a derivation in a Linux virtual machine (using Qemu/KVM).
18By default, there is no disk image; the root filesystem is a `tmpfs`, and the Nix store is shared with the host (via the [9P protocol](https://wiki.qemu.org/Documentation/9p#9p_Protocol)).
19Thus, any pure Nix derivation should run unmodified.
20
21If the build fails and Nix is run with the `-K/--keep-failed` option, a script `run-vm` will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively.
22
23### Attributes {#vm-tools-runInLinuxVM-attributes}
24
25* `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host).
26* `memSize` (optional, default `512`). The memory size of the VM in MiB.
27* `diskImage` (optional). A file system image to be attached to `/dev/sda`.
28 Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
29
30### Examples {#vm-tools-runInLinuxVM-examples}
31
32Build the derivation hello inside a VM:
33```nix
34{ pkgs }: with pkgs; with vmTools; runInLinuxVM hello
35```
36
37Build inside a VM with extra memory:
38```nix
39{ pkgs }:
40with pkgs;
41with vmTools;
42runInLinuxVM (
43 hello.overrideAttrs (_: {
44 memSize = 1024;
45 })
46)
47```
48
49Use VM with a disk image (implicitly sets `diskImage`, see [`vmTools.createEmptyImage`](#vm-tools-createEmptyImage)):
50```nix
51{ pkgs }:
52with pkgs;
53with vmTools;
54runInLinuxVM (
55 hello.overrideAttrs (_: {
56 preVM = createEmptyImage {
57 size = 1024;
58 fullName = "vm-image";
59 };
60 })
61)
62```
63
64## `vmTools.extractFs` {#vm-tools-extractFs}
65
66Takes a file, such as an ISO, and extracts its contents into the store.
67
68### Attributes {#vm-tools-extractFs-attributes}
69
70* `file`. Path to the file to be extracted.
71 Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
72* `fs` (optional). Filesystem of the contents of the file.
73
74### Examples {#vm-tools-extractFs-examples}
75
76Extract the contents of an ISO file:
77```nix
78{ pkgs }: with pkgs; with vmTools; extractFs { file = ./image.iso; }
79```
80
81## `vmTools.extractMTDfs` {#vm-tools-extractMTDfs}
82
83Like [](#vm-tools-extractFs), but it makes use of a [Memory Technology Device (MTD)](https://en.wikipedia.org/wiki/Memory_Technology_Device).
84
85## `vmTools.runInLinuxImage` {#vm-tools-runInLinuxImage}
86
87Like [](#vm-tools-runInLinuxVM), but instead of using `stdenv` from the Nix store, run the build using the tools provided by `/bin`, `/usr/bin`, etc. from the specified filesystem image, which typically is a filesystem containing a [FHS](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)-based Linux distribution.
88
89## `vmTools.makeImageTestScript` {#vm-tools-makeImageTestScript}
90
91Generate a script that can be used to run an interactive session in the given image.
92
93### Examples {#vm-tools-makeImageTestScript-examples}
94
95Create a script for running a Fedora 27 VM:
96```nix
97{ pkgs }: with pkgs; with vmTools; makeImageTestScript diskImages.fedora27x86_64
98```
99
100Create a script for running an Ubuntu 20.04 VM:
101```nix
102{ pkgs }: with pkgs; with vmTools; makeImageTestScript diskImages.ubuntu2004x86_64
103```
104
105## `vmTools.diskImageFuns` {#vm-tools-diskImageFuns}
106
107A set of functions that build a predefined set of minimal Linux distributions images.
108
109### Images {#vm-tools-diskImageFuns-images}
110
111* Fedora
112 * `fedora26x86_64`
113 * `fedora27x86_64`
114* CentOS
115 * `centos6i386`
116 * `centos6x86_64`
117 * `centos7x86_64`
118* Ubuntu
119 * `ubuntu1404i386`
120 * `ubuntu1404x86_64`
121 * `ubuntu1604i386`
122 * `ubuntu1604x86_64`
123 * `ubuntu1804i386`
124 * `ubuntu1804x86_64`
125 * `ubuntu2004i386`
126 * `ubuntu2004x86_64`
127 * `ubuntu2204i386`
128 * `ubuntu2204x86_64`
129* Debian
130 * `debian10i386`
131 * `debian10x86_64`
132 * `debian11i386`
133 * `debian11x86_64`
134 * `debian12i386`
135 * `debian12x86_64`
136
137### Attributes {#vm-tools-diskImageFuns-attributes}
138
139* `size` (optional, defaults to `4096`). The size of the image, in MiB.
140* `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image.
141
142### Examples {#vm-tools-diskImageFuns-examples}
143
1448GiB image containing Firefox in addition to the default packages:
145```nix
146{ pkgs }:
147with pkgs;
148with vmTools;
149diskImageFuns.ubuntu2004x86_64 {
150 extraPackages = [ "firefox" ];
151 size = 8192;
152}
153```
154
155## `vmTools.diskImageExtraFuns` {#vm-tools-diskImageExtraFuns}
156
157Shorthand for `vmTools.diskImageFuns.<attr> { extraPackages = ... }`.
158
159## `vmTools.diskImages` {#vm-tools-diskImages}
160
161Shorthand for `vmTools.diskImageFuns.<attr> { }`.