26417566c4
template for configuration.nix which uses the result of nixos-hardware-scan. svn path=/nixos/trunk/; revision=23926
376 lines
12 KiB
XML
376 lines
12 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||
|
||
<title>Installation</title>
|
||
|
||
|
||
<!--===============================================================-->
|
||
|
||
<section>
|
||
|
||
<title>Building the installation CD</title>
|
||
|
||
<para>Instead of building an installation CD, you could just download
|
||
one from <link xlink:href="http://nixos.org/nixos/"/>. If you want
|
||
(or need) to build it yourself:
|
||
|
||
<orderedlist>
|
||
|
||
<listitem><para>Make sure that you have a <emphasis>very</emphasis>
|
||
recent pre-release version of Nix installed (<link
|
||
xlink:href="http://nixos.org/releases/nix/nix-unstable/"/>).
|
||
The NixOS Nix expressions frequently use bleeding-edge features. If
|
||
you get any kind of expression evaluation error, try to upgrade your
|
||
Nix.</para></listitem>
|
||
|
||
<listitem><para>Optional but strongly recommended (and currently
|
||
<emphasis>required</emphasis> for building the
|
||
<literal>x86_64</literal> ISO): subscribe/pull from the Nixpkgs
|
||
channel to speed up building, i.e.,
|
||
|
||
<screen>
|
||
$ nix-channel --add http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable
|
||
$ nix-channel --update</screen>
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>Check out NixOS from <link
|
||
xlink:href="https://svn.nixos.org/repos/nix/nixos/trunk"/> as
|
||
<literal>nixos</literal>.</para></listitem>
|
||
|
||
<listitem><para>Check out Nixpkgs from
|
||
<link xlink:href="https://svn.nixos.org/repos/nix/nixos/trunk"/> as
|
||
<literal>nixpkgs</literal>.</para></listitem>
|
||
|
||
<listitem><para>Build the ISO image:
|
||
|
||
<screen>
|
||
$ nix-build ./nixos/release.nix -A iso_minimal.iso</screen>
|
||
|
||
If everything goes well, you’ll end up with an ISO image in
|
||
<filename>./result/iso/nixos-<replaceable>version</replaceable>-<replaceable>platform</replaceable>.iso</filename>
|
||
that you can burn onto a CD or attach to a virtual CD-ROM drive in
|
||
your favourite virtual machine software.</para></listitem>
|
||
|
||
</orderedlist>
|
||
|
||
</para>
|
||
|
||
</section>
|
||
|
||
|
||
<!--===============================================================-->
|
||
|
||
<section>
|
||
|
||
<title>Installation</title>
|
||
|
||
<orderedlist>
|
||
|
||
<listitem><para>Boot from the CD.</para></listitem>
|
||
|
||
<listitem><para>The CD contains a basic NixOS installation. (It
|
||
also contain 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
|
||
manually.</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>, empty
|
||
password.</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 Ext2/Ext3 partitions:
|
||
<command>mke2fs</command>. Ext3 is recommended; use the
|
||
<option>-j</option> to create a journalled file system. It is
|
||
also recommended that you assign a unique symbolic label to the
|
||
file system using the option <option>-L
|
||
<replaceable>label</replaceable></option>. This will make the
|
||
file system configuration independent from device
|
||
changes.</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>
|
||
|
||
Possibly you’ll need to do <userinput>initctl start
|
||
lvm</userinput> after this (TODO: check whether this is
|
||
needed).</para></listitem>
|
||
|
||
<listitem><para>For creating software RAID devices:
|
||
<command>mdadm</command>.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>Mount the target file system on
|
||
<filename>/mnt</filename> on which NixOS would be installed.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
|
||
<para>Generate a template configuration for the target system:</para>
|
||
|
||
<para>The command <command>nixos-option</command> can
|
||
generate an initial configuration file for you, i.e.,
|
||
|
||
<screen>
|
||
$ nixos-option --install</screen>
|
||
|
||
It tries to figure out the modules necessary for mounting the root
|
||
device, as well as various other hardware characteristics.
|
||
However, it doesn’t try to figure out the
|
||
<option>fileSystems</option> option yet.</para>
|
||
|
||
<para>Edit <filename>/mnt/etc/nixos/configuration.nix</filename> to
|
||
configure your system. The installation is declarative; you need to
|
||
write a description of the configuration that you want to be built and
|
||
activated. The configuration is specified in a Nix expression and must
|
||
be stored <emphasis>on the target file system</emphasis>. The text
|
||
editors <command>nano</command> and <command>vim</command> are
|
||
available.</para>
|
||
|
||
<para>You need to specify a root file system in
|
||
<option>fileSystems</option> and the target device for the Grub boot
|
||
loader in <option>boot.grubDevice</option>. See
|
||
<xref linkend="ch-options"/> for a list of the available configuration
|
||
options.</para>
|
||
|
||
<note><para>It is very important that you specify in the option
|
||
<option>boot.initrd.kernelModules</option> all 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 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>.)
|
||
<command>nixos-hardware-scan</command> should figure out the
|
||
required modules in most cases.</para></note>
|
||
|
||
<para>Examples are available in
|
||
<filename>/etc/nixos/nixos/doc/config-examples</filename> and some
|
||
actual NixOS configuration can be found at <link
|
||
xlink:href="https://svn.nixos.org/repos/nix/configurations/trunk/"/>.</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>Optionally, you can run
|
||
|
||
<screen>
|
||
$ nixos-checkout</screen>
|
||
|
||
to make the installer use the latest NixOS/Nixpkgs sources from the
|
||
Subversion repository, rather than the sources on CD.</para></listitem>
|
||
|
||
<listitem><para>Do the installation:
|
||
|
||
<screen>
|
||
$ nixos-install</screen>
|
||
|
||
Cross fingers.</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 go back easily 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><xref linkend="ex-install-sequence" /> shows a typical sequence
|
||
of commands for installing NixOS on an empty hard drive (here
|
||
<filename>/dev/sda). <xref linkend="ex-config" /> shows a
|
||
corresponding configuration Nix expression.</filename>
|
||
|
||
</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>
|
||
$ mke2fs -j -L nixos /dev/sda1 <lineannotation>(idem)</lineannotation>
|
||
$ mkswap -L swap /dev/sda2 <lineannotation>(idem)</lineannotation>
|
||
$ mount LABEL=nixos /mnt
|
||
$ nixos-option --install
|
||
$ nano /mnt/etc/nixos/configuration.nix
|
||
<lineannotation>(in particular, set the fileSystems and swapDevices options)</lineannotation>
|
||
$ nixos-install
|
||
$ reboot</screen>
|
||
</example>
|
||
|
||
<example xml:id='ex-config'><title>NixOS configuration</title>
|
||
<screen>
|
||
{
|
||
boot.initrd.kernelModules = [ "ata_piix" ];
|
||
boot.loader.grub.enable = true;
|
||
boot.loader.grub.device = "/dev/sda";
|
||
|
||
fileSystems = [
|
||
{ mountPoint = "/";
|
||
label = "nixos";
|
||
}
|
||
];
|
||
|
||
swapDevices = [
|
||
{ label = "swap"; }
|
||
];
|
||
|
||
services.sshd.enable = true;
|
||
}</screen>
|
||
</example>
|
||
|
||
</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, or to the NixOS/Nixpkgs sources in
|
||
<filename>/etc/nixos/nixos</filename> and
|
||
<filename>/etc/nixos/nixpkgs</filename>, respectively, you should do
|
||
|
||
<screen>
|
||
$ nixos-rebuild switch</screen>
|
||
|
||
to build the new configuration, make it the default configuration for
|
||
booting, and try to effect the configuration in the running system
|
||
(e.g., by restarting system services).</para>
|
||
|
||
<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>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>
|
||
|
||
</section>
|
||
|
||
|
||
|
||
<!--===============================================================-->
|
||
|
||
<section>
|
||
|
||
<title>Keeping NixOS up to date</title>
|
||
|
||
<para>The currently best way to keep your NixOS installation up to
|
||
date is to track the NixOS Subversion repository. The program
|
||
<command>nixos-checkout</command> does that for you. It will
|
||
check if the NixOS/NixPkgs sources are present and if they are under a
|
||
version control system (VCS) before updating them to the latest version. If your
|
||
sources are not under a VCS, then you can rename them before
|
||
running <command>nixos-checkout</command> which will checkout the sources.</para>
|
||
|
||
<para>To build the latest and greatest, do
|
||
|
||
<screen>
|
||
$ nixos-checkout
|
||
$ nixos-rebuild switch</screen>
|
||
|
||
(Or instead of <literal>switch</literal>, use any of the alternatives
|
||
shown in <xref linkend="sec-changing-config"/>.)</para>
|
||
|
||
<para>To customize your VCS or to handle more repositories with
|
||
<command>nixos-checkout</command>, you can have a look at the
|
||
options <option>installer.repos.nixos</option>
|
||
and <option>installer.repos.nixpkgs</option>.</para>
|
||
|
||
</section>
|
||
|
||
|
||
|
||
|
||
</chapter>
|