NixOS Installation Guide: Difference between revisions

This guide describes various ways of installing NixOS. The [https://nixos.org/nixos/manual/index.html#ch-installation official manual] should cover most usual use-cases.

== Installing from USB ==

For NixOS 14.04 and earlier, please read [[#Using Unetbootin]] and the other sections below.

{{Note|This section applies to NixOS 14.11. For NixOS 14.04, please refer to [[#Using Unetbootin]].}}

First, download a [http://nixos.org/nixos/download.html NixOS ISO image] or [[Creating a Nix OS live CD|create a custom ISO]]. Then plug in a USB stick large enough to accomodate the image. Then follow the platform instructions:

On Linux:

# Find the right device with <code>fdisk -l</code>, let's say <code>/dev/sdb</code>.

# Burn with: <code>cp nixos-xxx.iso /dev/sdb</code>

{{Note|do not use /dev/sdb1 or partitions of the disk, use the whole disk /dev/sdb.}}

On OS X:

# Find the right device with <code>diskutil list</code>, let's say <code>disk<b>2</b></code>.

# Unmount with <code>diskutil unmountDisk disk<b>2</b></code>.

# Burn with: <code>sudo dd if=<b>path_to_nixos.iso</b> of=/dev/<b>r</b>disk<b>2</b> bs=64k</code>

# Note the use of rdisk instead of disk, this makes a large speed difference. You can check the write speed with <code>iostat 2</code> in another terminal.

You could use Disk Utility to write the image but then you'd need to convert it first to a compatible format somehow.

On Windows:

# Download [http://sourceforge.net/projects/usbwriter/ USBwriter].

# Start USBwriter.

# Choose the downloaded ISO as 'Source'

# Choose the USB drive as 'Target'

# When USBwriter has finished writing, safely unplug the USB drive.

This should suffice to boot the installer. Otherwise look for other alternatives below.

The below is for BIOS installation. For UEFI installation see [http://nixos.org/nixos/manual/#sec-uefi-installation the manual].

It is possible to install NixOS from a USB stick, rather than from a CD.  This is useful if you want to install NixOS on a machine that doesn't have a CD-ROM drive (such as most netbooks), or if you don't want to waste a blank CD. Here is how to do it:

<ol>

<li>Download a [http://nixos.org/nixos/download.html NixOS ISO image] or [[#Build a custom installation image]].</li>

<li>Obtain a USB stick formatted with the VFAT/FAT32 filesystem with enough free disk space to hold the contents of the ISO image. {{Note|It's not necessary to erase the USB stick.}}</li>

<li>Install [http://unetbootin.sourceforge.net/ UNetbootin], a tool that allows you to create a bootable USB stick from an ISO image. UNetbootin runs on both Linux and Windows.  If you already have Nix/NixOS, you can install it by running <tt>nix-env -i unetbootin</tt>. [http://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems Other tools] may also work.</li>

<li>Insert the USB stick, start UNetbootin, select the ISO file and target USB drive, and press Ok.  This copies the contents of the ISO to the USB stick and installs the GRUB boot loader.</li>

<li>You should now be able to boot NixOS from the USB stick, and perform the installation as usual.</li>

</ol>

{{Note|For EFI support you may need to change the label of the FAT filesystem. You can do this on Linux with mlabel, and on OS X with diskutil: `sudo diskutil rename OLDNAME NIXOS_ISO`.}}

==== Using syslinux.cfg ====

If you have trouble booting from a USB drive or sdcard with Unetbootin (I just got a blinking cursor instead of a bootloader on an Asus eee 1000) the procedure described on http://knoppix.net/wiki/Bootable_USB_Key should work. After preparing the sdcard with mkdiskimage and syslinux you can mount it and copy all the content from the NixOS iso:

<syntaxhighlight lang="console">

$ mount -o loop ~/Downloads/nixos-graphical-0.1pre27337-i686-linux.iso /media/iso

$ rsync -av --progress /media/iso/ /media/sd-card/

The syslinux.cfg needs to be created manually, but the details can easily be derived from the grub.cfg on the NixOS install cd.

I specified the root device by UUID, to get the UUID:

<pre>

blkid /dev/mmcblk0p1

The relevant section from the live cd: /media/sd-card/boot/grub/grub.cfg

<pre>

  linux /boot/bzImage init=/nix/store/r7xhnzymi1ll49r4glf1dwr5y1alx0bl-system/init root=LABEL=NIXOS_INSTALL_CD_0.1pre27337 splash=verbose vga=0x317

  initrd /boot/initrd

can be used in the syslinux config file: /media/sd-card/syslinux.cfg (you should just need to update the init path and the root UUID / LABEL or device path)

<pre>

  SAY Now booting the kernel from SYSLINUX...

'''Note''': in place of using mkdiskimage, you can simply format your SDCard as a fat32 system and install syslinux on it:

<pre>

mkdosfs -F32 /dev/mmcblk0p1

syslinux -s /dev/mmcblk0p1

=== Using Command-line Tools ===

<ol>

<li>Download the ISO image from http://nixos.org/nixos/download.html.</li>

<li>Prepare your USB stick. If it isn't yet partitioned to your liking, create a bootable partition on <code>/dev/sdb1</code>:

<pre>

</pre>

And format it with:

<pre>

mkdosfs /dev/sdb1

</pre>

Add ext2 partitions if you like. If you want both 32-bit and 64-bit NixOS, you need at least two partitions.  You can directly use the entire disk without partition if that's what you like.  Once you have your VFAT (dosfs) block device, you should give it a label, within a 11-character limit, e.g.:

<pre>

dosfslabel /dev/sdb1 NIXBOOT

</li>

<li>Mount the bootable USB partition with:

<pre>

mkdir -p /media/iso

mount -o loop ~/Downloads/nixos-graphical-0.2pre4463_5e88e9b-c877f45-x86_64-linux.iso /media/iso

</li>

<li>Copy the contents of the NixOS ISO (<code>/media/iso</code>) to your USB stick (<code>/media/NIXBOOT</code>) with:

<pre>

rsync -av --progress /media/iso/ /media/NIXBOOT/

</li>

<li>Install a complete and recent GRUB to the USB stick with:

<pre>

grub-install /dev/sdb --root-directory=/media/NIXBOOT/

</li>

<li>Edit the file <code>/media/NIXBOOT/boot/grub/grub.cfg</code>. Start from an existing grub.cfg, say from your hard drive or from another working bootable USB stick (e.g., from GRML.org). Then, merge in the entry for NixOS from <code>/media/iso/boot/grub/grub.cfg</code>, modifying the LABEL to be that of your VFAT partition:

menuentry "NixOS Installer / Rescue" {

  linux /boot/bzImage init=/nix/store/p94ckcksmhj90cr868cpcajrqgzwy57w-nixos-0.2pre4463_5e88e9b-c877f45/init root=LABEL=NIXBOOT

<li>To share your USB stick with other distributions (e.g., GRML, or both 32- and 64- bit NixOS), you can move NixOS's bzImage and initrd to different location (e.g., <code>/boot/nix32/</code> and <code>/boot/nix64/</code>), and you appropriately edit the entries in your grub.cfg. If you have both nix32 and nix64, only one can have its <code>nix-store.squashfs</code> in the root of any given partition.  That's where you can use a second partition, for the second one.  For instance, copy the contents of your 64-bit NixOS to the first partition, with label <code>NIX64</code>, and copy the nix-store.squashfs of your 32-bit NixOS to the second partition with label <code>NIX32</code> (and create an empty nix/store). Copy the 32-bit kernel and initrd to <code>/boot/nix32/</code> on the bootable partition, and edit the grub.cfg of the bootable partition accordingly.</li>

 

<li>There you go: you have a bootable NixOS USB drive, possibly allowing you to boot NixOS 64-bit, NixOS 32-bit, GRML 64-bit, GRML 32-bit, FreeBSD, FreeDOS, boot-sector-tetris, etc. Just you convince your BIOS to let you boot off it.</li>

</ol>

 

 

NixOS provides an easy way to build a custom variant of the installation image. This might be useful to embed your own ssh key or enable additional features like zfs support. It allows to specify a custom <code>configuration.nix</code> which is used to build the image

 

 

Not all providers allow to upload own images or provide NixOS images for installation. However there are a few ways to install NixOS anyhow. [https://github.com/jeaye/nixos-in-place nixos-in-place] and [https://github.com/elitak/nixos-infect nixos-infect] are generic approaches to install NixOS from an existing Linux. A different approach is to build an kexec-based image to start the installer from an booted linux as shown in this [https://github.com/cleverca22/nix-tests/tree/master/kexec repo]. Here we list methods known to work on specific providers:

 

 

Hetzner provides an [https://wiki.hetzner.de/index.php/LARA/en#Installing_an_OS interface] to upload your own ISO-images. However you may want to build your own iso-image, which has openssh with ssh keys due the lack of a remote console. An easier method to install NixOS on Hetzner, is to use the existing integration into [https://nixos.org/nixops/manual/#idm140737318364240 NixOps].

 

 

 

On Digitalocean the project [https://github.com/elitak/nixos-infect nixos-infect] can be used to transform an existing installation into NixOS. This method will be also used in [https://nixos.org/nixops/manual/#sec-deploying-to-digital-ocean NixOps].

 

 

You can mount your own images similar to hetzner, see the [https://www.netcup-wiki.de/wiki/Server_Control_Panel_%28SCP%29#Eigene_DVDs official netcup documentation].

 

 

NixOS is official supported by Linode. Up to date documentation can be obtained from their [https://www.linode.com/docs/tools-reference/custom-kernels-distros/install-nixos-on-linode manual]

 

 

 

The <code>kexec</code> method above works well, but bear in mind it only works with the 'virtual' class of servers, as they run under a hypervisor which attaches the disks before the kernel boots. The 'bare-metal' servers rely on a special Linux kernel booting to attach network <code>/dev/nbdX</code> drives which works only with Scaleway supplied images.

 

 

 

 

 

 

 

You already have a running linux with GRUB on your primary partition and you don't want to waste a CD-R?

 

 

;/dev/sda1  : your boot partition, containing already working grub

 

;/dev/sda2  : your linux root partition, containing your currently working OS  (/dev/sda1 and /dev/sda2 *can* be the same partition!)

 

;/dev/sda3  : your spare partition to where you will install NixOS

 

;~/inst    : directory where the ISO is (loop) mounted

 

=== Installing through a chroot ===

In this section we will install NixOS by unpacking the ISO and then chrooting into its contents to start the final install.

 

Get a NixOS ISO and unpack the squashfs filesystem containing the nix store. A tool from squashfs-tools is required, so install that package first.

 

# wget https://d3g5gsiof5omrk.cloudfront.net/nixos/17.03/nixos-17.03.1449.2e983f14f6/nixos-minimal-17.03.1449.2e983f14f6-x86_64-linux.iso

# cd host

# mkdir -p etc dev proc sys

# cp /etc/resolv.conf etc

To properly chroot into the host system you must locate the packages named nixos and bash. The following commands may prove helpful:

'''Replace further mentions of these files with your own results! Note the missing prefix in some uses.'''

<syntaxhighlight lang="console">

# sed -i "s,exec systemd,exec /$BASH," $INIT

</syntaxhighlight>

==== Starting the install ====

Now we are able to chroot into the NixOS system used for installation. ''You may get several warnings and errors, but you can safely ignore them unless they are fatal.'' If you're installing from Arch, you may need to remove the mount call that tries to make / private in the same init script.

# chroot . /$INIT

The next steps are the same as with classical installation methods. Create a suitable NixOS [http://nixos.org/nixos/manual/#ch-configuration configuration] and start the build.

<syntaxhighlight lang="console">

# (chroot) mount /dev/sda3 /mnt

# (chroot) nixos-generate-config --root /mnt

</syntaxhighlight>

<syntaxhighlight lang="console">

Now your system should be set up. Be sure to change the root password to be able to login and double check that /mnt/boot/grub/menu.lst is present and looks sensible.

Finally, if you instructed nix not to overwrite your existing boot loader, manually copy the menu.lst entries into your existing system's GRUB menu.lst.

Once you're done tweaking, exit the chroot (exit or ctrl-d will) and reboot. With any luck, you will have new choices in the GRUB menu to choose from.

In this section we will install NixOS by transfering the installer from the ISO to a bootable partition and then running it.

This approach relies on merging the LiveCD image with the contents of your working partition, so several limitations apply:

* the target partition needs to have enough free space for both the working partition (/dev/sda2) and the uncompressed nix store from the LiveCD

==== Unpacking the ISO image ====

# wget https://d3g5gsiof5omrk.cloudfront.net/nixos/17.03/nixos-17.03.1449.2e983f14f6/nixos-minimal-17.03.1449.2e983f14f6-x86_64-linux.iso # get the latest iso (URL might change!)

# mount -o loop nixos-minimal-17.03.1449.2e983f14f6-x86_64-linux.iso ~/inst

# # mount /dev/sda1 # mount the /boot partition if you have it

# cp ~/inst/boot/bzImage /boot/nixos-livecd-bzImage

# cp ~/inst/boot/initrd /boot/nixos-livecd-initrd

# cp ~/inst/nix-store.squashfs /nix-store.squashfs

 

 

</pre>

 

The goal is to tell your bootloader to boot /nixos-livecd-bzImage with correct

 

 

lines to the config:

kernel /nixos-livecd-bzImage init=/nix/store/p5n72ay1c1wx4wry90zabr8jnljpdzgx-nixos-0.2pre4601_1def5ba-48a4e91/init root=/dev/sda2 splash=verbose vga=0x317

</pre>

 

 

 

 

 

<pre>

  initrd /nixos-lived-initrd

</pre>

 

 

==== Booting into LiveCD ====

 

Thats it. Now follow the manual (Alt-F8), mount /dev/sda3 as /mnt, do

nixos-option and so on.

 

== Special hardware ==

* Brand servers may require extra kernel modules be included into initrd (boot.initrd.extraKernelModules in configuration.nix) For example HP Proliant needs "hpsa" module to see the disk drive.

 

 

[[Category:Installation]]