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