pyrox.dev
1<!-- vim: set expandtab ts=2 softtabstop=2 shiftwidth=2 smarttab textwidth=80 wrapmargin=2 -->
2<section
3 xmlns="http://docbook.org/ns/docbook"
4 xmlns:xlink="http://www.w3.org/1999/xlink"
5 xmlns:xi="http://www.w3.org/2001/XInclude"
6 version="5.0"
7 xml:id="sec-installing-from-other-distro">
8 <title>Installing from another Linux distribution</title>
9
10 <para>
11 Because Nix (the package manager) & Nixpkgs (the Nix packages collection)
12 can both be installed on any (most?) Linux distributions, they can be used to
13 install NixOS in various creative ways. You can, for instance:
14 </para>
15
16 <orderedlist>
17 <listitem>
18 <para>
19 Install NixOS on another partition, from your existing Linux distribution
20 (without the use of a USB or optical device!)
21 </para>
22 </listitem>
23 <listitem>
24 <para>
25 Install NixOS on the same partition (in place!), from your existing
26 non-NixOS Linux distribution using <literal>NIXOS_LUSTRATE</literal>.
27 </para>
28 </listitem>
29 <listitem>
30 <para>
31 Install NixOS on your hard drive from the Live CD of any Linux
32 distribution.
33 </para>
34 </listitem>
35 </orderedlist>
36
37 <para>
38 The first steps to all these are the same:
39 </para>
40
41 <orderedlist>
42 <listitem>
43 <para>
44 Install the Nix package manager:
45 </para>
46 <para>
47 Short version:
48 </para>
49<screen>
50$ curl https://nixos.org/nix/install | sh
51$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen>
52 <para>
53 More details in the
54 <link
55 xlink:href="https://nixos.org/nix/manual/#chap-quick-start">
56 Nix manual</link>
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 Switch to the NixOS channel:
62 </para>
63 <para>
64 If you've just installed Nix on a non-NixOS distribution, you will be on
65 the <literal>nixpkgs</literal> channel by default.
66 </para>
67<screen>
68$ nix-channel --list
69nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen>
70 <para>
71 As that channel gets released without running the NixOS tests, it will be
72 safer to use the <literal>nixos-*</literal> channels instead:
73 </para>
74<screen>
75$ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen>
76 <para>
77 You may want to throw in a <literal>nix-channel --update</literal> for good
78 measure.
79 </para>
80 </listitem>
81 <listitem>
82 <para>
83 Install the NixOS installation tools:
84 </para>
85 <para>
86 You'll need <literal>nixos-generate-config</literal> and
87 <literal>nixos-install</literal> and we'll throw in some man pages and
88 <literal>nixos-enter</literal> just in case you want to chroot into your
89 NixOS partition. They are installed by default on NixOS, but you don't have
90 NixOS yet..
91 </para>
92<screen>$ nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen>
93 </listitem>
94 <listitem>
95 <note>
96 <para>
97 The following 5 steps are only for installing NixOS to another partition.
98 For installing NixOS in place using <literal>NIXOS_LUSTRATE</literal>,
99 skip ahead.
100 </para>
101 </note>
102 <para>
103 Prepare your target partition:
104 </para>
105 <para>
106 At this point it is time to prepare your target partition. Please refer to
107 the partitioning, file-system creation, and mounting steps of
108 <xref linkend="sec-installation" />
109 </para>
110 <para>
111 If you're about to install NixOS in place using
112 <literal>NIXOS_LUSTRATE</literal> there is nothing to do for this step.
113 </para>
114 </listitem>
115 <listitem>
116 <para>
117 Generate your NixOS configuration:
118 </para>
119<screen>$ sudo `which nixos-generate-config` --root /mnt</screen>
120 <para>
121 You'll probably want to edit the configuration files. Refer to the
122 <literal>nixos-generate-config</literal> step in
123 <xref
124 linkend="sec-installation" /> for more
125 information.
126 </para>
127 <para>
128 Consider setting up the NixOS bootloader to give you the ability to boot on
129 your existing Linux partition. For instance, if you're using GRUB and your
130 existing distribution is running Ubuntu, you may want to add something like
131 this to your <literal>configuration.nix</literal>:
132 </para>
133<programlisting>
134<xref linkend="opt-boot.loader.grub.extraEntries"/> = ''
135 menuentry "Ubuntu" {
136 search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
137 configfile "($ubuntu)/boot/grub/grub.cfg"
138 }
139'';</programlisting>
140 <para>
141 (You can find the appropriate UUID for your partition in
142 <literal>/dev/disk/by-uuid</literal>)
143 </para>
144 </listitem>
145 <listitem>
146 <para>
147 Create the <literal>nixbld</literal> group and user on your original
148 distribution:
149 </para>
150<screen>
151$ sudo groupadd -g 30000 nixbld
152$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen>
153 </listitem>
154 <listitem>
155 <para>
156 Download/build/install NixOS:
157 </para>
158 <warning>
159 <para>
160 Once you complete this step, you might no longer be able to boot on
161 existing systems without the help of a rescue USB drive or similar.
162 </para>
163 </warning>
164<screen>$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen>
165 <para>
166 Again, please refer to the <literal>nixos-install</literal> step in
167 <xref linkend="sec-installation" /> for more information.
168 </para>
169 <para>
170 That should be it for installation to another partition!
171 </para>
172 </listitem>
173 <listitem>
174 <para>
175 Optionally, you may want to clean up your non-NixOS distribution:
176 </para>
177<screen>
178$ sudo userdel nixbld
179$ sudo groupdel nixbld</screen>
180 <para>
181 If you do not wish to keep the Nix package manager installed either, run
182 something like <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the
183 line that the Nix installer added to your <literal>~/.profile</literal>.
184 </para>
185 </listitem>
186 <listitem>
187 <note>
188 <para>
189 The following steps are only for installing NixOS in place using
190 <literal>NIXOS_LUSTRATE</literal>:
191 </para>
192 </note>
193 <para>
194 Generate your NixOS configuration:
195 </para>
196<screen>$ sudo `which nixos-generate-config` --root /</screen>
197 <para>
198 Note that this will place the generated configuration files in
199 <literal>/etc/nixos</literal>. You'll probably want to edit the
200 configuration files. Refer to the <literal>nixos-generate-config</literal>
201 step in <xref
202 linkend="sec-installation" /> for more
203 information.
204 </para>
205 <para>
206 You'll likely want to set a root password for your first boot using the
207 configuration files because you won't have a chance to enter a password
208 until after you reboot. You can initalize the root password to an empty one
209 with this line: (and of course don't forget to set one once you've rebooted
210 or to lock the account with <literal>sudo passwd -l root</literal> if you
211 use <literal>sudo</literal>)
212 </para>
213<programlisting>
214<link linkend="opt-users.users._name__.initialHashedPassword">users.users.root.initialHashedPassword</link> = "";
215 </programlisting>
216 </listitem>
217 <listitem>
218 <para>
219 Build the NixOS closure and install it in the <literal>system</literal>
220 profile:
221 </para>
222<screen>$ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen>
223 </listitem>
224 <listitem>
225 <para>
226 Change ownership of the <literal>/nix</literal> tree to root (since your
227 Nix install was probably single user):
228 </para>
229<screen>$ sudo chown -R 0.0 /nix</screen>
230 </listitem>
231 <listitem>
232 <para>
233 Set up the <literal>/etc/NIXOS</literal> and
234 <literal>/etc/NIXOS_LUSTRATE</literal> files:
235 </para>
236 <para>
237 <literal>/etc/NIXOS</literal> officializes that this is now a NixOS
238 partition (the bootup scripts require its presence).
239 </para>
240 <para>
241 <literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup scripts to
242 move <emphasis>everything</emphasis> that's in the root partition to
243 <literal>/old-root</literal>. This will move your existing distribution out
244 of the way in the very early stages of the NixOS bootup. There are
245 exceptions (we do need to keep NixOS there after all), so the NixOS
246 lustrate process will not touch:
247 </para>
248 <itemizedlist>
249 <listitem>
250 <para>
251 The <literal>/nix</literal> directory
252 </para>
253 </listitem>
254 <listitem>
255 <para>
256 The <literal>/boot</literal> directory
257 </para>
258 </listitem>
259 <listitem>
260 <para>
261 Any file or directory listed in <literal>/etc/NIXOS_LUSTRATE</literal>
262 (one per line)
263 </para>
264 </listitem>
265 </itemizedlist>
266 <note>
267 <para>
268 Support for <literal>NIXOS_LUSTRATE</literal> was added in NixOS 16.09.
269 The act of "lustrating" refers to the wiping of the existing distribution.
270 Creating <literal>/etc/NIXOS_LUSTRATE</literal> can also be used on NixOS
271 to remove all mutable files from your root partition (anything that's not
272 in <literal>/nix</literal> or <literal>/boot</literal> gets "lustrated" on
273 the next boot.
274 </para>
275 <para>
276 lustrate /ˈlʌstreɪt/ verb.
277 </para>
278 <para>
279 purify by expiatory sacrifice, ceremonial washing, or some other ritual
280 action.
281 </para>
282 </note>
283 <para>
284 Let's create the files:
285 </para>
286<screen>
287$ sudo touch /etc/NIXOS
288$ sudo touch /etc/NIXOS_LUSTRATE
289 </screen>
290 <para>
291 Let's also make sure the NixOS configuration files are kept once we reboot
292 on NixOS:
293 </para>
294<screen>
295$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
296 </screen>
297 </listitem>
298 <listitem>
299 <para>
300 Finally, move the <literal>/boot</literal> directory of your current
301 distribution out of the way (the lustrate process will take care of the
302 rest once you reboot, but this one must be moved out now because NixOS
303 needs to install its own boot files:
304 </para>
305 <warning>
306 <para>
307 Once you complete this step, your current distribution will no longer be
308 bootable! If you didn't get all the NixOS configuration right, especially
309 those settings pertaining to boot loading and root partition, NixOS may
310 not be bootable either. Have a USB rescue device ready in case this
311 happens.
312 </para>
313 </warning>
314<screen>
315$ sudo mv -v /boot /boot.bak &&
316 sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot</screen>
317 <para>
318 Cross your fingers, reboot, hopefully you should get a NixOS prompt!
319 </para>
320 </listitem>
321 <listitem>
322 <para>
323 If for some reason you want to revert to the old distribution, you'll need
324 to boot on a USB rescue disk and do something along these lines:
325 </para>
326<screen>
327# mkdir root
328# mount /dev/sdaX root
329# mkdir root/nixos-root
330# mv -v root/* root/nixos-root/
331# mv -v root/nixos-root/old-root/* root/
332# mv -v root/boot.bak root/boot # We had renamed this by hand earlier
333# umount root
334# reboot</screen>
335 <para>
336 This may work as is or you might also need to reinstall the boot loader
337 </para>
338 <para>
339 And of course, if you're happy with NixOS and no longer need the old
340 distribution:
341 </para>
342<screen>sudo rm -rf /old-root</screen>
343 </listitem>
344 <listitem>
345 <para>
346 It's also worth noting that this whole process can be automated. This is
347 especially useful for Cloud VMs, where provider do not provide NixOS. For
348 instance,
349 <link
350 xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link>
351 uses the lustrate process to convert Digital Ocean droplets to NixOS from
352 other distributions automatically.
353 </para>
354 </listitem>
355 </orderedlist>
356</section>