pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="sec-installation">
6 <title>Installing NixOS</title>
7 <para>
8 NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI
9 installation is by and large the same as a BIOS installation. The differences
10 are mentioned in the steps that follow.
11 </para>
12 <orderedlist>
13 <listitem>
14 <para>
15 Boot from the CD.
16 </para>
17 <variablelist>
18 <varlistentry>
19 <term>
20 UEFI systems
21 </term>
22 <listitem>
23 <para>
24 You should boot the live CD in UEFI mode (consult your specific
25 hardware's documentation for instructions). You may find the
26 <link xlink:href="http://www.rodsbooks.com/refind">rEFInd boot
27 manager</link> useful.
28 </para>
29 </listitem>
30 </varlistentry>
31 </variablelist>
32 </listitem>
33 <listitem>
34 <para>
35 The CD contains a basic NixOS installation. (It also contains Memtest86+,
36 useful if you want to test new hardware). When it’s finished booting, it
37 should have detected most of your hardware.
38 </para>
39 </listitem>
40 <listitem>
41 <para>
42 The NixOS manual is available on virtual console 8 (press Alt+F8 to access)
43 or by running <command>nixos-help</command>.
44 </para>
45 </listitem>
46 <listitem>
47 <para>
48 You get logged in as <literal>root</literal> (with empty password).
49 </para>
50 </listitem>
51 <listitem>
52 <para>
53 If you downloaded the graphical ISO image, you can run <command>systemctl
54 start display-manager</command> to start KDE. If you want to continue on
55 the terminal, you can use <command>loadkeys</command> to switch to your
56 preferred keyboard layout. (We even provide neo2 via <command>loadkeys de
57 neo</command>!)
58 </para>
59 </listitem>
60 <listitem>
61 <para>
62 The boot process should have brought up networking (check <command>ip
63 a</command>). Networking is necessary for the installer, since it will
64 download lots of stuff (such as source tarballs or Nixpkgs channel
65 binaries). It’s best if you have a DHCP server on your network. Otherwise
66 configure networking manually using <command>ifconfig</command>.
67 </para>
68 <para>
69 To manually configure the network on the graphical installer, first disable
70 network-manager with <command>systemctl stop network-manager</command>.
71 </para>
72 <para>
73 To manually configure the wifi on the minimal installer, run
74 <command>wpa_supplicant -B -i interface -c <(wpa_passphrase 'SSID'
75 'key')</command>.
76 </para>
77 </listitem>
78 <listitem>
79 <para>
80 If you would like to continue the installation from a different machine you
81 need to activate the SSH daemon via <literal>systemctl start
82 sshd</literal>. In order to be able to login you also need to set a
83 password for <literal>root</literal> using <literal>passwd</literal>.
84 </para>
85 </listitem>
86 <listitem>
87 <para>
88 The NixOS installer doesn’t do any partitioning or formatting yet, so you
89 need to do that yourself. Use the following commands:
90 <itemizedlist>
91 <listitem>
92 <para>
93 For partitioning: <command>fdisk</command>.
94<screen>
95# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
96-- for UEFI systems only
97> n # <lineannotation>(create a new partition for /boot)</lineannotation>
98> 3 # <lineannotation>(make it a partition number 3)</lineannotation>
99> # <lineannotation>(press enter to accept the default)</lineannotation>
100> +512M # <lineannotation>(the size of the UEFI boot partition)</lineannotation>
101> t # <lineannotation>(change the partition type ...)</lineannotation>
102> 3 # <lineannotation>(... of the boot partition ...)</lineannotation>
103> 1 # <lineannotation>(... to 'UEFI System')</lineannotation>
104-- for BIOS or UEFI systems
105> n # <lineannotation>(create a new partition for /swap)</lineannotation>
106> 2 # <lineannotation>(make it a partition number 2)</lineannotation>
107> # <lineannotation>(press enter to accept the default)</lineannotation>
108> +8G # <lineannotation>(the size of the swap partition, set to whatever you like)</lineannotation>
109> n # <lineannotation>(create a new partition for /)</lineannotation>
110> 1 # <lineannotation>(make it a partition number 1)</lineannotation>
111> # <lineannotation>(press enter to accept the default)</lineannotation>
112> # <lineannotation>(press enter to accept the default and use the rest of the remaining space)</lineannotation>
113> a # <lineannotation>(make the partition bootable)</lineannotation>
114> x # <lineannotation>(enter expert mode)</lineannotation>
115> f # <lineannotation>(fix up the partition ordering)</lineannotation>
116> r # <lineannotation>(exit expert mode)</lineannotation>
117> w # <lineannotation>(write the partition table to disk and exit)</lineannotation></screen>
118 </para>
119 </listitem>
120 <listitem>
121 <para>
122 For initialising Ext4 partitions: <command>mkfs.ext4</command>. It is
123 recommended that you assign a unique symbolic label to the file system
124 using the option <option>-L <replaceable>label</replaceable></option>,
125 since this makes the file system configuration independent from device
126 changes. For example:
127<screen>
128# mkfs.ext4 -L nixos /dev/sda1</screen>
129 </para>
130 </listitem>
131 <listitem>
132 <para>
133 For creating swap partitions: <command>mkswap</command>. Again it’s
134 recommended to assign a label to the swap partition: <option>-L
135 <replaceable>label</replaceable></option>. For example:
136<screen>
137# mkswap -L swap /dev/sda2</screen>
138 </para>
139 </listitem>
140 <listitem>
141 <variablelist>
142 <varlistentry>
143 <term>
144 UEFI systems
145 </term>
146 <listitem>
147 <para>
148 For creating boot partitions: <command>mkfs.fat</command>. Again
149 it’s recommended to assign a label to the boot partition:
150 <option>-n <replaceable>label</replaceable></option>. For example:
151<screen>
152# mkfs.fat -F 32 -n boot /dev/sda3</screen>
153 </para>
154 </listitem>
155 </varlistentry>
156 </variablelist>
157 </listitem>
158 <listitem>
159 <para>
160 For creating LVM volumes, the LVM commands, e.g.,
161 <command>pvcreate</command>, <command>vgcreate</command>, and
162 <command>lvcreate</command>.
163 </para>
164 </listitem>
165 <listitem>
166 <para>
167 For creating software RAID devices, use <command>mdadm</command>.
168 </para>
169 </listitem>
170 </itemizedlist>
171 </para>
172 </listitem>
173 <listitem>
174 <para>
175 Mount the target file system on which NixOS should be installed on
176 <filename>/mnt</filename>, e.g.
177<screen>
178# mount /dev/disk/by-label/nixos /mnt
179</screen>
180 </para>
181 </listitem>
182 <listitem>
183 <variablelist>
184 <varlistentry>
185 <term>
186 UEFI systems
187 </term>
188 <listitem>
189 <para>
190 Mount the boot file system on <filename>/mnt/boot</filename>, e.g.
191<screen>
192# mkdir -p /mnt/boot
193# mount /dev/disk/by-label/boot /mnt/boot
194</screen>
195 </para>
196 </listitem>
197 </varlistentry>
198 </variablelist>
199 </listitem>
200 <listitem>
201 <para>
202 If your machine has a limited amount of memory, you may want to activate
203 swap devices now (<command>swapon
204 <replaceable>device</replaceable></command>). The installer (or rather, the
205 build actions that it may spawn) may need quite a bit of RAM, depending on
206 your configuration.
207<screen>
208# swapon /dev/sda2</screen>
209 </para>
210 </listitem>
211 <listitem>
212 <para>
213 You now need to create a file
214 <filename>/mnt/etc/nixos/configuration.nix</filename> that specifies the
215 intended configuration of the system. This is because NixOS has a
216 <emphasis>declarative</emphasis> configuration model: you create or edit a
217 description of the desired configuration of your system, and then NixOS
218 takes care of making it happen. The syntax of the NixOS configuration file
219 is described in <xref linkend="sec-configuration-syntax"/>, while a list of
220 available configuration options appears in
221 <xref
222 linkend="ch-options"/>. A minimal example is shown in
223 <xref
224 linkend="ex-config"/>.
225 </para>
226 <para>
227 The command <command>nixos-generate-config</command> can generate an
228 initial configuration file for you:
229<screen>
230# nixos-generate-config --root /mnt</screen>
231 You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename>
232 to suit your needs:
233<screen>
234# nano /mnt/etc/nixos/configuration.nix
235</screen>
236 If you’re using the graphical ISO image, other editors may be available
237 (such as <command>vim</command>). If you have network access, you can also
238 install other editors — for instance, you can install Emacs by running
239 <literal>nix-env -i emacs</literal>.
240 </para>
241 <variablelist>
242 <varlistentry>
243 <term>
244 BIOS systems
245 </term>
246 <listitem>
247 <para>
248 You <emphasis>must</emphasis> set the option
249 <xref linkend="opt-boot.loader.grub.device"/> to specify on which disk
250 the GRUB boot loader is to be installed. Without it, NixOS cannot boot.
251 </para>
252 </listitem>
253 </varlistentry>
254 <varlistentry>
255 <term>
256 UEFI systems
257 </term>
258 <listitem>
259 <para>
260 You <emphasis>must</emphasis> set the option
261 <xref linkend="opt-boot.loader.systemd-boot.enable"/> to
262 <literal>true</literal>. <command>nixos-generate-config</command> should
263 do this automatically for new configurations when booted in UEFI mode.
264 </para>
265 <para>
266 You may want to look at the options starting with
267 <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option>
268 and
269 <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd</link></option>
270 as well.
271 </para>
272 </listitem>
273 </varlistentry>
274 </variablelist>
275 <para>
276 If there are other operating systems running on the machine before
277 installing NixOS, the <xref linkend="opt-boot.loader.grub.useOSProber"/>
278 option can be set to <literal>true</literal> to automatically add them to
279 the grub menu.
280 </para>
281 <para>
282 Another critical option is <option>fileSystems</option>, specifying the
283 file systems that need to be mounted by NixOS. However, you typically
284 don’t need to set it yourself, because
285 <command>nixos-generate-config</command> sets it automatically in
286 <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> from your
287 currently mounted file systems. (The configuration file
288 <filename>hardware-configuration.nix</filename> is included from
289 <filename>configuration.nix</filename> and will be overwritten by future
290 invocations of <command>nixos-generate-config</command>; thus, you
291 generally should not modify it.)
292 </para>
293 <note>
294 <para>
295 Depending on your hardware configuration or type of file system, you may
296 need to set the option <option>boot.initrd.kernelModules</option> to
297 include the kernel modules that are necessary for mounting the root file
298 system, otherwise the installed system will not be able to boot. (If this
299 happens, boot from the CD again, mount the target file system on
300 <filename>/mnt</filename>, fix
301 <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun
302 <filename>nixos-install</filename>.) In most cases,
303 <command>nixos-generate-config</command> will figure out the required
304 modules.
305 </para>
306 </note>
307 </listitem>
308 <listitem>
309 <para>
310 Do the installation:
311<screen>
312# nixos-install</screen>
313 Cross fingers. If this fails due to a temporary problem (such as a network
314 issue while downloading binaries from the NixOS binary cache), you can just
315 re-run <command>nixos-install</command>. Otherwise, fix your
316 <filename>configuration.nix</filename> and then re-run
317 <command>nixos-install</command>.
318 </para>
319 <para>
320 As the last step, <command>nixos-install</command> will ask you to set the
321 password for the <literal>root</literal> user, e.g.
322<screen>
323setting root password...
324Enter new UNIX password: ***
325Retype new UNIX password: ***
326 </screen>
327 <note>
328 <para>
329 For unattended installations, it is possible to use
330 <command>nixos-install --no-root-passwd</command>
331 in order to disable the password prompt entirely.
332 </para>
333 </note>
334 </para>
335 </listitem>
336 <listitem>
337 <para>
338 If everything went well:
339<screen>
340 # reboot</screen>
341 </para>
342 </listitem>
343 <listitem>
344 <para>
345 You should now be able to boot into the installed NixOS. The GRUB boot menu
346 shows a list of <emphasis>available configurations</emphasis> (initially
347 just one). Every time you change the NixOS configuration (see
348 <link
349 linkend="sec-changing-config">Changing Configuration</link>
350 ), a new item is added to the menu. This allows you to easily roll back to
351 a previous configuration if something goes wrong.
352 </para>
353 <para>
354 You should log in and change the <literal>root</literal> password with
355 <command>passwd</command>.
356 </para>
357 <para>
358 You’ll probably want to create some user accounts as well, which can be
359 done with <command>useradd</command>:
360<screen>
361$ useradd -c 'Eelco Dolstra' -m eelco
362$ passwd eelco</screen>
363 </para>
364 <para>
365 You may also want to install some software. For instance,
366<screen>
367$ nix-env -qa \*</screen>
368 shows what packages are available, and
369<screen>
370$ nix-env -i w3m</screen>
371 install the <literal>w3m</literal> browser.
372 </para>
373 </listitem>
374 </orderedlist>
375 <para>
376 To summarise, <xref linkend="ex-install-sequence" /> shows a typical sequence
377 of commands for installing NixOS on an empty hard drive (here
378 <filename>/dev/sda</filename>). <xref linkend="ex-config"
379/> shows a
380 corresponding configuration Nix expression.
381 </para>
382 <example xml:id='ex-install-sequence'>
383 <title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>
384<screen>
385# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
386-- for UEFI systems only
387> n # <lineannotation>(create a new partition for /boot)</lineannotation>
388> 3 # <lineannotation>(make it a partition number 3)</lineannotation>
389> # <lineannotation>(press enter to accept the default)</lineannotation>
390> +512M # <lineannotation>(the size of the UEFI boot partition)</lineannotation>
391> t # <lineannotation>(change the partition type ...)</lineannotation>
392> 3 # <lineannotation>(... of the boot partition ...)</lineannotation>
393> 1 # <lineannotation>(... to 'UEFI System')</lineannotation>
394-- for BIOS or UEFI systems
395> n # <lineannotation>(create a new partition for /swap)</lineannotation>
396> 2 # <lineannotation>(make it a partition number 2)</lineannotation>
397> # <lineannotation>(press enter to accept the default)</lineannotation>
398> +8G # <lineannotation>(the size of the swap partition)</lineannotation>
399> n # <lineannotation>(create a new partition for /)</lineannotation>
400> 1 # <lineannotation>(make it a partition number 1)</lineannotation>
401> # <lineannotation>(press enter to accept the default)</lineannotation>
402> # <lineannotation>(press enter to accept the default and use the rest of the remaining space)</lineannotation>
403> a # <lineannotation>(make the partition bootable)</lineannotation>
404> x # <lineannotation>(enter expert mode)</lineannotation>
405> f # <lineannotation>(fix up the partition ordering)</lineannotation>
406> r # <lineannotation>(exit expert mode)</lineannotation>
407> w # <lineannotation>(write the partition table to disk and exit)</lineannotation>
408# mkfs.ext4 -L nixos /dev/sda1
409# mkswap -L swap /dev/sda2
410# swapon /dev/sda2
411# mkfs.fat -F 32 -n boot /dev/sda3 # <lineannotation>(for UEFI systems only)</lineannotation>
412# mount /dev/disk/by-label/nixos /mnt
413# mkdir -p /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation>
414# mount /dev/disk/by-label/boot /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation>
415# nixos-generate-config --root /mnt
416# nano /mnt/etc/nixos/configuration.nix
417# nixos-install
418# reboot</screen>
419 </example>
420 <example xml:id='ex-config'>
421 <title>NixOS Configuration</title>
422<screen>
423{ config, pkgs, ... }: {
424 imports = [
425 # Include the results of the hardware scan.
426 ./hardware-configuration.nix
427 ];
428
429 <xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; # <lineannotation>(for BIOS systems only)</lineannotation>
430 <xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation>
431
432 # Note: setting fileSystems is generally not
433 # necessary, since nixos-generate-config figures them out
434 # automatically in hardware-configuration.nix.
435 #<link linkend="opt-fileSystems._name__.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos";
436
437 # Enable the OpenSSH server.
438 services.sshd.enable = true;
439}
440 </screen>
441 </example>
442 <xi:include href="installing-usb.xml" />
443 <xi:include href="installing-pxe.xml" />
444 <xi:include href="installing-virtualbox-guest.xml" />
445 <xi:include href="installing-from-other-distro.xml" />
446 <xi:include href="installing-behind-a-proxy.xml" />
447</chapter>