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<orderedlist>
10
11 <listitem><para>Boot from the CD.</para></listitem>
12
13 <listitem><para>The CD contains a basic NixOS installation. (It
14 also contains Memtest86+, useful if you want to test new hardware).
15 When it’s finished booting, it should have detected most of your
16 hardware.</para></listitem>
17
18 <listitem><para>The NixOS manual is available on virtual console 8
19 (press Alt+F8 to access).</para></listitem>
20
21 <listitem><para>You get logged in as <literal>root</literal>
22 (with empty password).</para></listitem>
23
24 <listitem><para>If you downloaded the graphical ISO image, you can
25 run <command>systemctl start display-manager</command> to start KDE. If you
26 want to continue on the terminal, you can use
27 <command>loadkeys</command> to switch to your preferred keyboard layout.
28 (We even provide neo2 via <command>loadkeys de neo</command>!)</para></listitem>
29
30 <listitem><para>The boot process should have brought up networking (check
31 <command>ip a</command>). Networking is necessary for the
32 installer, since it will download lots of stuff (such as source
33 tarballs or Nixpkgs channel binaries). It’s best if you have a DHCP
34 server on your network. Otherwise configure networking manually
35 using <command>ifconfig</command>.</para>
36 <para>To manually configure the network on the graphical installer,
37 first disable network-manager with
38 <command>systemctl stop network-manager</command>.</para></listitem>
39
40 <listitem><para>The NixOS installer doesn’t do any partitioning or
41 formatting yet, so you need to do that yourself. Use the following
42 commands:
43
44 <itemizedlist>
45
46 <listitem><para>For partitioning:
47 <command>fdisk</command>.</para></listitem>
48
49 <listitem><para>For initialising Ext4 partitions:
50 <command>mkfs.ext4</command>. It is recommended that you assign a
51 unique symbolic label to the file system using the option
52 <option>-L <replaceable>label</replaceable></option>, since this
53 makes the file system configuration independent from device
54 changes. For example:
55
56<screen>
57# mkfs.ext4 -L nixos /dev/sda1</screen>
58
59 </para></listitem>
60
61 <listitem><para>For creating swap partitions:
62 <command>mkswap</command>. Again it’s recommended to assign a
63 label to the swap partition: <option>-L
64 <replaceable>label</replaceable></option>.</para></listitem>
65
66 <listitem><para>For creating LVM volumes, the LVM commands, e.g.,
67
68<screen>
69# pvcreate /dev/sda1 /dev/sdb1
70# vgcreate MyVolGroup /dev/sda1 /dev/sdb1
71# lvcreate --size 2G --name bigdisk MyVolGroup
72# lvcreate --size 1G --name smalldisk MyVolGroup</screen>
73
74 </para></listitem>
75
76 <listitem><para>For creating software RAID devices, use
77 <command>mdadm</command>.</para></listitem>
78
79 </itemizedlist>
80
81 </para></listitem>
82
83 <listitem><para>Mount the target file system on which NixOS should
84 be installed on <filename>/mnt</filename>, e.g.
85
86<screen>
87# mount /dev/disk/by-label/nixos /mnt
88</screen>
89
90 </para></listitem>
91
92 <listitem><para>If your machine has a limited amount of memory, you
93 may want to activate swap devices now (<command>swapon
94 <replaceable>device</replaceable></command>). The installer (or
95 rather, the build actions that it may spawn) may need quite a bit of
96 RAM, depending on your configuration.</para></listitem>
97
98 <listitem>
99
100 <para>You now need to create a file
101 <filename>/mnt/etc/nixos/configuration.nix</filename> that
102 specifies the intended configuration of the system. This is
103 because NixOS has a <emphasis>declarative</emphasis> configuration
104 model: you create or edit a description of the desired
105 configuration of your system, and then NixOS takes care of making
106 it happen. The syntax of the NixOS configuration file is
107 described in <xref linkend="sec-configuration-syntax"/>, while a
108 list of available configuration options appears in <xref
109 linkend="ch-options"/>. A minimal example is shown in <xref
110 linkend="ex-config"/>.</para>
111
112 <para>The command <command>nixos-generate-config</command> can
113 generate an initial configuration file for you:
114
115<screen>
116# nixos-generate-config --root /mnt</screen>
117
118 You should then edit
119 <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your
120 needs:
121
122<screen>
123# nano /mnt/etc/nixos/configuration.nix
124</screen>
125
126 If you’re using the graphical ISO image, other editors may be
127 available (such as <command>vim</command>). If you have network
128 access, you can also install other editors — for instance, you can
129 install Emacs by running <literal>nix-env -i
130 emacs</literal>.</para>
131
132 <para>You <emphasis>must</emphasis> set the option
133 <option>boot.loader.grub.device</option> to specify on which disk
134 the GRUB boot loader is to be installed. Without it, NixOS cannot
135 boot.</para>
136
137 <para>Another critical option is <option>fileSystems</option>,
138 specifying the file systems that need to be mounted by NixOS.
139 However, you typically don’t need to set it yourself, because
140 <command>nixos-generate-config</command> sets it automatically in
141 <filename>/mnt/etc/nixos/hardware-configuration.nix</filename>
142 from your currently mounted file systems. (The configuration file
143 <filename>hardware-configuration.nix</filename> is included from
144 <filename>configuration.nix</filename> and will be overwritten by
145 future invocations of <command>nixos-generate-config</command>;
146 thus, you generally should not modify it.)</para>
147
148 <note><para>Depending on your hardware configuration or type of
149 file system, you may need to set the option
150 <option>boot.initrd.kernelModules</option> to include the kernel
151 modules that are necessary for mounting the root file system,
152 otherwise the installed system will not be able to boot. (If this
153 happens, boot from the CD again, mount the target file system on
154 <filename>/mnt</filename>, fix
155 <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun
156 <filename>nixos-install</filename>.) In most cases,
157 <command>nixos-generate-config</command> will figure out the
158 required modules.</para></note>
159
160 </listitem>
161
162 <listitem><para>Do the installation:
163
164<screen>
165# nixos-install</screen>
166
167 Cross fingers. If this fails due to a temporary problem (such as
168 a network issue while downloading binaries from the NixOS binary
169 cache), you can just re-run <command>nixos-install</command>.
170 Otherwise, fix your <filename>configuration.nix</filename> and
171 then re-run <command>nixos-install</command>.</para>
172
173 <para>As the last step, <command>nixos-install</command> will ask
174 you to set the password for the <literal>root</literal> user, e.g.
175
176<screen>
177setting root password...
178Enter new UNIX password: ***
179Retype new UNIX password: ***
180</screen>
181
182 </para>
183
184 </listitem>
185
186 <listitem><para>If everything went well:
187
188<screen>
189# reboot</screen>
190
191 </para></listitem>
192
193 <listitem>
194
195 <para>You should now be able to boot into the installed NixOS. The
196 GRUB boot menu shows a list of <emphasis>available
197 configurations</emphasis> (initially just one). Every time you
198 change the NixOS configuration (see <link
199 linkend="sec-changing-config">Changing Configuration</link> ), a
200 new item is added to the menu. This allows you to easily roll back
201 to a previous configuration if something goes wrong.</para>
202
203 <para>You should log in and change the <literal>root</literal>
204 password with <command>passwd</command>.</para>
205
206 <para>You’ll probably want to create some user accounts as well,
207 which can be done with <command>useradd</command>:
208
209<screen>
210$ useradd -c 'Eelco Dolstra' -m eelco
211$ passwd eelco</screen>
212
213 </para>
214
215 <para>You may also want to install some software. For instance,
216
217<screen>
218$ nix-env -qa \*</screen>
219
220 shows what packages are available, and
221
222<screen>
223$ nix-env -i w3m</screen>
224
225 install the <literal>w3m</literal> browser.</para>
226
227 </listitem>
228
229</orderedlist>
230
231<para>To summarise, <xref linkend="ex-install-sequence" /> shows a
232typical sequence of commands for installing NixOS on an empty hard
233drive (here <filename>/dev/sda</filename>). <xref linkend="ex-config"
234/> shows a corresponding configuration Nix expression.</para>
235
236<example xml:id='ex-install-sequence'><title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>
237<screen>
238# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
239# mkfs.ext4 -L nixos /dev/sda1
240# mkswap -L swap /dev/sda2
241# swapon /dev/sda2
242# mount /dev/disk/by-label/nixos /mnt
243# nixos-generate-config --root /mnt
244# nano /mnt/etc/nixos/configuration.nix
245# nixos-install
246# reboot</screen>
247</example>
248
249<example xml:id='ex-config'><title>NixOS Configuration</title>
250<screen>
251{ config, pkgs, ... }:
252
253{
254 imports =
255 [ # Include the results of the hardware scan.
256 ./hardware-configuration.nix
257 ];
258
259 boot.loader.grub.device = "/dev/sda";
260
261 # Note: setting fileSystems is generally not
262 # necessary, since nixos-generate-config figures them out
263 # automatically in hardware-configuration.nix.
264 #fileSystems."/".device = "/dev/disk/by-label/nixos";
265
266 # Enable the OpenSSH server.
267 services.sshd.enable = true;
268}</screen>
269</example>
270
271<xi:include href="installing-uefi.xml" />
272<xi:include href="installing-usb.xml" />
273<xi:include href="installing-pxe.xml" />
274<xi:include href="installing-virtualbox-guest.xml" />
275
276</chapter>