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