Merge pull request #137082 from bobby285271/markdown
nixos/doc: Convert more articles to CommonMark
This commit is contained in:
Jörg Thalheim
GitHub
commit
fc4247e827
37 changed files with 1988 additions and 1114 deletions
28
nixos/doc/manual/administration/containers.chapter.md
Normal file
28
nixos/doc/manual/administration/containers.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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>
|
||||
|
|
@ -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
12
nixos/doc/manual/administration/troubleshooting.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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
19
nixos/doc/manual/configuration/config-syntax.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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" />
|
||||
```
|
||||
|
|
@ -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
42
nixos/doc/manual/configuration/file-systems.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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
16
nixos/doc/manual/configuration/networking.chapter.md
Normal 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 -->
|
||||
|
|
@ -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
18
nixos/doc/manual/configuration/package-mgmt.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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
34
nixos/doc/manual/configuration/profiles.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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><nixpkgs/nixos/modules/profiles></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 = [
|
||||
<nixpkgs/nixos/modules/profiles/profile-name.nix>
|
||||
];
|
||||
</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>
|
||||
|
|
@ -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
13
nixos/doc/manual/development/nixos-tests.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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
166
nixos/doc/manual/development/writing-modules.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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."/data" =
|
||||
{ device = "/dev/disk/by-label/data";
|
||||
fsType = "ext4";
|
||||
};
|
||||
</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>"noauto"</literal> is present in
|
||||
<link linkend="opt-fileSystems._name_.options">options</link>.
|
||||
<literal>"noauto"</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 = [ "nofail" ];</literal>.
|
||||
</para>
|
||||
</note>
|
||||
<xi:include href="luks-file-systems.section.xml" />
|
||||
<xi:include href="sshfs-file-systems.section.xml" />
|
||||
</chapter>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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
38
nixos/doc/manual/from_md/configuration/profiles.chapter.xml
Normal 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><nixpkgs/nixos/modules/profiles></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 = [
|
||||
<nixpkgs/nixos/modules/profiles/profile-name.nix>
|
||||
];
|
||||
</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
14
nixos/doc/manual/from_md/development/nixos-tests.chapter.xml
Normal 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
196
nixos/doc/manual/from_md/development/writing-modules.chapter.xml
Normal 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 = "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;
|
||||
};
|
||||
};
|
||||
}
|
||||
</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
642
nixos/doc/manual/from_md/installation/installing.chapter.xml
Normal 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>
|
||||
> 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
|
||||
</programlisting>
|
||||
<para>
|
||||
For enterprise networks, for example
|
||||
<emphasis>eduroam</emphasis>, instead do:
|
||||
</para>
|
||||
<programlisting>
|
||||
> 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
|
||||
</programlisting>
|
||||
<para>
|
||||
When successfully connected, you should see a line such as this
|
||||
one
|
||||
</para>
|
||||
<programlisting>
|
||||
<3>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 '<nixpkgs>' -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 = "/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;
|
||||
}
|
||||
</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>
|
||||
|
|
@ -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
479
nixos/doc/manual/installation/installing.chapter.md
Normal 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" />
|
||||
```
|
||||
|
|
@ -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>> </prompt>add_network
|
||||
0
|
||||
<prompt>> </prompt>set_network 0 ssid "myhomenetwork"
|
||||
OK
|
||||
<prompt>> </prompt>set_network 0 psk "mypassword"
|
||||
OK
|
||||
<prompt>> </prompt>set_network 0 key_mgmt WPA-PSK
|
||||
OK
|
||||
<prompt>> </prompt>enable_network 0
|
||||
OK
|
||||
</programlisting>
|
||||
For enterprise networks, for example <emphasis>eduroam</emphasis>, instead do:
|
||||
<programlisting>
|
||||
<prompt>> </prompt>add_network
|
||||
0
|
||||
<prompt>> </prompt>set_network 0 ssid "eduroam"
|
||||
OK
|
||||
<prompt>> </prompt>set_network 0 identity "myname@example.com"
|
||||
OK
|
||||
<prompt>> </prompt>set_network 0 password "mypassword"
|
||||
OK
|
||||
<prompt>> </prompt>set_network 0 key_mgmt WPA-EAP
|
||||
OK
|
||||
<prompt>> </prompt>enable_network 0
|
||||
OK
|
||||
</programlisting>
|
||||
When successfully connected, you should see a line such as this one
|
||||
<programlisting>
|
||||
<3>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 '<nixpkgs>' -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>
|
||||
Loading…
Reference in a new issue