diff options
Diffstat (limited to 'nixos/doc/manual/installation/installing.xml')
| -rw-r--r-- | nixos/doc/manual/installation/installing.xml | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml new file mode 100644 index 000000000000..b140c56fbee1 --- /dev/null +++ b/nixos/doc/manual/installation/installing.xml @@ -0,0 +1,264 @@ +<chapter 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-installation"> + +<title>Installing NixOS</title> + +<orderedlist> + + <listitem><para>Boot from the CD.</para></listitem> + + <listitem><para>The CD contains a basic NixOS installation. (It + also contains Memtest86+, useful if you want to test new hardware.) + When it’s finished booting, it should have detected most of your + hardware and brought up networking (check + <command>ifconfig</command>). Networking is necessary for the + installer, since it will download lots of stuff (such as source + tarballs or Nixpkgs channel binaries). It’s best if you have a DHCP + server on your network. Otherwise configure networking manually + using <command>ifconfig</command>.</para></listitem> + + <listitem><para>The NixOS manual is available on virtual console 8 + (press Alt+F8 to access).</para></listitem> + + <listitem><para>Login as <literal>root</literal> and the empty + password.</para></listitem> + + <listitem><para>If you downloaded the graphical ISO image, you can + run <command>start display-manager</command> to start KDE.</para></listitem> + + <listitem><para>The NixOS installer doesn’t do any partitioning or + formatting yet, so you need to that yourself. Use the following + commands: + + <itemizedlist> + + <listitem><para>For partitioning: + <command>fdisk</command>.</para></listitem> + + <listitem><para>For initialising Ext4 partitions: + <command>mkfs.ext4</command>. It is recommended that you assign a + unique symbolic label to the file system using the option + <option>-L <replaceable>label</replaceable></option>, since this + makes the file system configuration independent from device + changes. For example: + +<screen> +$ mkfs.ext4 -L nixos /dev/sda1</screen> + + </para></listitem> + + <listitem><para>For creating swap partitions: + <command>mkswap</command>. Again it’s recommended to assign a + label to the swap partition: <option>-L + <replaceable>label</replaceable></option>.</para></listitem> + + <listitem><para>For creating LVM volumes, the LVM commands, e.g., + +<screen> +$ pvcreate /dev/sda1 /dev/sdb1 +$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1 +$ lvcreate --size 2G --name bigdisk MyVolGroup +$ lvcreate --size 1G --name smalldisk MyVolGroup</screen> + + </para></listitem> + + <listitem><para>For creating software RAID devices, use + <command>mdadm</command>.</para></listitem> + + </itemizedlist> + + </para></listitem> + + <listitem><para>Mount the target file system on which NixOS should + be installed on <filename>/mnt</filename>, e.g. + +<screen> +$ mount /dev/disk/by-label/nixos /mnt +</screen> + + </para></listitem> + + <listitem><para>If your machine has a limited amount of memory, you + may want to activate swap devices now (<command>swapon + <replaceable>device</replaceable></command>). The installer (or + rather, the build actions that it may spawn) may need quite a bit of + RAM, depending on your configuration.</para></listitem> + + <listitem> + + <para>You now need to create a file + <filename>/mnt/etc/nixos/configuration.nix</filename> that + specifies the intended configuration of the system. This is + because NixOS has a <emphasis>declarative</emphasis> configuration + model: you create or edit a description of the desired + configuration of your system, and then NixOS takes care of making + it happen. The syntax of the NixOS configuration file is + described in <xref linkend="sec-configuration-syntax"/>, while a + list of available configuration options appears in <xref + linkend="ch-options"/>. A minimal example is shown in <xref + linkend="ex-config"/>.</para> + + <para>The command <command>nixos-generate-config</command> can + generate an initial configuration file for you: + +<screen> +$ nixos-generate-config --root /mnt</screen> + + You should then edit + <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your + needs: + +<screen> +$ nano /mnt/etc/nixos/configuration.nix +</screen> + + The <command>vim</command> text editor is also available.</para> + + <para>You <emphasis>must</emphasis> set the option + <option>boot.loader.grub.device</option> to specify on which disk + the GRUB boot loader is to be installed. Without it, NixOS cannot + boot.</para> + + <para>Another critical option is <option>fileSystems</option>, + specifying the file systems that need to be mounted by NixOS. + However, you typically don’t need to set it yourself, because + <command>nixos-generate-config</command> sets it automatically in + <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> + from your currently mounted file systems. (The configuration file + <filename>hardware-configuration.nix</filename> is included from + <filename>configuration.nix</filename> and will be overwritten by + future invocations of <command>nixos-generate-config</command>; + thus, you generally should not modify it.)</para> + + <note><para>Depending on your hardware configuration or type of + file system, you may need to set the option + <option>boot.initrd.kernelModules</option> to include the kernel + modules that are necessary for mounting the root file system, + otherwise the installed system will not be able to boot. (If this + happens, boot from the CD again, mount the target file system on + <filename>/mnt</filename>, fix + <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun + <filename>nixos-install</filename>.) In most cases, + <command>nixos-generate-config</command> will figure out the + required modules.</para></note> + + <para>Examples of real-world NixOS configuration files can be + found at <link + xlink:href="https://nixos.org/repos/nix/configurations/trunk/"/>.</para> + + </listitem> + + <listitem><para>Do the installation: + +<screen> +$ nixos-install</screen> + + Cross fingers. If this fails due to a temporary problem (such as + a network issue while downloading binaries from the NixOS binary + cache), you can just re-run <command>nixos-install</command>. + Otherwise, fix your <filename>configuration.nix</filename> and + then re-run <command>nixos-install</command>.</para> + + <para>As the last step, <command>nixos-install</command> will ask + you to set the password for the <literal>root</literal> user, e.g. + +<screen> +setting root password... +Enter new UNIX password: *** +Retype new UNIX password: *** +</screen> + + </para> + + </listitem> + + <listitem><para>If everything went well: + +<screen> +$ reboot</screen> + + </para></listitem> + + <listitem> + + <para>You should now be able to boot into the installed NixOS. The GRUB boot menu shows a list + of <emphasis>available configurations</emphasis> (initially just one). Every time + you change the NixOS configuration (see<link linkend="sec-changing-config">Changing + Configuration</link> ), a new item appears in the menu. This allows you to + easily roll back to another configuration if something goes wrong.</para> + + <para>You should log in and change the <literal>root</literal> + password with <command>passwd</command>.</para> + + <para>You’ll probably want to create some user accounts as well, + which can be done with <command>useradd</command>: + +<screen> +$ useradd -c 'Eelco Dolstra' -m eelco +$ passwd eelco</screen> + + </para> + + <para>You may also want to install some software. For instance, + +<screen> +$ nix-env -qa \*</screen> + + shows what packages are available, and + +<screen> +$ nix-env -i w3m</screen> + + install the <literal>w3m</literal> browser.</para> + + </listitem> + +</orderedlist> + +<para>To summarise, <xref linkend="ex-install-sequence" /> shows a +typical sequence of commands for installing NixOS on an empty hard +drive (here <filename>/dev/sda</filename>). <xref linkend="ex-config" +/> shows a corresponding configuration Nix expression.</para> + +<example xml:id='ex-install-sequence'><title>Commands for Installing NixOS on <filename>/dev/sda</filename></title> +<screen> +$ fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation> +$ mkfs.ext4 -L nixos /dev/sda1 +$ mkswap -L swap /dev/sda2 +$ swapon /dev/sda2 +$ mount /dev/disk/by-label/nixos /mnt +$ nixos-generate-config --root /mnt +$ nano /mnt/etc/nixos/configuration.nix +$ nixos-install +$ reboot</screen> +</example> + +<example xml:id='ex-config'><title>NixOS Configuration</title> +<screen> +{ config, pkgs, ... }: + +{ + imports = + [ # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; + + boot.loader.grub.device = "/dev/sda"; + + # Note: setting fileSystems is generally not + # necessary, since nixos-generate-config figures them out + # automatically in hardware-configuration.nix. + #fileSystems."/".device = "/dev/disk/by-label/nixos"; + + # Enable the OpenSSH server. + services.sshd.enable = true; +}</screen> +</example> + +<xi:include href="installing-uefi.xml" /> +<xi:include href="installing-usb.xml" /> + +</chapter> |