NixOS Installation Guide: Difference between revisions

From NixOS Wiki
← Older edit
VisualWikitext
imported>Ixxie
Fixed headers install from linux section.
Rrdpad (talk | contribs)
8 edits
Add blocks for console commands
 
(47 intermediate revisions by 20 users not shown)
Line 1: Line 1:
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.
This guide is a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation official manual]. It describes installation of [[NixOS]] as a complete operating system. For installation of [[Nix]] within an existing operating system, see [[Nix Installation Guide]].


== Installing from USB ==
In addition to describing the steps from the official manual, it provides known good instructions for common use cases. When there is a discrepancy between the manual and this guide, the supported case is the one described in the manual.


Since NixOS 14.11 the installer ISO is hybrid. This means it is bootable on both CD and USB drives. It also boots on EFI systems, like most modern motherboards and Mac* systems. Please read the [[#Hybrid image]] section on how to burn the ISO.
Use this guide as a step-by-step guide, choices will be presented, use only the selected section, and continue at the section it tells you to at the end.


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


=== Hybrid image ===
NixOS can be installed on an increasing variety of hardware:
{{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:
* regular (Intel or AMD) desktop computers, laptops or physically accessible servers, covered on this page
* SBCs (like the Raspberry Pis) and other ARM boards, see [[NixOS on ARM]]
* cloud and remote servers, see [[NixOS friendly hosters]]


On Linux:
== Installation method ==
# 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:
NixOS, as with most Linux-based operating systems, can be installed in different ways.
# 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.
# The classic way, booting from the installation media. (Described below.)
# [[Installing from Linux|Booting the media from an existing Linux installation]]


On Windows:
== Making the installation media ==
# Download [http://sourceforge.net/projects/usbwriter/ USBwriter].
# Start USBwriter.
# Choose the downloaded ISO as 'Source'
# Choose the USB drive as 'Target'
# Click 'Write'
# When USBwriter has finished writing, safely unplug the USB drive.


This should suffice to boot the installer. Otherwise look for other alternatives below.
Since NixOS 14.11 the installer ISO is hybrid. This means it is bootable on both CD and USB drives. It also boots on EFI systems, like most modern motherboards and apple systems. The following instructions will assume the standard way of copying the image to a USB drive. When using a CD or DVD, the usual methods to burn to disk should work with the iso.


=== UEFI note ===
=== "Burning" to USB drive ===


The below is for BIOS installation. For UEFI installation see [http://nixos.org/nixos/manual/#sec-uefi-installation the manual].
First, download a [https://nixos.org/download.html#nixos-iso NixOS ISO image] or [[Creating a NixOS live CD|create a custom ISO]]. Then plug in a USB stick large enough to accommodate the image. Then follow the platform instructions:


=== Using Unetbootin ===
==== From Linux ====


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:
# Find the right device with <code>lsblk</code> or <code>fdisk -l</code>. Replace <code><i>/dev/sdX</i></code> with the proper device in the following steps.
# Copy to device: <code>cp nixos-xxx.iso <em>/dev/sdX</em></code>


<ol>
{{note|do not use /dev/sdX1 or partitions of the disk, use the whole disk /dev/sdX.}}


<li>Download a [http://nixos.org/nixos/download.html NixOS ISO image] or [[Creating a Nix OS live CD|create a custom ISO]].</li>
Writing the disk image with <code>dd if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync</code> also works.


<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>
==== From macOS ====


<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>
# Find the right device with <code>diskutil list</code>, let's say <code><i>diskX</i></code>.
# Unmount with <code>diskutil unmountDisk <i>diskX</i></code>.
# Burn with: <code>sudo dd if=<b>path_to_nixos.iso</b> of=/dev/<i>diskX</i></code>


<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>
{{tip|Using <code>rdiskX</code> instead of <code>diskX</code> can makes a large speed difference. You can check the write speed with <code>iostat 2</code> in another terminal.}}


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


</ol>
# Download [http://sourceforge.net/projects/usbwriter/ USBwriter].
 
# Start USBwriter.
{{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`.}}
# Choose the downloaded ISO as 'Source'
 
# Choose the USB drive as 'Target'
=== Using syslinux ===
# Click 'Write'
 
# When USBwriter has finished writing, safely unplug the USB drive.
==== 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/
</syntaxhighlight>
 
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
</pre>
 
The relevant section from the live cd: /media/sd-card/boot/grub/grub.cfg
 
<pre>
menuentry "NixOS Installer / Rescue" {
  linux /boot/bzImage init=/nix/store/r7xhnzymi1ll49r4glf1dwr5y1alx0bl-system/init root=LABEL=NIXOS_INSTALL_CD_0.1pre27337 splash=verbose vga=0x317
  initrd /boot/initrd
}
</pre>
 
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>
DEFAULT linux
LABEL linux
  SAY Now booting the kernel from SYSLINUX...
  KERNEL /boot/bzImage
  APPEND init=/nix/store/r7xhnzymi1ll49r4glf1dwr5y1alx0bl-system/init root=UUID=509C-63E2 ro initrd=/boot/initrd splash=verbose
</pre>
 
'''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
</pre>
 
=== 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>
fdisk /dev/sdb
</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
</pre>
</li>
 
<li>Mount the bootable USB partition with:
 
<pre>
mkdir -p /media/NIXBOOT
mount /dev/sdb1 /media/NIXBOOT
</pre>
</li>
 
<li>Mount the ISO image with:
 
<pre>
mkdir -p /media/iso
mount -o loop ~/Downloads/nixos-graphical-0.2pre4463_5e88e9b-c877f45-x86_64-linux.iso /media/iso
</pre>
</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/
</pre>
</li>
 
<li>Install a complete and recent GRUB to the USB stick with:
 
<pre>
grub-install /dev/sdb --root-directory=/media/NIXBOOT/
</pre>
</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:
 
<pre>
menuentry "NixOS Installer / Rescue" {
  linux /boot/bzImage init=/nix/store/p94ckcksmhj90cr868cpcajrqgzwy57w-nixos-0.2pre4463_5e88e9b-c877f45/init root=LABEL=NIXBOOT
  initrd /boot/initrd
}
</pre>
</li>
 
<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>


== Build a custom installation image ==
=== Alternative installation media instructions ===


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
The previous methods are the supported methods of making the USB installation media.
This is explained in [[Creating a NixOS live CD]].


== Installing on VPS & Cloud Providers ==
Those methods are also documented, they can allow using the USB drive to boot multiple distributions. This is not supported, your mileage may vary.


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:
* [[NixOS_Installation_Guide/Unetbootin|Using Unetbootin]]
* [[NixOS_Installation_Guide/Manual USB Creation|Manual USB Creation]]
* [[NixOS_Installation_Guide/multibootusb|multibootusb]]


=== Hetzner ===
== Booting the installation media ==
{{expansion|Troubleshooting steps, and details are lacking.}}


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]
Since the installation media is hybrid, it will boot both in legacy bios mode and UEFI mode.


=== Digital Ocean ===
Whatever mode is used to boot the installation media, your motherboard or computer's configuration may need to be changed to allow booting from a Optical Disk Drive (for CD/DVD) or an external USB drive.


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].
=== Legacy bios boot ===


=== Netcup ===
This is the only boot possible on machines lacking EFI/UEFI.


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].
=== UEFI boot ===


=== Linode ===
The EFI bootloader of the installation media is not signed and is not using a signed shim to boot. This means that Secure Boot will need to be disabled to boot.


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]
== Connecting to the internet ==


=== CloudAtCost ===
The installation will '''definitely''' need a working internet connection. It is possible to install without one, but the available set of packages is limited.


=== Scaleway ===
=== Wired ===


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.
For network interfaces supported by the kernel, DHCP resolution should already have happened once the shell is available.


=== Rackspace ===
==Tethered (Internet Sharing)==


See [[Install NixOS on Rackspace Cloud Servers]].
If you can not connect to the internet via cable or wifi, you may use smartphone's tethering capability to share internet. Depending on your smartphones capabilities, only stock kernel drivers may be required which can help providing a working network connection.


=== Online.net ===
=== Wireless ===


See [[Install NixOS on Online.Net]].
Network Manager is installed on the graphical ISO, meaning that it is possible to use <code>nmtui</code> on the command line to connect to a network.


== Installing from Linux ==
Using the "Applications" tab at top
You already have a running linux with GRUB on your primary partition and you don't want to waste a CD-R?
left or the launcher bar at bottom, choose a terminal application and from there launch <code>nmtui</code>. This will allow you to 'activate' a (wireless) connection - your local SSIDs should be visible in the list, else you can add a new connection. When the wireless connection is active and you have tested it, it is likely the install app which launched on startup has not detected the new connection.  Close down the install app, and reopen it from the launcher bar at the bottom of the screen.  This should then find the new connection and proceed.
Right. We also assume that you have a spare partition where to install NixOS ready.


To simplify, we will be using these abbreviations:
On the minimal ISO, or if you are more familiar with <code>wpa_supplicant</code> then you can also run <code>wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf</code>, then enter your password and <code>systemctl restart wpa_supplicant</code>.


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


;/dev/sda2  : your linux root partition, containing your currently working OS  (/dev/sda1 and /dev/sda2 *can* be the same partition!)
To partition the persistent storage run <code>sudo fdisk /dev/diskX</code> and follow instructions for DOS or (U)EFI.
A very simple example setup is given here.


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


;/boot     : the boot directory, where grub is installed
* o (dos disk label)
* n new
* p primary (4 primary in total)
* 1 (partition number [1/4])
* 2048 first sector (alignment for performance)
* +500M last sector (boot sector size)
* rm signature (Y), if ex. => warning of overwriting existing system, could use wipefs
* n
* p
* 2
* default (fill up partition)
* default (fill up partition)
* w (write)


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


The following sections outline two installation methods. Choose the one that suits you best.
* g (gpt disk label)
 
* n
=== Installing through a chroot ===
* 1 (partition number [1/128])
In this section we will install NixOS by unpacking the ISO and then chrooting into its contents to start the final install.
* 2048 first sector
 
* +500M last sector (boot sector size)
==== Preparations ====
* t
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.
* 1 (EFI System)
 
* n
The following commands create two directories in your home directory, one for the ISO mountpoint and one for the host system. Then the ISO is downloaded (substitute as you please), mounted and the nix store extracted.
* 2
<syntaxhighlight lang="console">
* default (fill up partition)
# cd ~
* default (fill up partition)
# mkdir -p inst host/nix
* w (write)
# wget https://d3g5gsiof5omrk.cloudfront.net/nixos/17.03/nixos-17.03.1449.2e983f14f6/nixos-minimal-17.03.1449.2e983f14f6-x86_64-linux.iso
# modprobe loop
# mount -o loop nixos-minimal-17.03.1449.2e983f14f6-x86_64-linux.iso inst
# unsquashfs -d host/nix/store inst/nix-store.squashfs '*'
</syntaxhighlight>
 
To have a working network connection, copy /etc/resolv.conf to host/nix/etc. For a working chroot, you also need to bind /dev, /proc and /sys directories to the target system.
<syntaxhighlight lang="console">
# cd host
# mkdir -p etc dev proc sys
# cp /etc/resolv.conf etc
# for fn in dev proc sys; do mount --bind /$fn $fn; done
</syntaxhighlight>


==== Circumventing regular init sequence ====
== Label partitions ==


To properly chroot into the host system you must locate the packages named nixos and bash. The following commands may prove helpful:
This is useful for having multiple setups and makes partitions easier to handle<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
$ lsblk
# INIT=$(find . -type f -path '*nixos*/init')
$ sudo mkfs.fat -F 32 /dev/sdX1
# echo $INIT
$ sudo fatlabel /dev/sdX1 NIXBOOT
./nix/store/abwlkvzyjd2i39b1l1wfv7v9ilx88fwi-nixos-0.1pre34067-34077/init
$ sudo mkfs.ext4 /dev/sdX2 -L NIXROOT
# BASH=$(find . -type f -path '*/bin/bash' | tail -n 1)
$ sudo mount /dev/disk/by-label/NIXROOT /mnt
# echo $BASH
$ sudo mkdir -p /mnt/boot
./nix/store/bmgq2jrn6719r6j55gs4rzfp0azcbazy-bash-4.2-p24/bin/bash
$ sudo mount /dev/disk/by-label/NIXBOOT /mnt/boot
</syntaxhighlight>
</syntaxhighlight>


'''Replace further mentions of these files with your own results! Note the missing prefix in some uses.'''
== Swap file ==
 
Next we have to edit the target system init script to start a bash session instead of systemd. As that is the last thing the script does, adding an interactive program does not pose a problem.
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
# sed -i "s,exec systemd,exec /$BASH," $INIT
$ sudo dd if=/dev/zero of=/mnt/.swapfile bs=1024 count=2097152 (2GB size)
$ sudo chmod 600 /mnt/.swapfile
$ sudo mkswap /mnt/.swapfile
$ sudo swapon /mnt/.swapfile
</syntaxhighlight>
</syntaxhighlight>


==== Starting the install ====
== NixOS config ==
 
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.
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
# chroot . /$INIT
$ sudo nixos-generate-config --root /mnt
</syntaxhighlight>
$ cd /mnt/etc/nixos/
'''Further commands to be executed in the chrooted environment will be prefixed with "# (chroot)"'''.
$ sudo vim configuration.nix
</syntaxhighlight>Most essential changes:


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.
* keyboard layout, ie <code>[[Keyboard Layout Customization|services.xserver.xkb.layout]]</code>
<syntaxhighlight lang="console">
* <code>users.users.user</code> with adding entry <code>initialPassword = "pw123";</code>
# (chroot) mount /dev/sda3 /mnt
* [[networking]] (wifi), see below for fix if it breaks
# (chroot) nixos-generate-config --root /mnt
* <code>boot.loader.grub.device = "/dev/sda"; #or "nodev" for efi only</code>
# (chroot) nano /etc/nixos/configuration.nix
* install editor to edit the configuration
</syntaxhighlight>
* change hardware config to use labels


Before executing nixos-install you might want to run nixos-checkout to obtain the most recent version of packages to be installed into your NixOS system. You might need to copy /etc/resolv.conf from the host to the target system.  
The self-documenting NixOS options can be searched with [https://search.nixos.org/options NixOS options search].
<syntaxhighlight lang="console">
# (chroot) nixos-checkout
# (chroot) nixos-install
</syntaxhighlight>


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.
== NixOS installation ==
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
# (chroot) passwd
$ cd /mnt
</syntaxhighlight>
$ sudo nixos-install
 
</syntaxhighlight>after installation: Run <code>passwd</code> to change user password.
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.
 
=== Running the LiveCD installer from disk ===
In this section we will install NixOS by transfering the installer from the ISO to a bootable partition and then running it.
 
'''WARNING'''
 
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
* /etc will be merged, so your current settings can interfere with the final installation steps


==== Unpacking the ISO image ====
if internet broke/breaks, try one of the following:<syntaxhighlight lang="console">
 
$ nixos-rebuild switch --option substitute false # no downloads
<syntaxhighlight lang="console">
$ nixos-rebuild switch --option binary-caches "" # no downloads
# 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!)
# modprobe loop
# 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
</syntaxhighlight>
</syntaxhighlight>
* wpa_supplicant flags to connect to wifi


==== Modifying your bootloader's config ====
<hr />
 
Look at some_dir/boot/grub/grub.cfg. This is Grub-2 main config file of the ISO.
Locate the NixOS menuentry section:
 
<pre>
menuentry "NixOS Installer / Rescue" {
  linux /boot/bzImage init=/nix/store/p5n72ay1c1wx4wry90zabr8jnljpdzgx-nixos-0.2pre4601_1def5ba-48a4e91/init root=LABEL=NIXOS_0.2pre4601_1def5ba-48a4e91
  initrd /boot/initrd
}
</pre>
 
The goal is to tell your bootloader to boot /nixos-livecd-bzImage with correct
init argument.
 
===== GRUB 1 =====
 
To setup grub-1, edit your /boot/grub/menu.lst (or equivalent). Add following
lines to the config:
<pre>
title NixOS LiveCD
kernel /nixos-livecd-bzImage init=/nix/store/p5n72ay1c1wx4wry90zabr8jnljpdzgx-nixos-0.2pre4601_1def5ba-48a4e91/init root=/dev/sda2 splash=verbose vga=0x317
initrd /nixos-livecd-initrd
</pre>
 
Note, that hash should match with what you have seen in some_dir/grub/grub.cfg
 
Go to the reboot section
 
===== GRUB 2 =====
 
A grub entry for ubuntu might look like this:


<pre>
== Additional notes for specific hardware ==
menuentry "NixOS Installer / Rescue" {
  linux /nixos-livecd-bzImage init=/nix/store/p5n72ay1c1wx4wry90zabr8jnljpdzgx-nixos-0.2pre4601_1def5ba-48a4e91/init root=/dev/sda2
  initrd /nixos-lived-initrd
}
</pre>


===== Other bootloaders =====
These are collected notes or links for specific hardware issues.
 
Should also work. Please add instructions here.
 
==== Booting into LiveCD ====
 
Reboot. Select "NixOS LiveCD" from the bootloader menu. If everything is OK, you
will see Login prompt asking you to login as root with empty password.
''DO NOT TRUST IT BLINDLY.
You probably have your /etc mounted from /dev/sda2 so
it contains your old passwd (as well as LiveCD stuff merged into by the means of
UnionFS). So if empty password is not working, try your old root password.
 
Thats it. Now follow the manual (Alt-F8), mount /dev/sda3 as /mnt, do
nixos-option and so on.
 
== Special hardware ==


* Blog post how to install NixOS on a [http://grahamc.com/blog/nixos-on-dell-9560 Dell 9560]
* Blog post how to install NixOS on a [http://grahamc.com/blog/nixos-on-dell-9560 Dell 9560]
* for embedded Hardware like the Raspberry Pi2 see [[NixOS on ARM]]
* Brand servers may require extra kernel modules be included into initrd (<code>boot.initrd.extraKernelModules</code> in configuration.nix) For example HP Proliant needs "hpsa" module to see the disk drive.
* 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:Guide]]


[[Category:Installation]]
[[Category:Guide]][[Category:Deployment]]

Latest revision as of 16:00, 25 June 2024

This guide is a companion guide for the official manual. It describes installation of NixOS as a complete operating system. For installation of Nix within an existing operating system, see Nix Installation Guide.

In addition to describing the steps from the official manual, it provides known good instructions for common use cases. When there is a discrepancy between the manual and this guide, the supported case is the one described in the manual.

Use this guide as a step-by-step guide, choices will be presented, use only the selected section, and continue at the section it tells you to at the end.

Installation target

NixOS can be installed on an increasing variety of hardware:

  • regular (Intel or AMD) desktop computers, laptops or physically accessible servers, covered on this page
  • SBCs (like the Raspberry Pis) and other ARM boards, see NixOS on ARM
  • cloud and remote servers, see NixOS friendly hosters

Installation method

NixOS, as with most Linux-based operating systems, can be installed in different ways.

  1. The classic way, booting from the installation media. (Described below.)
  2. Booting the media from an existing Linux installation

Making the installation media

Since NixOS 14.11 the installer ISO is hybrid. This means it is bootable on both CD and USB drives. It also boots on EFI systems, like most modern motherboards and apple systems. The following instructions will assume the standard way of copying the image to a USB drive. When using a CD or DVD, the usual methods to burn to disk should work with the iso.

"Burning" to USB drive

First, download a NixOS ISO image or create a custom ISO. Then plug in a USB stick large enough to accommodate the image. Then follow the platform instructions:

From Linux

  1. Find the right device with lsblk or fdisk -l. Replace /dev/sdX with the proper device in the following steps.
  2. Copy to device: cp nixos-xxx.iso /dev/sdX
Note: do not use /dev/sdX1 or partitions of the disk, use the whole disk /dev/sdX.

Writing the disk image with dd if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync also works.

From macOS

  1. Find the right device with diskutil list, let's say diskX.
  2. Unmount with diskutil unmountDisk diskX.
  3. Burn with: sudo dd if=path_to_nixos.iso of=/dev/diskX

From Windows

  1. Download USBwriter.
  2. Start USBwriter.
  3. Choose the downloaded ISO as 'Source'
  4. Choose the USB drive as 'Target'
  5. Click 'Write'
  6. When USBwriter has finished writing, safely unplug the USB drive.

Alternative installation media instructions

The previous methods are the supported methods of making the USB installation media.

Those methods are also documented, they can allow using the USB drive to boot multiple distributions. This is not supported, your mileage may vary.

Booting the installation media

Since the installation media is hybrid, it will boot both in legacy bios mode and UEFI mode.

Whatever mode is used to boot the installation media, your motherboard or computer's configuration may need to be changed to allow booting from a Optical Disk Drive (for CD/DVD) or an external USB drive.

Legacy bios boot

This is the only boot possible on machines lacking EFI/UEFI.

UEFI boot

The EFI bootloader of the installation media is not signed and is not using a signed shim to boot. This means that Secure Boot will need to be disabled to boot.

Connecting to the internet

The installation will definitely need a working internet connection. It is possible to install without one, but the available set of packages is limited.

Wired

For network interfaces supported by the kernel, DHCP resolution should already have happened once the shell is available.

Tethered (Internet Sharing)

If you can not connect to the internet via cable or wifi, you may use smartphone's tethering capability to share internet. Depending on your smartphones capabilities, only stock kernel drivers may be required which can help providing a working network connection.

Wireless

Network Manager is installed on the graphical ISO, meaning that it is possible to use nmtui on the command line to connect to a network.

Using the "Applications" tab at top left or the launcher bar at bottom, choose a terminal application and from there launch nmtui. This will allow you to 'activate' a (wireless) connection - your local SSIDs should be visible in the list, else you can add a new connection. When the wireless connection is active and you have tested it, it is likely the install app which launched on startup has not detected the new connection. Close down the install app, and reopen it from the launcher bar at the bottom of the screen. This should then find the new connection and proceed.

On the minimal ISO, or if you are more familiar with wpa_supplicant then you can also run wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf, then enter your password and systemctl restart wpa_supplicant.

Partitioning

To partition the persistent storage run sudo fdisk /dev/diskX and follow instructions for DOS or (U)EFI. A very simple example setup is given here.

DOS

  • o (dos disk label)
  • n new
  • p primary (4 primary in total)
  • 1 (partition number [1/4])
  • 2048 first sector (alignment for performance)
  • +500M last sector (boot sector size)
  • rm signature (Y), if ex. => warning of overwriting existing system, could use wipefs
  • n
  • p
  • 2
  • default (fill up partition)
  • default (fill up partition)
  • w (write)

UEFI

  • g (gpt disk label)
  • n
  • 1 (partition number [1/128])
  • 2048 first sector
  • +500M last sector (boot sector size)
  • t
  • 1 (EFI System)
  • n
  • 2
  • default (fill up partition)
  • default (fill up partition)
  • w (write)

Label partitions

This is useful for having multiple setups and makes partitions easier to handle

$ lsblk
$ sudo mkfs.fat -F 32 /dev/sdX1
$ sudo fatlabel /dev/sdX1 NIXBOOT
$ sudo mkfs.ext4 /dev/sdX2 -L NIXROOT
$ sudo mount /dev/disk/by-label/NIXROOT /mnt
$ sudo mkdir -p /mnt/boot
$ sudo mount /dev/disk/by-label/NIXBOOT /mnt/boot

Swap file

$ sudo dd if=/dev/zero of=/mnt/.swapfile bs=1024 count=2097152 (2GB size)
$ sudo chmod 600 /mnt/.swapfile
$ sudo mkswap /mnt/.swapfile
$ sudo swapon /mnt/.swapfile

NixOS config

$ sudo nixos-generate-config --root /mnt
$ cd /mnt/etc/nixos/
$ sudo vim configuration.nix

Most essential changes:

  • keyboard layout, ie services.xserver.xkb.layout
  • users.users.user with adding entry initialPassword = "pw123";
  • networking (wifi), see below for fix if it breaks
  • boot.loader.grub.device = "/dev/sda"; #or "nodev" for efi only
  • install editor to edit the configuration
  • change hardware config to use labels

The self-documenting NixOS options can be searched with NixOS options search.

NixOS installation

$ cd /mnt
$ sudo nixos-install

after installation: Run passwd to change user password. if internet broke/breaks, try one of the following:

$ nixos-rebuild switch --option substitute false # no downloads
$ nixos-rebuild switch --option binary-caches "" # no downloads
  • wpa_supplicant flags to connect to wifi

Additional notes for specific hardware

These are collected notes or links for specific hardware issues.

  • Blog post how to install NixOS on a Dell 9560
  • 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.
Retrieved from "https://wiki.nixos.org/w/index.php?title=NixOS_Installation_Guide&oldid=13513"