diff options
Diffstat (limited to 'nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml')
| -rw-r--r-- | nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml | 388 |
1 files changed, 388 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml b/nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml new file mode 100644 index 00000000000..525531a4781 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml @@ -0,0 +1,388 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-installing-from-other-distro"> + <title>Installing from another Linux distribution</title> + <para> + Because Nix (the package manager) & Nixpkgs (the Nix packages + collection) can both be installed on any (most?) Linux + distributions, they can be used to install NixOS in various creative + ways. You can, for instance: + </para> + <orderedlist numeration="arabic"> + <listitem> + <para> + Install NixOS on another partition, from your existing Linux + distribution (without the use of a USB or optical device!) + </para> + </listitem> + <listitem> + <para> + Install NixOS on the same partition (in place!), from your + existing non-NixOS Linux distribution using + <literal>NIXOS_LUSTRATE</literal>. + </para> + </listitem> + <listitem> + <para> + Install NixOS on your hard drive from the Live CD of any Linux + distribution. + </para> + </listitem> + </orderedlist> + <para> + The first steps to all these are the same: + </para> + <orderedlist numeration="arabic"> + <listitem> + <para> + Install the Nix package manager: + </para> + <para> + Short version: + </para> + <programlisting> +$ curl -L https://nixos.org/nix/install | sh +$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell +</programlisting> + <para> + More details in the + <link xlink:href="https://nixos.org/nix/manual/#chap-quick-start"> + Nix manual</link> + </para> + </listitem> + <listitem> + <para> + Switch to the NixOS channel: + </para> + <para> + If you've just installed Nix on a non-NixOS distribution, you + will be on the <literal>nixpkgs</literal> channel by default. + </para> + <programlisting> +$ nix-channel --list +nixpkgs https://nixos.org/channels/nixpkgs-unstable +</programlisting> + <para> + As that channel gets released without running the NixOS tests, + it will be safer to use the <literal>nixos-*</literal> channels + instead: + </para> + <programlisting> +$ nix-channel --add https://nixos.org/channels/nixos-version nixpkgs +</programlisting> + <para> + You may want to throw in a + <literal>nix-channel --update</literal> for good measure. + </para> + </listitem> + <listitem> + <para> + Install the NixOS installation tools: + </para> + <para> + You'll need <literal>nixos-generate-config</literal> and + <literal>nixos-install</literal>, but this also makes some man + pages and <literal>nixos-enter</literal> available, just in case + you want to chroot into your NixOS partition. NixOS installs + these by default, but you don't have NixOS yet.. + </para> + <programlisting> +$ nix-env -f '<nixpkgs>' -iA nixos-install-tools +</programlisting> + </listitem> + <listitem> + <note> + <para> + The following 5 steps are only for installing NixOS to another + partition. For installing NixOS in place using + <literal>NIXOS_LUSTRATE</literal>, skip ahead. + </para> + </note> + <para> + Prepare your target partition: + </para> + <para> + At this point it is time to prepare your target partition. + Please refer to the partitioning, file-system creation, and + mounting steps of <xref linkend="sec-installation" /> + </para> + <para> + If you're about to install NixOS in place using + <literal>NIXOS_LUSTRATE</literal> there is nothing to do for + this step. + </para> + </listitem> + <listitem> + <para> + Generate your NixOS configuration: + </para> + <programlisting> +$ sudo `which nixos-generate-config` --root /mnt +</programlisting> + <para> + You'll probably want to edit the configuration files. Refer to + the <literal>nixos-generate-config</literal> step in + <xref linkend="sec-installation" /> for more information. + </para> + <para> + Consider setting up the NixOS bootloader to give you the ability + to boot on your existing Linux partition. For instance, if + you're using GRUB and your existing distribution is running + Ubuntu, you may want to add something like this to your + <literal>configuration.nix</literal>: + </para> + <programlisting language="bash"> +boot.loader.grub.extraEntries = '' + menuentry "Ubuntu" { + search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e + configfile "($ubuntu)/boot/grub/grub.cfg" + } +''; +</programlisting> + <para> + (You can find the appropriate UUID for your partition in + <literal>/dev/disk/by-uuid</literal>) + </para> + </listitem> + <listitem> + <para> + Create the <literal>nixbld</literal> group and user on your + original distribution: + </para> + <programlisting> +$ sudo groupadd -g 30000 nixbld +$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld +</programlisting> + </listitem> + <listitem> + <para> + Download/build/install NixOS: + </para> + <warning> + <para> + Once you complete this step, you might no longer be able to + boot on existing systems without the help of a rescue USB + drive or similar. + </para> + </warning> + <note> + <para> + On some distributions there are separate PATHS for programs + intended only for root. In order for the installation to + succeed, you might have to use + <literal>PATH="$PATH:/usr/sbin:/sbin"</literal> in + the following command. + </para> + </note> + <programlisting> +$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt +</programlisting> + <para> + Again, please refer to the <literal>nixos-install</literal> step + in <xref linkend="sec-installation" /> for more information. + </para> + <para> + That should be it for installation to another partition! + </para> + </listitem> + <listitem> + <para> + Optionally, you may want to clean up your non-NixOS + distribution: + </para> + <programlisting> +$ sudo userdel nixbld +$ sudo groupdel nixbld +</programlisting> + <para> + If you do not wish to keep the Nix package manager installed + either, run something like + <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the line + that the Nix installer added to your + <literal>~/.profile</literal>. + </para> + </listitem> + <listitem> + <note> + <para> + The following steps are only for installing NixOS in place + using <literal>NIXOS_LUSTRATE</literal>: + </para> + </note> + <para> + Generate your NixOS configuration: + </para> + <programlisting> +$ sudo `which nixos-generate-config` --root / +</programlisting> + <para> + Note that this will place the generated configuration files in + <literal>/etc/nixos</literal>. You'll probably want to edit the + configuration files. Refer to the + <literal>nixos-generate-config</literal> step in + <xref linkend="sec-installation" /> for more information. + </para> + <para> + You'll likely want to set a root password for your first boot + using the configuration files because you won't have a chance to + enter a password until after you reboot. You can initalize the + root password to an empty one with this line: (and of course + don't forget to set one once you've rebooted or to lock the + account with <literal>sudo passwd -l root</literal> if you use + <literal>sudo</literal>) + </para> + <programlisting language="bash"> +users.users.root.initialHashedPassword = ""; +</programlisting> + </listitem> + <listitem> + <para> + Build the NixOS closure and install it in the + <literal>system</literal> profile: + </para> + <programlisting> +$ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system +</programlisting> + </listitem> + <listitem> + <para> + Change ownership of the <literal>/nix</literal> tree to root + (since your Nix install was probably single user): + </para> + <programlisting> +$ sudo chown -R 0.0 /nix +</programlisting> + </listitem> + <listitem> + <para> + Set up the <literal>/etc/NIXOS</literal> and + <literal>/etc/NIXOS_LUSTRATE</literal> files: + </para> + <para> + <literal>/etc/NIXOS</literal> officializes that this is now a + NixOS partition (the bootup scripts require its presence). + </para> + <para> + <literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup + scripts to move <emphasis>everything</emphasis> that's in the + root partition to <literal>/old-root</literal>. This will move + your existing distribution out of the way in the very early + stages of the NixOS bootup. There are exceptions (we do need to + keep NixOS there after all), so the NixOS lustrate process will + not touch: + </para> + <itemizedlist> + <listitem> + <para> + The <literal>/nix</literal> directory + </para> + </listitem> + <listitem> + <para> + The <literal>/boot</literal> directory + </para> + </listitem> + <listitem> + <para> + Any file or directory listed in + <literal>/etc/NIXOS_LUSTRATE</literal> (one per line) + </para> + </listitem> + </itemizedlist> + <note> + <para> + Support for <literal>NIXOS_LUSTRATE</literal> was added in + NixOS 16.09. The act of "lustrating" refers to the + wiping of the existing distribution. Creating + <literal>/etc/NIXOS_LUSTRATE</literal> can also be used on + NixOS to remove all mutable files from your root partition + (anything that's not in <literal>/nix</literal> or + <literal>/boot</literal> gets "lustrated" on the + next boot. + </para> + <para> + lustrate /ˈlʌstreɪt/ verb. + </para> + <para> + purify by expiatory sacrifice, ceremonial washing, or some + other ritual action. + </para> + </note> + <para> + Let's create the files: + </para> + <programlisting> +$ sudo touch /etc/NIXOS +$ sudo touch /etc/NIXOS_LUSTRATE +</programlisting> + <para> + Let's also make sure the NixOS configuration files are kept once + we reboot on NixOS: + </para> + <programlisting> +$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE +</programlisting> + </listitem> + <listitem> + <para> + Finally, move the <literal>/boot</literal> directory of your + current distribution out of the way (the lustrate process will + take care of the rest once you reboot, but this one must be + moved out now because NixOS needs to install its own boot files: + </para> + <warning> + <para> + Once you complete this step, your current distribution will no + longer be bootable! If you didn't get all the NixOS + configuration right, especially those settings pertaining to + boot loading and root partition, NixOS may not be bootable + either. Have a USB rescue device ready in case this happens. + </para> + </warning> + <programlisting> +$ sudo mv -v /boot /boot.bak && +sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot +</programlisting> + <para> + Cross your fingers, reboot, hopefully you should get a NixOS + prompt! + </para> + </listitem> + <listitem> + <para> + If for some reason you want to revert to the old distribution, + you'll need to boot on a USB rescue disk and do something along + these lines: + </para> + <programlisting> +# mkdir root +# mount /dev/sdaX root +# mkdir root/nixos-root +# mv -v root/* root/nixos-root/ +# mv -v root/nixos-root/old-root/* root/ +# mv -v root/boot.bak root/boot # We had renamed this by hand earlier +# umount root +# reboot +</programlisting> + <para> + This may work as is or you might also need to reinstall the boot + loader. + </para> + <para> + And of course, if you're happy with NixOS and no longer need the + old distribution: + </para> + <programlisting> +sudo rm -rf /old-root +</programlisting> + </listitem> + <listitem> + <para> + It's also worth noting that this whole process can be automated. + This is especially useful for Cloud VMs, where provider do not + provide NixOS. For instance, + <link xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link> + uses the lustrate process to convert Digital Ocean droplets to + NixOS from other distributions automatically. + </para> + </listitem> + </orderedlist> +</section> |