NixOS on ARM/Building Images: Difference between revisions

From NixOS Wiki
Created page with "== Build your own image natively == You can customize image by using the following snippet. <syntaxhighlight lang="nix"> # save as sd-image.nix somewhere { ... }: { imports = [ <nixpkgs/nixos/modules/installer/sd-card/sd-image-aarch64.nix> ]; # put your own configuration here, for example ssh keys: users.users.root.openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAAC3NzaC1lZDI1.... username@tld" ]; } </syntaxhighlight> Then build with: <syntaxhighlig..."
 
m Add plan and update with alternatives section
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{ARM/breadcrumb}}
{{outdated|This page needs a cleanup; it was migrated from an organically evolving article from about three wikis ago. The information may still be accurate though.}}<!--
Plan
Make it obvious that this is not a public-facing API. Though the scheme is used for building e.g. armv7l and armv6l images.
Building complex images from the SD image tooling is not supported, and will not be.
-->
== Build your own image natively ==
== Build your own image natively ==


Line 93: Line 103:


It is also possible to build nixos images through full emulation using QEMU/kvm but will be way slower than native and binfmt QEMU.
It is also possible to build nixos images through full emulation using QEMU/kvm but will be way slower than native and binfmt QEMU.
== Alternatives to building custom images ==
=== Stock NixOS installer image with custom U-Boot ===
The [https://github.com/Mic92/nixos-aarch64-images Mic92/nixos-aarch64-images] repository provides a mechanism to modify the official NixOS installer to embed the board-specific U-Boot firmware required for different boards. This method does not require QEMU or native ARM builds since the existing Hydra-built U-Boot binaries are used.
=== Editing the image manually ===
For some simple operations, like adding an SSH public key, the expected usage for new users is to manually edit the image, add the proper directory and <tt>authorized_keys</tt> file, with proper modes.
<syntaxhighlight lang="console">
$ namei -l /home/nixos/.ssh/authorized_keys
f: /home/nixos/.ssh/authorized_keys
drwxr-xr-x root  root  /
drwxr-xr-x root  root  home
drwx------ nixos  users nixos
drwx------ nixos  users .ssh
-rw------- nixos  users authorized_keys
</syntaxhighlight>

Latest revision as of 01:46, 8 April 2024

Build your own image natively

You can customize image by using the following snippet.

# save as sd-image.nix somewhere
{ ... }: {
  imports = [
    <nixpkgs/nixos/modules/installer/sd-card/sd-image-aarch64.nix>
  ];
  # put your own configuration here, for example ssh keys:
  users.users.root.openssh.authorizedKeys.keys = [
     "ssh-ed25519 AAAAC3NzaC1lZDI1.... username@tld"
  ];
}

Then build with:

$ nix-build '<nixpkgs/nixos>' -A config.system.build.sdImage -I nixos-config=./sd-image.nix

Note that this requires a machine with aarch64. You can however also build it from your laptop using an aarch64 remote builder as described in Distributed build or ask for access on the community aarch64 builder.

if you use the experimental flake, instead of doing the above stuff, can put the following lines in flake.nix, git add flake.nix and build with nix build .#images.rpi2:

{
  description = "Build image";
  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-22.11";
  outputs = { self, nixpkgs }: rec {
    nixosConfigurations.rpi2 = nixpkgs.lib.nixosSystem {
      modules = [
        "${nixpkgs}/nixos/modules/installer/sd-card/sd-image-raspberrypi.nix"
        {
          nixpkgs.config.allowUnsupportedSystem = true;
          nixpkgs.hostPlatform.system = "armv7l-linux";
          nixpkgs.buildPlatform.system = "x86_64-linux"; #If you build on x86 other wise changes this.
          # ... extra configs as above
        }
      ];
    };
    images.rpi2 = nixosConfigurations.rpi2.config.system.build.sdImage;
  };
}

Cross-compiling

It is possible to cross-compile from a different architecture. To cross-compile to armv7l, on the same sd-image.nix add in crossSystem:

{ ... }: {
  nixpkgs.crossSystem.system = "armv7l-linux";
  imports = [
    <nixpkgs/nixos/modules/installer/sd-card/sd-image-aarch64.nix>
  ];
  # ...
}

Compiling through binfmt QEMU

It is also possible to compile for aarch64 on your non-aarch64 local machine, or a remote builder, by registering QEMU as a binfmt wrapper for the aarch64 architecture. This wrapper uses emulation and will therefore be slower than comparable native machines or cross-compiling.

To enable the binfmt wrapper on NixOS, add the following to configuration.nix

{
  boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
}

Then, add --argstr system aarch64-linux to the build command:

$ nix-build '<nixpkgs/nixos>' -A config.system.build.sdImage -I nixos-config=./sd-image.nix --argstr system aarch64-linux

If you are building on non-NixOS machine with QEMU binfmt wrapper configured, you will want to configure nix daemon to let it know that it can build for aarch64. Add the following line to /etc/nix/nix.conf: extra-platforms = aarch64-linux arm-linux

Note: archlinux users can install extra/qemu-system-aarch64, extra/qemu-user-static and extra/qemu-user-static-binfmt and restart systemd-binfmt.service. Check if binfmt is loaded by ls /proc/sys/fs/binfmt_misc/ (there must be qemu-aarch64 or needed architecture) and add line extra-sandbox-paths = /usr/bin/qemu-aarch64-static to /etc/nix/nix.conf and don't forget to restart the nix-daemon.service systemd unit afterwards.

If you want to build just one specific package, use this:

nix-build '<nixpkgs/nixos>' -A pkgs.theRequiredPackage --argstr system aarch64-linux -I nixos-config=/path/to/target/machine/nixos/config/copy

(the last option should not be required on NixOS machines)

Compiling through QEMU/kvm

It is also possible to build nixos images through full emulation using QEMU/kvm but will be way slower than native and binfmt QEMU.

Alternatives to building custom images

Stock NixOS installer image with custom U-Boot

The Mic92/nixos-aarch64-images repository provides a mechanism to modify the official NixOS installer to embed the board-specific U-Boot firmware required for different boards. This method does not require QEMU or native ARM builds since the existing Hydra-built U-Boot binaries are used.

Editing the image manually

For some simple operations, like adding an SSH public key, the expected usage for new users is to manually edit the image, add the proper directory and authorized_keys file, with proper modes.

$ namei -l /home/nixos/.ssh/authorized_keys
f: /home/nixos/.ssh/authorized_keys
drwxr-xr-x root   root  /
drwxr-xr-x root   root  home
drwx------ nixos  users nixos
drwx------ nixos  users .ssh
-rw------- nixos  users authorized_keys