diff --git a/nixos/doc/manual/from_md/installation/installing-behind-a-proxy.section.xml b/nixos/doc/manual/from_md/installation/installing-behind-a-proxy.section.xml new file mode 100644 index 000000000000..a551807cd47c --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-behind-a-proxy.section.xml @@ -0,0 +1,41 @@ +
+ Installing behind a proxy + + To install NixOS behind a proxy, do the following before running + nixos-install. + + + + + Update proxy configuration in + /mnt/etc/nixos/configuration.nix to keep the + internet accessible after reboot. + + +networking.proxy.default = "http://user:password@proxy:port/"; +networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; + + + + + Setup the proxy environment variables in the shell where you are + running nixos-install. + + +# proxy_url="http://user:password@proxy:port/" +# export http_proxy="$proxy_url" +# export HTTP_PROXY="$proxy_url" +# export https_proxy="$proxy_url" +# export HTTPS_PROXY="$proxy_url" + + + + + + If you are switching networks with different proxy configurations, + use the specialisation option in + configuration.nix to switch proxies at runtime. + Refer to for more information. + + +
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 000000000000..525531a47813 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml @@ -0,0 +1,388 @@ +
+ 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: + + +$ curl -L https://nixos.org/nix/install | sh +$ . $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, but this also makes some man + pages and nixos-enter available, just in case + you want to chroot into your NixOS partition. NixOS installs + these by default, but you don't have NixOS yet.. + + +$ nix-env -f '<nixpkgs>' -iA nixos-install-tools + + + + + + 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. + + + + + 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 + PATH="$PATH:/usr/sbin:/sbin" in + the following command. + + + +$ 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 manager 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.users.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) + + + + + + Support for NIXOS_LUSTRATE was added in + NixOS 16.09. The act of "lustrating" refers to the + wiping of the existing distribution. Creating + /etc/NIXOS_LUSTRATE can also be used on + NixOS to remove all mutable files from your root partition + (anything that's not in /nix or + /boot gets "lustrated" on the + next boot. + + + lustrate /ˈlʌstreɪt/ verb. + + + purify by expiatory sacrifice, ceremonial washing, or some + other ritual action. + + + + 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/from_md/installation/installing-pxe.section.xml b/nixos/doc/manual/from_md/installation/installing-pxe.section.xml new file mode 100644 index 000000000000..1dd15ddacba8 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-pxe.section.xml @@ -0,0 +1,42 @@ +
+ Booting from the <quote>netboot</quote> media (PXE) + + Advanced users may wish to install NixOS using an existing PXE or + iPXE setup. + + + These instructions assume that you have an existing PXE or iPXE + infrastructure and simply want to add the NixOS installer as another + option. To build the necessary files from a recent version of + nixpkgs, you can run: + + +nix-build -A netboot.x86_64-linux nixos/release.nix + + + This will create a result directory containing: * + bzImage – the Linux kernel * + initrd – the initrd file * + netboot.ipxe – an example ipxe script + demonstrating the appropriate kernel command line arguments for this + image + + + If you’re using plain PXE, configure your boot loader to use the + bzImage and initrd files and + have it provide the same kernel command line arguments found in + netboot.ipxe. + + + If you’re using iPXE, depending on how your HTTP/FTP/etc. server is + configured you may be able to use netboot.ipxe + unmodified, or you may need to update the paths to the files to + match your server’s directory layout. + + + In the future we may begin making these files available as build + products from hydra at which point we will update this documentation + with instructions on how to obtain them either for placing on a + dedicated TFTP server or to boot them directly over the internet. + +
diff --git a/nixos/doc/manual/from_md/installation/installing-usb.section.xml b/nixos/doc/manual/from_md/installation/installing-usb.section.xml new file mode 100644 index 000000000000..b46a1d565557 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-usb.section.xml @@ -0,0 +1,35 @@ +
+ Booting from a USB Drive + + For systems without CD drive, the NixOS live CD can be booted from a + USB stick. You can use the dd utility to write + the image: dd if=path-to-image of=/dev/sdX. Be + careful about specifying the correct drive; you can use the + lsblk command to get a list of block devices. + + + On macOS + +$ diskutil list +[..] +/dev/diskN (external, physical): + #: TYPE NAME SIZE IDENTIFIER +[..] +$ diskutil unmountDisk diskN +Unmount of all volumes on diskN was successful +$ sudo dd if=nix.iso of=/dev/rdiskN + + + Using the 'raw' rdiskN device instead of + diskN completes in minutes instead of hours. + After dd completes, a GUI dialog "The disk + you inserted was not readable by this computer" will pop up, + which can be ignored. + + + + The dd utility will write the image verbatim to + the drive, making it the recommended option for both UEFI and + non-UEFI installations. + +
diff --git a/nixos/doc/manual/from_md/installation/installing-virtualbox-guest.section.xml b/nixos/doc/manual/from_md/installation/installing-virtualbox-guest.section.xml new file mode 100644 index 000000000000..c8bb286c8f33 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-virtualbox-guest.section.xml @@ -0,0 +1,92 @@ +
+ Installing in a VirtualBox guest + + Installing NixOS into a VirtualBox guest is convenient for users who + want to try NixOS without installing it on bare metal. If you want + to use a pre-made VirtualBox appliance, it is available at + the + downloads page. If you want to set up a VirtualBox guest + manually, follow these instructions: + + + + + Add a New Machine in VirtualBox with OS Type "Linux / Other + Linux" + + + + + Base Memory Size: 768 MB or higher. + + + + + New Hard Disk of 8 GB or higher. + + + + + Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) + + + + + Click on Settings / System / Processor and enable PAE/NX + + + + + Click on Settings / System / Acceleration and enable + "VT-x/AMD-V" acceleration + + + + + Click on Settings / Display / Screen and select VMSVGA as + Graphics Controller + + + + + Save the settings, start the virtual machine, and continue + installation like normal + + + + + There are a few modifications you should make in configuration.nix. + Enable booting: + + +boot.loader.grub.device = "/dev/sda"; + + + Also remove the fsck that runs at startup. It will always fail to + run, stopping your boot until you press *. + + +boot.initrd.checkJournalingFS = false; + + + Shared folders can be given a name and a path in the host system in + the VirtualBox settings (Machine / Settings / Shared Folders, then + click on the "Add" icon). Add the following to the + /etc/nixos/configuration.nix to auto-mount them. + If you do not add "nofail", the system + will not boot properly. + + +{ config, pkgs, ...} : +{ + fileSystems."/virtualboxshare" = { + fsType = "vboxsf"; + device = "nameofthesharedfolder"; + options = [ "rw" "nofail" ]; + }; +} + + + The folder will be available directly under the root directory. + +
diff --git a/nixos/doc/manual/installation/installing-behind-a-proxy.section.md b/nixos/doc/manual/installation/installing-behind-a-proxy.section.md new file mode 100644 index 000000000000..aca151531d0f --- /dev/null +++ b/nixos/doc/manual/installation/installing-behind-a-proxy.section.md @@ -0,0 +1,29 @@ +# Installing behind a proxy {#sec-installing-behind-proxy} + +To install NixOS behind a proxy, do the following before running +`nixos-install`. + +1. Update proxy configuration in `/mnt/etc/nixos/configuration.nix` to + keep the internet accessible after reboot. + + ```nix + networking.proxy.default = "http://user:password@proxy:port/"; + networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; + ``` + +1. Setup the proxy environment variables in the shell where you are + running `nixos-install`. + + ```ShellSession + # proxy_url="http://user:password@proxy:port/" + # export http_proxy="$proxy_url" + # export HTTP_PROXY="$proxy_url" + # export https_proxy="$proxy_url" + # export HTTPS_PROXY="$proxy_url" + ``` + +::: {.note} +If you are switching networks with different proxy configurations, use +the `specialisation` option in `configuration.nix` to switch proxies at +runtime. Refer to [](#ch-options) for more information. +::: diff --git a/nixos/doc/manual/installation/installing-behind-a-proxy.xml b/nixos/doc/manual/installation/installing-behind-a-proxy.xml deleted file mode 100644 index 6788882aa8c0..000000000000 --- a/nixos/doc/manual/installation/installing-behind-a-proxy.xml +++ /dev/null @@ -1,48 +0,0 @@ -
- Installing behind a proxy - - - To install NixOS behind a proxy, do the following before running - nixos-install. - - - - - - Update proxy configuration in - /mnt/etc/nixos/configuration.nix to keep the internet - accessible after reboot. - - -networking.proxy.default = "http://user:password@proxy:port/"; -networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; - - - - - Setup the proxy environment variables in the shell where you are running - nixos-install. - - -# proxy_url="http://user:password@proxy:port/" -# export http_proxy="$proxy_url" -# export HTTP_PROXY="$proxy_url" -# export https_proxy="$proxy_url" -# export HTTPS_PROXY="$proxy_url" - - - - - - - If you are switching networks with different proxy configurations, use the - specialisation option in - configuration.nix to switch proxies at runtime. Refer to - for more information. - - -
diff --git a/nixos/doc/manual/installation/installing-from-other-distro.section.md b/nixos/doc/manual/installation/installing-from-other-distro.section.md new file mode 100644 index 000000000000..d9060eb89c37 --- /dev/null +++ b/nixos/doc/manual/installation/installing-from-other-distro.section.md @@ -0,0 +1,279 @@ +# Installing from another Linux distribution {#sec-installing-from-other-distro} + +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: + +1. Install NixOS on another partition, from your existing Linux + distribution (without the use of a USB or optical device!) + +1. Install NixOS on the same partition (in place!), from your existing + non-NixOS Linux distribution using `NIXOS_LUSTRATE`. + +1. Install NixOS on your hard drive from the Live CD of any Linux + distribution. + +The first steps to all these are the same: + +1. Install the Nix package manager: + + Short version: + + ```ShellSession + $ curl -L https://nixos.org/nix/install | sh + $ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell + ``` + + More details in the [ Nix + manual](https://nixos.org/nix/manual/#chap-quick-start) + +1. 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. + + ```ShellSession + $ 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: + + ```ShellSession + $ nix-channel --add https://nixos.org/channels/nixos-version nixpkgs + ``` + + You may want to throw in a `nix-channel --update` for good measure. + +1. Install the NixOS installation tools: + + You\'ll need `nixos-generate-config` and `nixos-install`, but this + also makes some man pages and `nixos-enter` available, just in case + you want to chroot into your NixOS partition. NixOS installs these + by default, but you don\'t have NixOS yet.. + + ```ShellSession + $ nix-env -f '' -iA nixos-install-tools + ``` + +1. ::: {.note} + 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 [](#sec-installation) + + If you\'re about to install NixOS in place using `NIXOS_LUSTRATE` + there is nothing to do for this step. + +1. Generate your NixOS configuration: + + ```ShellSession + $ sudo `which nixos-generate-config` --root /mnt + ``` + + You\'ll probably want to edit the configuration files. Refer to the + `nixos-generate-config` step in [](#sec-installation) 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`: + + ```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`) + +1. Create the `nixbld` group and user on your original distribution: + + ```ShellSession + $ sudo groupadd -g 30000 nixbld + $ sudo useradd -u 30000 -g nixbld -G nixbld nixbld + ``` + +1. Download/build/install NixOS: + + ::: {.warning} + 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. + ::: + + ::: {.note} + 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 `PATH="$PATH:/usr/sbin:/sbin"` in the following command. + ::: + + ```ShellSession + $ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt + ``` + + Again, please refer to the `nixos-install` step in + [](#sec-installation) for more information. + + That should be it for installation to another partition! + +1. Optionally, you may want to clean up your non-NixOS distribution: + + ```ShellSession + $ sudo userdel nixbld + $ sudo groupdel nixbld + ``` + + If you do not wish to keep the Nix package manager installed either, + run something like `sudo rm -rv ~/.nix-* /nix` and remove the line + that the Nix installer added to your `~/.profile`. + +1. ::: {.note} + The following steps are only for installing NixOS in place using + `NIXOS_LUSTRATE`: + ::: + + Generate your NixOS configuration: + + ```ShellSession + $ 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 + [](#sec-installation) 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`) + + ```nix + users.users.root.initialHashedPassword = ""; + ``` + +1. Build the NixOS closure and install it in the `system` profile: + + ```ShellSession + $ nix-env -p /nix/var/nix/profiles/system -f '' -I nixos-config=/etc/nixos/configuration.nix -iA system + ``` + +1. Change ownership of the `/nix` tree to root (since your Nix install + was probably single user): + + ```ShellSession + $ sudo chown -R 0.0 /nix + ``` + +1. 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) + + ::: {.note} + Support for `NIXOS_LUSTRATE` was added in NixOS 16.09. The act of + \"lustrating\" refers to the wiping of the existing distribution. + Creating `/etc/NIXOS_LUSTRATE` can also be used on NixOS to remove + all mutable files from your root partition (anything that\'s not in + `/nix` or `/boot` gets \"lustrated\" on the next boot. + + lustrate /ˈlʌstreɪt/ verb. + + purify by expiatory sacrifice, ceremonial washing, or some other + ritual action. + ::: + + Let\'s create the files: + + ```ShellSession + $ 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: + + ```ShellSession + $ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE + ``` + +1. 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: + + ::: {.warning} + 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. + ::: + + ```ShellSession + $ 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! + +1. 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: + + ```ShellSession + # 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: + + ```ShellSession + sudo rm -rf /old-root + ``` + +1. 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](https://github.com/elitak/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-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml deleted file mode 100644 index 63d1d52b01b2..000000000000 --- a/nixos/doc/manual/installation/installing-from-other-distro.xml +++ /dev/null @@ -1,364 +0,0 @@ - -
- 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: - - -$ curl -L https://nixos.org/nix/install | sh -$ . $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, but this also makes some man pages - and nixos-enter available, just in case you want to chroot into your - NixOS partition. NixOS installs these by default, but you don't have - NixOS yet.. - - $ nix-env -f '<nixpkgs>' -iA nixos-install-tools - - - - - 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: - - - = '' - 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. - - - - - 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 PATH="$PATH:/usr/sbin:/sbin" - in the following command. - - -$ 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 manager 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.users.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) - - - - - - Support for NIXOS_LUSTRATE was added in NixOS 16.09. - The act of "lustrating" refers to the wiping of the existing distribution. - Creating /etc/NIXOS_LUSTRATE can also be used on NixOS - to remove all mutable files from your root partition (anything that's not - in /nix or /boot gets "lustrated" on - the next boot. - - - lustrate /ˈlʌstreɪt/ verb. - - - purify by expiatory sacrifice, ceremonial washing, or some other ritual - action. - - - - 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-pxe.section.md b/nixos/doc/manual/installation/installing-pxe.section.md new file mode 100644 index 000000000000..2016a258251f --- /dev/null +++ b/nixos/doc/manual/installation/installing-pxe.section.md @@ -0,0 +1,32 @@ +# Booting from the "netboot" media (PXE) {#sec-booting-from-pxe} + +Advanced users may wish to install NixOS using an existing PXE or iPXE +setup. + +These instructions assume that you have an existing PXE or iPXE +infrastructure and simply want to add the NixOS installer as another +option. To build the necessary files from a recent version of nixpkgs, +you can run: + +```ShellSession +nix-build -A netboot.x86_64-linux nixos/release.nix +``` + +This will create a `result` directory containing: \* `bzImage` -- the +Linux kernel \* `initrd` -- the initrd file \* `netboot.ipxe` -- an +example ipxe script demonstrating the appropriate kernel command line +arguments for this image + +If you're using plain PXE, configure your boot loader to use the +`bzImage` and `initrd` files and have it provide the same kernel command +line arguments found in `netboot.ipxe`. + +If you're using iPXE, depending on how your HTTP/FTP/etc. server is +configured you may be able to use `netboot.ipxe` unmodified, or you may +need to update the paths to the files to match your server's directory +layout. + +In the future we may begin making these files available as build +products from hydra at which point we will update this documentation +with instructions on how to obtain them either for placing on a +dedicated TFTP server or to boot them directly over the internet. diff --git a/nixos/doc/manual/installation/installing-pxe.xml b/nixos/doc/manual/installation/installing-pxe.xml deleted file mode 100644 index ea88fbdad7e2..000000000000 --- a/nixos/doc/manual/installation/installing-pxe.xml +++ /dev/null @@ -1,50 +0,0 @@ -
- Booting from the <quote>netboot</quote> media (PXE) - - - Advanced users may wish to install NixOS using an existing PXE or iPXE setup. - - - - These instructions assume that you have an existing PXE or iPXE - infrastructure and simply want to add the NixOS installer as another option. - To build the necessary files from a recent version of nixpkgs, you can run: - - - -nix-build -A netboot.x86_64-linux nixos/release.nix - - - - This will create a result directory containing: * - bzImage – the Linux kernel * initrd - – the initrd file * netboot.ipxe – an example ipxe - script demonstrating the appropriate kernel command line arguments for this - image - - - - If you’re using plain PXE, configure your boot loader to use the - bzImage and initrd files and have it - provide the same kernel command line arguments found in - netboot.ipxe. - - - - If you’re using iPXE, depending on how your HTTP/FTP/etc. server is - configured you may be able to use netboot.ipxe unmodified, - or you may need to update the paths to the files to match your server’s - directory layout - - - - In the future we may begin making these files available as build products - from hydra at which point we will update this documentation with instructions - on how to obtain them either for placing on a dedicated TFTP server or to - boot them directly over the internet. - -
diff --git a/nixos/doc/manual/installation/installing-usb.section.md b/nixos/doc/manual/installation/installing-usb.section.md new file mode 100644 index 000000000000..ae58c08e5237 --- /dev/null +++ b/nixos/doc/manual/installation/installing-usb.section.md @@ -0,0 +1,31 @@ +# Booting from a USB Drive {#sec-booting-from-usb} + +For systems without CD drive, the NixOS live CD can be booted from a USB +stick. You can use the `dd` utility to write the image: +`dd if=path-to-image of=/dev/sdX`. Be careful about specifying the correct +drive; you can use the `lsblk` command to get a list of block devices. + +::: {.note} +::: {.title} +On macOS +::: + +```ShellSession +$ diskutil list +[..] +/dev/diskN (external, physical): + #: TYPE NAME SIZE IDENTIFIER +[..] +$ diskutil unmountDisk diskN +Unmount of all volumes on diskN was successful +$ sudo dd if=nix.iso of=/dev/rdiskN +``` + +Using the \'raw\' `rdiskN` device instead of `diskN` completes in +minutes instead of hours. After `dd` completes, a GUI dialog \"The disk +you inserted was not readable by this computer\" will pop up, which can +be ignored. +::: + +The `dd` utility will write the image verbatim to the drive, making it +the recommended option for both UEFI and non-UEFI installations. diff --git a/nixos/doc/manual/installation/installing-usb.xml b/nixos/doc/manual/installation/installing-usb.xml deleted file mode 100644 index 83598635acca..000000000000 --- a/nixos/doc/manual/installation/installing-usb.xml +++ /dev/null @@ -1,40 +0,0 @@ -
- Booting from a USB Drive - - - For systems without CD drive, the NixOS live CD can be booted from a USB - stick. You can use the dd utility to write the image: - dd if=path-to-image - of=/dev/sdX. Be careful about specifying - the correct drive; you can use the lsblk command to get a - list of block devices. - - On macOS - - -$ diskutil list -[..] -/dev/diskN (external, physical): - #: TYPE NAME SIZE IDENTIFIER -[..] -$ diskutil unmountDisk diskN -Unmount of all volumes on diskN was successful -$ sudo dd if=nix.iso of=/dev/rdiskN - - Using the 'raw' rdiskN device instead of - diskN completes in minutes instead of hours. After - dd completes, a GUI dialog "The disk you inserted was - not readable by this computer" will pop up, which can be ignored. - - - - - - The dd utility will write the image verbatim to the drive, - making it the recommended option for both UEFI and non-UEFI installations. - -
diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.section.md b/nixos/doc/manual/installation/installing-virtualbox-guest.section.md new file mode 100644 index 000000000000..e9c2a621c1bb --- /dev/null +++ b/nixos/doc/manual/installation/installing-virtualbox-guest.section.md @@ -0,0 +1,59 @@ +# Installing in a VirtualBox guest {#sec-instaling-virtualbox-guest} + +Installing NixOS into a VirtualBox guest is convenient for users who +want to try NixOS without installing it on bare metal. If you want to +use a pre-made VirtualBox appliance, it is available at [the downloads +page](https://nixos.org/nixos/download.html). If you want to set up a +VirtualBox guest manually, follow these instructions: + +1. Add a New Machine in VirtualBox with OS Type \"Linux / Other Linux\" + +1. Base Memory Size: 768 MB or higher. + +1. New Hard Disk of 8 GB or higher. + +1. Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) + +1. Click on Settings / System / Processor and enable PAE/NX + +1. Click on Settings / System / Acceleration and enable \"VT-x/AMD-V\" + acceleration + +1. Click on Settings / Display / Screen and select VMSVGA as Graphics + Controller + +1. Save the settings, start the virtual machine, and continue + installation like normal + +There are a few modifications you should make in configuration.nix. +Enable booting: + +```nix +boot.loader.grub.device = "/dev/sda"; +``` + +Also remove the fsck that runs at startup. It will always fail to run, +stopping your boot until you press `*`. + +```nix +boot.initrd.checkJournalingFS = false; +``` + +Shared folders can be given a name and a path in the host system in the +VirtualBox settings (Machine / Settings / Shared Folders, then click on +the \"Add\" icon). Add the following to the +`/etc/nixos/configuration.nix` to auto-mount them. If you do not add +`"nofail"`, the system will not boot properly. + +```nix +{ config, pkgs, ...} : +{ + fileSystems."/virtualboxshare" = { + fsType = "vboxsf"; + device = "nameofthesharedfolder"; + options = [ "rw" "nofail" ]; + }; +} +``` + +The folder will be available directly under the root directory. diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.xml b/nixos/doc/manual/installation/installing-virtualbox-guest.xml deleted file mode 100644 index 019e5098a8e2..000000000000 --- a/nixos/doc/manual/installation/installing-virtualbox-guest.xml +++ /dev/null @@ -1,103 +0,0 @@ -
- Installing in a VirtualBox guest - - - Installing NixOS into a VirtualBox guest is convenient for users who want to - try NixOS without installing it on bare metal. If you want to use a pre-made - VirtualBox appliance, it is available at - the downloads - page. If you want to set up a VirtualBox guest manually, follow these - instructions: - - - - - - Add a New Machine in VirtualBox with OS Type "Linux / Other Linux" - - - - - Base Memory Size: 768 MB or higher. - - - - - New Hard Disk of 8 GB or higher. - - - - - Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) - - - - - Click on Settings / System / Processor and enable PAE/NX - - - - - Click on Settings / System / Acceleration and enable "VT-x/AMD-V" - acceleration - - - - - Click on Settings / Display / Screen and select VMSVGA as Graphics Controller - - - - - Save the settings, start the virtual machine, and continue installation - like normal - - - - - - There are a few modifications you should make in configuration.nix. Enable - booting: - - - - = "/dev/sda"; - - - - Also remove the fsck that runs at startup. It will always fail to run, - stopping your boot until you press *. - - - - = false; - - - - Shared folders can be given a name and a path in the host system in the - VirtualBox settings (Machine / Settings / Shared Folders, then click on the - "Add" icon). Add the following to the - /etc/nixos/configuration.nix to auto-mount them. If you do - not add "nofail", the system will not boot properly. - - - -{ config, pkgs, ...} : -{ - fileSystems."/virtualboxshare" = { - fsType = "vboxsf"; - device = "nameofthesharedfolder"; - options = [ "rw" "nofail" ]; - }; -} - - - - The folder will be available directly under the root directory. - -
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml index ff2425e725e8..6eb097f243ab 100644 --- a/nixos/doc/manual/installation/installing.xml +++ b/nixos/doc/manual/installation/installing.xml @@ -603,14 +603,14 @@ Retype new password: ***
Additional installation notes - + - + - + - + - +