diff --git a/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml new file mode 100644 index 00000000000..55623898827 --- /dev/null +++ b/nixos/doc/manual/installation/installing-from-other-distro.xml @@ -0,0 +1,297 @@ + +
+ + Installing from another Linux distribution + + + 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: + + + + Install NixOS on another partition, from your existing + Linux distribution (without the use of a USB or optical + device!) + + Install NixOS on the same partition (in place!), from + your existing non-NixOS Linux distribution using + NIXOS_LUSTRATE. + + Install NixOS on your hard drive from the Live CD of + any Linux distribution. + + + The first steps to all these are the same: + + + + Install the Nix package manager: + + Short version: + + +$ bash <(curl https://nixos.org/nix/install) +$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell + + More details in the + Nix manual + + + + Switch to the NixOS channel: + + If you've just installed Nix on a non-NixOS distribution, you + will be on the nixpkgs channel by + default. + + +$ nix-channel --list +nixpkgs https://nixos.org/channels/nixpkgs-unstable + + As that channel gets released without running the NixOS + tests, it will be safer to use the nixos-* + channels instead: + + +$ nix-channel --add https://nixos.org/channels/nixos-version nixpkgs + + You may want to throw in a nix-channel + --update for good measure. + + + + Install the NixOS installation tools: + + You'll need nixos-generate-config and + nixos-install and we'll throw in some man + pages and nixos-enter 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.. + + $ nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]" + + + + The following 5 steps are only for installing NixOS to + another partition. For installing NixOS in place using + NIXOS_LUSTRATE, skip ahead. + + Prepare your target partition: + + At this point it is time to prepare your target partition. + Please refer to the partitioning, file-system creation, and + mounting steps of + + If you're about to install NixOS in place using + NIXOS_LUSTRATE there is nothing to do for + this step. + + + + Generate your NixOS configuration: + + $ sudo `which nixos-generate-config` --root /mnt + + You'll probably want to edit the configuration files. Refer + to the nixos-generate-config step in for more information. + + 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 + configuration.nix: + + +boot.loader.grub.extraEntries = '' + menuentry "Ubuntu" { + search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e + configfile "($ubuntu)/boot/grub/grub.cfg" + } +''; + + (You can find the appropriate UUID for your partition in + /dev/disk/by-uuid) + + + + Create the nixbld group and user on your + original distribution: + + +$ sudo groupadd -g 30000 nixbld +$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld + + + + Download/build/install NixOS: + + 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. + + $ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt + + Again, please refer to the nixos-install + step in for more + information. + + That should be it for installation to another partition! + + + + Optionally, you may want to clean up your non-NixOS distribution: + + +$ sudo userdel nixbld +$ sudo groupdel nixbld + + If you do not wish to keep the Nix package mananager + installed either, run something like sudo rm -rv + ~/.nix-* /nix and remove the line that the Nix + installer added to your ~/.profile. + + + + The following steps are only for installing NixOS in + place using + NIXOS_LUSTRATE: + + Generate your NixOS configuration: + + $ sudo `which nixos-generate-config` --root / + + Note that this will place the generated configuration files + in /etc/nixos. You'll probably want to edit + the configuration files. Refer to the + nixos-generate-config step in for more information. + + 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 sudo passwd -l root if you use + sudo) + + users.extraUsers.root.initialHashedPassword = ""; + + + + Build the NixOS closure and install it in the + system profile: + + $ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system + + + + Change ownership of the /nix tree to root + (since your Nix install was probably single user): + + $ sudo chown -R 0.0 /nix + + + + Set up the /etc/NIXOS and + /etc/NIXOS_LUSTRATE files: + + /etc/NIXOS officializes that this is now a + NixOS partition (the bootup scripts require its presence). + + /etc/NIXOS_LUSTRATE tells the NixOS bootup + scripts to move everything that's in the + root partition to /old-root. 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: + + + The /nix + directory + + The /boot + directory + + Any file or directory listed in + /etc/NIXOS_LUSTRATE (one per + line) + + + Let's create the files: + + +$ sudo touch /etc/NIXOS +$ sudo touch /etc/NIXOS_LUSTRATE + + Let's also make sure the NixOS configuration files are kept + once we reboot on NixOS: + + +$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE + + + + Finally, move the /boot 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: + + 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. + + +$ sudo mv -v /boot /boot.bak && + sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot + + Cross your fingers, reboot, hopefully you should get a NixOS + prompt! + + + 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: + + +# 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 + + This may work as is or you might also need to reinstall the + boot loader + + And of course, if you're happy with NixOS and no longer need + the old distribution: + + sudo rm -rf /old-root + + + + 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, nixos-infect + uses the lustrate process to convert Digital Ocean droplets to + NixOS from other distributions automatically. + + +
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml index 2a5d1fc3ce8..e20b6574b72 100644 --- a/nixos/doc/manual/installation/installing.xml +++ b/nixos/doc/manual/installation/installing.xml @@ -401,5 +401,6 @@ drive (here /dev/sda). +