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