pyrox.dev
1# Building a NixOS (Live) ISO {#sec-building-image}
2
3Default live installer configurations are available inside `nixos/modules/installer/cd-dvd`.
4For building other system images, [nixos-generators] is a good place to start looking at.
5
6You have two options:
7
8- Use any of those default configurations as is
9- Combine them with (any of) your host config(s)
10
11System images, such as the live installer ones, know how to enforce configuration settings
12on which they immediately depend in order to work correctly.
13
14However, if you are confident, you can opt to override those
15enforced values with `mkForce`.
16
17[nixos-generators]: https://github.com/nix-community/nixos-generators
18
19## Practical Instructions {#sec-building-image-instructions}
20
21To build an ISO image for the channel `nixos-unstable`:
22
23```ShellSession
24$ git clone https://github.com/NixOS/nixpkgs.git
25$ cd nixpkgs/nixos
26$ git switch nixos-unstable
27$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix
28```
29
30To check the content of an ISO image, mount it like so:
31
32```ShellSession
33# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso
34```
35
36## Additional drivers or firmware {#sec-building-image-drivers}
37
38If you need additional (non-distributable) drivers or firmware in the
39installer, you might want to extend these configurations.
40
41For example, to build the GNOME graphical installer ISO, but with support for
42certain WiFi adapters present in some MacBooks, you can create the following
43file at `modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix`:
44
45```nix
46{ config, ... }:
47
48{
49 imports = [ ./installation-cd-graphical-gnome.nix ];
50
51 boot.initrd.kernelModules = [ "wl" ];
52
53 boot.kernelModules = [ "kvm-intel" "wl" ];
54 boot.extraModulePackages = [ config.boot.kernelPackages.broadcom_sta ];
55}
56```
57
58Then build it like in the example above:
59
60```ShellSession
61$ git clone https://github.com/NixOS/nixpkgs.git
62$ cd nixpkgs/nixos
63$ export NIXPKGS_ALLOW_UNFREE=1
64$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix default.nix
65```
66
67## Technical Notes {#sec-building-image-tech-notes}
68
69The config value enforcement is implemented via `mkImageMediaOverride = mkOverride 60;`
70and therefore primes over simple value assignments, but also yields to `mkForce`.
71
72This property allows image designers to implement in semantically correct ways those
73configuration values upon which the correct functioning of the image depends.
74
75For example, the iso base image overrides those file systems which it needs at a minimum
76for correct functioning, while the installer base image overrides the entire file system
77layout because there can't be any other guarantees on a live medium than those given
78by the live medium itself. The latter is especially true before formatting the target
79block device(s). On the other hand, the netboot iso only overrides its minimum dependencies
80since netboot images are always made-to-target.