View source for NixOS on ARM/Initial Configuration

{{ARM/breadcrumb}}<!--

Plan

This page will assume SD image is used, but should stay as generic as possible.
We should point out what option sets are specific to U-Boot systems (e.g. extlinux-compatible).

Otherwise, describe what to do to get started with the image.

And maybe a short troubleshooting section... thinking mainly "when I reboot I am back in the first generation" ("/boot" mounted when it doesn't need to be.)


-->
== NixOS installation & configuration ==

{{outdated|The kernel version recommendations of this section are severely outdated. This section should be rewritten to be generic and refer people to the board-specific page. Only the board specific page should make recommendations about the kernel.}}

The installation image is actually a MBR partition table plus two partitions; a FAT16 /boot and a ext4 root filesystem. The image is designed such that it's possible to directly reuse the SD image's partition layout and "install" NixOS on the very same SD card by simply replacing the default configuration.nix and running nixos-rebuild. Using this installation method is strongly recommended, though if you know exactly what you're doing and how U-Boot on your board works, you can use nixos-install as usual. To help with the SD card installation method, the boot scripts on the image automatically resize the rootfs partition to fit the SD card on the first boot.

* To generate a default <code>/etc/nixos/configuration.nix</code> file, run <code>sudo nixos-generate-config</code>.

* You can also use an existing template:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ config, pkgs, lib, ... }:
{
  # NixOS wants to enable GRUB by default
  boot.loader.grub.enable = false;
  # Enables the generation of /boot/extlinux/extlinux.conf
  boot.loader.generic-extlinux-compatible.enable = true;
 
  # !!! If your board is a Raspberry Pi 1, select this:
  boot.kernelPackages = pkgs.linuxPackages_rpi;
  # On other boards, pick a different kernel, note that on most boards with good mainline support, default, latest and hardened should all work
  # Others might need a BSP kernel, which should be noted in their respective wiki entries
  
  # nixos-generate-config should normally set up file systems correctly
  imports = [ ./hardware-configuration.nix ];
  # If not, you can set them up manually as shown below
  /*
  fileSystems = {
    # Prior to 19.09, the boot partition was hosted on the smaller first partition
    # Starting with 19.09, the /boot folder is on the main bigger partition.
    # The following is to be used only with older images. Note such old images should not be considered supported anymore whatsoever, but if you installed back then, this might be needed
    /*
    "/boot" = {
      device = "/dev/disk/by-label/NIXOS_BOOT";
      fsType = "vfat";
    };
    */
    "/" = {
      device = "/dev/disk/by-label/NIXOS_SD";
      fsType = "ext4";
    };
  };
  */
    
  # !!! Adding a swap file is optional, but recommended if you use RAM-intensive applications that might OOM otherwise. 
  # Size is in MiB, set to whatever you want (though note a larger value will use more disk space).
  # swapDevices = [ { device = "/swapfile"; size = 1024; } ];
}</nowiki>}}
Note: the default configuration.nix will contain something like <code>imports = [ <nixos/modules/installer/sd-card/sd-image-armv7l-multiplatform.nix> ];</code> do not include that in your final installation or you will experience interesting problems. It is only for building the installation image!

==== First rebuild on ARMv6 and ARMv7 ====

To rebuild your system, run: <code>sudo nixos-rebuild switch</code>

{{note|Instructions removed since they referred to a long abandoned user-provided cache...}}
<!--
To make the unsupported ARM experience slightly less painful, the config template adds <code>[...]</code> as a binary cache, which contains a small subset of packages on the unstable channel (though a caution for US users: the server hosting them is physically located in Finland). Note that the binary cache isn't enabled on the prebuilt images, so enable it via the command line when building for the first time:

<syntaxhighlight lang="bash">nixos-rebuild switch --fast --option binary-caches [...]/channel --option binary-cache-public-keys [...]-1:XXXXXXXXXXXXXX+XXXXXXXXXXXXXX=%</syntaxhighlight>
-->