diff options
Diffstat (limited to 'nixos/doc/manual/installation.xml')
| -rw-r--r-- | nixos/doc/manual/installation.xml | 570 |
1 files changed, 0 insertions, 570 deletions
diff --git a/nixos/doc/manual/installation.xml b/nixos/doc/manual/installation.xml deleted file mode 100644 index 4cbfcc229fa4..000000000000 --- a/nixos/doc/manual/installation.xml +++ /dev/null @@ -1,570 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="ch-installation"> - -<title>Installing NixOS</title> - - -<!--===============================================================--> - -<section xml:id="sec-obtaining"> - -<title>Obtaining NixOS</title> - -<para>NixOS ISO images can be downloaded from the <link -xlink:href="http://nixos.org/nixos/download.html">NixOS -homepage</link>. These can be burned onto a CD. It is also possible -to copy them onto a USB stick and install NixOS from there. For -details, see the <link -xlink:href="https://nixos.org/wiki/Installing_NixOS_from_a_USB_stick">NixOS -Wiki</link>.</para> - -<para>As an alternative to installing NixOS yourself, you can get a -running NixOS system through several other means: - -<itemizedlist> - <listitem> - <para>Using virtual appliances in Open Virtualization Format (OVF) - that can be imported into VirtualBox. These are available from - the <link xlink:href="http://nixos.org/nixos/download.html">NixOS - homepage</link>.</para> - </listitem> - <listitem> - <para>Using AMIs for Amazon’s EC2. To find one for your region - and instance type, please refer to the <link - xlink:href="https://github.com/NixOS/nixops/blob/master/nix/ec2-amis.nix">list - of most recent AMIs</link>.</para> - </listitem> - <listitem> - <para>Using NixOps, the NixOS-based cloud deployment tool, which - allows you to provision VirtualBox and EC2 NixOS instances from - declarative specifications. Check out the <link - xlink:href="https://github.com/NixOS/nixops">NixOps - homepage</link> for details.</para> - </listitem> -</itemizedlist> - -</para> - -</section> - - -<!--===============================================================--> - -<section xml:id="sec-installation"> - -<title>Installation</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 <xref - linkend="sec-changing-config" />), 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> - -<section xml:id="sec-uefi-installation"> - -<title>UEFI Installation</title> - -<para>NixOS can also be installed on UEFI systems. The procedure -is by and large the same as a BIOS installation, with the following -changes: - -<itemizedlist> - <listitem> - <para>You should boot the live CD in UEFI mode (consult your - specific hardware's documentation for instructions). You may find - the <link - xlink:href="http://www.rodsbooks.com/refind">rEFInd - boot manager</link> useful.</para> - </listitem> - <listitem> - <para>Instead of <command>fdisk</command>, you should use - <command>gdisk</command> to partition your disks. You will need to - have a separate partition for <filename>/boot</filename> with - partition code EF00, and it should be formatted as a - <literal>vfat</literal> filesystem.</para> - </listitem> - <listitem> - <para>You must set <option>boot.loader.gummiboot.enable</option> to - <literal>true</literal>. <command>nixos-generate-config</command> - should do this automatically for new configurations when booted in - UEFI mode.</para> - </listitem> - <listitem> - <para>After having mounted your installation partition to - <code>/mnt</code>, you must mount the <code>boot</code> partition - to <code>/mnt/boot</code>.</para> - </listitem> - <listitem> - <para>You may want to look at the options starting with - <option>boot.loader.efi</option> and <option>boot.loader.gummiboot</option> - as well.</para> - </listitem> - <listitem> - <para>To see console messages during early boot, add <literal>"fbcon"</literal> - to your <option>boot.initrd.kernelModules</option>.</para> - </listitem> -</itemizedlist> -</para> - -</section> - -<section> - -<title xml:id="sec-booting-from-usb">Booting from a USB stick</title> - -<para>For systems without CD drive, the NixOS livecd can be booted from -a usb stick. For non-UEFI installations, -<link xlink:href="http://unetbootin.sourceforge.net/">unetbootin</link> -will work. For UEFI installations, you should mount the ISO, copy its contents -verbatim to your drive, then either: - -<itemizedlist> - <listitem> - <para>Change the label of the disk partition to the label of the ISO - (visible with the blkid command), or</para> - </listitem> - <listitem> - <para>Edit <filename>loader/entries/nixos-livecd.conf</filename> on the drive - and change the <literal>root=</literal> field in the <literal>options</literal> - line to point to your drive (see the documentation on <literal>root=</literal> - in <link xlink:href="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"> - the kernel documentation</link> for more details).</para> - </listitem> -</itemizedlist> -</para> -</section> - -</section> - - -<!--===============================================================--> - -<section xml:id="sec-changing-config"> - -<title>Changing the configuration</title> - -<para>The file <filename>/etc/nixos/configuration.nix</filename> -contains the current configuration of your machine. Whenever you’ve -changed something to that file, you should do - -<screen> -$ nixos-rebuild switch</screen> - -to build the new configuration, make it the default configuration for -booting, and try to realise the configuration in the running system -(e.g., by restarting system services).</para> - -<warning><para>These commands must be executed as root, so you should -either run them from a root shell or by prefixing them with -<literal>sudo -i</literal>.</para></warning> - -<para>You can also do - -<screen> -$ nixos-rebuild test</screen> - -to build the configuration and switch the running system to it, but -without making it the boot default. So if (say) the configuration -locks up your machine, you can just reboot to get back to a working -configuration.</para> - -<para>There is also - -<screen> -$ nixos-rebuild boot</screen> - -to build the configuration and make it the boot default, but not -switch to it now (so it will only take effect after the next -reboot).</para> - -<para>You can make your configuration show up in a different submenu -of the GRUB 2 boot screen by giving it a different <emphasis>profile -name</emphasis>, e.g. - -<screen> -$ nixos-rebuild switch -p test </screen> - -which causes the new configuration (and previous ones created using -<literal>-p test</literal>) to show up in the GRUB submenu “NixOS - -Profile 'test'”. This can be useful to separate test configurations -from “stable” configurations.</para> - -<para>Finally, you can do - -<screen> -$ nixos-rebuild build</screen> - -to build the configuration but nothing more. This is useful to see -whether everything compiles cleanly.</para> - -<para>If you have a machine that supports hardware virtualisation, you -can also test the new configuration in a sandbox by building and -running a QEMU <emphasis>virtual machine</emphasis> that contains the -desired configuration. Just do - -<screen> -$ nixos-rebuild build-vm -$ ./result/bin/run-*-vm -</screen> - -The VM does not have any data from your host system, so your existing -user accounts and home directories will not be available. You can -forward ports on the host to the guest. For instance, the following -will forward host port 2222 to guest port 22 (SSH): - -<screen> -$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm -</screen> - -allowing you to log in via SSH (assuming you have set the appropriate -passwords or SSH authorized keys): - -<screen> -$ ssh -p 2222 localhost -</screen> - -</para> - -</section> - - -<!--===============================================================--> - -<section xml:id="sec-upgrading"> - -<title>Upgrading NixOS</title> - -<para>The best way to keep your NixOS installation up to date is to -use one of the NixOS <emphasis>channels</emphasis>. A channel is a -Nix mechanism for distributing Nix expressions and associated -binaries. The NixOS channels are updated automatically from NixOS’s -Git repository after certain tests have passed and all packages have -been built. These channels are: - -<itemizedlist> - <listitem> - <para>Stable channels, such as <literal - xlink:href="http://nixos.org/channels/nixos-14.04">nixos-14.04</literal>. - These only get conservative bug fixes and package upgrades. For - instance, a channel update may cause the Linux kernel on your - system to be upgraded from 3.4.66 to 3.4.67 (a minor bug fix), but - not from 3.4.<replaceable>x</replaceable> to - 3.11.<replaceable>x</replaceable> (a major change that has the - potential to break things). Stable channels are generally - maintained until the next stable branch is created.</para> - </listitem> - <listitem> - <para>The unstable channel, <literal - xlink:href="http://nixos.org/channels/nixos-unstable">nixos-unstable</literal>. - This corresponds to NixOS’s main development branch, and may thus - see radical changes between channel updates. It’s not recommended - for production systems.</para> - </listitem> -</itemizedlist> - -To see what channels are available, go to <link -xlink:href="http://nixos.org/channels"/>. (Note that the URIs of the -various channels redirect to a directory that contains the channel’s -latest version and includes ISO images and VirtualBox -appliances.)</para> - -<para>When you first install NixOS, you’re automatically subscribed to -the NixOS channel that corresponds to your installation source. For -instance, if you installed from a 14.04 ISO, you will be subscribed to -the <literal>nixos-14.04</literal> channel. To see which NixOS -channel you’re subscribed to, run the following as root: - -<screen> -$ nix-channel --list | grep nixos -nixos https://nixos.org/channels/nixos-unstable -</screen> - -To switch to a different NixOS channel, do - -<screen> -$ nix-channel --add http://nixos.org/channels/<replaceable>channel-name</replaceable> nixos -</screen> - -(Be sure to include the <literal>nixos</literal> parameter at the -end.) For instance, to use the NixOS 14.04 stable channel: - -<screen> -$ nix-channel --add http://nixos.org/channels/nixos-14.04 nixos -</screen> - -But it you want to live on the bleeding edge: - -<screen> -$ nix-channel --add http://nixos.org/channels/nixos-unstable nixos -</screen> - -</para> - -<para>You can then upgrade NixOS to the latest version in your chosen -channel by running - -<screen> -$ nixos-rebuild switch --upgrade -</screen> - -which is equivalent to the more verbose <literal>nix-channel --update -nixos; nixos-rebuild switch</literal>.</para> - -<warning><para>It is generally safe to switch back and forth between -channels. The only exception is that a newer NixOS may also have a -newer Nix version, which may involve an upgrade of Nix’s database -schema. This cannot be undone easily, so in that case you will not be -able to go back to your original channel.</para></warning> - -</section> - -</chapter> |