nixos/doc/manual/installation/building-images-via-systemd-repart.chapter.md

   1 # Building Images via `systemd-repart` {#sec-image-repart}
   2
   3 You can build disk images in NixOS with the `image.repart` option provided by
   4 the module [image/repart.nix][]. This module uses `systemd-repart` to build the
   5 images 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
   9 An 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
  44 You can define a partition that only contains the Nix store and then mount it
  45 under `/nix/store`. Because the `/nix/store` part of the paths is already
  46 determined by the mount point, you have to set `stripNixStorePrefix = true;` so
  47 that 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
  69 The `image/repart.nix` module can also be used to build self-contained [software
  70 appliances][].
  71
  72 [software appliances]: https://en.wikipedia.org/wiki/Software_appliance
  73
  74 The generation based update mechanism of NixOS is not suited for appliances.
  75 Updates of appliances are usually either performed by replacing the entire
  76 image 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
  78 this. 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
  80 this 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
  86 let
  87   pkgs = import <nixpkgs> { };
  88   efiArch = pkgs.stdenv.hostPlatform.efiArch;
  89 in
  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 ```