pyrox.dev
1# Installing NixOS {#sec-installation}
2
3## Booting the system {#sec-installation-booting}
4
5NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI
6installation is by and large the same as a BIOS installation. The
7differences are mentioned in the steps that follow.
8
9The installation media can be burned to a CD, or now more commonly,
10"burned" to a USB drive (see [](#sec-booting-from-usb)).
11
12The installation media contains a basic NixOS installation. When it's
13finished booting, it should have detected most of your hardware.
14
15The NixOS manual is available by running `nixos-help`.
16
17You are logged-in automatically as `nixos`. The `nixos` user account has
18an empty password so you can use `sudo` without a password:
19```ShellSession
20$ sudo -i
21```
22
23If you downloaded the graphical ISO image, you can run `systemctl
24start display-manager` to start the desktop environment. If you want
25to continue on the terminal, you can use `loadkeys` to switch to your
26preferred keyboard layout. (We even provide neo2 via `loadkeys de
27neo`!)
28
29If the text is too small to be legible, try `setfont ter-v32n` to
30increase the font size.
31
32To install over a serial port connect with `115200n8` (e.g.
33`picocom -b 115200 /dev/ttyUSB0`). When the bootloader lists boot
34entries, select the serial console boot entry.
35
36### Networking in the installer {#sec-installation-booting-networking}
37
38The boot process should have brought up networking (check `ip
39a`). Networking is necessary for the installer, since it will
40download lots of stuff (such as source tarballs or Nixpkgs channel
41binaries). It's best if you have a DHCP server on your network.
42Otherwise configure networking manually using `ifconfig`.
43
44On the graphical installer, you can configure the network, wifi
45included, through NetworkManager. Using the `nmtui` program, you can do
46so even in a non-graphical session. If you prefer to configure the
47network manually, disable NetworkManager with
48`systemctl stop NetworkManager`.
49
50On the minimal installer, NetworkManager is not available, so
51configuration must be perfomed manually. To configure the wifi, first
52start wpa_supplicant with `sudo systemctl start wpa_supplicant`, then
53run `wpa_cli`. For most home networks, you need to type in the following
54commands:
55
56```plain
57> add_network
580
59> set_network 0 ssid "myhomenetwork"
60OK
61> set_network 0 psk "mypassword"
62OK
63> set_network 0 key_mgmt WPA-PSK
64OK
65> enable_network 0
66OK
67```
68
69For enterprise networks, for example *eduroam*, instead do:
70
71```plain
72> add_network
730
74> set_network 0 ssid "eduroam"
75OK
76> set_network 0 identity "myname@example.com"
77OK
78> set_network 0 password "mypassword"
79OK
80> set_network 0 key_mgmt WPA-EAP
81OK
82> enable_network 0
83OK
84```
85
86When successfully connected, you should see a line such as this one
87
88```plain
89<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=]
90```
91
92you can now leave `wpa_cli` by typing `quit`.
93
94If you would like to continue the installation from a different machine
95you can use activated SSH daemon. You need to copy your ssh key to
96either `/home/nixos/.ssh/authorized_keys` or
97`/root/.ssh/authorized_keys` (Tip: For installers with a modifiable
98filesystem such as the sd-card installer image a key can be manually
99placed by mounting the image on a different machine). Alternatively you
100must set a password for either `root` or `nixos` with `passwd` to be
101able to login.
102
103## Partitioning and formatting {#sec-installation-partitioning}
104
105The NixOS installer doesn't do any partitioning or formatting, so you
106need to do that yourself.
107
108The NixOS installer ships with multiple partitioning tools. The examples
109below use `parted`, but also provides `fdisk`, `gdisk`, `cfdisk`, and
110`cgdisk`.
111
112The recommended partition scheme differs depending if the computer uses
113*Legacy Boot* or *UEFI*.
114
115### UEFI (GPT) {#sec-installation-partitioning-UEFI}
116
117Here\'s an example partition scheme for UEFI, using `/dev/sda` as the
118device.
119
120::: {.note}
121You can safely ignore `parted`\'s informational message about needing to
122update /etc/fstab.
123:::
124
1251. Create a *GPT* partition table.
126
127 ```ShellSession
128 # parted /dev/sda -- mklabel gpt
129 ```
130
1312. Add the *root* partition. This will fill the disk except for the end
132 part, where the swap will live, and the space left in front (512MiB)
133 which will be used by the boot partition.
134
135 ```ShellSession
136 # parted /dev/sda -- mkpart primary 512MiB -8GiB
137 ```
138
1393. Next, add a *swap* partition. The size required will vary according
140 to needs, here a 8GiB one is created.
141
142 ```ShellSession
143 # parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
144 ```
145
146 ::: {.note}
147 The swap partition size rules are no different than for other Linux
148 distributions.
149 :::
150
1514. Finally, the *boot* partition. NixOS by default uses the ESP (EFI
152 system partition) as its */boot* partition. It uses the initially
153 reserved 512MiB at the start of the disk.
154
155 ```ShellSession
156 # parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
157 # parted /dev/sda -- set 3 esp on
158 ```
159
160Once complete, you can follow with
161[](#sec-installation-partitioning-formatting).
162
163### Legacy Boot (MBR) {#sec-installation-partitioning-MBR}
164
165Here\'s an example partition scheme for Legacy Boot, using `/dev/sda` as
166the device.
167
168::: {.note}
169You can safely ignore `parted`\'s informational message about needing to
170update /etc/fstab.
171:::
172
1731. Create a *MBR* partition table.
174
175 ```ShellSession
176 # parted /dev/sda -- mklabel msdos
177 ```
178
1792. Add the *root* partition. This will fill the the disk except for the
180 end part, where the swap will live.
181
182 ```ShellSession
183 # parted /dev/sda -- mkpart primary 1MiB -8GiB
184 ```
185
1863. Finally, add a *swap* partition. The size required will vary
187 according to needs, here a 8GiB one is created.
188
189 ```ShellSession
190 # parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
191 ```
192
193 ::: {.note}
194 The swap partition size rules are no different than for other Linux
195 distributions.
196 :::
197
198Once complete, you can follow with
199[](#sec-installation-partitioning-formatting).
200
201### Formatting {#sec-installation-partitioning-formatting}
202
203Use the following commands:
204
205- For initialising Ext4 partitions: `mkfs.ext4`. It is recommended
206 that you assign a unique symbolic label to the file system using the
207 option `-L label`, since this makes the file system configuration
208 independent from device changes. For example:
209
210 ```ShellSession
211 # mkfs.ext4 -L nixos /dev/sda1
212 ```
213
214- For creating swap partitions: `mkswap`. Again it's recommended to
215 assign a label to the swap partition: `-L label`. For example:
216
217 ```ShellSession
218 # mkswap -L swap /dev/sda2
219 ```
220
221- **UEFI systems**
222
223 For creating boot partitions: `mkfs.fat`. Again it's recommended
224 to assign a label to the boot partition: `-n label`. For
225 example:
226
227 ```ShellSession
228 # mkfs.fat -F 32 -n boot /dev/sda3
229 ```
230
231- For creating LVM volumes, the LVM commands, e.g., `pvcreate`,
232 `vgcreate`, and `lvcreate`.
233
234- For creating software RAID devices, use `mdadm`.
235
236## Installing {#sec-installation-installing}
237
2381. Mount the target file system on which NixOS should be installed on
239 `/mnt`, e.g.
240
241 ```ShellSession
242 # mount /dev/disk/by-label/nixos /mnt
243 ```
244
2452. **UEFI systems**
246
247 Mount the boot file system on `/mnt/boot`, e.g.
248
249 ```ShellSession
250 # mkdir -p /mnt/boot
251 # mount /dev/disk/by-label/boot /mnt/boot
252 ```
253
2543. If your machine has a limited amount of memory, you may want to
255 activate swap devices now (`swapon device`).
256 The installer (or rather, the build actions that it
257 may spawn) may need quite a bit of RAM, depending on your
258 configuration.
259
260 ```ShellSession
261 # swapon /dev/sda2
262 ```
263
2644. You now need to create a file `/mnt/etc/nixos/configuration.nix`
265 that specifies the intended configuration of the system. This is
266 because NixOS has a *declarative* configuration model: you create or
267 edit a description of the desired configuration of your system, and
268 then NixOS takes care of making it happen. The syntax of the NixOS
269 configuration file is described in [](#sec-configuration-syntax),
270 while a list of available configuration options appears in
271 [](#ch-options). A minimal example is shown in
272 [Example: NixOS Configuration](#ex-config).
273
274 The command `nixos-generate-config` can generate an initial
275 configuration file for you:
276
277 ```ShellSession
278 # nixos-generate-config --root /mnt
279 ```
280
281 You should then edit `/mnt/etc/nixos/configuration.nix` to suit your
282 needs:
283
284 ```ShellSession
285 # nano /mnt/etc/nixos/configuration.nix
286 ```
287
288 If you're using the graphical ISO image, other editors may be
289 available (such as `vim`). If you have network access, you can also
290 install other editors -- for instance, you can install Emacs by
291 running `nix-env -f '<nixpkgs>' -iA emacs`.
292
293 BIOS systems
294
295 : You *must* set the option [](#opt-boot.loader.grub.device) to
296 specify on which disk the GRUB boot loader is to be installed.
297 Without it, NixOS cannot boot.
298
299 UEFI systems
300
301 : You *must* set the option [](#opt-boot.loader.systemd-boot.enable)
302 to `true`. `nixos-generate-config` should do this automatically
303 for new configurations when booted in UEFI mode.
304
305 You may want to look at the options starting with
306 [`boot.loader.efi`](#opt-boot.loader.efi.canTouchEfiVariables) and
307 [`boot.loader.systemd-boot`](#opt-boot.loader.systemd-boot.enable)
308 as well.
309
310 If there are other operating systems running on the machine before
311 installing NixOS, the [](#opt-boot.loader.grub.useOSProber)
312 option can be set to `true` to automatically add them to the grub
313 menu.
314
315 If you need to configure networking for your machine the
316 configuration options are described in [](#sec-networking). In
317 particular, while wifi is supported on the installation image, it is
318 not enabled by default in the configuration generated by
319 `nixos-generate-config`.
320
321 Another critical option is `fileSystems`, specifying the file
322 systems that need to be mounted by NixOS. However, you typically
323 don't need to set it yourself, because `nixos-generate-config` sets
324 it automatically in `/mnt/etc/nixos/hardware-configuration.nix` from
325 your currently mounted file systems. (The configuration file
326 `hardware-configuration.nix` is included from `configuration.nix`
327 and will be overwritten by future invocations of
328 `nixos-generate-config`; thus, you generally should not modify it.)
329 Additionally, you may want to look at [Hardware configuration for
330 known-hardware](https://github.com/NixOS/nixos-hardware) at this
331 point or after installation.
332
333 ::: {.note}
334 Depending on your hardware configuration or type of file system, you
335 may need to set the option `boot.initrd.kernelModules` to include
336 the kernel modules that are necessary for mounting the root file
337 system, otherwise the installed system will not be able to boot. (If
338 this happens, boot from the installation media again, mount the
339 target file system on `/mnt`, fix `/mnt/etc/nixos/configuration.nix`
340 and rerun `nixos-install`.) In most cases, `nixos-generate-config`
341 will figure out the required modules.
342 :::
343
3445. Do the installation:
345
346 ```ShellSession
347 # nixos-install
348 ```
349
350 This will install your system based on the configuration you
351 provided. If anything fails due to a configuration problem or any
352 other issue (such as a network outage while downloading binaries
353 from the NixOS binary cache), you can re-run `nixos-install` after
354 fixing your `configuration.nix`.
355
356 As the last step, `nixos-install` will ask you to set the password
357 for the `root` user, e.g.
358
359 ```plain
360 setting root password...
361 New password: ***
362 Retype new password: ***
363 ```
364
365 ::: {.note}
366 For unattended installations, it is possible to use
367 `nixos-install --no-root-passwd` in order to disable the password
368 prompt entirely.
369 :::
370
3716. If everything went well:
372
373 ```ShellSession
374 # reboot
375 ```
376
3777. You should now be able to boot into the installed NixOS. The GRUB
378 boot menu shows a list of *available configurations* (initially just
379 one). Every time you change the NixOS configuration (see [Changing
380 Configuration](#sec-changing-config)), a new item is added to the
381 menu. This allows you to easily roll back to a previous
382 configuration if something goes wrong.
383
384 You should log in and change the `root` password with `passwd`.
385
386 You'll probably want to create some user accounts as well, which can
387 be done with `useradd`:
388
389 ```ShellSession
390 $ useradd -c 'Eelco Dolstra' -m eelco
391 $ passwd eelco
392 ```
393
394 You may also want to install some software. This will be covered in
395 [](#sec-package-management).
396
397## Installation summary {#sec-installation-summary}
398
399To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence)
400shows a typical sequence of commands for installing NixOS on an empty hard
401drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a
402corresponding configuration Nix expression.
403
404::: {#ex-partition-scheme-MBR .example}
405::: {.title}
406**Example: Example partition schemes for NixOS on `/dev/sda` (MBR)**
407:::
408```ShellSession
409# parted /dev/sda -- mklabel msdos
410# parted /dev/sda -- mkpart primary 1MiB -8GiB
411# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
412```
413:::
414
415::: {#ex-partition-scheme-UEFI .example}
416::: {.title}
417**Example: Example partition schemes for NixOS on `/dev/sda` (UEFI)**
418:::
419```ShellSession
420# parted /dev/sda -- mklabel gpt
421# parted /dev/sda -- mkpart primary 512MiB -8GiB
422# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
423# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
424# parted /dev/sda -- set 3 esp on
425```
426:::
427
428::: {#ex-install-sequence .example}
429::: {.title}
430**Example: Commands for Installing NixOS on `/dev/sda`**
431:::
432With a partitioned disk.
433
434```ShellSession
435# mkfs.ext4 -L nixos /dev/sda1
436# mkswap -L swap /dev/sda2
437# swapon /dev/sda2
438# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only)
439# mount /dev/disk/by-label/nixos /mnt
440# mkdir -p /mnt/boot # (for UEFI systems only)
441# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
442# nixos-generate-config --root /mnt
443# nano /mnt/etc/nixos/configuration.nix
444# nixos-install
445# reboot
446```
447:::
448
449::: {#ex-config .example}
450::: {.title}
451**Example: NixOS Configuration**
452:::
453```ShellSession
454{ config, pkgs, ... }: {
455 imports = [
456 # Include the results of the hardware scan.
457 ./hardware-configuration.nix
458 ];
459
460 boot.loader.grub.device = "/dev/sda"; # (for BIOS systems only)
461 boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
462
463 # Note: setting fileSystems is generally not
464 # necessary, since nixos-generate-config figures them out
465 # automatically in hardware-configuration.nix.
466 #fileSystems."/".device = "/dev/disk/by-label/nixos";
467
468 # Enable the OpenSSH server.
469 services.sshd.enable = true;
470}
471```
472:::
473
474## Additional installation notes {#sec-installation-additional-notes}
475
476```{=docbook}
477<xi:include href="installing-usb.section.xml" />
478<xi:include href="installing-pxe.section.xml" />
479<xi:include href="installing-virtualbox-guest.section.xml" />
480<xi:include href="installing-from-other-distro.section.xml" />
481<xi:include href="installing-behind-a-proxy.section.xml" />
482```