pyrox.dev
1# Building Images via `systemd-repart` {#sec-image-repart}
2
3You can build disk images in NixOS with the `image.repart` option provided by
4the module [image/repart.nix][]. This module uses `systemd-repart` to build the
5images and exposes it's entire interface via the `repartConfig` option.
6
7[image/repart.nix]: https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/image/repart.nix
8
9An example of how to build an image:
10
11```nix
12{ config, modulesPath, ... }: {
13
14 imports = [ "${modulesPath}/image/repart.nix" ];
15
16 image.repart = {
17 name = "image";
18 partitions = {
19 "esp" = {
20 contents = {
21 # ...
22 };
23 repartConfig = {
24 Type = "esp";
25 # ...
26 };
27 };
28 "root" = {
29 storePaths = [ config.system.build.toplevel ];
30 repartConfig = {
31 Type = "root";
32 Label = "nixos";
33 # ...
34 };
35 };
36 };
37 };
38
39}
40```
41
42## Nix Store Partition {#sec-image-repart-store-partition}
43
44You can define a partition that only contains the Nix store and then mount it
45under `/nix/store`. Because the `/nix/store` part of the paths is already
46determined by the mount point, you have to set `stripNixStorePrefix = true;` so
47that the prefix is stripped from the paths before copying them into the image.
48
49```nix
50{
51 fileSystems."/nix/store".device = "/dev/disk/by-partlabel/nix-store";
52
53 image.repart.partitions = {
54 "store" = {
55 storePaths = [ config.system.build.toplevel ];
56 stripNixStorePrefix = true;
57 repartConfig = {
58 Type = "linux-generic";
59 Label = "nix-store";
60 # ...
61 };
62 };
63 };
64}
65```
66
67## Appliance Image {#sec-image-repart-appliance}
68
69The `image/repart.nix` module can also be used to build self-contained [software
70appliances][].
71
72[software appliances]: https://en.wikipedia.org/wiki/Software_appliance
73
74The generation based update mechanism of NixOS is not suited for appliances.
75Updates of appliances are usually either performed by replacing the entire
76image with a new one or by updating partitions via an A/B scheme. See the
77[Chrome OS update process][chrome-os-update] for an example of how to achieve
78this. The appliance image built in the following example does not contain a
79`configuration.nix` and thus you will not be able to call `nixos-rebuild` from
80this system. Furthermore, it uses a [Unified Kernel Image][unified-kernel-image].
81
82[chrome-os-update]: https://chromium.googlesource.com/aosp/platform/system/update_engine/+/HEAD/README.md
83[unified-kernel-image]: https://uapi-group.org/specifications/specs/unified_kernel_image/
84
85```nix
86let
87 pkgs = import <nixpkgs> { };
88 efiArch = pkgs.stdenv.hostPlatform.efiArch;
89in
90(pkgs.nixos [
91 ({ config, lib, pkgs, modulesPath, ... }: {
92
93 imports = [ "${modulesPath}/image/repart.nix" ];
94
95 boot.loader.grub.enable = false;
96
97 fileSystems."/".device = "/dev/disk/by-label/nixos";
98
99 image.repart = {
100 name = "image";
101 partitions = {
102 "esp" = {
103 contents = {
104 "/EFI/BOOT/BOOT${lib.toUpper efiArch}.EFI".source =
105 "${pkgs.systemd}/lib/systemd/boot/efi/systemd-boot${efiArch}.efi";
106
107 "/EFI/Linux/${config.system.boot.loader.ukiFile}".source =
108 "${config.system.build.uki}/${config.system.boot.loader.ukiFile}";
109 };
110 repartConfig = {
111 Type = "esp";
112 Format = "vfat";
113 SizeMinBytes = "96M";
114 };
115 };
116 "root" = {
117 storePaths = [ config.system.build.toplevel ];
118 repartConfig = {
119 Type = "root";
120 Format = "ext4";
121 Label = "nixos";
122 Minimize = "guess";
123 };
124 };
125 };
126 };
127
128 })
129]).image
130```