diff options
16 files changed, 1033 insertions, 610 deletions
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 0000000000000..a551807cd47c7 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-behind-a-proxy.section.xml @@ -0,0 +1,41 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-installing-behind-proxy"> + <title>Installing behind a proxy</title> + <para> + To install NixOS behind a proxy, do the following before running + <literal>nixos-install</literal>. + </para> + <orderedlist numeration="arabic"> + <listitem> + <para> + Update proxy configuration in + <literal>/mnt/etc/nixos/configuration.nix</literal> to keep the + internet accessible after reboot. + </para> + <programlisting language="bash"> +networking.proxy.default = "http://user:password@proxy:port/"; +networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; +</programlisting> + </listitem> + <listitem> + <para> + Setup the proxy environment variables in the shell where you are + running <literal>nixos-install</literal>. + </para> + <programlisting> +# 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" +</programlisting> + </listitem> + </orderedlist> + <note> + <para> + If you are switching networks with different proxy configurations, + use the <literal>specialisation</literal> option in + <literal>configuration.nix</literal> to switch proxies at runtime. + Refer to <xref linkend="ch-options" /> for more information. + </para> + </note> +</section> 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 0000000000000..525531a478135 --- /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> 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 0000000000000..1dd15ddacba86 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-pxe.section.xml @@ -0,0 +1,42 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-booting-from-pxe"> + <title>Booting from the <quote>netboot</quote> media (PXE)</title> + <para> + Advanced users may wish to install NixOS using an existing PXE or + iPXE setup. + </para> + <para> + 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: + </para> + <programlisting> +nix-build -A netboot.x86_64-linux nixos/release.nix +</programlisting> + <para> + This will create a <literal>result</literal> directory containing: * + <literal>bzImage</literal> – the Linux kernel * + <literal>initrd</literal> – the initrd file * + <literal>netboot.ipxe</literal> – an example ipxe script + demonstrating the appropriate kernel command line arguments for this + image + </para> + <para> + If you’re using plain PXE, configure your boot loader to use the + <literal>bzImage</literal> and <literal>initrd</literal> files and + have it provide the same kernel command line arguments found in + <literal>netboot.ipxe</literal>. + </para> + <para> + If you’re using iPXE, depending on how your HTTP/FTP/etc. server is + configured you may be able to use <literal>netboot.ipxe</literal> + unmodified, or you may need to update the paths to the files to + match your server’s directory layout. + </para> + <para> + 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. + </para> +</section> 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 0000000000000..b46a1d565557d --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-usb.section.xml @@ -0,0 +1,35 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-booting-from-usb"> + <title>Booting from a USB Drive</title> + <para> + For systems without CD drive, the NixOS live CD can be booted from a + USB stick. You can use the <literal>dd</literal> utility to write + the image: <literal>dd if=path-to-image of=/dev/sdX</literal>. Be + careful about specifying the correct drive; you can use the + <literal>lsblk</literal> command to get a list of block devices. + </para> + <note> + <title>On macOS</title> + <programlisting> +$ 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 +</programlisting> + <para> + Using the 'raw' <literal>rdiskN</literal> device instead of + <literal>diskN</literal> completes in minutes instead of hours. + After <literal>dd</literal> completes, a GUI dialog "The disk + you inserted was not readable by this computer" will pop up, + which can be ignored. + </para> + </note> + <para> + The <literal>dd</literal> utility will write the image verbatim to + the drive, making it the recommended option for both UEFI and + non-UEFI installations. + </para> +</section> 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 0000000000000..c8bb286c8f336 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-virtualbox-guest.section.xml @@ -0,0 +1,92 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-instaling-virtualbox-guest"> + <title>Installing in a VirtualBox guest</title> + <para> + 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 + <link xlink:href="https://nixos.org/nixos/download.html">the + downloads page</link>. If you want to set up a VirtualBox guest + manually, follow these instructions: + </para> + <orderedlist numeration="arabic"> + <listitem> + <para> + Add a New Machine in VirtualBox with OS Type "Linux / Other + Linux" + </para> + </listitem> + <listitem> + <para> + Base Memory Size: 768 MB or higher. + </para> + </listitem> + <listitem> + <para> + New Hard Disk of 8 GB or higher. + </para> + </listitem> + <listitem> + <para> + Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) + </para> + </listitem> + <listitem> + <para> + Click on Settings / System / Processor and enable PAE/NX + </para> + </listitem> + <listitem> + <para> + Click on Settings / System / Acceleration and enable + "VT-x/AMD-V" acceleration + </para> + </listitem> + <listitem> + <para> + Click on Settings / Display / Screen and select VMSVGA as + Graphics Controller + </para> + </listitem> + <listitem> + <para> + Save the settings, start the virtual machine, and continue + installation like normal + </para> + </listitem> + </orderedlist> + <para> + There are a few modifications you should make in configuration.nix. + Enable booting: + </para> + <programlisting language="bash"> +boot.loader.grub.device = "/dev/sda"; +</programlisting> + <para> + Also remove the fsck that runs at startup. It will always fail to + run, stopping your boot until you press <literal>*</literal>. + </para> + <programlisting language="bash"> +boot.initrd.checkJournalingFS = false; +</programlisting> + <para> + 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 + <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. + If you do not add <literal>"nofail"</literal>, the system + will not boot properly. + </para> + <programlisting language="bash"> +{ config, pkgs, ...} : +{ + fileSystems."/virtualboxshare" = { + fsType = "vboxsf"; + device = "nameofthesharedfolder"; + options = [ "rw" "nofail" ]; + }; +} +</programlisting> + <para> + The folder will be available directly under the root directory. + </para> +</section> 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 0000000000000..aca151531d0f4 --- /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 6788882aa8c0f..0000000000000 --- a/nixos/doc/manual/installation/installing-behind-a-proxy.xml +++ /dev/null @@ -1,48 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-installing-behind-proxy"> - <title>Installing behind a proxy</title> - - <para> - To install NixOS behind a proxy, do the following before running - <literal>nixos-install</literal>. - </para> - - <orderedlist numeration="arabic"> - <listitem> - <para> - Update proxy configuration in - <literal>/mnt/etc/nixos/configuration.nix</literal> to keep the internet - accessible after reboot. - </para> -<programlisting> -networking.proxy.default = "http://user:password@proxy:port/"; -networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; -</programlisting> - </listitem> - <listitem> - <para> - Setup the proxy environment variables in the shell where you are running - <literal>nixos-install</literal>. - </para> -<screen> -<prompt># </prompt>proxy_url="http://user:password@proxy:port/" -<prompt># </prompt>export http_proxy="$proxy_url" -<prompt># </prompt>export HTTP_PROXY="$proxy_url" -<prompt># </prompt>export https_proxy="$proxy_url" -<prompt># </prompt>export HTTPS_PROXY="$proxy_url" -</screen> - </listitem> - </orderedlist> - - <note> - <para> - If you are switching networks with different proxy configurations, use the - <literal>specialisation</literal> option in - <literal>configuration.nix</literal> to switch proxies at runtime. Refer to - <xref linkend="ch-options" /> for more information. - </para> - </note> -</section> 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 0000000000000..d9060eb89c372 --- /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 '<nixpkgs>' -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 '<nixpkgs/nixos>' -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 63d1d52b01b2f..0000000000000 --- a/nixos/doc/manual/installation/installing-from-other-distro.xml +++ /dev/null @@ -1,364 +0,0 @@ -<!-- vim: set expandtab ts=2 softtabstop=2 shiftwidth=2 smarttab textwidth=80 wrapmargin=2 --> -<section - xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - 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> -<prompt>$ </prompt>curl -L https://nixos.org/nix/install | sh -<prompt>$ </prompt>. $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen> - <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> -<prompt>$ </prompt>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> -<prompt>$ </prompt>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>, 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> - <screen><prompt>$ </prompt>nix-env -f '<nixpkgs>' -iA nixos-install-tools</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><prompt>$ </prompt>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> -<prompt>$ </prompt>sudo groupadd -g 30000 nixbld -<prompt>$ </prompt>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> - <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> -<screen><prompt>$ </prompt>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> -<prompt>$ </prompt>sudo userdel nixbld -<prompt>$ </prompt>sudo groupdel nixbld</screen> - <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><prompt>$ </prompt>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.users.root.initialHashedPassword</link> = ""; -</programlisting> - </listitem> - <listitem> - <para> - Build the NixOS closure and install it in the <literal>system</literal> - profile: - </para> -<screen><prompt>$ </prompt>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><prompt>$ </prompt>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> -<prompt>$ </prompt>sudo touch /etc/NIXOS -<prompt>$ </prompt>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> -<prompt>$ </prompt>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> -<prompt>$ </prompt>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> -<prompt># </prompt>mkdir root -<prompt># </prompt>mount /dev/sdaX root -<prompt># </prompt>mkdir root/nixos-root -<prompt># </prompt>mv -v root/* root/nixos-root/ -<prompt># </prompt>mv -v root/nixos-root/old-root/* root/ -<prompt># </prompt>mv -v root/boot.bak root/boot # We had renamed this by hand earlier -<prompt># </prompt>umount root -<prompt># </prompt>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 - 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> 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 0000000000000..2016a258251f8 --- /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 ea88fbdad7e29..0000000000000 --- a/nixos/doc/manual/installation/installing-pxe.xml +++ /dev/null @@ -1,50 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-booting-from-pxe"> - <title>Booting from the <quote>netboot</quote> media (PXE)</title> - - <para> - Advanced users may wish to install NixOS using an existing PXE or iPXE setup. - </para> - - <para> - 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: - </para> - -<programlisting> -nix-build -A netboot.x86_64-linux nixos/release.nix -</programlisting> - - <para> - This will create a <literal>result</literal> directory containing: * - <literal>bzImage</literal> – the Linux kernel * <literal>initrd</literal> - – the initrd file * <literal>netboot.ipxe</literal> – an example ipxe - script demonstrating the appropriate kernel command line arguments for this - image - </para> - - <para> - If you’re using plain PXE, configure your boot loader to use the - <literal>bzImage</literal> and <literal>initrd</literal> files and have it - provide the same kernel command line arguments found in - <literal>netboot.ipxe</literal>. - </para> - - <para> - If you’re using iPXE, depending on how your HTTP/FTP/etc. server is - configured you may be able to use <literal>netboot.ipxe</literal> unmodified, - or you may need to update the paths to the files to match your server’s - directory layout - </para> - - <para> - 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. - </para> -</section> 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 0000000000000..ae58c08e5237e --- /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 83598635accab..0000000000000 --- a/nixos/doc/manual/installation/installing-usb.xml +++ /dev/null @@ -1,40 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-booting-from-usb"> - <title>Booting from a USB Drive</title> - - <para> - For systems without CD drive, the NixOS live CD can be booted from a USB - stick. You can use the <command>dd</command> utility to write the image: - <command>dd if=<replaceable>path-to-image</replaceable> - of=<replaceable>/dev/sdX</replaceable></command>. Be careful about specifying - the correct drive; you can use the <command>lsblk</command> command to get a - list of block devices. - <note> - <title>On macOS</title> - <para> -<screen> -<prompt>$ </prompt>diskutil list -[..] -/dev/diskN (external, physical): - #: TYPE NAME SIZE IDENTIFIER -[..] -<prompt>$ </prompt>diskutil unmountDisk diskN -Unmount of all volumes on diskN was successful -<prompt>$ </prompt>sudo dd if=nix.iso of=/dev/rdiskN -</screen> - Using the 'raw' <command>rdiskN</command> device instead of - <command>diskN</command> completes in minutes instead of hours. After - <command>dd</command> completes, a GUI dialog "The disk you inserted was - not readable by this computer" will pop up, which can be ignored. - </para> - </note> - </para> - - <para> - The <command>dd</command> utility will write the image verbatim to the drive, - making it the recommended option for both UEFI and non-UEFI installations. - </para> -</section> 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 0000000000000..e9c2a621c1bba --- /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 019e5098a8e27..0000000000000 --- a/nixos/doc/manual/installation/installing-virtualbox-guest.xml +++ /dev/null @@ -1,103 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-instaling-virtualbox-guest"> - <title>Installing in a VirtualBox guest</title> - - <para> - 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 - <link - xlink:href="https://nixos.org/nixos/download.html">the downloads - page</link>. If you want to set up a VirtualBox guest manually, follow these - instructions: - </para> - - <orderedlist> - <listitem> - <para> - Add a New Machine in VirtualBox with OS Type "Linux / Other Linux" - </para> - </listitem> - <listitem> - <para> - Base Memory Size: 768 MB or higher. - </para> - </listitem> - <listitem> - <para> - New Hard Disk of 8 GB or higher. - </para> - </listitem> - <listitem> - <para> - Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) - </para> - </listitem> - <listitem> - <para> - Click on Settings / System / Processor and enable PAE/NX - </para> - </listitem> - <listitem> - <para> - Click on Settings / System / Acceleration and enable "VT-x/AMD-V" - acceleration - </para> - </listitem> - <listitem> - <para> - Click on Settings / Display / Screen and select VMSVGA as Graphics Controller - </para> - </listitem> - <listitem> - <para> - Save the settings, start the virtual machine, and continue installation - like normal - </para> - </listitem> - </orderedlist> - - <para> - There are a few modifications you should make in configuration.nix. Enable - booting: - </para> - -<programlisting> -<xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; -</programlisting> - - <para> - Also remove the fsck that runs at startup. It will always fail to run, - stopping your boot until you press <literal>*</literal>. - </para> - -<programlisting> -<xref linkend="opt-boot.initrd.checkJournalingFS"/> = false; -</programlisting> - - <para> - 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 - <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. If you do - not add <literal>"nofail"</literal>, the system will not boot properly. - </para> - -<programlisting> -{ config, pkgs, ...} : -{ - fileSystems."/virtualboxshare" = { - fsType = "vboxsf"; - device = "nameofthesharedfolder"; - options = [ "rw" "nofail" ]; - }; -} -</programlisting> - - <para> - The folder will be available directly under the root directory. - </para> -</section> diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml index ff2425e725e8c..6eb097f243ab8 100644 --- a/nixos/doc/manual/installation/installing.xml +++ b/nixos/doc/manual/installation/installing.xml @@ -603,14 +603,14 @@ Retype new password: ***</screen> <section xml:id="sec-installation-additional-notes"> <title>Additional installation notes</title> - <xi:include href="installing-usb.xml" /> + <xi:include href="../from_md/installation/installing-usb.section.xml" /> - <xi:include href="installing-pxe.xml" /> + <xi:include href="../from_md/installation/installing-pxe.section.xml" /> - <xi:include href="installing-virtualbox-guest.xml" /> + <xi:include href="../from_md/installation/installing-virtualbox-guest.section.xml" /> - <xi:include href="installing-from-other-distro.xml" /> + <xi:include href="../from_md/installation/installing-from-other-distro.section.xml" /> - <xi:include href="installing-behind-a-proxy.xml" /> + <xi:include href="../from_md/installation/installing-behind-a-proxy.section.xml" /> </section> </chapter> |