alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

Merge pull request #137082 from bobby285271/markdown

Browse source 
nixos/doc: Convert more articles to CommonMark
This commit is contained in:
Jörg Thalheim 2021-09-12 04:51:20 +01:00 committed by GitHub
parent 22eb660417 7fb52b1325
commit fc4247e827
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
37 changed files with 1988 additions and 1114 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
nixos/doc/manual/administration/containers.chapter.md Normal file
View file

@ -0,0 +1,28 @@
# Container Management {#ch-containers}
NixOS allows you to easily run other NixOS instances as *containers*.
Containers are a light-weight approach to virtualisation that runs
software in the container at the same speed as in the host system. NixOS
containers share the Nix store of the host, making container creation
very efficient.
::: {.warning}
Currently, NixOS containers are not perfectly isolated from the host
system. This means that a user with root access to the container can do
things that affect the host. So you should not give container root
access to untrusted users.
:::
NixOS containers can be created in two ways: imperatively, using the
command `nixos-container`, and declaratively, by specifying them in your
`configuration.nix`. The declarative approach implies that containers
get upgraded along with your host system when you run `nixos-rebuild`,
which is often not what you want. By contrast, in the imperative
approach, containers are configured and updated independently from the
host system.
```{=docbook}
<xi:include href="imperative-containers.section.xml" />
<xi:include href="declarative-containers.section.xml" />
<xi:include href="container-networking.section.xml" />
```

34
nixos/doc/manual/administration/containers.xml
View file

@ -1,34 +0,0 @@
<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="ch-containers">
<title>Container Management</title>
<para>
NixOS allows you to easily run other NixOS instances as
<emphasis>containers</emphasis>. Containers are a light-weight approach to
virtualisation that runs software in the container at the same speed as in
the host system. NixOS containers share the Nix store of the host, making
container creation very efficient.
</para>
<warning>
<para>
Currently, NixOS containers are not perfectly isolated from the host system.
This means that a user with root access to the container can do things that
affect the host. So you should not give container root access to untrusted
users.
</para>
</warning>
<para>
NixOS containers can be created in two ways: imperatively, using the command
<command>nixos-container</command>, and declaratively, by specifying them in
your <filename>configuration.nix</filename>. The declarative approach implies
that containers get upgraded along with your host system when you run
<command>nixos-rebuild</command>, which is often not what you want. By
contrast, in the imperative approach, containers are configured and updated
independently from the host system.
</para>
<xi:include href="../from_md/administration/imperative-containers.section.xml" />
<xi:include href="../from_md/administration/declarative-containers.section.xml" />
<xi:include href="../from_md/administration/container-networking.section.xml" />
</chapter>

4
nixos/doc/manual/administration/running.xml
View file

@ -16,6 +16,6 @@
<xi:include href="../from_md/administration/control-groups.chapter.xml" />
<xi:include href="../from_md/administration/logging.chapter.xml" />
<xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
<xi:include href="containers.xml" />
<xi:include href="troubleshooting.xml" />
<xi:include href="../from_md/administration/containers.chapter.xml" />
<xi:include href="../from_md/administration/troubleshooting.chapter.xml" />
</part>

12
nixos/doc/manual/administration/troubleshooting.chapter.md Normal file
View file

@ -0,0 +1,12 @@
# Troubleshooting {#ch-troubleshooting}
This chapter describes solutions to common problems you might encounter
when you manage your NixOS system.
```{=docbook}
<xi:include href="boot-problems.section.xml" />
<xi:include href="maintenance-mode.section.xml" />
<xi:include href="rollback.section.xml" />
<xi:include href="store-corruption.section.xml" />
<xi:include href="network-problems.section.xml" />
```

16
nixos/doc/manual/administration/troubleshooting.xml
View file

@ -1,16 +0,0 @@
<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="ch-troubleshooting">
<title>Troubleshooting</title>
<para>
This chapter describes solutions to common problems you might encounter when
you manage your NixOS system.
</para>
<xi:include href="../from_md/administration/boot-problems.section.xml" />
<xi:include href="../from_md/administration/maintenance-mode.section.xml" />
<xi:include href="../from_md/administration/rollback.section.xml" />
<xi:include href="../from_md/administration/store-corruption.section.xml" />
<xi:include href="../from_md/administration/network-problems.section.xml" />
</chapter>

19
nixos/doc/manual/configuration/config-syntax.chapter.md Normal file
View file

@ -0,0 +1,19 @@
# Configuration Syntax {#sec-configuration-syntax}
The NixOS configuration file `/etc/nixos/configuration.nix` is actually
a *Nix expression*, which is the Nix package manager's purely functional
language for describing how to build packages and configurations. This
means you have all the expressive power of that language at your
disposal, including the ability to abstract over common patterns, which
is very useful when managing complex systems. The syntax and semantics
of the Nix language are fully described in the [Nix
manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions), but
here we give a short overview of the most important constructs useful in
NixOS configuration files.
```{=docbook}
<xi:include href="config-file.section.xml" />
<xi:include href="abstractions.section.xml" />
<xi:include href="modularity.section.xml" />
<xi:include href="summary.section.xml" />
```

25
nixos/doc/manual/configuration/config-syntax.xml
View file

@ -1,25 +0,0 @@
<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-configuration-syntax">
<title>Configuration Syntax</title>
<para>
The NixOS configuration file
<filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix
expression</emphasis>, which is the Nix package manager’s purely functional
language for describing how to build packages and configurations. This means
you have all the expressive power of that language at your disposal,
including the ability to abstract over common patterns, which is very useful
when managing complex systems. The syntax and semantics of the Nix language
are fully described in the
<link
xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
manual</link>, but here we give a short overview of the most important
constructs useful in NixOS configuration files.
</para>
<xi:include href="../from_md/configuration/config-file.section.xml" />
<xi:include href="../from_md/configuration/abstractions.section.xml" />
<xi:include href="../from_md/configuration/modularity.section.xml" />
<xi:include href="../from_md/configuration/summary.section.xml" />
</chapter>

10
nixos/doc/manual/configuration/configuration.xml
View file

@ -13,19 +13,19 @@
effect after you run <command>nixos-rebuild</command>.
</para>
</partintro>
<xi:include href="config-syntax.xml" />
<xi:include href="package-mgmt.xml" />
<xi:include href="../from_md/configuration/config-syntax.chapter.xml" />
<xi:include href="../from_md/configuration/package-mgmt.chapter.xml" />
<xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />
<xi:include href="file-systems.xml" />
<xi:include href="../from_md/configuration/file-systems.chapter.xml" />
<xi:include href="../from_md/configuration/x-windows.chapter.xml" />
<xi:include href="../from_md/configuration/wayland.chapter.xml" />
<xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />
<xi:include href="../from_md/configuration/xfce.chapter.xml" />
<xi:include href="networking.xml" />
<xi:include href="../from_md/configuration/networking.chapter.xml" />
<xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
<xi:include href="../from_md/configuration/subversion.chapter.xml" />
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
<xi:include href="profiles.xml" />
<xi:include href="../from_md/configuration/profiles.chapter.xml" />
<xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
<!-- Apache; libvirtd virtualisation -->
</part>

46
nixos/doc/manual/configuration/declarative-packages.section.md Normal file
View file

@ -0,0 +1,46 @@
# Declarative Package Management {#sec-declarative-package-mgmt}
With declarative package management, you specify which packages you want
on your system by setting the option
[](#opt-environment.systemPackages). For instance, adding the
following line to `configuration.nix` enables the Mozilla Thunderbird
email application:
```nix
environment.systemPackages = [ pkgs.thunderbird ];
```
The effect of this specification is that the Thunderbird package from
Nixpkgs will be built or downloaded as part of the system when you run
`nixos-rebuild switch`.
::: {.note}
Some packages require additional global configuration such as D-Bus or
systemd service registration so adding them to
[](#opt-environment.systemPackages) might not be sufficient. You are
advised to check the [list of options](#ch-options) whether a NixOS
module for the package does not exist.
:::
You can get a list of the available packages as follows:
```ShellSession
$ nix-env -qaP '*' --description
nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
...
```
The first column in the output is the *attribute name*, such as
`nixos.thunderbird`.
Note: the `nixos` prefix tells us that we want to get the package from
the `nixos` channel and works only in CLI tools. In declarative
configuration use `pkgs` prefix (variable).
To "uninstall" a package, simply remove it from
[](#opt-environment.systemPackages) and run `nixos-rebuild switch`.
```{=docbook}
<xi:include href="customizing-packages.section.xml" />
<xi:include href="adding-custom-packages.section.xml" />
```

54
nixos/doc/manual/configuration/declarative-packages.xml
View file

@ -1,54 +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-declarative-package-mgmt">
<title>Declarative Package Management</title>
<para>
With declarative package management, you specify which packages you want on
your system by setting the option
<xref linkend="opt-environment.systemPackages"/>. For instance, adding the
following line to <filename>configuration.nix</filename> enables the Mozilla
Thunderbird email application:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
</programlisting>
The effect of this specification is that the Thunderbird package from Nixpkgs
will be built or downloaded as part of the system when you run
<command>nixos-rebuild switch</command>.
</para>
<note>
<para>
Some packages require additional global configuration such as D-Bus or systemd service registration so adding them to <xref linkend="opt-environment.systemPackages"/> might not be sufficient. You are advised to check the <link xlink:href="#ch-options">list of options</link> whether a NixOS module for the package does not exist.
</para>
</note>
<para>
You can get a list of the available packages as follows:
<screen>
<prompt>$ </prompt>nix-env -qaP '*' --description
nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
<replaceable>...</replaceable>
</screen>
The first column in the output is the <emphasis>attribute name</emphasis>,
such as <literal>nixos.thunderbird</literal>.
</para>
<para>
Note: the <literal>nixos</literal> prefix tells us that we want to get the
package from the <literal>nixos</literal> channel and works only in CLI tools.
In declarative configuration use <literal>pkgs</literal> prefix (variable).
</para>
<para>
To “uninstall” a package, simply remove it from
<xref linkend="opt-environment.systemPackages"/> and run
<command>nixos-rebuild switch</command>.
</para>
<xi:include href="../from_md/configuration/customizing-packages.section.xml" />
<xi:include href="../from_md/configuration/adding-custom-packages.section.xml" />
</section>

42
nixos/doc/manual/configuration/file-systems.chapter.md Normal file
View file

@ -0,0 +1,42 @@
# File Systems {#ch-file-systems}
You can define file systems using the `fileSystems` configuration
option. For instance, the following definition causes NixOS to mount the
Ext4 file system on device `/dev/disk/by-label/data` onto the mount
point `/data`:
```nix
fileSystems."/data" =
{ device = "/dev/disk/by-label/data";
fsType = "ext4";
};
```
This will create an entry in `/etc/fstab`, which will generate a
corresponding [systemd.mount](https://www.freedesktop.org/software/systemd/man/systemd.mount.html)
unit via [systemd-fstab-generator](https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html).
The filesystem will be mounted automatically unless `"noauto"` is
present in [options](#opt-fileSystems._name_.options). `"noauto"`
filesystems can be mounted explicitly using `systemctl` e.g.
`systemctl start data.mount`. Mount points are created automatically if they don't
already exist. For `device`, it's best to use the topology-independent
device aliases in `/dev/disk/by-label` and `/dev/disk/by-uuid`, as these
don't change if the topology changes (e.g. if a disk is moved to another
IDE controller).
You can usually omit the file system type (`fsType`), since `mount` can
usually detect the type and load the necessary kernel module
automatically. However, if the file system is needed at early boot (in
the initial ramdisk) and is not `ext2`, `ext3` or `ext4`, then it's best
to specify `fsType` to ensure that the kernel module is available.
::: {.note}
System startup will fail if any of the filesystems fails to mount,
dropping you to the emergency shell. You can make a mount asynchronous
and non-critical by adding `options = [ "nofail" ];`.
:::
```{=docbook}
<xi:include href="luks-file-systems.section.xml" />
<xi:include href="sshfs-file-systems.section.xml" />
```

58
nixos/doc/manual/configuration/file-systems.xml
View file

@ -1,58 +0,0 @@
<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="ch-file-systems">
<title>File Systems</title>
<para>
You can define file systems using the <option>fileSystems</option>
configuration option. For instance, the following definition causes NixOS to
mount the Ext4 file system on device
<filename>/dev/disk/by-label/data</filename> onto the mount point
<filename>/data</filename>:
<programlisting>
<xref linkend="opt-fileSystems"/>."/data" =
{ device = "/dev/disk/by-label/data";
fsType = "ext4";
};
</programlisting>
This will create an entry in <filename>/etc/fstab</filename>, which will
generate a corresponding
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.mount.html">systemd.mount</link>
unit via
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html">systemd-fstab-generator</link>.
The filesystem will be mounted automatically unless
<literal>"noauto"</literal> is present in <link
linkend="opt-fileSystems._name_.options">options</link>.
<literal>"noauto"</literal> filesystems can be mounted explicitly using
<command>systemctl</command> e.g. <command>systemctl start
data.mount</command>.
Mount points are created automatically if they don’t already exist. For
<option><link linkend="opt-fileSystems._name_.device">device</link></option>,
it’s best to use the topology-independent device aliases in
<filename>/dev/disk/by-label</filename> and
<filename>/dev/disk/by-uuid</filename>, as these don’t change if the
topology changes (e.g. if a disk is moved to another IDE controller).
</para>
<para>
You can usually omit the file system type
(<option><link linkend="opt-fileSystems._name_.fsType">fsType</link></option>),
since <command>mount</command> can usually detect the type and load the
necessary kernel module automatically. However, if the file system is needed
at early boot (in the initial ramdisk) and is not <literal>ext2</literal>,
<literal>ext3</literal> or <literal>ext4</literal>, then it’s best to
specify <option>fsType</option> to ensure that the kernel module is
available.
</para>
<note>
<para>
System startup will fail if any of the filesystems fails to mount, dropping
you to the emergency shell. You can make a mount asynchronous and
non-critical by adding
<literal><link linkend="opt-fileSystems._name_.options">options</link> = [
"nofail" ];</literal>.
</para>
</note>
<xi:include href="../from_md/configuration/luks-file-systems.section.xml" />
<xi:include href="../from_md/configuration/sshfs-file-systems.section.xml" />
</chapter>

16
nixos/doc/manual/configuration/networking.chapter.md Normal file
View file

@ -0,0 +1,16 @@
# Networking {#sec-networking}
This section describes how to configure networking components
on your NixOS machine.
```{=docbook}
<xi:include href="network-manager.section.xml" />
<xi:include href="ssh.section.xml" />
<xi:include href="ipv4-config.section.xml" />
<xi:include href="ipv6-config.section.xml" />
<xi:include href="firewall.section.xml" />
<xi:include href="wireless.section.xml" />
<xi:include href="ad-hoc-network-config.section.xml" />
<xi:include href="renaming-interfaces.section.xml" />
```
<!-- TODO: OpenVPN, NAT -->

20
nixos/doc/manual/configuration/networking.xml
View file

@ -1,20 +0,0 @@
<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-networking">
<title>Networking</title>
<para>
This section describes how to configure networking components on your NixOS
machine.
</para>
<xi:include href="../from_md/configuration/network-manager.section.xml" />
<xi:include href="../from_md/configuration/ssh.section.xml" />
<xi:include href="../from_md/configuration/ipv4-config.section.xml" />
<xi:include href="../from_md/configuration/ipv6-config.section.xml" />
<xi:include href="../from_md/configuration/firewall.section.xml" />
<xi:include href="../from_md/configuration/wireless.section.xml" />
<xi:include href="../from_md/configuration/ad-hoc-network-config.section.xml" />
<xi:include href="../from_md/configuration/renaming-interfaces.section.xml" />
<!-- TODO: OpenVPN, NAT -->
</chapter>

18
nixos/doc/manual/configuration/package-mgmt.chapter.md Normal file
View file

@ -0,0 +1,18 @@
# Package Management {#sec-package-management}
This section describes how to add additional packages to your system.
NixOS has two distinct styles of package management:
- *Declarative*, where you declare what packages you want in your
`configuration.nix`. Every time you run `nixos-rebuild`, NixOS will
ensure that you get a consistent set of binaries corresponding to
your specification.
- *Ad hoc*, where you install, upgrade and uninstall packages via the
`nix-env` command. This style allows mixing packages from different
Nixpkgs versions. It's the only choice for non-root users.
```{=docbook}
<xi:include href="declarative-packages.section.xml" />
<xi:include href="ad-hoc-packages.section.xml" />
```

31
nixos/doc/manual/configuration/package-mgmt.xml
View file

@ -1,31 +0,0 @@
<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-package-management">
<title>Package Management</title>
<para>
This section describes how to add additional packages to your system. NixOS
has two distinct styles of package management:
<itemizedlist>
<listitem>
<para>
<emphasis>Declarative</emphasis>, where you declare what packages you want
in your <filename>configuration.nix</filename>. Every time you run
<command>nixos-rebuild</command>, NixOS will ensure that you get a
consistent set of binaries corresponding to your specification.
</para>
</listitem>
<listitem>
<para>
<emphasis>Ad hoc</emphasis>, where you install, upgrade and uninstall
packages via the <command>nix-env</command> command. This style allows
mixing packages from different Nixpkgs versions. It’s the only choice
for non-root users.
</para>
</listitem>
</itemizedlist>
</para>
<xi:include href="declarative-packages.xml" />
<xi:include href="../from_md/configuration/ad-hoc-packages.section.xml" />
</chapter>

34
nixos/doc/manual/configuration/profiles.chapter.md Normal file
View file

@ -0,0 +1,34 @@
# Profiles {#ch-profiles}
In some cases, it may be desirable to take advantage of commonly-used,
predefined configurations provided by nixpkgs, but different from those
that come as default. This is a role fulfilled by NixOS\'s Profiles,
which come as files living in `<nixpkgs/nixos/modules/profiles>`. That
is to say, expected usage is to add them to the imports list of your
`/etc/configuration.nix` as such:
```nix
imports = [
<nixpkgs/nixos/modules/profiles/profile-name.nix>
];
```
Even if some of these profiles seem only useful in the context of
install media, many are actually intended to be used in real installs.
What follows is a brief explanation on the purpose and use-case for each
profile. Detailing each option configured by each one is out of scope.
```{=docbook}
<xi:include href="profiles/all-hardware.section.xml" />
<xi:include href="profiles/base.section.xml" />
<xi:include href="profiles/clone-config.section.xml" />
<xi:include href="profiles/demo.section.xml" />
<xi:include href="profiles/docker-container.section.xml" />
<xi:include href="profiles/graphical.section.xml" />
<xi:include href="profiles/hardened.section.xml" />
<xi:include href="profiles/headless.section.xml" />
<xi:include href="profiles/installation-device.section.xml" />
<xi:include href="profiles/minimal.section.xml" />
<xi:include href="profiles/qemu-guest.section.xml" />
```

39
nixos/doc/manual/configuration/profiles.xml
View file

@ -1,39 +0,0 @@
<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="ch-profiles">
<title>Profiles</title>
<para>
In some cases, it may be desirable to take advantage of commonly-used,
predefined configurations provided by nixpkgs, but different from those that
come as default. This is a role fulfilled by NixOS's Profiles, which come as
files living in <filename>&lt;nixpkgs/nixos/modules/profiles&gt;</filename>.
That is to say, expected usage is to add them to the imports list of your
<filename>/etc/configuration.nix</filename> as such:
</para>
<programlisting>
imports = [
&lt;nixpkgs/nixos/modules/profiles/profile-name.nix&gt;
];
</programlisting>
<para>
Even if some of these profiles seem only useful in the context of install
media, many are actually intended to be used in real installs.
</para>
<para>
What follows is a brief explanation on the purpose and use-case for each
profile. Detailing each option configured by each one is out of scope.
</para>
<xi:include href="../from_md/configuration/profiles/all-hardware.section.xml" />
<xi:include href="../from_md/configuration/profiles/base.section.xml" />
<xi:include href="../from_md/configuration/profiles/clone-config.section.xml" />
<xi:include href="../from_md/configuration/profiles/demo.section.xml" />
<xi:include href="../from_md/configuration/profiles/docker-container.section.xml" />
<xi:include href="../from_md/configuration/profiles/graphical.section.xml" />
<xi:include href="../from_md/configuration/profiles/hardened.section.xml" />
<xi:include href="../from_md/configuration/profiles/headless.section.xml" />
<xi:include href="../from_md/configuration/profiles/installation-device.section.xml" />
<xi:include href="../from_md/configuration/profiles/minimal.section.xml" />
<xi:include href="../from_md/configuration/profiles/qemu-guest.section.xml" />
</chapter>

4
nixos/doc/manual/development/development.xml
View file

@ -10,10 +10,10 @@
</para>
</partintro>
<xi:include href="../from_md/development/sources.chapter.xml" />
<xi:include href="writing-modules.xml" />
<xi:include href="../from_md/development/writing-modules.chapter.xml" />
<xi:include href="../from_md/development/building-parts.chapter.xml" />
<xi:include href="../from_md/development/writing-documentation.chapter.xml" />
<xi:include href="../from_md/development/building-nixos.chapter.xml" />
<xi:include href="nixos-tests.xml" />
<xi:include href="../from_md/development/nixos-tests.chapter.xml" />
<xi:include href="../from_md/development/testing-installer.chapter.xml" />
</part>

13
nixos/doc/manual/development/nixos-tests.chapter.md Normal file
View file

@ -0,0 +1,13 @@
# NixOS Tests {#sec-nixos-tests}
When you add some feature to NixOS, you should write a test for it.
NixOS tests are kept in the directory `nixos/tests`, and are executed
(using Nix) by a testing framework that automatically starts one or more
virtual machines containing the NixOS system(s) required for the test.
```{=docbook}
<xi:include href="writing-nixos-tests.section.xml" />
<xi:include href="running-nixos-tests.section.xml" />
<xi:include href="running-nixos-tests-interactively.section.xml" />
<xi:include href="linking-nixos-tests-to-packages.section.xml" />
```

20
nixos/doc/manual/development/nixos-tests.xml
View file

@ -1,20 +0,0 @@
<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-nixos-tests">
<title>NixOS Tests</title>
<para>
When you add some feature to NixOS, you should write a test for it. NixOS
tests are kept in the directory
<filename
xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>,
and are executed (using Nix) by a testing framework that automatically starts
one or more virtual machines containing the NixOS system(s) required for the
test.
</para>
<xi:include href="../from_md/development/writing-nixos-tests.section.xml" />
<xi:include href="../from_md/development/running-nixos-tests.section.xml" />
<xi:include href="../from_md/development/running-nixos-tests-interactively.section.xml" />
<xi:include href="../from_md/development/linking-nixos-tests-to-packages.section.xml" />
</chapter>

166
nixos/doc/manual/development/writing-modules.chapter.md Normal file
View file

@ -0,0 +1,166 @@
# Writing NixOS Modules {#sec-writing-modules}
NixOS has a modular system for declarative configuration. This system
combines multiple *modules* to produce the full system configuration.
One of the modules that constitute the configuration is
`/etc/nixos/configuration.nix`. Most of the others live in the
[`nixos/modules`](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules)
subdirectory of the Nixpkgs tree.
Each NixOS module is a file that handles one logical aspect of the
configuration, such as a specific kind of hardware, a service, or
network settings. A module configuration does not have to handle
everything from scratch; it can use the functionality provided by other
modules for its implementation. Thus a module can *declare* options that
can be used by other modules, and conversely can *define* options
provided by other modules in its own implementation. For example, the
module
[`pam.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix)
declares the option `security.pam.services` that allows other modules (e.g.
[`sshd.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix))
to define PAM services; and it defines the option `environment.etc` (declared by
[`etc.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix))
to cause files to be created in `/etc/pam.d`.
In [](#sec-configuration-syntax), we saw the following structure of
NixOS modules:
```nix
{ config, pkgs, ... }:
{ option definitions
}
```
This is actually an *abbreviated* form of module that only defines
options, but does not declare any. The structure of full NixOS modules
is shown in [Example: Structure of NixOS Modules](#ex-module-syntax).
::: {#ex-module-syntax .example}
::: {.title}
**Example: Structure of NixOS Modules**
:::
```nix
{ config, pkgs, ... }:
{
imports =
[ paths of other modules
];
options = {
option declarations
};
config = {
option definitions
};
}
```
:::
The meaning of each part is as follows.
- The first line makes the current Nix expression a function. The variable
`pkgs` contains Nixpkgs (by default, it takes the `nixpkgs` entry of
`NIX_PATH`, see the [Nix manual](https://nixos.org/manual/nix/stable/#sec-common-env)
for further details), while `config` contains the full system
configuration. This line can be omitted if there is no reference to
`pkgs` and `config` inside the module.
- This `imports` list enumerates the paths to other NixOS modules that
should be included in the evaluation of the system configuration. A
default set of modules is defined in the file `modules/module-list.nix`.
These don\'t need to be added in the import list.
- The attribute `options` is a nested set of *option declarations*
(described below).
- The attribute `config` is a nested set of *option definitions* (also
described below).
[Example: NixOS Module for the "locate" Service](#locate-example)
shows a module that handles the regular update of the "locate" database,
an index of all files in the file system. This module declares two
options that can be defined by other modules (typically the user's
`configuration.nix`): `services.locate.enable` (whether the database should
be updated) and `services.locate.interval` (when the update should be done).
It implements its functionality by defining two options declared by other
modules: `systemd.services` (the set of all systemd services) and
`systemd.timers` (the list of commands to be executed periodically by
`systemd`).
::: {#locate-example .example}
::: {.title}
**Example: NixOS Module for the "locate" Service**
:::
```nix
{ config, lib, pkgs, ... }:
with lib;
let
cfg = config.services.locate;
in {
options.services.locate = {
enable = mkOption {
type = types.bool;
default = false;
description = ''
If enabled, NixOS will periodically update the database of
files used by the locate command.
'';
};
interval = mkOption {
type = types.str;
default = "02:15";
example = "hourly";
description = ''
Update the locate database at this interval. Updates by
default at 2:15 AM every day.
The format is described in
systemd.time(7).
'';
};
# Other options omitted for documentation
};
config = {
systemd.services.update-locatedb =
{ description = "Update Locate Database";
path = [ pkgs.su ];
script =
''
mkdir -m 0755 -p $(dirname ${toString cfg.output})
exec updatedb \
--localuser=${cfg.localuser} \
${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \
--output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags}
'';
};
systemd.timers.update-locatedb = mkIf cfg.enable
{ description = "Update timer for locate database";
partOf = [ "update-locatedb.service" ];
wantedBy = [ "timers.target" ];
timerConfig.OnCalendar = cfg.interval;
};
};
}
```
:::
```{=docbook}
<xi:include href="option-declarations.section.xml" />
<xi:include href="option-types.section.xml" />
<xi:include href="option-def.section.xml" />
<xi:include href="assertions.section.xml" />
<xi:include href="meta-attributes.section.xml" />
<xi:include href="importing-modules.section.xml" />
<xi:include href="replace-modules.section.xml" />
<xi:include href="freeform-modules.section.xml" />
<xi:include href="settings-options.section.xml" />
```

191
nixos/doc/manual/development/writing-modules.xml
View file

@ -1,191 +0,0 @@
<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-writing-modules">
<title>Writing NixOS Modules</title>
<para>
NixOS has a modular system for declarative configuration. This system
combines multiple <emphasis>modules</emphasis> to produce the full system
configuration. One of the modules that constitute the configuration is
<filename>/etc/nixos/configuration.nix</filename>. Most of the others live in
the
<link
xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link>
subdirectory of the Nixpkgs tree.
</para>
<para>
Each NixOS module is a file that handles one logical aspect of the
configuration, such as a specific kind of hardware, a service, or network
settings. A module configuration does not have to handle everything from
scratch; it can use the functionality provided by other modules for its
implementation. Thus a module can <emphasis>declare</emphasis> options that
can be used by other modules, and conversely can <emphasis>define</emphasis>
options provided by other modules in its own implementation. For example, the
module
<link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link>
declares the option <option>security.pam.services</option> that allows other
modules (e.g.
<link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>)
to define PAM services; and it defines the option
<option>environment.etc</option> (declared by
<link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>)
to cause files to be created in <filename>/etc/pam.d</filename>.
</para>
<para xml:id="para-module-syn">
In <xref
linkend="sec-configuration-syntax"/>, we saw the following structure
of NixOS modules:
<programlisting>
{ config, pkgs, ... }:
{ <replaceable>option definitions</replaceable>
}
</programlisting>
This is actually an <emphasis>abbreviated</emphasis> form of module that only
defines options, but does not declare any. The structure of full NixOS
modules is shown in <xref linkend='ex-module-syntax' />.
</para>
<example xml:id='ex-module-syntax'>
<title>Structure of NixOS Modules</title>
<programlisting>
{ config, pkgs, ... }: <co xml:id='module-syntax-1' />
{
imports =
[ <replaceable>paths of other modules</replaceable> <co xml:id='module-syntax-2' />
];
options = {
<replaceable>option declarations</replaceable> <co xml:id='module-syntax-3' />
};
config = {
<replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' />
};
}</programlisting>
</example>
<para>
The meaning of each part is as follows.
<calloutlist>
<callout arearefs='module-syntax-1'>
<para>
This line makes the current Nix expression a function. The variable
<varname>pkgs</varname> contains Nixpkgs (by default, it takes the
<varname>nixpkgs</varname> entry of <envar>NIX_PATH</envar>, see the <link
xlink:href="https://nixos.org/manual/nix/stable/#sec-common-env">Nix
manual</link> for further details), while <varname>config</varname>
contains the full system configuration. This line can be omitted if there
is no reference to <varname>pkgs</varname> and <varname>config</varname>
inside the module.
</para>
</callout>
<callout arearefs='module-syntax-2'>
<para>
This list enumerates the paths to other NixOS modules that should be
included in the evaluation of the system configuration. A default set of
modules is defined in the file
<filename>modules/module-list.nix</filename>. These don't need to be added
in the import list.
</para>
</callout>
<callout arearefs='module-syntax-3'>
<para>
The attribute <varname>options</varname> is a nested set of
<emphasis>option declarations</emphasis> (described below).
</para>
</callout>
<callout arearefs='module-syntax-4'>
<para>
The attribute <varname>config</varname> is a nested set of
<emphasis>option definitions</emphasis> (also described below).
</para>
</callout>
</calloutlist>
</para>
<para>
<xref linkend='locate-example' /> shows a module that handles the regular
update of the “locate” database, an index of all files in the file
system. This module declares two options that can be defined by other modules
(typically the user’s <filename>configuration.nix</filename>):
<option>services.locate.enable</option> (whether the database should be
updated) and <option>services.locate.interval</option> (when the update
should be done). It implements its functionality by defining two options
declared by other modules: <option>systemd.services</option> (the set of all
systemd services) and <option>systemd.timers</option> (the list of commands
to be executed periodically by <command>systemd</command>).
</para>
<example xml:id='locate-example'>
<title>NixOS Module for the “locate” Service</title>
<programlisting>
{ config, lib, pkgs, ... }:
with lib;
let
cfg = config.services.locate;
in {
options.services.locate = {
enable = mkOption {
type = types.bool;
default = false;
description = ''
If enabled, NixOS will periodically update the database of
files used by the <command>locate</command> command.
'';
};
interval = mkOption {
type = types.str;
default = "02:15";
example = "hourly";
description = ''
Update the locate database at this interval. Updates by
default at 2:15 AM every day.
The format is described in
<citerefentry><refentrytitle>systemd.time</refentrytitle>
<manvolnum>7</manvolnum></citerefentry>.
'';
};
# Other options omitted for documentation
};
config = {
systemd.services.update-locatedb =
{ description = "Update Locate Database";
path = [ pkgs.su ];
script =
''
mkdir -m 0755 -p $(dirname ${toString cfg.output})
exec updatedb \
--localuser=${cfg.localuser} \
${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \
--output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags}
'';
};
systemd.timers.update-locatedb = mkIf cfg.enable
{ description = "Update timer for locate database";
partOf = [ "update-locatedb.service" ];
wantedBy = [ "timers.target" ];
timerConfig.OnCalendar = cfg.interval;
};
};
}
</programlisting>
</example>
<xi:include href="../from_md/development/option-declarations.section.xml" />
<xi:include href="../from_md/development/option-types.section.xml" />
<xi:include href="../from_md/development/option-def.section.xml" />
<xi:include href="../from_md/development/assertions.section.xml" />
<xi:include href="../from_md/development/meta-attributes.section.xml" />
<xi:include href="../from_md/development/importing-modules.section.xml" />
<xi:include href="../from_md/development/replace-modules.section.xml" />
<xi:include href="../from_md/development/freeform-modules.section.xml" />
<xi:include href="../from_md/development/settings-options.section.xml" />
</chapter>

31
nixos/doc/manual/from_md/administration/containers.chapter.xml Normal file
View file

@ -0,0 +1,31 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-containers">
<title>Container Management</title>
<para>
NixOS allows you to easily run other NixOS instances as
<emphasis>containers</emphasis>. Containers are a light-weight
approach to virtualisation that runs software in the container at
the same speed as in the host system. NixOS containers share the Nix
store of the host, making container creation very efficient.
</para>
<warning>
<para>
Currently, NixOS containers are not perfectly isolated from the
host system. This means that a user with root access to the
container can do things that affect the host. So you should not
give container root access to untrusted users.
</para>
</warning>
<para>
NixOS containers can be created in two ways: imperatively, using the
command <literal>nixos-container</literal>, and declaratively, by
specifying them in your <literal>configuration.nix</literal>. The
declarative approach implies that containers get upgraded along with
your host system when you run <literal>nixos-rebuild</literal>,
which is often not what you want. By contrast, in the imperative
approach, containers are configured and updated independently from
the host system.
</para>
<xi:include href="imperative-containers.section.xml" />
<xi:include href="declarative-containers.section.xml" />
<xi:include href="container-networking.section.xml" />
</chapter>

12
nixos/doc/manual/from_md/administration/troubleshooting.chapter.xml Normal file
View file

@ -0,0 +1,12 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-troubleshooting">
<title>Troubleshooting</title>
<para>
This chapter describes solutions to common problems you might
encounter when you manage your NixOS system.
</para>
<xi:include href="boot-problems.section.xml" />
<xi:include href="maintenance-mode.section.xml" />
<xi:include href="rollback.section.xml" />
<xi:include href="store-corruption.section.xml" />
<xi:include href="network-problems.section.xml" />
</chapter>

21
nixos/doc/manual/from_md/configuration/config-syntax.chapter.xml Normal file
View file

@ -0,0 +1,21 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-configuration-syntax">
<title>Configuration Syntax</title>
<para>
The NixOS configuration file
<literal>/etc/nixos/configuration.nix</literal> is actually a
<emphasis>Nix expression</emphasis>, which is the Nix package
manager’s purely functional language for describing how to build
packages and configurations. This means you have all the expressive
power of that language at your disposal, including the ability to
abstract over common patterns, which is very useful when managing
complex systems. The syntax and semantics of the Nix language are
fully described in the
<link xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
manual</link>, but here we give a short overview of the most
important constructs useful in NixOS configuration files.
</para>
<xi:include href="config-file.section.xml" />
<xi:include href="abstractions.section.xml" />
<xi:include href="modularity.section.xml" />
<xi:include href="summary.section.xml" />
</chapter>

53
nixos/doc/manual/from_md/configuration/declarative-packages.section.xml Normal file
View file

@ -0,0 +1,53 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-declarative-package-mgmt">
<title>Declarative Package Management</title>
<para>
With declarative package management, you specify which packages you
want on your system by setting the option
<xref linkend="opt-environment.systemPackages" />. For instance,
adding the following line to <literal>configuration.nix</literal>
enables the Mozilla Thunderbird email application:
</para>
<programlisting language="bash">
environment.systemPackages = [ pkgs.thunderbird ];
</programlisting>
<para>
The effect of this specification is that the Thunderbird package
from Nixpkgs will be built or downloaded as part of the system when
you run <literal>nixos-rebuild switch</literal>.
</para>
<note>
<para>
Some packages require additional global configuration such as
D-Bus or systemd service registration so adding them to
<xref linkend="opt-environment.systemPackages" /> might not be
sufficient. You are advised to check the
<link linkend="ch-options">list of options</link> whether a NixOS
module for the package does not exist.
</para>
</note>
<para>
You can get a list of the available packages as follows:
</para>
<programlisting>
$ nix-env -qaP '*' --description
nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
...
</programlisting>
<para>
The first column in the output is the <emphasis>attribute
name</emphasis>, such as <literal>nixos.thunderbird</literal>.
</para>
<para>
Note: the <literal>nixos</literal> prefix tells us that we want to
get the package from the <literal>nixos</literal> channel and works
only in CLI tools. In declarative configuration use
<literal>pkgs</literal> prefix (variable).
</para>
<para>
To <quote>uninstall</quote> a package, simply remove it from
<xref linkend="opt-environment.systemPackages" /> and run
<literal>nixos-rebuild switch</literal>.
</para>
<xi:include href="customizing-packages.section.xml" />
<xi:include href="adding-custom-packages.section.xml" />
</section>

55
nixos/doc/manual/from_md/configuration/file-systems.chapter.xml Normal file
View file

@ -0,0 +1,55 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-file-systems">
<title>File Systems</title>
<para>
You can define file systems using the <literal>fileSystems</literal>
configuration option. For instance, the following definition causes
NixOS to mount the Ext4 file system on device
<literal>/dev/disk/by-label/data</literal> onto the mount point
<literal>/data</literal>:
</para>
<programlisting language="bash">
fileSystems.&quot;/data&quot; =
{ device = &quot;/dev/disk/by-label/data&quot;;
fsType = &quot;ext4&quot;;
};
</programlisting>
<para>
This will create an entry in <literal>/etc/fstab</literal>, which
will generate a corresponding
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.mount.html">systemd.mount</link>
unit via
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html">systemd-fstab-generator</link>.
The filesystem will be mounted automatically unless
<literal>&quot;noauto&quot;</literal> is present in
<link linkend="opt-fileSystems._name_.options">options</link>.
<literal>&quot;noauto&quot;</literal> filesystems can be mounted
explicitly using <literal>systemctl</literal> e.g.
<literal>systemctl start data.mount</literal>. Mount points are
created automatically if they don’t already exist. For
<literal>device</literal>, it’s best to use the topology-independent
device aliases in <literal>/dev/disk/by-label</literal> and
<literal>/dev/disk/by-uuid</literal>, as these don’t change if the
topology changes (e.g. if a disk is moved to another IDE
controller).
</para>
<para>
You can usually omit the file system type
(<literal>fsType</literal>), since <literal>mount</literal> can
usually detect the type and load the necessary kernel module
automatically. However, if the file system is needed at early boot
(in the initial ramdisk) and is not <literal>ext2</literal>,
<literal>ext3</literal> or <literal>ext4</literal>, then it’s best
to specify <literal>fsType</literal> to ensure that the kernel
module is available.
</para>
<note>
<para>
System startup will fail if any of the filesystems fails to mount,
dropping you to the emergency shell. You can make a mount
asynchronous and non-critical by adding
<literal>options = [ &quot;nofail&quot; ];</literal>.
</para>
</note>
<xi:include href="luks-file-systems.section.xml" />
<xi:include href="sshfs-file-systems.section.xml" />
</chapter>

15
nixos/doc/manual/from_md/configuration/networking.chapter.xml Normal file
View file

@ -0,0 +1,15 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-networking">
<title>Networking</title>
<para>
This section describes how to configure networking components on
your NixOS machine.
</para>
<xi:include href="network-manager.section.xml" />
<xi:include href="ssh.section.xml" />
<xi:include href="ipv4-config.section.xml" />
<xi:include href="ipv6-config.section.xml" />
<xi:include href="firewall.section.xml" />
<xi:include href="wireless.section.xml" />
<xi:include href="ad-hoc-network-config.section.xml" />
<xi:include href="renaming-interfaces.section.xml" />
</chapter>

28
nixos/doc/manual/from_md/configuration/package-mgmt.chapter.xml Normal file
View file

@ -0,0 +1,28 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-package-management">
<title>Package Management</title>
<para>
This section describes how to add additional packages to your
system. NixOS has two distinct styles of package management:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>Declarative</emphasis>, where you declare what
packages you want in your <literal>configuration.nix</literal>.
Every time you run <literal>nixos-rebuild</literal>, NixOS will
ensure that you get a consistent set of binaries corresponding
to your specification.
</para>
</listitem>
<listitem>
<para>
<emphasis>Ad hoc</emphasis>, where you install, upgrade and
uninstall packages via the <literal>nix-env</literal> command.
This style allows mixing packages from different Nixpkgs
versions. It’s the only choice for non-root users.
</para>
</listitem>
</itemizedlist>
<xi:include href="declarative-packages.section.xml" />
<xi:include href="ad-hoc-packages.section.xml" />
</chapter>

38
nixos/doc/manual/from_md/configuration/profiles.chapter.xml Normal file
View file

@ -0,0 +1,38 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-profiles">
<title>Profiles</title>
<para>
In some cases, it may be desirable to take advantage of
commonly-used, predefined configurations provided by nixpkgs, but
different from those that come as default. This is a role fulfilled
by NixOS's Profiles, which come as files living in
<literal>&lt;nixpkgs/nixos/modules/profiles&gt;</literal>. That is
to say, expected usage is to add them to the imports list of your
<literal>/etc/configuration.nix</literal> as such:
</para>
<programlisting language="bash">
imports = [
&lt;nixpkgs/nixos/modules/profiles/profile-name.nix&gt;
];
</programlisting>
<para>
Even if some of these profiles seem only useful in the context of
install media, many are actually intended to be used in real
installs.
</para>
<para>
What follows is a brief explanation on the purpose and use-case for
each profile. Detailing each option configured by each one is out of
scope.
</para>
<xi:include href="profiles/all-hardware.section.xml" />
<xi:include href="profiles/base.section.xml" />
<xi:include href="profiles/clone-config.section.xml" />
<xi:include href="profiles/demo.section.xml" />
<xi:include href="profiles/docker-container.section.xml" />
<xi:include href="profiles/graphical.section.xml" />
<xi:include href="profiles/hardened.section.xml" />
<xi:include href="profiles/headless.section.xml" />
<xi:include href="profiles/installation-device.section.xml" />
<xi:include href="profiles/minimal.section.xml" />
<xi:include href="profiles/qemu-guest.section.xml" />
</chapter>

14
nixos/doc/manual/from_md/development/nixos-tests.chapter.xml Normal file
View file

@ -0,0 +1,14 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-nixos-tests">
<title>NixOS Tests</title>
<para>
When you add some feature to NixOS, you should write a test for it.
NixOS tests are kept in the directory
<literal>nixos/tests</literal>, and are executed (using Nix) by a
testing framework that automatically starts one or more virtual
machines containing the NixOS system(s) required for the test.
</para>
<xi:include href="writing-nixos-tests.section.xml" />
<xi:include href="running-nixos-tests.section.xml" />
<xi:include href="running-nixos-tests-interactively.section.xml" />
<xi:include href="linking-nixos-tests-to-packages.section.xml" />
</chapter>

196
nixos/doc/manual/from_md/development/writing-modules.chapter.xml Normal file
View file

@ -0,0 +1,196 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-writing-modules">
<title>Writing NixOS Modules</title>
<para>
NixOS has a modular system for declarative configuration. This
system combines multiple <emphasis>modules</emphasis> to produce the
full system configuration. One of the modules that constitute the
configuration is <literal>/etc/nixos/configuration.nix</literal>.
Most of the others live in the
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><literal>nixos/modules</literal></link>
subdirectory of the Nixpkgs tree.
</para>
<para>
Each NixOS module is a file that handles one logical aspect of the
configuration, such as a specific kind of hardware, a service, or
network settings. A module configuration does not have to handle
everything from scratch; it can use the functionality provided by
other modules for its implementation. Thus a module can
<emphasis>declare</emphasis> options that can be used by other
modules, and conversely can <emphasis>define</emphasis> options
provided by other modules in its own implementation. For example,
the module
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><literal>pam.nix</literal></link>
declares the option <literal>security.pam.services</literal> that
allows other modules (e.g.
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><literal>sshd.nix</literal></link>)
to define PAM services; and it defines the option
<literal>environment.etc</literal> (declared by
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><literal>etc.nix</literal></link>)
to cause files to be created in <literal>/etc/pam.d</literal>.
</para>
<para>
In <xref linkend="sec-configuration-syntax" />, we saw the following
structure of NixOS modules:
</para>
<programlisting language="bash">
{ config, pkgs, ... }:
{ option definitions
}
</programlisting>
<para>
This is actually an <emphasis>abbreviated</emphasis> form of module
that only defines options, but does not declare any. The structure
of full NixOS modules is shown in
<link linkend="ex-module-syntax">Example: Structure of NixOS
Modules</link>.
</para>
<anchor xml:id="ex-module-syntax" />
<para>
<emphasis role="strong">Example: Structure of NixOS
Modules</emphasis>
</para>
<programlisting language="bash">
{ config, pkgs, ... }:
{
imports =
[ paths of other modules
];
options = {
option declarations
};
config = {
option definitions
};
}
</programlisting>
<para>
The meaning of each part is as follows.
</para>
<itemizedlist>
<listitem>
<para>
The first line makes the current Nix expression a function. The
variable <literal>pkgs</literal> contains Nixpkgs (by default,
it takes the <literal>nixpkgs</literal> entry of
<literal>NIX_PATH</literal>, see the
<link xlink:href="https://nixos.org/manual/nix/stable/#sec-common-env">Nix
manual</link> for further details), while
<literal>config</literal> contains the full system
configuration. This line can be omitted if there is no reference
to <literal>pkgs</literal> and <literal>config</literal> inside
the module.
</para>
</listitem>
<listitem>
<para>
This <literal>imports</literal> list enumerates the paths to
other NixOS modules that should be included in the evaluation of
the system configuration. A default set of modules is defined in
the file <literal>modules/module-list.nix</literal>. These don't
need to be added in the import list.
</para>
</listitem>
<listitem>
<para>
The attribute <literal>options</literal> is a nested set of
<emphasis>option declarations</emphasis> (described below).
</para>
</listitem>
<listitem>
<para>
The attribute <literal>config</literal> is a nested set of
<emphasis>option definitions</emphasis> (also described below).
</para>
</listitem>
</itemizedlist>
<para>
<link linkend="locate-example">Example: NixOS Module for the
<quote>locate</quote> Service</link> shows a module that handles the
regular update of the <quote>locate</quote> database, an index of
all files in the file system. This module declares two options that
can be defined by other modules (typically the user’s
<literal>configuration.nix</literal>):
<literal>services.locate.enable</literal> (whether the database
should be updated) and <literal>services.locate.interval</literal>
(when the update should be done). It implements its functionality by
defining two options declared by other modules:
<literal>systemd.services</literal> (the set of all systemd
services) and <literal>systemd.timers</literal> (the list of
commands to be executed periodically by <literal>systemd</literal>).
</para>
<anchor xml:id="locate-example" />
<para>
<emphasis role="strong">Example: NixOS Module for the
<quote>locate</quote> Service</emphasis>
</para>
<programlisting language="bash">
{ config, lib, pkgs, ... }:
with lib;
let
cfg = config.services.locate;
in {
options.services.locate = {
enable = mkOption {
type = types.bool;
default = false;
description = ''
If enabled, NixOS will periodically update the database of
files used by the locate command.
'';
};
interval = mkOption {
type = types.str;
default = &quot;02:15&quot;;
example = &quot;hourly&quot;;
description = ''
Update the locate database at this interval. Updates by
default at 2:15 AM every day.
The format is described in
systemd.time(7).
'';
};
# Other options omitted for documentation
};
config = {
systemd.services.update-locatedb =
{ description = &quot;Update Locate Database&quot;;
path = [ pkgs.su ];
script =
''
mkdir -m 0755 -p $(dirname ${toString cfg.output})
exec updatedb \
--localuser=${cfg.localuser} \
${optionalString (!cfg.includeStore) &quot;--prunepaths='/nix/store'&quot;} \
--output=${toString cfg.output} ${concatStringsSep &quot; &quot; cfg.extraFlags}
'';
};
systemd.timers.update-locatedb = mkIf cfg.enable
{ description = &quot;Update timer for locate database&quot;;
partOf = [ &quot;update-locatedb.service&quot; ];
wantedBy = [ &quot;timers.target&quot; ];
timerConfig.OnCalendar = cfg.interval;
};
};
}
</programlisting>
<xi:include href="option-declarations.section.xml" />
<xi:include href="option-types.section.xml" />
<xi:include href="option-def.section.xml" />
<xi:include href="assertions.section.xml" />
<xi:include href="meta-attributes.section.xml" />
<xi:include href="importing-modules.section.xml" />
<xi:include href="replace-modules.section.xml" />
<xi:include href="freeform-modules.section.xml" />
<xi:include href="settings-options.section.xml" />
</chapter>

642
nixos/doc/manual/from_md/installation/installing.chapter.xml Normal file
View file

@ -0,0 +1,642 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-installation">
<title>Installing NixOS</title>
<section xml:id="sec-installation-booting">
<title>Booting the system</title>
<para>
NixOS can be installed on BIOS or UEFI systems. The procedure for
a UEFI installation is by and large the same as a BIOS
installation. The differences are mentioned in the steps that
follow.
</para>
<para>
The installation media can be burned to a CD, or now more
commonly, <quote>burned</quote> to a USB drive (see
<xref linkend="sec-booting-from-usb" />).
</para>
<para>
The installation media contains a basic NixOS installation. When
it’s finished booting, it should have detected most of your
hardware.
</para>
<para>
The NixOS manual is available by running
<literal>nixos-help</literal>.
</para>
<para>
You are logged-in automatically as <literal>nixos</literal>. The
<literal>nixos</literal> user account has an empty password so you
can use <literal>sudo</literal> without a password.
</para>
<para>
If you downloaded the graphical ISO image, you can run
<literal>systemctl start display-manager</literal> to start the
desktop environment. If you want to continue on the terminal, you
can use <literal>loadkeys</literal> to switch to your preferred
keyboard layout. (We even provide neo2 via
<literal>loadkeys de neo</literal>!)
</para>
<para>
If the text is too small to be legible, try
<literal>setfont ter-v32n</literal> to increase the font size.
</para>
<para>
To install over a serial port connect with
<literal>115200n8</literal> (e.g.
<literal>picocom -b 115200 /dev/ttyUSB0</literal>). When the
bootloader lists boot entries, select the serial console boot
entry.
</para>
<section xml:id="sec-installation-booting-networking">
<title>Networking in the installer</title>
<para>
The boot process should have brought up networking (check
<literal>ip a</literal>). 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 <literal>ifconfig</literal>.
</para>
<para>
On the graphical installer, you can configure the network, wifi
included, through NetworkManager. Using the
<literal>nmtui</literal> program, you can do so even in a
non-graphical session. If you prefer to configure the network
manually, disable NetworkManager with
<literal>systemctl stop NetworkManager</literal>.
</para>
<para>
On the minimal installer, NetworkManager is not available, so
configuration must be perfomed manually. To configure the wifi,
first start wpa_supplicant with
<literal>sudo systemctl start wpa_supplicant</literal>, then run
<literal>wpa_cli</literal>. For most home networks, you need to
type in the following commands:
</para>
<programlisting>
&gt; add_network
0
&gt; set_network 0 ssid &quot;myhomenetwork&quot;
OK
&gt; set_network 0 psk &quot;mypassword&quot;
OK
&gt; set_network 0 key_mgmt WPA-PSK
OK
&gt; enable_network 0
OK
</programlisting>
<para>
For enterprise networks, for example
<emphasis>eduroam</emphasis>, instead do:
</para>
<programlisting>
&gt; add_network
0
&gt; set_network 0 ssid &quot;eduroam&quot;
OK
&gt; set_network 0 identity &quot;myname@example.com&quot;
OK
&gt; set_network 0 password &quot;mypassword&quot;
OK
&gt; set_network 0 key_mgmt WPA-EAP
OK
&gt; enable_network 0
OK
</programlisting>
<para>
When successfully connected, you should see a line such as this
one
</para>
<programlisting>
&lt;3&gt;CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=]
</programlisting>
<para>
you can now leave <literal>wpa_cli</literal> by typing
<literal>quit</literal>.
</para>
<para>
If you would like to continue the installation from a different
machine you can use activated SSH daemon. You need to copy your
ssh key to either
<literal>/home/nixos/.ssh/authorized_keys</literal> or
<literal>/root/.ssh/authorized_keys</literal> (Tip: For
installers with a modifiable filesystem such as the sd-card
installer image a key can be manually placed by mounting the
image on a different machine). Alternatively you must set a
password for either <literal>root</literal> or
<literal>nixos</literal> with <literal>passwd</literal> to be
able to login.
</para>
</section>
</section>
<section xml:id="sec-installation-partitioning">
<title>Partitioning and formatting</title>
<para>
The NixOS installer doesn’t do any partitioning or formatting, so
you need to do that yourself.
</para>
<para>
The NixOS installer ships with multiple partitioning tools. The
examples below use <literal>parted</literal>, but also provides
<literal>fdisk</literal>, <literal>gdisk</literal>,
<literal>cfdisk</literal>, and <literal>cgdisk</literal>.
</para>
<para>
The recommended partition scheme differs depending if the computer
uses <emphasis>Legacy Boot</emphasis> or
<emphasis>UEFI</emphasis>.
</para>
<section xml:id="sec-installation-partitioning-UEFI">
<title>UEFI (GPT)</title>
<para>
Here's an example partition scheme for UEFI, using
<literal>/dev/sda</literal> as the device.
</para>
<note>
<para>
You can safely ignore <literal>parted</literal>'s
informational message about needing to update /etc/fstab.
</para>
</note>
<orderedlist numeration="arabic">
<listitem>
<para>
Create a <emphasis>GPT</emphasis> partition table.
</para>
<programlisting>
# parted /dev/sda -- mklabel gpt
</programlisting>
</listitem>
<listitem>
<para>
Add the <emphasis>root</emphasis> partition. This will fill
the disk except for the end part, where the swap will live,
and the space left in front (512MiB) which will be used by
the boot partition.
</para>
<programlisting>
# parted /dev/sda -- mkpart primary 512MiB -8GiB
</programlisting>
</listitem>
<listitem>
<para>
Next, add a <emphasis>swap</emphasis> partition. The size
required will vary according to needs, here a 8GiB one is
created.
</para>
<programlisting>
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
</programlisting>
<note>
<para>
The swap partition size rules are no different than for
other Linux distributions.
</para>
</note>
</listitem>
<listitem>
<para>
Finally, the <emphasis>boot</emphasis> partition. NixOS by
default uses the ESP (EFI system partition) as its
<emphasis>/boot</emphasis> partition. It uses the initially
reserved 512MiB at the start of the disk.
</para>
<programlisting>
# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
# parted /dev/sda -- set 3 esp on
</programlisting>
</listitem>
</orderedlist>
<para>
Once complete, you can follow with
<xref linkend="sec-installation-partitioning-formatting" />.
</para>
</section>
<section xml:id="sec-installation-partitioning-MBR">
<title>Legacy Boot (MBR)</title>
<para>
Here's an example partition scheme for Legacy Boot, using
<literal>/dev/sda</literal> as the device.
</para>
<note>
<para>
You can safely ignore <literal>parted</literal>'s
informational message about needing to update /etc/fstab.
</para>
</note>
<orderedlist numeration="arabic">
<listitem>
<para>
Create a <emphasis>MBR</emphasis> partition table.
</para>
<programlisting>
# parted /dev/sda -- mklabel msdos
</programlisting>
</listitem>
<listitem>
<para>
Add the <emphasis>root</emphasis> partition. This will fill
the the disk except for the end part, where the swap will
live.
</para>
<programlisting>
# parted /dev/sda -- mkpart primary 1MiB -8GiB
</programlisting>
</listitem>
<listitem>
<para>
Finally, add a <emphasis>swap</emphasis> partition. The size
required will vary according to needs, here a 8GiB one is
created.
</para>
<programlisting>
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
</programlisting>
<note>
<para>
The swap partition size rules are no different than for
other Linux distributions.
</para>
</note>
</listitem>
</orderedlist>
<para>
Once complete, you can follow with
<xref linkend="sec-installation-partitioning-formatting" />.
</para>
</section>
<section xml:id="sec-installation-partitioning-formatting">
<title>Formatting</title>
<para>
Use the following commands:
</para>
<itemizedlist>
<listitem>
<para>
For initialising Ext4 partitions:
<literal>mkfs.ext4</literal>. It is recommended that you
assign a unique symbolic label to the file system using the
option <literal>-L label</literal>, since this makes the
file system configuration independent from device changes.
For example:
</para>
<programlisting>
# mkfs.ext4 -L nixos /dev/sda1
</programlisting>
</listitem>
<listitem>
<para>
For creating swap partitions: <literal>mkswap</literal>.
Again it’s recommended to assign a label to the swap
partition: <literal>-L label</literal>. For example:
</para>
<programlisting>
# mkswap -L swap /dev/sda2
</programlisting>
</listitem>
<listitem>
<para>
<emphasis role="strong">UEFI systems</emphasis>
</para>
<para>
For creating boot partitions: <literal>mkfs.fat</literal>.
Again it’s recommended to assign a label to the boot
partition: <literal>-n label</literal>. For example:
</para>
<programlisting>
# mkfs.fat -F 32 -n boot /dev/sda3
</programlisting>
</listitem>
<listitem>
<para>
For creating LVM volumes, the LVM commands, e.g.,
<literal>pvcreate</literal>, <literal>vgcreate</literal>,
and <literal>lvcreate</literal>.
</para>
</listitem>
<listitem>
<para>
For creating software RAID devices, use
<literal>mdadm</literal>.
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="sec-installation-installing">
<title>Installing</title>
<orderedlist numeration="arabic">
<listitem>
<para>
Mount the target file system on which NixOS should be
installed on <literal>/mnt</literal>, e.g.
</para>
<programlisting>
# mount /dev/disk/by-label/nixos /mnt
</programlisting>
</listitem>
<listitem>
<para>
<emphasis role="strong">UEFI systems</emphasis>
</para>
<para>
Mount the boot file system on <literal>/mnt/boot</literal>,
e.g.
</para>
<programlisting>
# mkdir -p /mnt/boot
# mount /dev/disk/by-label/boot /mnt/boot
</programlisting>
</listitem>
<listitem>
<para>
If your machine has a limited amount of memory, you may want
to activate swap devices now
(<literal>swapon device</literal>). The installer (or rather,
the build actions that it may spawn) may need quite a bit of
RAM, depending on your configuration.
</para>
<programlisting>
# swapon /dev/sda2
</programlisting>
</listitem>
<listitem>
<para>
You now need to create a file
<literal>/mnt/etc/nixos/configuration.nix</literal> 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
<link linkend="ex-config">Example: NixOS Configuration</link>.
</para>
<para>
The command <literal>nixos-generate-config</literal> can
generate an initial configuration file for you:
</para>
<programlisting>
# nixos-generate-config --root /mnt
</programlisting>
<para>
You should then edit
<literal>/mnt/etc/nixos/configuration.nix</literal> to suit
your needs:
</para>
<programlisting>
# nano /mnt/etc/nixos/configuration.nix
</programlisting>
<para>
If you’re using the graphical ISO image, other editors may be
available (such as <literal>vim</literal>). If you have
network access, you can also install other editors – for
instance, you can install Emacs by running
<literal>nix-env -f '&lt;nixpkgs&gt;' -iA emacs</literal>.
</para>
<variablelist>
<varlistentry>
<term>
BIOS systems
</term>
<listitem>
<para>
You <emphasis>must</emphasis> set the option
<xref linkend="opt-boot.loader.grub.device" /> to
specify on which disk the GRUB boot loader is to be
installed. Without it, NixOS cannot boot.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
UEFI systems
</term>
<listitem>
<para>
You <emphasis>must</emphasis> set the option
<xref linkend="opt-boot.loader.systemd-boot.enable" />
to <literal>true</literal>.
<literal>nixos-generate-config</literal> should do this
automatically for new configurations when booted in UEFI
mode.
</para>
<para>
You may want to look at the options starting with
<link linkend="opt-boot.loader.efi.canTouchEfiVariables"><literal>boot.loader.efi</literal></link>
and
<link linkend="opt-boot.loader.systemd-boot.enable"><literal>boot.loader.systemd-boot</literal></link>
as well.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
If there are other operating systems running on the machine
before installing NixOS, the
<xref linkend="opt-boot.loader.grub.useOSProber" /> option can
be set to <literal>true</literal> to automatically add them to
the grub menu.
</para>
<para>
If you need to configure networking for your machine the
configuration options are described in
<xref linkend="sec-networking" />. In particular, while wifi
is supported on the installation image, it is not enabled by
default in the configuration generated by
<literal>nixos-generate-config</literal>.
</para>
<para>
Another critical option is <literal>fileSystems</literal>,
specifying the file systems that need to be mounted by NixOS.
However, you typically don’t need to set it yourself, because
<literal>nixos-generate-config</literal> sets it automatically
in
<literal>/mnt/etc/nixos/hardware-configuration.nix</literal>
from your currently mounted file systems. (The configuration
file <literal>hardware-configuration.nix</literal> is included
from <literal>configuration.nix</literal> and will be
overwritten by future invocations of
<literal>nixos-generate-config</literal>; thus, you generally
should not modify it.) Additionally, you may want to look at
<link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware
configuration for known-hardware</link> at this point or after
installation.
</para>
<note>
<para>
Depending on your hardware configuration or type of file
system, you may need to set the option
<literal>boot.initrd.kernelModules</literal> 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 installation media
again, mount the target file system on
<literal>/mnt</literal>, fix
<literal>/mnt/etc/nixos/configuration.nix</literal> and
rerun <literal>nixos-install</literal>.) In most cases,
<literal>nixos-generate-config</literal> will figure out the
required modules.
</para>
</note>
</listitem>
<listitem>
<para>
Do the installation:
</para>
<programlisting>
# nixos-install
</programlisting>
<para>
This will install your system based on the configuration you
provided. If anything fails due to a configuration problem or
any other issue (such as a network outage while downloading
binaries from the NixOS binary cache), you can re-run
<literal>nixos-install</literal> after fixing your
<literal>configuration.nix</literal>.
</para>
<para>
As the last step, <literal>nixos-install</literal> will ask
you to set the password for the <literal>root</literal> user,
e.g.
</para>
<programlisting>
setting root password...
New password: ***
Retype new password: ***
</programlisting>
<note>
<para>
For unattended installations, it is possible to use
<literal>nixos-install --no-root-passwd</literal> in order
to disable the password prompt entirely.
</para>
</note>
</listitem>
<listitem>
<para>
If everything went well:
</para>
<programlisting>
# reboot
</programlisting>
</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 is added to the menu. This
allows you to easily roll back to a previous configuration if
something goes wrong.
</para>
<para>
You should log in and change the <literal>root</literal>
password with <literal>passwd</literal>.
</para>
<para>
You’ll probably want to create some user accounts as well,
which can be done with <literal>useradd</literal>:
</para>
<programlisting>
$ useradd -c 'Eelco Dolstra' -m eelco
$ passwd eelco
</programlisting>
<para>
You may also want to install some software. This will be
covered in <xref linkend="sec-package-management" />.
</para>
</listitem>
</orderedlist>
</section>
<section xml:id="sec-installation-summary">
<title>Installation summary</title>
<para>
To summarise, <link linkend="ex-install-sequence">Example:
Commands for Installing NixOS on
<literal>/dev/sda</literal></link> shows a typical sequence of
commands for installing NixOS on an empty hard drive (here
<literal>/dev/sda</literal>). <link linkend="ex-config">Example:
NixOS Configuration</link> shows a corresponding configuration Nix
expression.
</para>
<anchor xml:id="ex-partition-scheme-MBR" />
<para>
<emphasis role="strong">Example: Example partition schemes for
NixOS on <literal>/dev/sda</literal> (MBR)</emphasis>
</para>
<programlisting>
# parted /dev/sda -- mklabel msdos
# parted /dev/sda -- mkpart primary 1MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
</programlisting>
<anchor xml:id="ex-partition-scheme-UEFI" />
<para>
<emphasis role="strong">Example: Example partition schemes for
NixOS on <literal>/dev/sda</literal> (UEFI)</emphasis>
</para>
<programlisting>
# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart primary 512MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
# parted /dev/sda -- set 3 esp on
</programlisting>
<anchor xml:id="ex-install-sequence" />
<para>
<emphasis role="strong">Example: Commands for Installing NixOS on
<literal>/dev/sda</literal></emphasis>
</para>
<para>
With a partitioned disk.
</para>
<programlisting>
# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only)
# mount /dev/disk/by-label/nixos /mnt
# mkdir -p /mnt/boot # (for UEFI systems only)
# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot
</programlisting>
<anchor xml:id="ex-config" />
<para>
<emphasis role="strong">Example: NixOS Configuration</emphasis>
</para>
<programlisting>
{ config, pkgs, ... }: {
imports = [
# Include the results of the hardware scan.
./hardware-configuration.nix
];
boot.loader.grub.device = &quot;/dev/sda&quot;; # (for BIOS systems only)
boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
# Note: setting fileSystems is generally not
# necessary, since nixos-generate-config figures them out
# automatically in hardware-configuration.nix.
#fileSystems.&quot;/&quot;.device = &quot;/dev/disk/by-label/nixos&quot;;
# Enable the OpenSSH server.
services.sshd.enable = true;
}
</programlisting>
</section>
<section xml:id="sec-installation-additional-notes">
<title>Additional installation notes</title>
<xi:include href="installing-usb.section.xml" />
<xi:include href="installing-pxe.section.xml" />
<xi:include href="installing-virtualbox-guest.section.xml" />
<xi:include href="installing-from-other-distro.section.xml" />
<xi:include href="installing-behind-a-proxy.section.xml" />
</section>
</chapter>

2
nixos/doc/manual/installation/installation.xml
View file

@ -11,7 +11,7 @@
</para>
</partintro>
<xi:include href="../from_md/installation/obtaining.chapter.xml" />
<xi:include href="installing.xml" />
<xi:include href="../from_md/installation/installing.chapter.xml" />
<xi:include href="../from_md/installation/changing-config.chapter.xml" />
<xi:include href="../from_md/installation/upgrading.chapter.xml" />
</part>

479
nixos/doc/manual/installation/installing.chapter.md Normal file
View file

@ -0,0 +1,479 @@
# Installing NixOS {#sec-installation}
## Booting the system {#sec-installation-booting}
NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI
installation is by and large the same as a BIOS installation. The
differences are mentioned in the steps that follow.
The installation media can be burned to a CD, or now more commonly,
"burned" to a USB drive (see [](#sec-booting-from-usb)).
The installation media contains a basic NixOS installation. When it's
finished booting, it should have detected most of your hardware.
The NixOS manual is available by running `nixos-help`.
You are logged-in automatically as `nixos`. The `nixos` user account has
an empty password so you can use `sudo` without a password.
If you downloaded the graphical ISO image, you can run `systemctl
start display-manager` to start the desktop environment. If you want
to continue on the terminal, you can use `loadkeys` to switch to your
preferred keyboard layout. (We even provide neo2 via `loadkeys de
neo`!)
If the text is too small to be legible, try `setfont ter-v32n` to
increase the font size.
To install over a serial port connect with `115200n8` (e.g.
`picocom -b 115200 /dev/ttyUSB0`). When the bootloader lists boot
entries, select the serial console boot entry.
### Networking in the installer {#sec-installation-booting-networking}
The boot process should have brought up networking (check `ip
a`). 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 `ifconfig`.
On the graphical installer, you can configure the network, wifi
included, through NetworkManager. Using the `nmtui` program, you can do
so even in a non-graphical session. If you prefer to configure the
network manually, disable NetworkManager with
`systemctl stop NetworkManager`.
On the minimal installer, NetworkManager is not available, so
configuration must be perfomed manually. To configure the wifi, first
start wpa_supplicant with `sudo systemctl start wpa_supplicant`, then
run `wpa_cli`. For most home networks, you need to type in the following
commands:
```plain
> add_network
0
> set_network 0 ssid "myhomenetwork"
OK
> set_network 0 psk "mypassword"
OK
> set_network 0 key_mgmt WPA-PSK
OK
> enable_network 0
OK
```
For enterprise networks, for example *eduroam*, instead do:
```plain
> add_network
0
> set_network 0 ssid "eduroam"
OK
> set_network 0 identity "myname@example.com"
OK
> set_network 0 password "mypassword"
OK
> set_network 0 key_mgmt WPA-EAP
OK
> enable_network 0
OK
```
When successfully connected, you should see a line such as this one
```plain
<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=]
```
you can now leave `wpa_cli` by typing `quit`.
If you would like to continue the installation from a different machine
you can use activated SSH daemon. You need to copy your ssh key to
either `/home/nixos/.ssh/authorized_keys` or
`/root/.ssh/authorized_keys` (Tip: For installers with a modifiable
filesystem such as the sd-card installer image a key can be manually
placed by mounting the image on a different machine). Alternatively you
must set a password for either `root` or `nixos` with `passwd` to be
able to login.
## Partitioning and formatting {#sec-installation-partitioning}
The NixOS installer doesn't do any partitioning or formatting, so you
need to do that yourself.
The NixOS installer ships with multiple partitioning tools. The examples
below use `parted`, but also provides `fdisk`, `gdisk`, `cfdisk`, and
`cgdisk`.
The recommended partition scheme differs depending if the computer uses
*Legacy Boot* or *UEFI*.
### UEFI (GPT) {#sec-installation-partitioning-UEFI}
Here\'s an example partition scheme for UEFI, using `/dev/sda` as the
device.
::: {.note}
You can safely ignore `parted`\'s informational message about needing to
update /etc/fstab.
:::
1. Create a *GPT* partition table.
```ShellSession
# parted /dev/sda -- mklabel gpt
```
2. Add the *root* partition. This will fill the disk except for the end
part, where the swap will live, and the space left in front (512MiB)
which will be used by the boot partition.
```ShellSession
# parted /dev/sda -- mkpart primary 512MiB -8GiB
```
3. Next, add a *swap* partition. The size required will vary according
to needs, here a 8GiB one is created.
```ShellSession
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
```
::: {.note}
The swap partition size rules are no different than for other Linux
distributions.
:::
4. Finally, the *boot* partition. NixOS by default uses the ESP (EFI
system partition) as its */boot* partition. It uses the initially
reserved 512MiB at the start of the disk.
```ShellSession
# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
# parted /dev/sda -- set 3 esp on
```
Once complete, you can follow with
[](#sec-installation-partitioning-formatting).
### Legacy Boot (MBR) {#sec-installation-partitioning-MBR}
Here\'s an example partition scheme for Legacy Boot, using `/dev/sda` as
the device.
::: {.note}
You can safely ignore `parted`\'s informational message about needing to
update /etc/fstab.
:::
1. Create a *MBR* partition table.
```ShellSession
# parted /dev/sda -- mklabel msdos
```
2. Add the *root* partition. This will fill the the disk except for the
end part, where the swap will live.
```ShellSession
# parted /dev/sda -- mkpart primary 1MiB -8GiB
```
3. Finally, add a *swap* partition. The size required will vary
according to needs, here a 8GiB one is created.
```ShellSession
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
```
::: {.note}
The swap partition size rules are no different than for other Linux
distributions.
:::
Once complete, you can follow with
[](#sec-installation-partitioning-formatting).
### Formatting {#sec-installation-partitioning-formatting}
Use the following commands:
- For initialising Ext4 partitions: `mkfs.ext4`. It is recommended
that you assign a unique symbolic label to the file system using the
option `-L label`, since this makes the file system configuration
independent from device changes. For example:
```ShellSession
# mkfs.ext4 -L nixos /dev/sda1
```
- For creating swap partitions: `mkswap`. Again it's recommended to
assign a label to the swap partition: `-L label`. For example:
```ShellSession
# mkswap -L swap /dev/sda2
```
- **UEFI systems**
For creating boot partitions: `mkfs.fat`. Again it's recommended
to assign a label to the boot partition: `-n label`. For
example:
```ShellSession
# mkfs.fat -F 32 -n boot /dev/sda3
```
- For creating LVM volumes, the LVM commands, e.g., `pvcreate`,
`vgcreate`, and `lvcreate`.
- For creating software RAID devices, use `mdadm`.
## Installing {#sec-installation-installing}
1. Mount the target file system on which NixOS should be installed on
`/mnt`, e.g.
```ShellSession
# mount /dev/disk/by-label/nixos /mnt
```
2. **UEFI systems**
Mount the boot file system on `/mnt/boot`, e.g.
```ShellSession
# mkdir -p /mnt/boot
# mount /dev/disk/by-label/boot /mnt/boot
```
3. If your machine has a limited amount of memory, you may want to
activate swap devices now (`swapon device`).
The installer (or rather, the build actions that it
may spawn) may need quite a bit of RAM, depending on your
configuration.
```ShellSession
# swapon /dev/sda2
```
4. You now need to create a file `/mnt/etc/nixos/configuration.nix`
that specifies the intended configuration of the system. This is
because NixOS has a *declarative* 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 [](#sec-configuration-syntax),
while a list of available configuration options appears in
[](#ch-options). A minimal example is shown in
[Example: NixOS Configuration](#ex-config).
The command `nixos-generate-config` can generate an initial
configuration file for you:
```ShellSession
# nixos-generate-config --root /mnt
```
You should then edit `/mnt/etc/nixos/configuration.nix` to suit your
needs:
```ShellSession
# nano /mnt/etc/nixos/configuration.nix
```
If you're using the graphical ISO image, other editors may be
available (such as `vim`). If you have network access, you can also
install other editors -- for instance, you can install Emacs by
running `nix-env -f '<nixpkgs>' -iA emacs`.
BIOS systems
: You *must* set the option [](#opt-boot.loader.grub.device) to
specify on which disk the GRUB boot loader is to be installed.
Without it, NixOS cannot boot.
UEFI systems
: You *must* set the option [](#opt-boot.loader.systemd-boot.enable)
to `true`. `nixos-generate-config` should do this automatically
for new configurations when booted in UEFI mode.
You may want to look at the options starting with
[`boot.loader.efi`](#opt-boot.loader.efi.canTouchEfiVariables) and
[`boot.loader.systemd-boot`](#opt-boot.loader.systemd-boot.enable)
as well.
If there are other operating systems running on the machine before
installing NixOS, the [](#opt-boot.loader.grub.useOSProber)
option can be set to `true` to automatically add them to the grub
menu.
If you need to configure networking for your machine the
configuration options are described in [](#sec-networking). In
particular, while wifi is supported on the installation image, it is
not enabled by default in the configuration generated by
`nixos-generate-config`.
Another critical option is `fileSystems`, specifying the file
systems that need to be mounted by NixOS. However, you typically
don't need to set it yourself, because `nixos-generate-config` sets
it automatically in `/mnt/etc/nixos/hardware-configuration.nix` from
your currently mounted file systems. (The configuration file
`hardware-configuration.nix` is included from `configuration.nix`
and will be overwritten by future invocations of
`nixos-generate-config`; thus, you generally should not modify it.)
Additionally, you may want to look at [Hardware configuration for
known-hardware](https://github.com/NixOS/nixos-hardware) at this
point or after installation.
::: {.note}
Depending on your hardware configuration or type of file system, you
may need to set the option `boot.initrd.kernelModules` 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 installation media again, mount the
target file system on `/mnt`, fix `/mnt/etc/nixos/configuration.nix`
and rerun `nixos-install`.) In most cases, `nixos-generate-config`
will figure out the required modules.
:::
5. Do the installation:
```ShellSession
# nixos-install
```
This will install your system based on the configuration you
provided. If anything fails due to a configuration problem or any
other issue (such as a network outage while downloading binaries
from the NixOS binary cache), you can re-run `nixos-install` after
fixing your `configuration.nix`.
As the last step, `nixos-install` will ask you to set the password
for the `root` user, e.g.
```plain
setting root password...
New password: ***
Retype new password: ***
```
::: {.note}
For unattended installations, it is possible to use
`nixos-install --no-root-passwd` in order to disable the password
prompt entirely.
:::
6. If everything went well:
```ShellSession
# reboot
```
7. You should now be able to boot into the installed NixOS. The GRUB
boot menu shows a list of *available configurations* (initially just
one). Every time you change the NixOS configuration (see [Changing
Configuration](#sec-changing-config)), a new item is added to the
menu. This allows you to easily roll back to a previous
configuration if something goes wrong.
You should log in and change the `root` password with `passwd`.
You'll probably want to create some user accounts as well, which can
be done with `useradd`:
```ShellSession
$ useradd -c 'Eelco Dolstra' -m eelco
$ passwd eelco
```
You may also want to install some software. This will be covered in
[](#sec-package-management).
## Installation summary {#sec-installation-summary}
To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence)
shows a typical sequence of commands for installing NixOS on an empty hard
drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a
corresponding configuration Nix expression.
::: {#ex-partition-scheme-MBR .example}
::: {.title}
**Example: Example partition schemes for NixOS on `/dev/sda` (MBR)**
:::
```ShellSession
# parted /dev/sda -- mklabel msdos
# parted /dev/sda -- mkpart primary 1MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
```
:::
::: {#ex-partition-scheme-UEFI .example}
::: {.title}
**Example: Example partition schemes for NixOS on `/dev/sda` (UEFI)**
:::
```ShellSession
# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart primary 512MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
# parted /dev/sda -- set 3 esp on
```
:::
::: {#ex-install-sequence .example}
::: {.title}
**Example: Commands for Installing NixOS on `/dev/sda`**
:::
With a partitioned disk.
```ShellSession
# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only)
# mount /dev/disk/by-label/nixos /mnt
# mkdir -p /mnt/boot # (for UEFI systems only)
# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot
```
:::
::: {#ex-config .example}
::: {.title}
**Example: NixOS Configuration**
:::
```ShellSession
{ config, pkgs, ... }: {
imports = [
# Include the results of the hardware scan.
./hardware-configuration.nix
];
boot.loader.grub.device = "/dev/sda"; # (for BIOS systems only)
boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
# 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;
}
```
:::
## Additional installation notes {#sec-installation-additional-notes}
```{=docbook}
<xi:include href="installing-usb.section.xml" />
<xi:include href="installing-pxe.section.xml" />
<xi:include href="installing-virtualbox-guest.section.xml" />
<xi:include href="installing-from-other-distro.section.xml" />
<xi:include href="installing-behind-a-proxy.section.xml" />
```

616
nixos/doc/manual/installation/installing.xml
View file

@ -1,616 +0,0 @@
<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>
<section xml:id="sec-installation-booting">
<title>Booting the system</title>
<para>
NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI
installation is by and large the same as a BIOS installation. The
differences are mentioned in the steps that follow.
</para>
<para>
The installation media can be burned to a CD, or now more commonly, "burned"
to a USB drive (see <xref linkend="sec-booting-from-usb"/>).
</para>
<para>
The installation media contains a basic NixOS installation. When it’s
finished booting, it should have detected most of your hardware.
</para>
<para>
The NixOS manual is available by running <command>nixos-help</command>.
</para>
<para>
You are logged-in automatically as <literal>nixos</literal>.
The <literal>nixos</literal> user account has an empty password so you
can use <command>sudo</command> without a password.
</para>
<para>
If you downloaded the graphical ISO image, you can run <command>systemctl
start display-manager</command> to start the desktop environment. If you want to continue on the
terminal, you can use <command>loadkeys</command> to switch to your
preferred keyboard layout. (We even provide neo2 via <command>loadkeys de
neo</command>!)
</para>
<para>
If the text is too small to be legible, try <command>setfont ter-v32n</command>
to increase the font size.
</para>
<para>
To install over a serial port connect with <literal>115200n8</literal>
(e.g. <command>picocom -b 115200 /dev/ttyUSB0</command>). When the
bootloader lists boot entries, select the serial console boot entry.
</para>
<section xml:id="sec-installation-booting-networking">
<title>Networking in the installer</title>
<para>
The boot process should have brought up networking (check <command>ip
a</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>
<para>
On the graphical installer, you can configure the network, wifi included,
through NetworkManager. Using the <command>nmtui</command> program, you
can do so even in a non-graphical session. If you prefer to configure the
network manually, disable NetworkManager with
<command>systemctl stop NetworkManager</command>.
</para>
<para>
On the minimal installer, NetworkManager is not available, so configuration
must be perfomed manually. To configure the wifi, first start wpa_supplicant
with <command>sudo systemctl start wpa_supplicant</command>, then run
<command>wpa_cli</command>. For most home networks, you need to type
in the following commands:
<programlisting>
<prompt>&gt; </prompt>add_network
0
<prompt>&gt; </prompt>set_network 0 ssid "myhomenetwork"
OK
<prompt>&gt; </prompt>set_network 0 psk "mypassword"
OK
<prompt>&gt; </prompt>set_network 0 key_mgmt WPA-PSK
OK
<prompt>&gt; </prompt>enable_network 0
OK
</programlisting>
For enterprise networks, for example <emphasis>eduroam</emphasis>, instead do:
<programlisting>
<prompt>&gt; </prompt>add_network
0
<prompt>&gt; </prompt>set_network 0 ssid "eduroam"
OK
<prompt>&gt; </prompt>set_network 0 identity "myname@example.com"
OK
<prompt>&gt; </prompt>set_network 0 password "mypassword"
OK
<prompt>&gt; </prompt>set_network 0 key_mgmt WPA-EAP
OK
<prompt>&gt; </prompt>enable_network 0
OK
</programlisting>
When successfully connected, you should see a line such as this one
<programlisting>
&lt;3&gt;CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=]
</programlisting>
you can now leave <command>wpa_cli</command> by typing <command>quit</command>.
</para>
<para>
If you would like to continue the installation from a different machine you
can use activated SSH daemon. You need to copy your ssh key to either
<literal>/home/nixos/.ssh/authorized_keys</literal> or
<literal>/root/.ssh/authorized_keys</literal> (Tip: For installers with a
modifiable filesystem such as the sd-card installer image a key can be manually
placed by mounting the image on a different machine). Alternatively you must set
a password for either <literal>root</literal> or <literal>nixos</literal> with
<command>passwd</command> to be able to login.
</para>
</section>
</section>
<section xml:id="sec-installation-partitioning">
<title>Partitioning and formatting</title>
<para>
The NixOS installer doesn’t do any partitioning or formatting, so you need
to do that yourself.
</para>
<para>
The NixOS installer ships with multiple partitioning tools. The examples
below use <command>parted</command>, but also provides
<command>fdisk</command>, <command>gdisk</command>,
<command>cfdisk</command>, and <command>cgdisk</command>.
</para>
<para>
The recommended partition scheme differs depending if the computer uses
<emphasis>Legacy Boot</emphasis> or <emphasis>UEFI</emphasis>.
</para>
<section xml:id="sec-installation-partitioning-UEFI">
<title>UEFI (GPT)</title>
<para>
Here's an example partition scheme for UEFI, using
<filename>/dev/sda</filename> as the device.
<note>
<para>
You can safely ignore <command>parted</command>'s informational message
about needing to update /etc/fstab.
</para>
</note>
</para>
<para>
<orderedlist>
<listitem>
<para>
Create a <emphasis>GPT</emphasis> partition table.
<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel gpt</screen>
</para>
</listitem>
<listitem>
<para>
Add the <emphasis>root</emphasis> partition. This will fill the disk
except for the end part, where the swap will live, and the space left in
front (512MiB) which will be used by the boot partition.
<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB</screen>
</para>
</listitem>
<listitem>
<para>
Next, add a <emphasis>swap</emphasis> partition. The size required will
vary according to needs, here a 8GiB one is created.
<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen>
<note>
<para>
The swap partition size rules are no different than for other Linux
distributions.
</para>
</note>
</para>
</listitem>
<listitem>
<para>
Finally, the <emphasis>boot</emphasis> partition. NixOS by default uses
the ESP (EFI system partition) as its <emphasis>/boot</emphasis>
partition. It uses the initially reserved 512MiB at the start of the
disk.
<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
<prompt># </prompt>parted /dev/sda -- set 3 esp on</screen>
</para>
</listitem>
</orderedlist>
</para>
<para>
Once complete, you can follow with
<xref linkend="sec-installation-partitioning-formatting"/>.
</para>
</section>
<section xml:id="sec-installation-partitioning-MBR">
<title>Legacy Boot (MBR)</title>
<para>
Here's an example partition scheme for Legacy Boot, using
<filename>/dev/sda</filename> as the device.
<note>
<para>
You can safely ignore <command>parted</command>'s informational message
about needing to update /etc/fstab.
</para>
</note>
</para>
<para>
<orderedlist>
<listitem>
<para>
Create a <emphasis>MBR</emphasis> partition table.
<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel msdos</screen>
</para>
</listitem>
<listitem>
<para>
Add the <emphasis>root</emphasis> partition. This will fill the the disk
except for the end part, where the swap will live.
<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB</screen>
</para>
</listitem>
<listitem>
<para>
Finally, add a <emphasis>swap</emphasis> partition. The size required
will vary according to needs, here a 8GiB one is created.
<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen>
<note>
<para>
The swap partition size rules are no different than for other Linux
distributions.
</para>
</note>
</para>
</listitem>
</orderedlist>
</para>
<para>
Once complete, you can follow with
<xref linkend="sec-installation-partitioning-formatting"/>.
</para>
</section>
<section xml:id="sec-installation-partitioning-formatting">
<title>Formatting</title>
<para>
Use the following commands:
<itemizedlist>
<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>
<prompt># </prompt>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>. For example:
<screen>
<prompt># </prompt>mkswap -L swap /dev/sda2</screen>
</para>
</listitem>
<listitem>
<variablelist>
<varlistentry>
<term>
UEFI systems
</term>
<listitem>
<para>
For creating boot partitions: <command>mkfs.fat</command>. Again
it’s recommended to assign a label to the boot partition:
<option>-n <replaceable>label</replaceable></option>. For example:
<screen>
<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3</screen>
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
<listitem>
<para>
For creating LVM volumes, the LVM commands, e.g.,
<command>pvcreate</command>, <command>vgcreate</command>, and
<command>lvcreate</command>.
</para>
</listitem>
<listitem>
<para>
For creating software RAID devices, use <command>mdadm</command>.
</para>
</listitem>
</itemizedlist>
</para>
</section>
</section>
<section xml:id="sec-installation-installing">
<title>Installing</title>
<orderedlist>
<listitem>
<para>
Mount the target file system on which NixOS should be installed on
<filename>/mnt</filename>, e.g.
<screen>
<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt
</screen>
</para>
</listitem>
<listitem>
<variablelist>
<varlistentry>
<term>
UEFI systems
</term>
<listitem>
<para>
Mount the boot file system on <filename>/mnt/boot</filename>, e.g.
<screen>
<prompt># </prompt>mkdir -p /mnt/boot
<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot
</screen>
</para>
</listitem>
</varlistentry>
</variablelist>
</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.
<screen>
<prompt># </prompt>swapon /dev/sda2</screen>
</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>
<prompt># </prompt>nixos-generate-config --root /mnt</screen>
You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename>
to suit your needs:
<screen>
<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix
</screen>
If you’re using the graphical ISO image, other editors may be available
(such as <command>vim</command>). If you have network access, you can also
install other editors — for instance, you can install Emacs by running
<literal>nix-env -f '&lt;nixpkgs&gt;' -iA emacs</literal>.
</para>
<variablelist>
<varlistentry>
<term>
BIOS systems
</term>
<listitem>
<para>
You <emphasis>must</emphasis> set the option
<xref linkend="opt-boot.loader.grub.device"/> to specify on which disk
the GRUB boot loader is to be installed. Without it, NixOS cannot boot.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
UEFI systems
</term>
<listitem>
<para>
You <emphasis>must</emphasis> set the option
<xref linkend="opt-boot.loader.systemd-boot.enable"/> to
<literal>true</literal>. <command>nixos-generate-config</command>
should do this automatically for new configurations when booted in UEFI
mode.
</para>
<para>
You may want to look at the options starting with
<option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option>
and
<option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd-boot</link></option>
as well.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
If there are other operating systems running on the machine before
installing NixOS, the <xref linkend="opt-boot.loader.grub.useOSProber"/>
option can be set to <literal>true</literal> to automatically add them to
the grub menu.
</para>
<para>
If you need to configure networking for your machine the configuration
options are described in <xref linkend="sec-networking"/>. In particular,
while wifi is supported on the installation image, it is not enabled by
default in the configuration generated by
<command>nixos-generate-config</command>.
</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.) Additionally, you may want to look at
<link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware
configuration for known-hardware</link> at this point or after
installation.
</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 installation media 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>
</listitem>
<listitem>
<para>
Do the installation:
<screen>
<prompt># </prompt>nixos-install</screen>
This will install your system based on the configuration you provided.
If anything fails due to a configuration problem or any other issue
(such as a network outage while downloading binaries from the NixOS
binary cache), you can re-run <command>nixos-install</command> after
fixing your <filename>configuration.nix</filename>.
</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...
New password: ***
Retype new password: ***</screen>
<note>
<para>
For unattended installations, it is possible to use
<command>nixos-install --no-root-passwd</command> in order to disable
the password prompt entirely.
</para>
</note>
</para>
</listitem>
<listitem>
<para>
If everything went well:
<screen>
<prompt># </prompt>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 is added to the menu. This allows you to easily roll back to
a previous 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>
<prompt>$ </prompt>useradd -c 'Eelco Dolstra' -m eelco
<prompt>$ </prompt>passwd eelco</screen>
</para>
<para>
You may also want to install some software. This will be covered
in <xref linkend="sec-package-management" />.
</para>
</listitem>
</orderedlist>
</section>
<section xml:id="sec-installation-summary">
<title>Installation summary</title>
<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-partition-scheme-MBR">
<title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR)</title>
<screen language="commands">
<prompt># </prompt>parted /dev/sda -- mklabel msdos
<prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB
<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen>
</example>
<example xml:id="ex-partition-scheme-UEFI">
<title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI)</title>
<screen language="commands">
<prompt># </prompt>parted /dev/sda -- mklabel gpt
<prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB
<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
<prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
<prompt># </prompt>parted /dev/sda -- set 3 esp on</screen>
</example>
<example xml:id="ex-install-sequence">
<title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>
<para>
With a partitioned disk.
<screen language="commands">
<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1
<prompt># </prompt>mkswap -L swap /dev/sda2
<prompt># </prompt>swapon /dev/sda2
<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3 # <lineannotation>(for UEFI systems only)</lineannotation>
<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt
<prompt># </prompt>mkdir -p /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation>
<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation>
<prompt># </prompt>nixos-generate-config --root /mnt
<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix
<prompt># </prompt>nixos-install
<prompt># </prompt>reboot</screen>
</para>
</example>
<example xml:id='ex-config'>
<title>NixOS Configuration</title>
<programlisting>
{ config, pkgs, ... }: {
imports = [
# Include the results of the hardware scan.
./hardware-configuration.nix
];
<xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; # <lineannotation>(for BIOS systems only)</lineannotation>
<xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation>
# Note: setting fileSystems is generally not
# necessary, since nixos-generate-config figures them out
# automatically in hardware-configuration.nix.
#<link linkend="opt-fileSystems._name_.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos";
# Enable the OpenSSH server.
services.sshd.enable = true;
}
</programlisting>
</example>
</section>
<section xml:id="sec-installation-additional-notes">
<title>Additional installation notes</title>
<xi:include href="../from_md/installation/installing-usb.section.xml" />
<xi:include href="../from_md/installation/installing-pxe.section.xml" />
<xi:include href="../from_md/installation/installing-virtualbox-guest.section.xml" />
<xi:include href="../from_md/installation/installing-from-other-distro.section.xml" />
<xi:include href="../from_md/installation/installing-behind-a-proxy.section.xml" />
</section>
</chapter>