diff options
Diffstat (limited to 'nixos/doc/manual/installation/installing-from-other-distro.xml')
| -rw-r--r-- | nixos/doc/manual/installation/installing-from-other-distro.xml | 585 |
1 files changed, 314 insertions, 271 deletions
diff --git a/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml index 7e6ddb05cd66..8b0c350b064d 100644 --- a/nixos/doc/manual/installation/installing-from-other-distro.xml +++ b/nixos/doc/manual/installation/installing-from-other-distro.xml @@ -5,284 +5,325 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" 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> - <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> - <listitem> - <para>Install the Nix package manager:</para> - - <para>Short version:</para> - - <screen> + <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> + <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> + <listitem> + <para> + Install the Nix package manager: + </para> + <para> + Short version: + </para> +<screen> $ bash <(curl https://nixos.org/nix/install) $ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen> - - <para>More details in the <link + <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> - - <screen> + 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> +<screen> $ nix-channel --list nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen> - - <para>As that channel gets released without running the NixOS - tests, it will be safer to use the <literal>nixos-*</literal> - channels instead:</para> - - <screen> + <para> + As that channel gets released without running the NixOS tests, it will be + safer to use the <literal>nixos-*</literal> channels instead: + </para> +<screen> $ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen> - - <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> and we'll throw in some man - pages and <literal>nixos-enter</literal> just in case you want - to chroot into your NixOS partition. They are installed by - default on NixOS, but you don't have NixOS yet..</para> - - <screen>$ nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen> - </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> - - <screen>$ sudo `which nixos-generate-config` --root /mnt</screen> - - <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> + <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> and we'll throw in some man pages and + <literal>nixos-enter</literal> just in case you want to chroot into your + NixOS partition. They are installed by default on NixOS, but you don't have + NixOS yet.. + </para> +<screen>$ nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen> + </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> +<screen>$ sudo `which nixos-generate-config` --root /mnt</screen> + <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> <xref linkend="opt-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> - - <screen> + <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> +<screen> $ sudo groupadd -g 30000 nixbld $ sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen> - </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> - - <screen>$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen> - - <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> - - <screen> + </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> +<screen>$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen> + <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> +<screen> $ sudo userdel nixbld $ sudo groupdel nixbld</screen> - - <para>If you do not wish to keep the Nix package mananager - 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> - - <screen>$ sudo `which nixos-generate-config` --root /</screen> - - <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> + <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> +<screen>$ sudo `which nixos-generate-config` --root /</screen> + <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> <link linkend="opt-users.users._name__.initialHashedPassword">users.extraUsers.root.initialHashedPassword</link> = ""; </programlisting> - </listitem> - - <listitem> - <para>Build the NixOS closure and install it in the - <literal>system</literal> profile:</para> - - <screen>$ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen> - </listitem> - - <listitem> - <para>Change ownership of the <literal>/nix</literal> tree to root - (since your Nix install was probably single user):</para> - - <screen>$ sudo chown -R 0.0 /nix</screen> - </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> - - <screen> + </listitem> + <listitem> + <para> + Build the NixOS closure and install it in the <literal>system</literal> + profile: + </para> +<screen>$ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen> + </listitem> + <listitem> + <para> + Change ownership of the <literal>/nix</literal> tree to root (since your + Nix install was probably single user): + </para> +<screen>$ sudo chown -R 0.0 /nix</screen> + </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> +<screen> $ sudo touch /etc/NIXOS $ sudo touch /etc/NIXOS_LUSTRATE </screen> - - <para>Let's also make sure the NixOS configuration files are kept - once we reboot on NixOS:</para> - - <screen> + <para> + Let's also make sure the NixOS configuration files are kept once we reboot + on NixOS: + </para> +<screen> $ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE </screen> - </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> - - <screen> + </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> +<screen> $ sudo mv -v /boot /boot.bak && sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot</screen> - - <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> - - <screen> + <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> +<screen> # mkdir root # mount /dev/sdaX root # mkdir root/nixos-root @@ -291,23 +332,25 @@ $ sudo mv -v /boot /boot.bak && # mv -v root/boot.bak root/boot # We had renamed this by hand earlier # umount root # reboot</screen> - - <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> - - <screen>sudo rm -rf /old-root</screen> - </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 + <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> +<screen>sudo rm -rf /old-root</screen> + </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> + uses the lustrate process to convert Digital Ocean droplets to NixOS from + other distributions automatically. + </para> + </listitem> + </orderedlist> </section> |