mirror of
https://github.com/SebastianWendel/nixpkgs.git
synced 2024-09-22 13:29:00 +02:00
Merge remote-tracking branch 'upstream/staging-next' into staging
This commit is contained in:
commit
9af75b49ec
|
@ -1324,6 +1324,12 @@
|
||||||
githubId = 7346933;
|
githubId = 7346933;
|
||||||
name = "betaboon";
|
name = "betaboon";
|
||||||
};
|
};
|
||||||
|
bew = {
|
||||||
|
email = "benoit.dechezelles@gmail.com";
|
||||||
|
github = "bew";
|
||||||
|
githubId = 9730330;
|
||||||
|
name = "Benoit de Chezelles";
|
||||||
|
};
|
||||||
bfortz = {
|
bfortz = {
|
||||||
email = "bernard.fortz@gmail.com";
|
email = "bernard.fortz@gmail.com";
|
||||||
github = "bfortz";
|
github = "bfortz";
|
||||||
|
@ -10278,6 +10284,12 @@
|
||||||
githubId = 8668915;
|
githubId = 8668915;
|
||||||
name = "Stephane Schitter";
|
name = "Stephane Schitter";
|
||||||
};
|
};
|
||||||
|
staccato = {
|
||||||
|
name = "staccato";
|
||||||
|
email = "moveq@riseup.net";
|
||||||
|
github = "staccato";
|
||||||
|
githubId = 86573128;
|
||||||
|
};
|
||||||
steell = {
|
steell = {
|
||||||
email = "steve@steellworks.com";
|
email = "steve@steellworks.com";
|
||||||
github = "Steell";
|
github = "Steell";
|
||||||
|
|
|
@ -16,7 +16,7 @@ If NixOS fails to boot, there are a number of kernel command line parameters tha
|
||||||
|
|
||||||
`boot.debug1mounts`
|
`boot.debug1mounts`
|
||||||
|
|
||||||
: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](options.html#opt-fileSystems._name_.neededForBoot) on a file system.
|
: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](#opt-fileSystems._name_.neededForBoot) on a file system.
|
||||||
|
|
||||||
`boot.trace`
|
`boot.trace`
|
||||||
|
|
||||||
|
|
62
nixos/doc/manual/administration/cleaning-store.chapter.md
Normal file
62
nixos/doc/manual/administration/cleaning-store.chapter.md
Normal file
|
@ -0,0 +1,62 @@
|
||||||
|
# Cleaning the Nix Store {#sec-nix-gc}
|
||||||
|
|
||||||
|
Nix has a purely functional model, meaning that packages are never
|
||||||
|
upgraded in place. Instead new versions of packages end up in a
|
||||||
|
different location in the Nix store (`/nix/store`). You should
|
||||||
|
periodically run Nix's *garbage collector* to remove old, unreferenced
|
||||||
|
packages. This is easy:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-collect-garbage
|
||||||
|
```
|
||||||
|
|
||||||
|
Alternatively, you can use a systemd unit that does the same in the
|
||||||
|
background:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# systemctl start nix-gc.service
|
||||||
|
```
|
||||||
|
|
||||||
|
You can tell NixOS in `configuration.nix` to run this unit automatically
|
||||||
|
at certain points in time, for instance, every night at 03:15:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
nix.gc.automatic = true;
|
||||||
|
nix.gc.dates = "03:15";
|
||||||
|
```
|
||||||
|
|
||||||
|
The commands above do not remove garbage collector roots, such as old
|
||||||
|
system configurations. Thus they do not remove the ability to roll back
|
||||||
|
to previous configurations. The following command deletes old roots,
|
||||||
|
removing the ability to roll back to them:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-collect-garbage -d
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also do this for specific profiles, e.g.
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that NixOS system configurations are stored in the profile
|
||||||
|
`/nix/var/nix/profiles/system`.
|
||||||
|
|
||||||
|
Another way to reclaim disk space (often as much as 40% of the size of
|
||||||
|
the Nix store) is to run Nix's store optimiser, which seeks out
|
||||||
|
identical files in the store and replaces them with hard links to a
|
||||||
|
single copy.
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-store --optimise
|
||||||
|
```
|
||||||
|
|
||||||
|
Since this command needs to read the entire Nix store, it can take quite
|
||||||
|
a while to finish.
|
||||||
|
|
||||||
|
## NixOS Boot Entries {#sect-nixos-gc-boot-entries}
|
||||||
|
|
||||||
|
If your `/boot` partition runs out of space, after clearing old profiles
|
||||||
|
you must rebuild your system with `nixos-rebuild` to update the `/boot`
|
||||||
|
partition and clear space.
|
|
@ -1,63 +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-nix-gc">
|
|
||||||
<title>Cleaning the Nix Store</title>
|
|
||||||
<para>
|
|
||||||
Nix has a purely functional model, meaning that packages are never upgraded
|
|
||||||
in place. Instead new versions of packages end up in a different location in
|
|
||||||
the Nix store (<filename>/nix/store</filename>). You should periodically run
|
|
||||||
Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced
|
|
||||||
packages. This is easy:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-collect-garbage
|
|
||||||
</screen>
|
|
||||||
Alternatively, you can use a systemd unit that does the same in the
|
|
||||||
background:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>systemctl start nix-gc.service
|
|
||||||
</screen>
|
|
||||||
You can tell NixOS in <filename>configuration.nix</filename> to run this unit
|
|
||||||
automatically at certain points in time, for instance, every night at 03:15:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-nix.gc.automatic"/> = true;
|
|
||||||
<xref linkend="opt-nix.gc.dates"/> = "03:15";
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The commands above do not remove garbage collector roots, such as old system
|
|
||||||
configurations. Thus they do not remove the ability to roll back to previous
|
|
||||||
configurations. The following command deletes old roots, removing the ability
|
|
||||||
to roll back to them:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-collect-garbage -d
|
|
||||||
</screen>
|
|
||||||
You can also do this for specific profiles, e.g.
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
|
|
||||||
</screen>
|
|
||||||
Note that NixOS system configurations are stored in the profile
|
|
||||||
<filename>/nix/var/nix/profiles/system</filename>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Another way to reclaim disk space (often as much as 40% of the size of the
|
|
||||||
Nix store) is to run Nix’s store optimiser, which seeks out identical files
|
|
||||||
in the store and replaces them with hard links to a single copy.
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-store --optimise
|
|
||||||
</screen>
|
|
||||||
Since this command needs to read the entire Nix store, it can take quite a
|
|
||||||
while to finish.
|
|
||||||
</para>
|
|
||||||
<section xml:id="sect-nixos-gc-boot-entries">
|
|
||||||
<title>NixOS Boot Entries</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If your <filename>/boot</filename> partition runs out of space, after
|
|
||||||
clearing old profiles you must rebuild your system with
|
|
||||||
<literal>nixos-rebuild</literal> to update the <filename>/boot</filename>
|
|
||||||
partition and clear space.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
</chapter>
|
|
|
@ -0,0 +1,44 @@
|
||||||
|
# Container Networking {#sec-container-networking}
|
||||||
|
|
||||||
|
When you create a container using `nixos-container create`, it gets it
|
||||||
|
own private IPv4 address in the range `10.233.0.0/16`. You can get the
|
||||||
|
container's IPv4 address as follows:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container show-ip foo
|
||||||
|
10.233.4.2
|
||||||
|
|
||||||
|
$ ping -c1 10.233.4.2
|
||||||
|
64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms
|
||||||
|
```
|
||||||
|
|
||||||
|
Networking is implemented using a pair of virtual Ethernet devices. The
|
||||||
|
network interface in the container is called `eth0`, while the matching
|
||||||
|
interface in the host is called `ve-container-name` (e.g., `ve-foo`).
|
||||||
|
The container has its own network namespace and the `CAP_NET_ADMIN`
|
||||||
|
capability, so it can perform arbitrary network configuration such as
|
||||||
|
setting up firewall rules, without affecting or having access to the
|
||||||
|
host's network.
|
||||||
|
|
||||||
|
By default, containers cannot talk to the outside network. If you want
|
||||||
|
that, you should set up Network Address Translation (NAT) rules on the
|
||||||
|
host to rewrite container traffic to use your external IP address. This
|
||||||
|
can be accomplished using the following configuration on the host:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.nat.enable = true;
|
||||||
|
networking.nat.internalInterfaces = ["ve-+"];
|
||||||
|
networking.nat.externalInterface = "eth0";
|
||||||
|
```
|
||||||
|
|
||||||
|
where `eth0` should be replaced with the desired external interface.
|
||||||
|
Note that `ve-+` is a wildcard that matches all container interfaces.
|
||||||
|
|
||||||
|
If you are using Network Manager, you need to explicitly prevent it from
|
||||||
|
managing container interfaces:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
You may need to restart your system for the changes to take effect.
|
|
@ -1,59 +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-container-networking">
|
|
||||||
<title>Container Networking</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
When you create a container using <literal>nixos-container create</literal>,
|
|
||||||
it gets it own private IPv4 address in the range
|
|
||||||
<literal>10.233.0.0/16</literal>. You can get the container’s IPv4 address
|
|
||||||
as follows:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container show-ip foo
|
|
||||||
10.233.4.2
|
|
||||||
|
|
||||||
<prompt>$ </prompt>ping -c1 10.233.4.2
|
|
||||||
64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Networking is implemented using a pair of virtual Ethernet devices. The
|
|
||||||
network interface in the container is called <literal>eth0</literal>, while
|
|
||||||
the matching interface in the host is called
|
|
||||||
<literal>ve-<replaceable>container-name</replaceable></literal> (e.g.,
|
|
||||||
<literal>ve-foo</literal>). The container has its own network namespace and
|
|
||||||
the <literal>CAP_NET_ADMIN</literal> capability, so it can perform arbitrary
|
|
||||||
network configuration such as setting up firewall rules, without affecting or
|
|
||||||
having access to the host’s network.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, containers cannot talk to the outside network. If you want that,
|
|
||||||
you should set up Network Address Translation (NAT) rules on the host to
|
|
||||||
rewrite container traffic to use your external IP address. This can be
|
|
||||||
accomplished using the following configuration on the host:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.nat.enable"/> = true;
|
|
||||||
<xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"];
|
|
||||||
<xref linkend="opt-networking.nat.externalInterface"/> = "eth0";
|
|
||||||
</programlisting>
|
|
||||||
where <literal>eth0</literal> should be replaced with the desired external
|
|
||||||
interface. Note that <literal>ve-+</literal> is a wildcard that matches all
|
|
||||||
container interfaces.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If you are using Network Manager, you need to explicitly prevent it from
|
|
||||||
managing container interfaces:
|
|
||||||
<programlisting>
|
|
||||||
networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You may need to restart your system for the changes to take effect.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -28,7 +28,7 @@
|
||||||
contrast, in the imperative approach, containers are configured and updated
|
contrast, in the imperative approach, containers are configured and updated
|
||||||
independently from the host system.
|
independently from the host system.
|
||||||
</para>
|
</para>
|
||||||
<xi:include href="imperative-containers.xml" />
|
<xi:include href="../from_md/administration/imperative-containers.section.xml" />
|
||||||
<xi:include href="declarative-containers.xml" />
|
<xi:include href="../from_md/administration/declarative-containers.section.xml" />
|
||||||
<xi:include href="container-networking.xml" />
|
<xi:include href="../from_md/administration/container-networking.section.xml" />
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
59
nixos/doc/manual/administration/control-groups.chapter.md
Normal file
59
nixos/doc/manual/administration/control-groups.chapter.md
Normal file
|
@ -0,0 +1,59 @@
|
||||||
|
# Control Groups {#sec-cgroups}
|
||||||
|
|
||||||
|
To keep track of the processes in a running system, systemd uses
|
||||||
|
*control groups* (cgroups). A control group is a set of processes used
|
||||||
|
to allocate resources such as CPU, memory or I/O bandwidth. There can be
|
||||||
|
multiple control group hierarchies, allowing each kind of resource to be
|
||||||
|
managed independently.
|
||||||
|
|
||||||
|
The command `systemd-cgls` lists all control groups in the `systemd`
|
||||||
|
hierarchy, which is what systemd uses to keep track of the processes
|
||||||
|
belonging to each service or user session:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ systemd-cgls
|
||||||
|
├─user
|
||||||
|
│ └─eelco
|
||||||
|
│ └─c1
|
||||||
|
│ ├─ 2567 -:0
|
||||||
|
│ ├─ 2682 kdeinit4: kdeinit4 Running...
|
||||||
|
│ ├─ ...
|
||||||
|
│ └─10851 sh -c less -R
|
||||||
|
└─system
|
||||||
|
├─httpd.service
|
||||||
|
│ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH
|
||||||
|
│ └─...
|
||||||
|
├─dhcpcd.service
|
||||||
|
│ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
|
||||||
|
└─ ...
|
||||||
|
```
|
||||||
|
|
||||||
|
Similarly, `systemd-cgls cpu` shows the cgroups in the CPU hierarchy,
|
||||||
|
which allows per-cgroup CPU scheduling priorities. By default, every
|
||||||
|
systemd service gets its own CPU cgroup, while all user sessions are in
|
||||||
|
the top-level CPU cgroup. This ensures, for instance, that a thousand
|
||||||
|
run-away processes in the `httpd.service` cgroup cannot starve the CPU
|
||||||
|
for one process in the `postgresql.service` cgroup. (By contrast, it
|
||||||
|
they were in the same cgroup, then the PostgreSQL process would get
|
||||||
|
1/1001 of the cgroup's CPU time.) You can limit a service's CPU share in
|
||||||
|
`configuration.nix`:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
systemd.services.httpd.serviceConfig.CPUShares = 512;
|
||||||
|
```
|
||||||
|
|
||||||
|
By default, every cgroup has 1024 CPU shares, so this will halve the CPU
|
||||||
|
allocation of the `httpd.service` cgroup.
|
||||||
|
|
||||||
|
There also is a `memory` hierarchy that controls memory allocation
|
||||||
|
limits; by default, all processes are in the top-level cgroup, so any
|
||||||
|
service or session can exhaust all available memory. Per-cgroup memory
|
||||||
|
limits can be specified in `configuration.nix`; for instance, to limit
|
||||||
|
`httpd.service` to 512 MiB of RAM (excluding swap):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
systemd.services.httpd.serviceConfig.MemoryLimit = "512M";
|
||||||
|
```
|
||||||
|
|
||||||
|
The command `systemd-cgtop` shows a continuously updated list of all
|
||||||
|
cgroups with their CPU and memory usage.
|
|
@ -1,65 +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-cgroups">
|
|
||||||
<title>Control Groups</title>
|
|
||||||
<para>
|
|
||||||
To keep track of the processes in a running system, systemd uses
|
|
||||||
<emphasis>control groups</emphasis> (cgroups). A control group is a set of
|
|
||||||
processes used to allocate resources such as CPU, memory or I/O bandwidth.
|
|
||||||
There can be multiple control group hierarchies, allowing each kind of
|
|
||||||
resource to be managed independently.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The command <command>systemd-cgls</command> lists all control groups in the
|
|
||||||
<literal>systemd</literal> hierarchy, which is what systemd uses to keep
|
|
||||||
track of the processes belonging to each service or user session:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>systemd-cgls
|
|
||||||
├─user
|
|
||||||
│ └─eelco
|
|
||||||
│ └─c1
|
|
||||||
│ ├─ 2567 -:0
|
|
||||||
│ ├─ 2682 kdeinit4: kdeinit4 Running...
|
|
||||||
│ ├─ <replaceable>...</replaceable>
|
|
||||||
│ └─10851 sh -c less -R
|
|
||||||
└─system
|
|
||||||
├─httpd.service
|
|
||||||
│ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH
|
|
||||||
│ └─<replaceable>...</replaceable>
|
|
||||||
├─dhcpcd.service
|
|
||||||
│ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
|
|
||||||
└─ <replaceable>...</replaceable>
|
|
||||||
</screen>
|
|
||||||
Similarly, <command>systemd-cgls cpu</command> shows the cgroups in the CPU
|
|
||||||
hierarchy, which allows per-cgroup CPU scheduling priorities. By default,
|
|
||||||
every systemd service gets its own CPU cgroup, while all user sessions are in
|
|
||||||
the top-level CPU cgroup. This ensures, for instance, that a thousand
|
|
||||||
run-away processes in the <literal>httpd.service</literal> cgroup cannot
|
|
||||||
starve the CPU for one process in the <literal>postgresql.service</literal>
|
|
||||||
cgroup. (By contrast, it they were in the same cgroup, then the PostgreSQL
|
|
||||||
process would get 1/1001 of the cgroup’s CPU time.) You can limit a
|
|
||||||
service’s CPU share in <filename>configuration.nix</filename>:
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512;
|
|
||||||
</programlisting>
|
|
||||||
By default, every cgroup has 1024 CPU shares, so this will halve the CPU
|
|
||||||
allocation of the <literal>httpd.service</literal> cgroup.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
There also is a <literal>memory</literal> hierarchy that controls memory
|
|
||||||
allocation limits; by default, all processes are in the top-level cgroup, so
|
|
||||||
any service or session can exhaust all available memory. Per-cgroup memory
|
|
||||||
limits can be specified in <filename>configuration.nix</filename>; for
|
|
||||||
instance, to limit <literal>httpd.service</literal> to 512 MiB of RAM
|
|
||||||
(excluding swap):
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.MemoryLimit = "512M";
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The command <command>systemd-cgtop</command> shows a continuously updated
|
|
||||||
list of all cgroups with their CPU and memory usage.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
|
@ -0,0 +1,48 @@
|
||||||
|
# Declarative Container Specification {#sec-declarative-containers}
|
||||||
|
|
||||||
|
You can also specify containers and their configuration in the host's
|
||||||
|
`configuration.nix`. For example, the following specifies that there
|
||||||
|
shall be a container named `database` running PostgreSQL:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
containers.database =
|
||||||
|
{ config =
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
{ services.postgresql.enable = true;
|
||||||
|
services.postgresql.package = pkgs.postgresql_9_6;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
If you run `nixos-rebuild switch`, the container will be built. If the
|
||||||
|
container was already running, it will be updated in place, without
|
||||||
|
rebooting. The container can be configured to start automatically by
|
||||||
|
setting `containers.database.autoStart = true` in its configuration.
|
||||||
|
|
||||||
|
By default, declarative containers share the network namespace of the
|
||||||
|
host, meaning that they can listen on (privileged) ports. However, they
|
||||||
|
cannot change the network configuration. You can give a container its
|
||||||
|
own network as follows:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
containers.database = {
|
||||||
|
privateNetwork = true;
|
||||||
|
hostAddress = "192.168.100.10";
|
||||||
|
localAddress = "192.168.100.11";
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
This gives the container a private virtual Ethernet interface with IP
|
||||||
|
address `192.168.100.11`, which is hooked up to a virtual Ethernet
|
||||||
|
interface on the host with IP address `192.168.100.10`. (See the next
|
||||||
|
section for details on container networking.)
|
||||||
|
|
||||||
|
To disable the container, just remove it from `configuration.nix` and
|
||||||
|
run `nixos-rebuild
|
||||||
|
switch`. Note that this will not delete the root directory of the
|
||||||
|
container in `/var/lib/containers`. Containers can be destroyed using
|
||||||
|
the imperative method: `nixos-container destroy foo`.
|
||||||
|
|
||||||
|
Declarative containers can be started and stopped using the
|
||||||
|
corresponding systemd service, e.g.
|
||||||
|
`systemctl start container@database`.
|
|
@ -1,60 +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-containers">
|
|
||||||
<title>Declarative Container Specification</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You can also specify containers and their configuration in the host’s
|
|
||||||
<filename>configuration.nix</filename>. For example, the following specifies
|
|
||||||
that there shall be a container named <literal>database</literal> running
|
|
||||||
PostgreSQL:
|
|
||||||
<programlisting>
|
|
||||||
containers.database =
|
|
||||||
{ config =
|
|
||||||
{ config, pkgs, ... }:
|
|
||||||
{ <xref linkend="opt-services.postgresql.enable"/> = true;
|
|
||||||
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_9_6;
|
|
||||||
};
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
If you run <literal>nixos-rebuild switch</literal>, the container will be
|
|
||||||
built. If the container was already running, it will be updated in place,
|
|
||||||
without rebooting. The container can be configured to start automatically by
|
|
||||||
setting <literal>containers.database.autoStart = true</literal> in its
|
|
||||||
configuration.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, declarative containers share the network namespace of the host,
|
|
||||||
meaning that they can listen on (privileged) ports. However, they cannot
|
|
||||||
change the network configuration. You can give a container its own network as
|
|
||||||
follows:
|
|
||||||
<programlisting>
|
|
||||||
containers.database = {
|
|
||||||
<link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true;
|
|
||||||
<link linkend="opt-containers._name_.hostAddress">hostAddress</link> = "192.168.100.10";
|
|
||||||
<link linkend="opt-containers._name_.localAddress">localAddress</link> = "192.168.100.11";
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
This gives the container a private virtual Ethernet interface with IP address
|
|
||||||
<literal>192.168.100.11</literal>, which is hooked up to a virtual Ethernet
|
|
||||||
interface on the host with IP address <literal>192.168.100.10</literal>. (See
|
|
||||||
the next section for details on container networking.)
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
To disable the container, just remove it from
|
|
||||||
<filename>configuration.nix</filename> and run <literal>nixos-rebuild
|
|
||||||
switch</literal>. Note that this will not delete the root directory of the
|
|
||||||
container in <literal>/var/lib/containers</literal>. Containers can be
|
|
||||||
destroyed using the imperative method: <literal>nixos-container destroy
|
|
||||||
foo</literal>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Declarative containers can be started and stopped using the corresponding
|
|
||||||
systemd service, e.g. <literal>systemctl start container@database</literal>.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
115
nixos/doc/manual/administration/imperative-containers.section.md
Normal file
115
nixos/doc/manual/administration/imperative-containers.section.md
Normal file
|
@ -0,0 +1,115 @@
|
||||||
|
# Imperative Container Management {#sec-imperative-containers}
|
||||||
|
|
||||||
|
We'll cover imperative container management using `nixos-container`
|
||||||
|
first. Be aware that container management is currently only possible as
|
||||||
|
`root`.
|
||||||
|
|
||||||
|
You create a container with identifier `foo` as follows:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container create foo
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates the container's root directory in `/var/lib/containers/foo`
|
||||||
|
and a small configuration file in `/etc/containers/foo.conf`. It also
|
||||||
|
builds the container's initial system configuration and stores it in
|
||||||
|
`/nix/var/nix/profiles/per-container/foo/system`. You can modify the
|
||||||
|
initial configuration of the container on the command line. For
|
||||||
|
instance, to create a container that has `sshd` running, with the given
|
||||||
|
public key for `root`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container create foo --config '
|
||||||
|
services.openssh.enable = true;
|
||||||
|
users.users.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
By default the next free address in the `10.233.0.0/16` subnet will be
|
||||||
|
chosen as container IP. This behavior can be altered by setting
|
||||||
|
`--host-address` and `--local-address`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container create test --config-file test-container.nix \
|
||||||
|
--local-address 10.235.1.2 --host-address 10.235.1.1
|
||||||
|
```
|
||||||
|
|
||||||
|
Creating a container does not start it. To start the container, run:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container start foo
|
||||||
|
```
|
||||||
|
|
||||||
|
This command will return as soon as the container has booted and has
|
||||||
|
reached `multi-user.target`. On the host, the container runs within a
|
||||||
|
systemd unit called `container@container-name.service`. Thus, if
|
||||||
|
something went wrong, you can get status info using `systemctl`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# systemctl status container@foo
|
||||||
|
```
|
||||||
|
|
||||||
|
If the container has started successfully, you can log in as root using
|
||||||
|
the `root-login` operation:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container root-login foo
|
||||||
|
[root@foo:~]#
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that only root on the host can do this (since there is no
|
||||||
|
authentication). You can also get a regular login prompt using the
|
||||||
|
`login` operation, which is available to all users on the host:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container login foo
|
||||||
|
foo login: alice
|
||||||
|
Password: ***
|
||||||
|
```
|
||||||
|
|
||||||
|
With `nixos-container run`, you can execute arbitrary commands in the
|
||||||
|
container:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container run foo -- uname -a
|
||||||
|
Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
|
||||||
|
```
|
||||||
|
|
||||||
|
There are several ways to change the configuration of the container.
|
||||||
|
First, on the host, you can edit
|
||||||
|
`/var/lib/container/name/etc/nixos/configuration.nix`, and run
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container update foo
|
||||||
|
```
|
||||||
|
|
||||||
|
This will build and activate the new configuration. You can also specify
|
||||||
|
a new configuration on the command line:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container update foo --config '
|
||||||
|
services.httpd.enable = true;
|
||||||
|
services.httpd.adminAddr = "foo@example.org";
|
||||||
|
networking.firewall.allowedTCPPorts = [ 80 ];
|
||||||
|
'
|
||||||
|
|
||||||
|
# curl http://$(nixos-container show-ip foo)/
|
||||||
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
|
||||||
|
```
|
||||||
|
|
||||||
|
However, note that this will overwrite the container's
|
||||||
|
`/etc/nixos/configuration.nix`.
|
||||||
|
|
||||||
|
Alternatively, you can change the configuration from within the
|
||||||
|
container itself by running `nixos-rebuild switch` inside the container.
|
||||||
|
Note that the container by default does not have a copy of the NixOS
|
||||||
|
channel, so you should run `nix-channel --update` first.
|
||||||
|
|
||||||
|
Containers can be stopped and started using `nixos-container
|
||||||
|
stop` and `nixos-container start`, respectively, or by using
|
||||||
|
`systemctl` on the container's service unit. To destroy a container,
|
||||||
|
including its file system, do
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-container destroy foo
|
||||||
|
```
|
|
@ -1,123 +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-imperative-containers">
|
|
||||||
<title>Imperative Container Management</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
We’ll cover imperative container management using
|
|
||||||
<command>nixos-container</command> first. Be aware that container management
|
|
||||||
is currently only possible as <literal>root</literal>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You create a container with identifier <literal>foo</literal> as follows:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container create <replaceable>foo</replaceable>
|
|
||||||
</screen>
|
|
||||||
This creates the container’s root directory in
|
|
||||||
<filename>/var/lib/containers/<replaceable>foo</replaceable></filename> and a small configuration file
|
|
||||||
in <filename>/etc/containers/<replaceable>foo</replaceable>.conf</filename>. It also builds the
|
|
||||||
container’s initial system configuration and stores it in
|
|
||||||
<filename>/nix/var/nix/profiles/per-container/<replaceable>foo</replaceable>/system</filename>. You can
|
|
||||||
modify the initial configuration of the container on the command line. For
|
|
||||||
instance, to create a container that has <command>sshd</command> running,
|
|
||||||
with the given public key for <literal>root</literal>:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container create <replaceable>foo</replaceable> --config '
|
|
||||||
<xref linkend="opt-services.openssh.enable"/> = true;
|
|
||||||
<link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"];
|
|
||||||
'
|
|
||||||
</screen>
|
|
||||||
By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen
|
|
||||||
as container IP. This behavior can be altered by setting <literal>--host-address</literal> and
|
|
||||||
<literal>--local-address</literal>:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container create test --config-file test-container.nix \
|
|
||||||
--local-address 10.235.1.2 --host-address 10.235.1.1
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Creating a container does not start it. To start the container, run:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container start <replaceable>foo</replaceable>
|
|
||||||
</screen>
|
|
||||||
This command will return as soon as the container has booted and has reached
|
|
||||||
<literal>multi-user.target</literal>. On the host, the container runs within
|
|
||||||
a systemd unit called
|
|
||||||
<literal>container@<replaceable>container-name</replaceable>.service</literal>.
|
|
||||||
Thus, if something went wrong, you can get status info using
|
|
||||||
<command>systemctl</command>:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>systemctl status container@<replaceable>foo</replaceable>
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If the container has started successfully, you can log in as root using the
|
|
||||||
<command>root-login</command> operation:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container root-login <replaceable>foo</replaceable>
|
|
||||||
<prompt>[root@foo:~]#</prompt>
|
|
||||||
</screen>
|
|
||||||
Note that only root on the host can do this (since there is no
|
|
||||||
authentication). You can also get a regular login prompt using the
|
|
||||||
<command>login</command> operation, which is available to all users on the
|
|
||||||
host:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container login <replaceable>foo</replaceable>
|
|
||||||
foo login: alice
|
|
||||||
Password: ***
|
|
||||||
</screen>
|
|
||||||
With <command>nixos-container run</command>, you can execute arbitrary
|
|
||||||
commands in the container:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container run <replaceable>foo</replaceable> -- uname -a
|
|
||||||
Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
There are several ways to change the configuration of the container. First,
|
|
||||||
on the host, you can edit
|
|
||||||
<literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>,
|
|
||||||
and run
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container update <replaceable>foo</replaceable>
|
|
||||||
</screen>
|
|
||||||
This will build and activate the new configuration. You can also specify a
|
|
||||||
new configuration on the command line:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container update <replaceable>foo</replaceable> --config '
|
|
||||||
<xref linkend="opt-services.httpd.enable"/> = true;
|
|
||||||
<xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org";
|
|
||||||
<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ];
|
|
||||||
'
|
|
||||||
|
|
||||||
<prompt># </prompt>curl http://$(nixos-container show-ip <replaceable>foo</replaceable>)/
|
|
||||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
|
|
||||||
</screen>
|
|
||||||
However, note that this will overwrite the container’s
|
|
||||||
<filename>/etc/nixos/configuration.nix</filename>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Alternatively, you can change the configuration from within the container
|
|
||||||
itself by running <command>nixos-rebuild switch</command> inside the
|
|
||||||
container. Note that the container by default does not have a copy of the
|
|
||||||
NixOS channel, so you should run <command>nix-channel --update</command>
|
|
||||||
first.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Containers can be stopped and started using <literal>nixos-container
|
|
||||||
stop</literal> and <literal>nixos-container start</literal>, respectively, or
|
|
||||||
by using <command>systemctl</command> on the container’s service unit. To
|
|
||||||
destroy a container, including its file system, do
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-container destroy <replaceable>foo</replaceable>
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
38
nixos/doc/manual/administration/logging.chapter.md
Normal file
38
nixos/doc/manual/administration/logging.chapter.md
Normal file
|
@ -0,0 +1,38 @@
|
||||||
|
# Logging {#sec-logging}
|
||||||
|
|
||||||
|
System-wide logging is provided by systemd's *journal*, which subsumes
|
||||||
|
traditional logging daemons such as syslogd and klogd. Log entries are
|
||||||
|
kept in binary files in `/var/log/journal/`. The command `journalctl`
|
||||||
|
allows you to see the contents of the journal. For example,
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ journalctl -b
|
||||||
|
```
|
||||||
|
|
||||||
|
shows all journal entries since the last reboot. (The output of
|
||||||
|
`journalctl` is piped into `less` by default.) You can use various
|
||||||
|
options and match operators to restrict output to messages of interest.
|
||||||
|
For instance, to get all messages from PostgreSQL:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ journalctl -u postgresql.service
|
||||||
|
-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --
|
||||||
|
...
|
||||||
|
Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down
|
||||||
|
-- Reboot --
|
||||||
|
Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET
|
||||||
|
Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections
|
||||||
|
```
|
||||||
|
|
||||||
|
Or to get all messages since the last reboot that have at least a
|
||||||
|
"critical" severity level:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ journalctl -b -p crit
|
||||||
|
Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]
|
||||||
|
Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1)
|
||||||
|
```
|
||||||
|
|
||||||
|
The system journal is readable by root and by users in the `wheel` and
|
||||||
|
`systemd-journal` groups. All users have a private journal that can be
|
||||||
|
read using `journalctl`.
|
|
@ -1,43 +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-logging">
|
|
||||||
<title>Logging</title>
|
|
||||||
<para>
|
|
||||||
System-wide logging is provided by systemd’s <emphasis>journal</emphasis>,
|
|
||||||
which subsumes traditional logging daemons such as syslogd and klogd. Log
|
|
||||||
entries are kept in binary files in <filename>/var/log/journal/</filename>.
|
|
||||||
The command <literal>journalctl</literal> allows you to see the contents of
|
|
||||||
the journal. For example,
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>journalctl -b
|
|
||||||
</screen>
|
|
||||||
shows all journal entries since the last reboot. (The output of
|
|
||||||
<command>journalctl</command> is piped into <command>less</command> by
|
|
||||||
default.) You can use various options and match operators to restrict output
|
|
||||||
to messages of interest. For instance, to get all messages from PostgreSQL:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>journalctl -u postgresql.service
|
|
||||||
-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --
|
|
||||||
...
|
|
||||||
Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down
|
|
||||||
-- Reboot --
|
|
||||||
Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET
|
|
||||||
Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections
|
|
||||||
</screen>
|
|
||||||
Or to get all messages since the last reboot that have at least a
|
|
||||||
“critical” severity level:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>journalctl -b -p crit
|
|
||||||
Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]
|
|
||||||
Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1)
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The system journal is readable by root and by users in the
|
|
||||||
<literal>wheel</literal> and <literal>systemd-journal</literal> groups. All
|
|
||||||
users have a private journal that can be read using
|
|
||||||
<command>journalctl</command>.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
11
nixos/doc/manual/administration/maintenance-mode.section.md
Normal file
11
nixos/doc/manual/administration/maintenance-mode.section.md
Normal file
|
@ -0,0 +1,11 @@
|
||||||
|
# Maintenance Mode {#sec-maintenance-mode}
|
||||||
|
|
||||||
|
You can enter rescue mode by running:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# systemctl rescue
|
||||||
|
```
|
||||||
|
|
||||||
|
This will eventually give you a single-user root shell. Systemd will
|
||||||
|
stop (almost) all system services. To get out of maintenance mode, just
|
||||||
|
exit from the rescue shell.
|
|
@ -1,16 +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-maintenance-mode">
|
|
||||||
<title>Maintenance Mode</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You can enter rescue mode by running:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>systemctl rescue</screen>
|
|
||||||
This will eventually give you a single-user root shell. Systemd will stop
|
|
||||||
(almost) all system services. To get out of maintenance mode, just exit from
|
|
||||||
the rescue shell.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
21
nixos/doc/manual/administration/network-problems.section.md
Normal file
21
nixos/doc/manual/administration/network-problems.section.md
Normal file
|
@ -0,0 +1,21 @@
|
||||||
|
# Network Problems {#sec-nix-network-issues}
|
||||||
|
|
||||||
|
Nix uses a so-called *binary cache* to optimise building a package from
|
||||||
|
source into downloading it as a pre-built binary. That is, whenever a
|
||||||
|
command like `nixos-rebuild` needs a path in the Nix store, Nix will try
|
||||||
|
to download that path from the Internet rather than build it from
|
||||||
|
source. The default binary cache is `https://cache.nixos.org/`. If this
|
||||||
|
cache is unreachable, Nix operations may take a long time due to HTTP
|
||||||
|
connection timeouts. You can disable the use of the binary cache by
|
||||||
|
adding `--option use-binary-caches false`, e.g.
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-rebuild switch --option use-binary-caches false
|
||||||
|
```
|
||||||
|
|
||||||
|
If you have an alternative binary cache at your disposal, you can use it
|
||||||
|
instead:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
|
||||||
|
```
|
|
@ -1,27 +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-nix-network-issues">
|
|
||||||
<title>Network Problems</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Nix uses a so-called <emphasis>binary cache</emphasis> to optimise building a
|
|
||||||
package from source into downloading it as a pre-built binary. That is,
|
|
||||||
whenever a command like <command>nixos-rebuild</command> needs a path in the
|
|
||||||
Nix store, Nix will try to download that path from the Internet rather than
|
|
||||||
build it from source. The default binary cache is
|
|
||||||
<uri>https://cache.nixos.org/</uri>. If this cache is unreachable, Nix
|
|
||||||
operations may take a long time due to HTTP connection timeouts. You can
|
|
||||||
disable the use of the binary cache by adding <option>--option
|
|
||||||
use-binary-caches false</option>, e.g.
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-rebuild switch --option use-binary-caches false
|
|
||||||
</screen>
|
|
||||||
If you have an alternative binary cache at your disposal, you can use it
|
|
||||||
instead:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-rebuild switch --option binary-caches <replaceable>http://my-cache.example.org/</replaceable>
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
30
nixos/doc/manual/administration/rebooting.chapter.md
Normal file
30
nixos/doc/manual/administration/rebooting.chapter.md
Normal file
|
@ -0,0 +1,30 @@
|
||||||
|
# Rebooting and Shutting Down {#sec-rebooting}
|
||||||
|
|
||||||
|
The system can be shut down (and automatically powered off) by doing:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# shutdown
|
||||||
|
```
|
||||||
|
|
||||||
|
This is equivalent to running `systemctl poweroff`.
|
||||||
|
|
||||||
|
To reboot the system, run
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# reboot
|
||||||
|
```
|
||||||
|
|
||||||
|
which is equivalent to `systemctl reboot`. Alternatively, you can
|
||||||
|
quickly reboot the system using `kexec`, which bypasses the BIOS by
|
||||||
|
directly loading the new kernel into memory:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# systemctl kexec
|
||||||
|
```
|
||||||
|
|
||||||
|
The machine can be suspended to RAM (if supported) using `systemctl suspend`,
|
||||||
|
and suspended to disk using `systemctl hibernate`.
|
||||||
|
|
||||||
|
These commands can be run by any user who is logged in locally, i.e. on
|
||||||
|
a virtual console or in X11; otherwise, the user is asked for
|
||||||
|
authentication.
|
|
@ -1,35 +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-rebooting">
|
|
||||||
<title>Rebooting and Shutting Down</title>
|
|
||||||
<para>
|
|
||||||
The system can be shut down (and automatically powered off) by doing:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>shutdown
|
|
||||||
</screen>
|
|
||||||
This is equivalent to running <command>systemctl poweroff</command>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To reboot the system, run
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>reboot
|
|
||||||
</screen>
|
|
||||||
which is equivalent to <command>systemctl reboot</command>. Alternatively,
|
|
||||||
you can quickly reboot the system using <literal>kexec</literal>, which
|
|
||||||
bypasses the BIOS by directly loading the new kernel into memory:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>systemctl kexec
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The machine can be suspended to RAM (if supported) using <command>systemctl
|
|
||||||
suspend</command>, and suspended to disk using <command>systemctl
|
|
||||||
hibernate</command>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
These commands can be run by any user who is logged in locally, i.e. on a
|
|
||||||
virtual console or in X11; otherwise, the user is asked for authentication.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
38
nixos/doc/manual/administration/rollback.section.md
Normal file
38
nixos/doc/manual/administration/rollback.section.md
Normal file
|
@ -0,0 +1,38 @@
|
||||||
|
# Rolling Back Configuration Changes {#sec-rollback}
|
||||||
|
|
||||||
|
After running `nixos-rebuild` to switch to a new configuration, you may
|
||||||
|
find that the new configuration doesn't work very well. In that case,
|
||||||
|
there are several ways to return to a previous configuration.
|
||||||
|
|
||||||
|
First, the GRUB boot manager allows you to boot into any previous
|
||||||
|
configuration that hasn't been garbage-collected. These configurations
|
||||||
|
can be found under the GRUB submenu "NixOS - All configurations". This
|
||||||
|
is especially useful if the new configuration fails to boot. After the
|
||||||
|
system has booted, you can make the selected configuration the default
|
||||||
|
for subsequent boots:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# /run/current-system/bin/switch-to-configuration boot
|
||||||
|
```
|
||||||
|
|
||||||
|
Second, you can switch to the previous configuration in a running
|
||||||
|
system:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-rebuild switch --rollback
|
||||||
|
```
|
||||||
|
|
||||||
|
This is equivalent to running:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch
|
||||||
|
```
|
||||||
|
|
||||||
|
where `N` is the number of the NixOS system configuration. To get a
|
||||||
|
list of the available configurations, do:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ ls -l /nix/var/nix/profiles/system-*-link
|
||||||
|
...
|
||||||
|
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
|
||||||
|
```
|
|
@ -1,41 +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-rollback">
|
|
||||||
<title>Rolling Back Configuration Changes</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
After running <command>nixos-rebuild</command> to switch to a new
|
|
||||||
configuration, you may find that the new configuration doesn’t work very
|
|
||||||
well. In that case, there are several ways to return to a previous
|
|
||||||
configuration.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
First, the GRUB boot manager allows you to boot into any previous
|
|
||||||
configuration that hasn’t been garbage-collected. These configurations can
|
|
||||||
be found under the GRUB submenu “NixOS - All configurations”. This is
|
|
||||||
especially useful if the new configuration fails to boot. After the system
|
|
||||||
has booted, you can make the selected configuration the default for
|
|
||||||
subsequent boots:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>/run/current-system/bin/switch-to-configuration boot</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Second, you can switch to the previous configuration in a running system:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-rebuild switch --rollback</screen>
|
|
||||||
This is equivalent to running:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>/nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
|
|
||||||
where <replaceable>N</replaceable> is the number of the NixOS system
|
|
||||||
configuration. To get a list of the available configurations, do:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>ls -l /nix/var/nix/profiles/system-*-link
|
|
||||||
<replaceable>...</replaceable>
|
|
||||||
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -10,12 +10,12 @@
|
||||||
such as how to use the <command>systemd</command> service manager.
|
such as how to use the <command>systemd</command> service manager.
|
||||||
</para>
|
</para>
|
||||||
</partintro>
|
</partintro>
|
||||||
<xi:include href="service-mgmt.xml" />
|
<xi:include href="../from_md/administration/service-mgmt.chapter.xml" />
|
||||||
<xi:include href="rebooting.xml" />
|
<xi:include href="../from_md/administration/rebooting.chapter.xml" />
|
||||||
<xi:include href="user-sessions.xml" />
|
<xi:include href="../from_md/administration/user-sessions.chapter.xml" />
|
||||||
<xi:include href="control-groups.xml" />
|
<xi:include href="../from_md/administration/control-groups.chapter.xml" />
|
||||||
<xi:include href="logging.xml" />
|
<xi:include href="../from_md/administration/logging.chapter.xml" />
|
||||||
<xi:include href="cleaning-store.xml" />
|
<xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
|
||||||
<xi:include href="containers.xml" />
|
<xi:include href="containers.xml" />
|
||||||
<xi:include href="troubleshooting.xml" />
|
<xi:include href="troubleshooting.xml" />
|
||||||
</part>
|
</part>
|
||||||
|
|
120
nixos/doc/manual/administration/service-mgmt.chapter.md
Normal file
120
nixos/doc/manual/administration/service-mgmt.chapter.md
Normal file
|
@ -0,0 +1,120 @@
|
||||||
|
# Service Management {#sec-systemctl}
|
||||||
|
|
||||||
|
In NixOS, all system services are started and monitored using the
|
||||||
|
systemd program. systemd is the "init" process of the system (i.e. PID
|
||||||
|
1), the parent of all other processes. It manages a set of so-called
|
||||||
|
"units", which can be things like system services (programs), but also
|
||||||
|
mount points, swap files, devices, targets (groups of units) and more.
|
||||||
|
Units can have complex dependencies; for instance, one unit can require
|
||||||
|
that another unit must be successfully started before the first unit can
|
||||||
|
be started. When the system boots, it starts a unit named
|
||||||
|
`default.target`; the dependencies of this unit cause all system
|
||||||
|
services to be started, file systems to be mounted, swap files to be
|
||||||
|
activated, and so on.
|
||||||
|
|
||||||
|
## Interacting with a running systemd {#sect-nixos-systemd-general}
|
||||||
|
|
||||||
|
The command `systemctl` is the main way to interact with `systemd`. The
|
||||||
|
following paragraphs demonstrate ways to interact with any OS running
|
||||||
|
systemd as init system. NixOS is of no exception. The [next section
|
||||||
|
](#sect-nixos-systemd-nixos) explains NixOS specific things worth
|
||||||
|
knowing.
|
||||||
|
|
||||||
|
Without any arguments, `systemctl` the status of active units:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ systemctl
|
||||||
|
-.mount loaded active mounted /
|
||||||
|
swapfile.swap loaded active active /swapfile
|
||||||
|
sshd.service loaded active running SSH Daemon
|
||||||
|
graphical.target loaded active active Graphical Interface
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
You can ask for detailed status information about a unit, for instance,
|
||||||
|
the PostgreSQL database service:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ systemctl status postgresql.service
|
||||||
|
postgresql.service - PostgreSQL Server
|
||||||
|
Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
|
||||||
|
Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago
|
||||||
|
Main PID: 2390 (postgres)
|
||||||
|
CGroup: name=systemd:/system/postgresql.service
|
||||||
|
├─2390 postgres
|
||||||
|
├─2418 postgres: writer process
|
||||||
|
├─2419 postgres: wal writer process
|
||||||
|
├─2420 postgres: autovacuum launcher process
|
||||||
|
├─2421 postgres: stats collector process
|
||||||
|
└─2498 postgres: zabbix zabbix [local] idle
|
||||||
|
|
||||||
|
Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET
|
||||||
|
Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections
|
||||||
|
Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started
|
||||||
|
Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that this shows the status of the unit (active and running), all
|
||||||
|
the processes belonging to the service, as well as the most recent log
|
||||||
|
messages from the service.
|
||||||
|
|
||||||
|
Units can be stopped, started or restarted:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# systemctl stop postgresql.service
|
||||||
|
# systemctl start postgresql.service
|
||||||
|
# systemctl restart postgresql.service
|
||||||
|
```
|
||||||
|
|
||||||
|
These operations are synchronous: they wait until the service has
|
||||||
|
finished starting or stopping (or has failed). Starting a unit will
|
||||||
|
cause the dependencies of that unit to be started as well (if
|
||||||
|
necessary).
|
||||||
|
|
||||||
|
## systemd in NixOS {#sect-nixos-systemd-nixos}
|
||||||
|
|
||||||
|
Packages in Nixpkgs sometimes provide systemd units with them, usually
|
||||||
|
in e.g `#pkg-out#/lib/systemd/`. Putting such a package in
|
||||||
|
`environment.systemPackages` doesn\'t make the service available to
|
||||||
|
users or the system.
|
||||||
|
|
||||||
|
In order to enable a systemd *system* service with provided upstream
|
||||||
|
package, use (e.g):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
systemd.packages = [ pkgs.packagekit ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Usually NixOS modules written by the community do the above, plus take
|
||||||
|
care of other details. If a module was written for a service you are
|
||||||
|
interested in, you\'d probably need only to use
|
||||||
|
`services.#name#.enable = true;`. These services are defined in
|
||||||
|
Nixpkgs\' [ `nixos/modules/` directory
|
||||||
|
](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules). In case
|
||||||
|
the service is simple enough, the above method should work, and start
|
||||||
|
the service on boot.
|
||||||
|
|
||||||
|
*User* systemd services on the other hand, should be treated
|
||||||
|
differently. Given a package that has a systemd unit file at
|
||||||
|
`#pkg-out#/lib/systemd/user/`, using [](#opt-systemd.packages) will
|
||||||
|
make you able to start the service via `systemctl --user start`, but it
|
||||||
|
won\'t start automatically on login. However, You can imperatively
|
||||||
|
enable it by adding the package\'s attribute to
|
||||||
|
[](#opt-systemd.packages) and then do this (e.g):
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ mkdir -p ~/.config/systemd/user/default.target.wants
|
||||||
|
$ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
|
||||||
|
$ systemctl --user daemon-reload
|
||||||
|
$ systemctl --user enable syncthing.service
|
||||||
|
```
|
||||||
|
|
||||||
|
If you are interested in a timer file, use `timers.target.wants` instead
|
||||||
|
of `default.target.wants` in the 1st and 2nd command.
|
||||||
|
|
||||||
|
Using `systemctl --user enable syncthing.service` instead of the above,
|
||||||
|
will work, but it\'ll use the absolute path of `syncthing.service` for
|
||||||
|
the symlink, and this path is in `/nix/store/.../lib/systemd/user/`.
|
||||||
|
Hence [garbage collection](#sec-nix-gc) will remove that file and you
|
||||||
|
will wind up with a broken symlink in your systemd configuration, which
|
||||||
|
in turn will not make the service / timer start on login.
|
|
@ -1,140 +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-systemctl">
|
|
||||||
<title>Service Management</title>
|
|
||||||
<para>
|
|
||||||
In NixOS, all system services are started and monitored using the systemd
|
|
||||||
program. systemd is the “init” process of the system (i.e. PID 1), the
|
|
||||||
parent of all other processes. It manages a set of so-called “units”,
|
|
||||||
which can be things like system services (programs), but also mount points,
|
|
||||||
swap files, devices, targets (groups of units) and more. Units can have
|
|
||||||
complex dependencies; for instance, one unit can require that another unit
|
|
||||||
must be successfully started before the first unit can be started. When the
|
|
||||||
system boots, it starts a unit named <literal>default.target</literal>; the
|
|
||||||
dependencies of this unit cause all system services to be started, file
|
|
||||||
systems to be mounted, swap files to be activated, and so on.
|
|
||||||
</para>
|
|
||||||
<section xml:id="sect-nixos-systemd-general">
|
|
||||||
<title>Interacting with a running systemd</title>
|
|
||||||
<para>
|
|
||||||
The command <command>systemctl</command> is the main way to interact with
|
|
||||||
<command>systemd</command>. The following paragraphs demonstrate ways to
|
|
||||||
interact with any OS running systemd as init system. NixOS is of no
|
|
||||||
exception. The <link xlink:href="#sect-nixos-systemd-nixos">next section
|
|
||||||
</link> explains NixOS specific things worth knowing.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Without any arguments, <literal>systmctl</literal> the status of active units:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>systemctl
|
|
||||||
-.mount loaded active mounted /
|
|
||||||
swapfile.swap loaded active active /swapfile
|
|
||||||
sshd.service loaded active running SSH Daemon
|
|
||||||
graphical.target loaded active active Graphical Interface
|
|
||||||
<replaceable>...</replaceable>
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
You can ask for detailed status information about a unit, for instance, the
|
|
||||||
PostgreSQL database service:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>systemctl status postgresql.service
|
|
||||||
postgresql.service - PostgreSQL Server
|
|
||||||
Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
|
|
||||||
Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago
|
|
||||||
Main PID: 2390 (postgres)
|
|
||||||
CGroup: name=systemd:/system/postgresql.service
|
|
||||||
├─2390 postgres
|
|
||||||
├─2418 postgres: writer process
|
|
||||||
├─2419 postgres: wal writer process
|
|
||||||
├─2420 postgres: autovacuum launcher process
|
|
||||||
├─2421 postgres: stats collector process
|
|
||||||
└─2498 postgres: zabbix zabbix [local] idle
|
|
||||||
|
|
||||||
Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET
|
|
||||||
Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections
|
|
||||||
Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started
|
|
||||||
Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
|
|
||||||
</screen>
|
|
||||||
Note that this shows the status of the unit (active and running), all the
|
|
||||||
processes belonging to the service, as well as the most recent log messages
|
|
||||||
from the service.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Units can be stopped, started or restarted:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>systemctl stop postgresql.service
|
|
||||||
<prompt># </prompt>systemctl start postgresql.service
|
|
||||||
<prompt># </prompt>systemctl restart postgresql.service
|
|
||||||
</screen>
|
|
||||||
These operations are synchronous: they wait until the service has finished
|
|
||||||
starting or stopping (or has failed). Starting a unit will cause the
|
|
||||||
dependencies of that unit to be started as well (if necessary).
|
|
||||||
</para>
|
|
||||||
<!-- TODO: document cgroups, draft:
|
|
||||||
each service and user session is a cgroup
|
|
||||||
|
|
||||||
- cgroup resource management -->
|
|
||||||
</section>
|
|
||||||
<section xml:id="sect-nixos-systemd-nixos">
|
|
||||||
<title>systemd in NixOS</title>
|
|
||||||
<para>
|
|
||||||
Packages in Nixpkgs sometimes provide systemd units with them, usually in
|
|
||||||
e.g <literal>#pkg-out#/lib/systemd/</literal>. Putting such a package in
|
|
||||||
<literal>environment.systemPackages</literal> doesn't make the service
|
|
||||||
available to users or the system.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
In order to enable a systemd <emphasis>system</emphasis> service with
|
|
||||||
provided upstream package, use (e.g):
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-systemd.packages"/> = [ pkgs.packagekit ];
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Usually NixOS modules written by the community do the above, plus take care of
|
|
||||||
other details. If a module was written for a service you are interested in,
|
|
||||||
you'd probably need only to use
|
|
||||||
<literal>services.#name#.enable = true;</literal>. These services are defined
|
|
||||||
in Nixpkgs'
|
|
||||||
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">
|
|
||||||
<literal>nixos/modules/</literal> directory </link>. In case the service is
|
|
||||||
simple enough, the above method should work, and start the service on boot.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<emphasis>User</emphasis> systemd services on the other hand, should be
|
|
||||||
treated differently. Given a package that has a systemd unit file at
|
|
||||||
<literal>#pkg-out#/lib/systemd/user/</literal>, using
|
|
||||||
<xref linkend="opt-systemd.packages"/> will make you able to start the service via
|
|
||||||
<literal>systemctl --user start</literal>, but it won't start automatically on login.
|
|
||||||
<!-- TODO: Document why systemd.packages doesn't work for user services or fix this.
|
|
||||||
https://github.com/NixOS/nixpkgs/blob/2cd6594a8710a801038af2b72348658f732ce84a/nixos/modules/system/boot/systemd-lib.nix#L177-L198
|
|
||||||
|
|
||||||
This has been talked over at https://discourse.nixos.org/t/how-to-enable-upstream-systemd-user-services-declaratively/7649/5
|
|
||||||
-->
|
|
||||||
However, You can imperatively enable it by adding the package's attribute to
|
|
||||||
<link linkend="opt-environment.systemPackages">
|
|
||||||
<literal>systemd.packages</literal></link> and then do this (e.g):
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>mkdir -p ~/.config/systemd/user/default.target.wants
|
|
||||||
<prompt>$ </prompt>ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
|
|
||||||
<prompt>$ </prompt>systemctl --user daemon-reload
|
|
||||||
<prompt>$ </prompt>systemctl --user enable syncthing.service
|
|
||||||
</screen>
|
|
||||||
If you are interested in a timer file, use <literal>timers.target.wants</literal>
|
|
||||||
instead of <literal>default.target.wants</literal> in the 1st and 2nd command.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Using <literal>systemctl --user enable syncthing.service</literal> instead of
|
|
||||||
the above, will work, but it'll use the absolute path of
|
|
||||||
<literal>syncthing.service</literal> for the symlink, and this path is in
|
|
||||||
<literal>/nix/store/.../lib/systemd/user/</literal>. Hence
|
|
||||||
<link xlink:href="#sec-nix-gc">garbage collection</link> will remove that file
|
|
||||||
and you will wind up with a broken symlink in your systemd configuration, which
|
|
||||||
in turn will not make the service / timer start on login.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
</chapter>
|
|
||||||
|
|
28
nixos/doc/manual/administration/store-corruption.section.md
Normal file
28
nixos/doc/manual/administration/store-corruption.section.md
Normal file
|
@ -0,0 +1,28 @@
|
||||||
|
# Nix Store Corruption {#sec-nix-store-corruption}
|
||||||
|
|
||||||
|
After a system crash, it's possible for files in the Nix store to become
|
||||||
|
corrupted. (For instance, the Ext4 file system has the tendency to
|
||||||
|
replace un-synced files with zero bytes.) NixOS tries hard to prevent
|
||||||
|
this from happening: it performs a `sync` before switching to a new
|
||||||
|
configuration, and Nix's database is fully transactional. If corruption
|
||||||
|
still occurs, you may be able to fix it automatically.
|
||||||
|
|
||||||
|
If the corruption is in a path in the closure of the NixOS system
|
||||||
|
configuration, you can fix it by doing
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-rebuild switch --repair
|
||||||
|
```
|
||||||
|
|
||||||
|
This will cause Nix to check every path in the closure, and if its
|
||||||
|
cryptographic hash differs from the hash recorded in Nix's database, the
|
||||||
|
path is rebuilt or redownloaded.
|
||||||
|
|
||||||
|
You can also scan the entire Nix store for corrupt paths:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nix-store --verify --check-contents --repair
|
||||||
|
```
|
||||||
|
|
||||||
|
Any corrupt paths will be redownloaded if they're available in a binary
|
||||||
|
cache; otherwise, they cannot be repaired.
|
|
@ -1,36 +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-nix-store-corruption">
|
|
||||||
<title>Nix Store Corruption</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
After a system crash, it’s possible for files in the Nix store to become
|
|
||||||
corrupted. (For instance, the Ext4 file system has the tendency to replace
|
|
||||||
un-synced files with zero bytes.) NixOS tries hard to prevent this from
|
|
||||||
happening: it performs a <command>sync</command> before switching to a new
|
|
||||||
configuration, and Nix’s database is fully transactional. If corruption
|
|
||||||
still occurs, you may be able to fix it automatically.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If the corruption is in a path in the closure of the NixOS system
|
|
||||||
configuration, you can fix it by doing
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-rebuild switch --repair
|
|
||||||
</screen>
|
|
||||||
This will cause Nix to check every path in the closure, and if its
|
|
||||||
cryptographic hash differs from the hash recorded in Nix’s database, the
|
|
||||||
path is rebuilt or redownloaded.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You can also scan the entire Nix store for corrupt paths:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nix-store --verify --check-contents --repair
|
|
||||||
</screen>
|
|
||||||
Any corrupt paths will be redownloaded if they’re available in a binary
|
|
||||||
cache; otherwise, they cannot be repaired.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -9,8 +9,8 @@
|
||||||
you manage your NixOS system.
|
you manage your NixOS system.
|
||||||
</para>
|
</para>
|
||||||
<xi:include href="../from_md/administration/boot-problems.section.xml" />
|
<xi:include href="../from_md/administration/boot-problems.section.xml" />
|
||||||
<xi:include href="maintenance-mode.xml" />
|
<xi:include href="../from_md/administration/maintenance-mode.section.xml" />
|
||||||
<xi:include href="rollback.xml" />
|
<xi:include href="../from_md/administration/rollback.section.xml" />
|
||||||
<xi:include href="store-corruption.xml" />
|
<xi:include href="../from_md/administration/store-corruption.section.xml" />
|
||||||
<xi:include href="network-problems.xml" />
|
<xi:include href="../from_md/administration/network-problems.section.xml" />
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
43
nixos/doc/manual/administration/user-sessions.chapter.md
Normal file
43
nixos/doc/manual/administration/user-sessions.chapter.md
Normal file
|
@ -0,0 +1,43 @@
|
||||||
|
# User Sessions {#sec-user-sessions}
|
||||||
|
|
||||||
|
Systemd keeps track of all users who are logged into the system (e.g. on
|
||||||
|
a virtual console or remotely via SSH). The command `loginctl` allows
|
||||||
|
querying and manipulating user sessions. For instance, to list all user
|
||||||
|
sessions:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ loginctl
|
||||||
|
SESSION UID USER SEAT
|
||||||
|
c1 500 eelco seat0
|
||||||
|
c3 0 root seat0
|
||||||
|
c4 500 alice
|
||||||
|
```
|
||||||
|
|
||||||
|
This shows that two users are logged in locally, while another is logged
|
||||||
|
in remotely. ("Seats" are essentially the combinations of displays and
|
||||||
|
input devices attached to the system; usually, there is only one seat.)
|
||||||
|
To get information about a session:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ loginctl session-status c3
|
||||||
|
c3 - root (0)
|
||||||
|
Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago
|
||||||
|
Leader: 2536 (login)
|
||||||
|
Seat: seat0; vc3
|
||||||
|
TTY: /dev/tty3
|
||||||
|
Service: login; type tty; class user
|
||||||
|
State: online
|
||||||
|
CGroup: name=systemd:/user/root/c3
|
||||||
|
├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --
|
||||||
|
├─10339 -bash
|
||||||
|
└─10355 w3m nixos.org
|
||||||
|
```
|
||||||
|
|
||||||
|
This shows that the user is logged in on virtual console 3. It also
|
||||||
|
lists the processes belonging to this session. Since systemd keeps track
|
||||||
|
of this, you can terminate a session in a way that ensures that all the
|
||||||
|
session's processes are gone:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# loginctl terminate-session c3
|
||||||
|
```
|
|
@ -1,45 +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-user-sessions">
|
|
||||||
<title>User Sessions</title>
|
|
||||||
<para>
|
|
||||||
Systemd keeps track of all users who are logged into the system (e.g. on a
|
|
||||||
virtual console or remotely via SSH). The command <command>loginctl</command>
|
|
||||||
allows querying and manipulating user sessions. For instance, to list all
|
|
||||||
user sessions:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>loginctl
|
|
||||||
SESSION UID USER SEAT
|
|
||||||
c1 500 eelco seat0
|
|
||||||
c3 0 root seat0
|
|
||||||
c4 500 alice
|
|
||||||
</screen>
|
|
||||||
This shows that two users are logged in locally, while another is logged in
|
|
||||||
remotely. (“Seats” are essentially the combinations of displays and input
|
|
||||||
devices attached to the system; usually, there is only one seat.) To get
|
|
||||||
information about a session:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>loginctl session-status c3
|
|
||||||
c3 - root (0)
|
|
||||||
Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago
|
|
||||||
Leader: 2536 (login)
|
|
||||||
Seat: seat0; vc3
|
|
||||||
TTY: /dev/tty3
|
|
||||||
Service: login; type tty; class user
|
|
||||||
State: online
|
|
||||||
CGroup: name=systemd:/user/root/c3
|
|
||||||
├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --
|
|
||||||
├─10339 -bash
|
|
||||||
└─10355 w3m nixos.org
|
|
||||||
</screen>
|
|
||||||
This shows that the user is logged in on virtual console 3. It also lists the
|
|
||||||
processes belonging to this session. Since systemd keeps track of this, you
|
|
||||||
can terminate a session in a way that ensures that all the session’s
|
|
||||||
processes are gone:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>loginctl terminate-session c3
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
|
@ -0,0 +1,13 @@
|
||||||
|
# Ad-Hoc Configuration {#ad-hoc-network-config}
|
||||||
|
|
||||||
|
You can use [](#opt-networking.localCommands) to
|
||||||
|
specify shell commands to be run at the end of `network-setup.service`. This
|
||||||
|
is useful for doing network configuration not covered by the existing NixOS
|
||||||
|
modules. For instance, to statically configure an IPv6 address:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.localCommands =
|
||||||
|
''
|
||||||
|
ip -6 addr add 2001:610:685:1::1/64 dev eth0
|
||||||
|
'';
|
||||||
|
```
|
|
@ -1,20 +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="ad-hoc-network-config">
|
|
||||||
<title>Ad-Hoc Configuration</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You can use <xref linkend="opt-networking.localCommands"/> to specify shell
|
|
||||||
commands to be run at the end of <literal>network-setup.service</literal>.
|
|
||||||
This is useful for doing network configuration not covered by the existing
|
|
||||||
NixOS modules. For instance, to statically configure an IPv6 address:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.localCommands"/> =
|
|
||||||
''
|
|
||||||
ip -6 addr add 2001:610:685:1::1/64 dev eth0
|
|
||||||
'';
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
51
nixos/doc/manual/configuration/ad-hoc-packages.section.md
Normal file
51
nixos/doc/manual/configuration/ad-hoc-packages.section.md
Normal file
|
@ -0,0 +1,51 @@
|
||||||
|
# Ad-Hoc Package Management {#sec-ad-hoc-packages}
|
||||||
|
|
||||||
|
With the command `nix-env`, you can install and uninstall packages from
|
||||||
|
the command line. For instance, to install Mozilla Thunderbird:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-env -iA nixos.thunderbird
|
||||||
|
```
|
||||||
|
|
||||||
|
If you invoke this as root, the package is installed in the Nix profile
|
||||||
|
`/nix/var/nix/profiles/default` and visible to all users of the system;
|
||||||
|
otherwise, the package ends up in
|
||||||
|
`/nix/var/nix/profiles/per-user/username/profile` and is not visible to
|
||||||
|
other users. The `-A` flag specifies the package by its attribute name;
|
||||||
|
without it, the package is installed by matching against its package
|
||||||
|
name (e.g. `thunderbird`). The latter is slower because it requires
|
||||||
|
matching against all available Nix packages, and is ambiguous if there
|
||||||
|
are multiple matching packages.
|
||||||
|
|
||||||
|
Packages come from the NixOS channel. You typically upgrade a package by
|
||||||
|
updating to the latest version of the NixOS channel:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-channel --update nixos
|
||||||
|
```
|
||||||
|
|
||||||
|
and then running `nix-env -i` again. Other packages in the profile are
|
||||||
|
*not* affected; this is the crucial difference with the declarative
|
||||||
|
style of package management, where running `nixos-rebuild switch` causes
|
||||||
|
all packages to be updated to their current versions in the NixOS
|
||||||
|
channel. You can however upgrade all packages for which there is a newer
|
||||||
|
version by doing:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-env -u '*'
|
||||||
|
```
|
||||||
|
|
||||||
|
A package can be uninstalled using the `-e` flag:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-env -e thunderbird
|
||||||
|
```
|
||||||
|
|
||||||
|
Finally, you can roll back an undesirable `nix-env` action:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-env --rollback
|
||||||
|
```
|
||||||
|
|
||||||
|
`nix-env` has many more flags. For details, see the nix-env(1) manpage or
|
||||||
|
the Nix manual.
|
|
@ -1,61 +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-ad-hoc-packages">
|
|
||||||
<title>Ad-Hoc Package Management</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
With the command <command>nix-env</command>, you can install and uninstall
|
|
||||||
packages from the command line. For instance, to install Mozilla Thunderbird:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen>
|
|
||||||
If you invoke this as root, the package is installed in the Nix profile
|
|
||||||
<filename>/nix/var/nix/profiles/default</filename> and visible to all users
|
|
||||||
of the system; otherwise, the package ends up in
|
|
||||||
<filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename>
|
|
||||||
and is not visible to other users. The <option>-A</option> flag specifies the
|
|
||||||
package by its attribute name; without it, the package is installed by
|
|
||||||
matching against its package name (e.g. <literal>thunderbird</literal>). The
|
|
||||||
latter is slower because it requires matching against all available Nix
|
|
||||||
packages, and is ambiguous if there are multiple matching packages.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Packages come from the NixOS channel. You typically upgrade a package by
|
|
||||||
updating to the latest version of the NixOS channel:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-channel --update nixos
|
|
||||||
</screen>
|
|
||||||
and then running <literal>nix-env -i</literal> again. Other packages in the
|
|
||||||
profile are <emphasis>not</emphasis> affected; this is the crucial difference
|
|
||||||
with the declarative style of package management, where running
|
|
||||||
<command>nixos-rebuild switch</command> causes all packages to be updated to
|
|
||||||
their current versions in the NixOS channel. You can however upgrade all
|
|
||||||
packages for which there is a newer version by doing:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-env -u '*'
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
A package can be uninstalled using the <option>-e</option> flag:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-env -e thunderbird
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Finally, you can roll back an undesirable <command>nix-env</command> action:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-env --rollback
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<command>nix-env</command> has many more flags. For details, see the
|
|
||||||
<citerefentry>
|
|
||||||
<refentrytitle>nix-env</refentrytitle>
|
|
||||||
<manvolnum>1</manvolnum></citerefentry> manpage or the Nix manual.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -0,0 +1,74 @@
|
||||||
|
# Adding Custom Packages {#sec-custom-packages}
|
||||||
|
|
||||||
|
It's possible that a package you need is not available in NixOS. In that
|
||||||
|
case, you can do two things. First, you can clone the Nixpkgs
|
||||||
|
repository, add the package to your clone, and (optionally) submit a
|
||||||
|
patch or pull request to have it accepted into the main Nixpkgs repository.
|
||||||
|
This is described in detail in the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).
|
||||||
|
In short, you clone Nixpkgs:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ git clone https://github.com/NixOS/nixpkgs
|
||||||
|
$ cd nixpkgs
|
||||||
|
```
|
||||||
|
|
||||||
|
Then you write and test the package as described in the Nixpkgs manual.
|
||||||
|
Finally, you add it to [](#opt-environment.systemPackages), e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
environment.systemPackages = [ pkgs.my-package ];
|
||||||
|
```
|
||||||
|
|
||||||
|
and you run `nixos-rebuild`, specifying your own Nixpkgs tree:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
|
||||||
|
```
|
||||||
|
|
||||||
|
The second possibility is to add the package outside of the Nixpkgs
|
||||||
|
tree. For instance, here is how you specify a build of the
|
||||||
|
[GNU Hello](https://www.gnu.org/software/hello/) package directly in
|
||||||
|
`configuration.nix`:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
environment.systemPackages =
|
||||||
|
let
|
||||||
|
my-hello = with pkgs; stdenv.mkDerivation rec {
|
||||||
|
name = "hello-2.8";
|
||||||
|
src = fetchurl {
|
||||||
|
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||||
|
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
in
|
||||||
|
[ my-hello ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Of course, you can also move the definition of `my-hello` into a
|
||||||
|
separate Nix expression, e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
environment.systemPackages = [ (import ./my-hello.nix) ];
|
||||||
|
```
|
||||||
|
|
||||||
|
where `my-hello.nix` contains:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
with import <nixpkgs> {}; # bring all of Nixpkgs into scope
|
||||||
|
|
||||||
|
stdenv.mkDerivation rec {
|
||||||
|
name = "hello-2.8";
|
||||||
|
src = fetchurl {
|
||||||
|
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||||
|
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This allows testing the package easily:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-build my-hello.nix
|
||||||
|
$ ./result/bin/hello
|
||||||
|
Hello, world!
|
||||||
|
```
|
|
@ -1,73 +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-custom-packages">
|
|
||||||
<title>Adding Custom Packages</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
It’s possible that a package you need is not available in NixOS. In that
|
|
||||||
case, you can do two things. First, you can clone the Nixpkgs repository, add
|
|
||||||
the package to your clone, and (optionally) submit a patch or pull request to
|
|
||||||
have it accepted into the main Nixpkgs repository. This is described in
|
|
||||||
detail in the <link
|
|
||||||
xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
|
|
||||||
manual</link>. In short, you clone Nixpkgs:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
|
|
||||||
<prompt>$ </prompt>cd nixpkgs
|
|
||||||
</screen>
|
|
||||||
Then you write and test the package as described in the Nixpkgs manual.
|
|
||||||
Finally, you add it to <literal>environment.systemPackages</literal>, e.g.
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];
|
|
||||||
</programlisting>
|
|
||||||
and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs
|
|
||||||
tree:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The second possibility is to add the package outside of the Nixpkgs tree. For
|
|
||||||
instance, here is how you specify a build of the
|
|
||||||
<link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link>
|
|
||||||
package directly in <filename>configuration.nix</filename>:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> =
|
|
||||||
let
|
|
||||||
my-hello = with pkgs; stdenv.mkDerivation rec {
|
|
||||||
name = "hello-2.8";
|
|
||||||
src = fetchurl {
|
|
||||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
|
||||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
in
|
|
||||||
[ my-hello ];
|
|
||||||
</programlisting>
|
|
||||||
Of course, you can also move the definition of <literal>my-hello</literal>
|
|
||||||
into a separate Nix expression, e.g.
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];
|
|
||||||
</programlisting>
|
|
||||||
where <filename>my-hello.nix</filename> contains:
|
|
||||||
<programlisting>
|
|
||||||
with import <nixpkgs> {}; # bring all of Nixpkgs into scope
|
|
||||||
|
|
||||||
stdenv.mkDerivation rec {
|
|
||||||
name = "hello-2.8";
|
|
||||||
src = fetchurl {
|
|
||||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
|
||||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
|
||||||
};
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
This allows testing the package easily:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-build my-hello.nix
|
|
||||||
<prompt>$ </prompt>./result/bin/hello
|
|
||||||
Hello, world!
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
175
nixos/doc/manual/configuration/config-file.section.md
Normal file
175
nixos/doc/manual/configuration/config-file.section.md
Normal file
|
@ -0,0 +1,175 @@
|
||||||
|
# NixOS Configuration File {#sec-configuration-file}
|
||||||
|
|
||||||
|
The NixOS configuration file generally looks like this:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
|
||||||
|
{ option definitions
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The first line (`{ config, pkgs, ... }:`) denotes that this is actually
|
||||||
|
a function that takes at least the two arguments `config` and `pkgs`.
|
||||||
|
(These are explained later, in chapter [](#sec-writing-modules)) The
|
||||||
|
function returns a *set* of option definitions (`{ ... }`).
|
||||||
|
These definitions have the form `name = value`, where `name` is the
|
||||||
|
name of an option and `value` is its value. For example,
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
|
||||||
|
{ services.httpd.enable = true;
|
||||||
|
services.httpd.adminAddr = "alice@example.org";
|
||||||
|
services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
defines a configuration with three option definitions that together
|
||||||
|
enable the Apache HTTP Server with `/webroot` as the document root.
|
||||||
|
|
||||||
|
Sets can be nested, and in fact dots in option names are shorthand for
|
||||||
|
defining a set containing another set. For instance,
|
||||||
|
[](#opt-services.httpd.enable) defines a set named
|
||||||
|
`services` that contains a set named `httpd`, which in turn contains an
|
||||||
|
option definition named `enable` with value `true`. This means that the
|
||||||
|
example above can also be written as:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
|
||||||
|
{ services = {
|
||||||
|
httpd = {
|
||||||
|
enable = true;
|
||||||
|
adminAddr = "alice@example.org";
|
||||||
|
virtualHosts = {
|
||||||
|
localhost = {
|
||||||
|
documentRoot = "/webroot";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
which may be more convenient if you have lots of option definitions that
|
||||||
|
share the same prefix (such as `services.httpd`).
|
||||||
|
|
||||||
|
NixOS checks your option definitions for correctness. For instance, if
|
||||||
|
you try to define an option that doesn't exist (that is, doesn't have a
|
||||||
|
corresponding *option declaration*), `nixos-rebuild` will give an error
|
||||||
|
like:
|
||||||
|
|
||||||
|
```plain
|
||||||
|
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
|
||||||
|
```
|
||||||
|
|
||||||
|
Likewise, values in option definitions must have a correct type. For
|
||||||
|
instance, `services.httpd.enable` must be a Boolean (`true` or `false`).
|
||||||
|
Trying to give it a value of another type, such as a string, will cause
|
||||||
|
an error:
|
||||||
|
|
||||||
|
```plain
|
||||||
|
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
|
||||||
|
```
|
||||||
|
|
||||||
|
Options have various types of values. The most important are:
|
||||||
|
|
||||||
|
Strings
|
||||||
|
|
||||||
|
: Strings are enclosed in double quotes, e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.hostName = "dexter";
|
||||||
|
```
|
||||||
|
|
||||||
|
Special characters can be escaped by prefixing them with a backslash
|
||||||
|
(e.g. `\"`).
|
||||||
|
|
||||||
|
Multi-line strings can be enclosed in *double single quotes*, e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.extraHosts =
|
||||||
|
''
|
||||||
|
127.0.0.2 other-localhost
|
||||||
|
10.0.0.1 server
|
||||||
|
'';
|
||||||
|
```
|
||||||
|
|
||||||
|
The main difference is that it strips from each line a number of
|
||||||
|
spaces equal to the minimal indentation of the string as a whole
|
||||||
|
(disregarding the indentation of empty lines), and that characters
|
||||||
|
like `"` and `\` are not special (making it more convenient for
|
||||||
|
including things like shell code). See more info about this in the
|
||||||
|
Nix manual [here](https://nixos.org/nix/manual/#ssec-values).
|
||||||
|
|
||||||
|
Booleans
|
||||||
|
|
||||||
|
: These can be `true` or `false`, e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.firewall.enable = true;
|
||||||
|
networking.firewall.allowPing = false;
|
||||||
|
```
|
||||||
|
|
||||||
|
Integers
|
||||||
|
|
||||||
|
: For example,
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
|
||||||
|
```
|
||||||
|
|
||||||
|
(Note that here the attribute name `net.ipv4.tcp_keepalive_time` is
|
||||||
|
enclosed in quotes to prevent it from being interpreted as a set
|
||||||
|
named `net` containing a set named `ipv4`, and so on. This is
|
||||||
|
because it's not a NixOS option but the literal name of a Linux
|
||||||
|
kernel setting.)
|
||||||
|
|
||||||
|
Sets
|
||||||
|
|
||||||
|
: Sets were introduced above. They are name/value pairs enclosed in
|
||||||
|
braces, as in the option definition
|
||||||
|
|
||||||
|
```nix
|
||||||
|
fileSystems."/boot" =
|
||||||
|
{ device = "/dev/sda1";
|
||||||
|
fsType = "ext4";
|
||||||
|
options = [ "rw" "data=ordered" "relatime" ];
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Lists
|
||||||
|
|
||||||
|
: The important thing to note about lists is that list elements are
|
||||||
|
separated by whitespace, like this:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
List elements can be any other type, e.g. sets:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Packages
|
||||||
|
|
||||||
|
: Usually, the packages you need are already part of the Nix Packages
|
||||||
|
collection, which is a set that can be accessed through the function
|
||||||
|
argument `pkgs`. Typical uses:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
environment.systemPackages =
|
||||||
|
[ pkgs.thunderbird
|
||||||
|
pkgs.emacs
|
||||||
|
];
|
||||||
|
|
||||||
|
services.postgresql.package = pkgs.postgresql_10;
|
||||||
|
```
|
||||||
|
|
||||||
|
The latter option definition changes the default PostgreSQL package
|
||||||
|
used by NixOS's PostgreSQL service to 10.x. For more information on
|
||||||
|
packages, including how to add new ones, see
|
||||||
|
[](#sec-custom-packages).
|
|
@ -1,216 +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-configuration-file">
|
|
||||||
<title>NixOS Configuration File</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The NixOS configuration file generally looks like this:
|
|
||||||
<programlisting>
|
|
||||||
{ config, pkgs, ... }:
|
|
||||||
|
|
||||||
{ <replaceable>option definitions</replaceable>
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this
|
|
||||||
is actually a function that takes at least the two arguments
|
|
||||||
<varname>config</varname> and <varname>pkgs</varname>. (These are explained
|
|
||||||
later, in chapter <xref linkend="sec-writing-modules" />) The function returns
|
|
||||||
a <emphasis>set</emphasis> of option definitions (<literal>{
|
|
||||||
<replaceable>...</replaceable> }</literal>). These definitions have the form
|
|
||||||
<literal><replaceable>name</replaceable> =
|
|
||||||
<replaceable>value</replaceable></literal>, where
|
|
||||||
<replaceable>name</replaceable> is the name of an option and
|
|
||||||
<replaceable>value</replaceable> is its value. For example,
|
|
||||||
<programlisting>
|
|
||||||
{ config, pkgs, ... }:
|
|
||||||
|
|
||||||
{ <xref linkend="opt-services.httpd.enable"/> = true;
|
|
||||||
<xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org";
|
|
||||||
<link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.localhost.documentRoot</link> = "/webroot";
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
defines a configuration with three option definitions that together enable
|
|
||||||
the Apache HTTP Server with <filename>/webroot</filename> as the document
|
|
||||||
root.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Sets can be nested, and in fact dots in option names are shorthand for
|
|
||||||
defining a set containing another set. For instance,
|
|
||||||
<xref linkend="opt-services.httpd.enable"/> defines a set named
|
|
||||||
<varname>services</varname> that contains a set named
|
|
||||||
<varname>httpd</varname>, which in turn contains an option definition named
|
|
||||||
<varname>enable</varname> with value <literal>true</literal>. This means that
|
|
||||||
the example above can also be written as:
|
|
||||||
<programlisting>
|
|
||||||
{ config, pkgs, ... }:
|
|
||||||
|
|
||||||
{ services = {
|
|
||||||
httpd = {
|
|
||||||
enable = true;
|
|
||||||
adminAddr = "alice@example.org";
|
|
||||||
virtualHosts = {
|
|
||||||
localhost = {
|
|
||||||
documentRoot = "/webroot";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
which may be more convenient if you have lots of option definitions that
|
|
||||||
share the same prefix (such as <literal>services.httpd</literal>).
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
NixOS checks your option definitions for correctness. For instance, if you
|
|
||||||
try to define an option that doesn’t exist (that is, doesn’t have a
|
|
||||||
corresponding <emphasis>option declaration</emphasis>),
|
|
||||||
<command>nixos-rebuild</command> will give an error like:
|
|
||||||
<screen>
|
|
||||||
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
|
|
||||||
</screen>
|
|
||||||
Likewise, values in option definitions must have a correct type. For
|
|
||||||
instance, <option>services.httpd.enable</option> must be a Boolean
|
|
||||||
(<literal>true</literal> or <literal>false</literal>). Trying to give it a
|
|
||||||
value of another type, such as a string, will cause an error:
|
|
||||||
<screen>
|
|
||||||
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Options have various types of values. The most important are:
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
Strings
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Strings are enclosed in double quotes, e.g.
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.hostName"/> = "dexter";
|
|
||||||
</programlisting>
|
|
||||||
Special characters can be escaped by prefixing them with a backslash
|
|
||||||
(e.g. <literal>\"</literal>).
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Multi-line strings can be enclosed in <emphasis>double single
|
|
||||||
quotes</emphasis>, e.g.
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.extraHosts"/> =
|
|
||||||
''
|
|
||||||
127.0.0.2 other-localhost
|
|
||||||
10.0.0.1 server
|
|
||||||
'';
|
|
||||||
</programlisting>
|
|
||||||
The main difference is that it strips from each line a number of spaces
|
|
||||||
equal to the minimal indentation of the string as a whole (disregarding
|
|
||||||
the indentation of empty lines), and that characters like
|
|
||||||
<literal>"</literal> and <literal>\</literal> are not special (making it
|
|
||||||
more convenient for including things like shell code). See more info
|
|
||||||
about this in the Nix manual
|
|
||||||
<link
|
|
||||||
xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
Booleans
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
These can be <literal>true</literal> or <literal>false</literal>, e.g.
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.firewall.enable"/> = true;
|
|
||||||
<xref linkend="opt-networking.firewall.allowPing"/> = false;
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
Integers
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
For example,
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
|
|
||||||
</programlisting>
|
|
||||||
(Note that here the attribute name
|
|
||||||
<literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to
|
|
||||||
prevent it from being interpreted as a set named <literal>net</literal>
|
|
||||||
containing a set named <literal>ipv4</literal>, and so on. This is
|
|
||||||
because it’s not a NixOS option but the literal name of a Linux kernel
|
|
||||||
setting.)
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
Sets
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Sets were introduced above. They are name/value pairs enclosed in braces,
|
|
||||||
as in the option definition
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-fileSystems"/>."/boot" =
|
|
||||||
{ device = "/dev/sda1";
|
|
||||||
fsType = "ext4";
|
|
||||||
options = [ "rw" "data=ordered" "relatime" ];
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
Lists
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The important thing to note about lists is that list elements are
|
|
||||||
separated by whitespace, like this:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
|
|
||||||
</programlisting>
|
|
||||||
List elements can be any other type, e.g. sets:
|
|
||||||
<programlisting>
|
|
||||||
swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
Packages
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Usually, the packages you need are already part of the Nix Packages
|
|
||||||
collection, which is a set that can be accessed through the function
|
|
||||||
argument <varname>pkgs</varname>. Typical uses:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> =
|
|
||||||
[ pkgs.thunderbird
|
|
||||||
pkgs.emacs
|
|
||||||
];
|
|
||||||
|
|
||||||
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10;
|
|
||||||
</programlisting>
|
|
||||||
The latter option definition changes the default PostgreSQL package used
|
|
||||||
by NixOS’s PostgreSQL service to 10.x. For more information on
|
|
||||||
packages, including how to add new ones, see
|
|
||||||
<xref linkend="sec-custom-packages"/>.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -18,8 +18,8 @@ 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
|
manual</link>, but here we give a short overview of the most important
|
||||||
constructs useful in NixOS configuration files.
|
constructs useful in NixOS configuration files.
|
||||||
</para>
|
</para>
|
||||||
<xi:include href="config-file.xml" />
|
<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/abstractions.section.xml" />
|
||||||
<xi:include href="modularity.xml" />
|
<xi:include href="../from_md/configuration/modularity.section.xml" />
|
||||||
<xi:include href="summary.xml" />
|
<xi:include href="../from_md/configuration/summary.section.xml" />
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
|
@ -15,17 +15,17 @@
|
||||||
</partintro>
|
</partintro>
|
||||||
<xi:include href="config-syntax.xml" />
|
<xi:include href="config-syntax.xml" />
|
||||||
<xi:include href="package-mgmt.xml" />
|
<xi:include href="package-mgmt.xml" />
|
||||||
<xi:include href="user-mgmt.xml" />
|
<xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />
|
||||||
<xi:include href="file-systems.xml" />
|
<xi:include href="file-systems.xml" />
|
||||||
<xi:include href="x-windows.xml" />
|
<xi:include href="../from_md/configuration/x-windows.chapter.xml" />
|
||||||
<xi:include href="wayland.xml" />
|
<xi:include href="../from_md/configuration/wayland.chapter.xml" />
|
||||||
<xi:include href="gpu-accel.xml" />
|
<xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />
|
||||||
<xi:include href="xfce.xml" />
|
<xi:include href="../from_md/configuration/xfce.chapter.xml" />
|
||||||
<xi:include href="networking.xml" />
|
<xi:include href="networking.xml" />
|
||||||
<xi:include href="linux-kernel.xml" />
|
<xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
|
||||||
<xi:include href="subversion.xml" />
|
<xi:include href="../from_md/configuration/subversion.chapter.xml" />
|
||||||
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
|
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
|
||||||
<xi:include href="profiles.xml" />
|
<xi:include href="profiles.xml" />
|
||||||
<xi:include href="kubernetes.xml" />
|
<xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
|
||||||
<!-- Apache; libvirtd virtualisation -->
|
<!-- Apache; libvirtd virtualisation -->
|
||||||
</part>
|
</part>
|
||||||
|
|
|
@ -0,0 +1,74 @@
|
||||||
|
# Customising Packages {#sec-customising-packages}
|
||||||
|
|
||||||
|
Some packages in Nixpkgs have options to enable or disable optional
|
||||||
|
functionality or change other aspects of the package. For instance, the
|
||||||
|
Firefox wrapper package (which provides Firefox with a set of plugins
|
||||||
|
such as the Adobe Flash player) has an option to enable the Google Talk
|
||||||
|
plugin. It can be set in `configuration.nix` as follows:
|
||||||
|
`nixpkgs.config.firefox.enableGoogleTalkPlugin = true;`
|
||||||
|
|
||||||
|
::: {.warning}
|
||||||
|
Unfortunately, Nixpkgs currently lacks a way to query available
|
||||||
|
configuration options.
|
||||||
|
:::
|
||||||
|
|
||||||
|
Apart from high-level options, it's possible to tweak a package in
|
||||||
|
almost arbitrary ways, such as changing or disabling dependencies of a
|
||||||
|
package. For instance, the Emacs package in Nixpkgs by default has a
|
||||||
|
dependency on GTK 2. If you want to build it against GTK 3, you can
|
||||||
|
specify that as follows:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
|
||||||
|
```
|
||||||
|
|
||||||
|
The function `override` performs the call to the Nix function that
|
||||||
|
produces Emacs, with the original arguments amended by the set of
|
||||||
|
arguments specified by you. So here the function argument `gtk` gets the
|
||||||
|
value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses
|
||||||
|
are necessary because in Nix, function application binds more weakly
|
||||||
|
than list construction, so without them,
|
||||||
|
[](#opt-environment.systemPackages)
|
||||||
|
would be a list with two elements.)
|
||||||
|
|
||||||
|
Even greater customisation is possible using the function
|
||||||
|
`overrideAttrs`. While the `override` mechanism above overrides the
|
||||||
|
arguments of a package function, `overrideAttrs` allows changing the
|
||||||
|
*attributes* passed to `mkDerivation`. This permits changing any aspect
|
||||||
|
of the package, such as the source code. For instance, if you want to
|
||||||
|
override the source code of Emacs, you can say:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
environment.systemPackages = [
|
||||||
|
(pkgs.emacs.overrideAttrs (oldAttrs: {
|
||||||
|
name = "emacs-25.0-pre";
|
||||||
|
src = /path/to/my/emacs/tree;
|
||||||
|
}))
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs`
|
||||||
|
and produces a new derivation in which the original's `name` and `src`
|
||||||
|
attribute have been replaced by the given values by re-calling
|
||||||
|
`stdenv.mkDerivation`. The original attributes are accessible via the
|
||||||
|
function argument, which is conventionally named `oldAttrs`.
|
||||||
|
|
||||||
|
The overrides shown above are not global. They do not affect the
|
||||||
|
original package; other packages in Nixpkgs continue to depend on the
|
||||||
|
original rather than the customised package. This means that if another
|
||||||
|
package in your system depends on the original package, you end up with
|
||||||
|
two instances of the package. If you want to have everything depend on
|
||||||
|
your customised instance, you can apply a *global* override as follows:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
nixpkgs.config.packageOverrides = pkgs:
|
||||||
|
{ emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
The effect of this definition is essentially equivalent to modifying the
|
||||||
|
`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs
|
||||||
|
that depends on `emacs` will be passed your customised instance.
|
||||||
|
(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides`
|
||||||
|
refers to the original rather than overridden instance, to prevent an
|
||||||
|
infinite recursion.)
|
|
@ -1,86 +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-customising-packages">
|
|
||||||
<title>Customising Packages</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Some packages in Nixpkgs have options to enable or disable optional
|
|
||||||
functionality or change other aspects of the package. For instance, the
|
|
||||||
Firefox wrapper package (which provides Firefox with a set of plugins such as
|
|
||||||
the Adobe Flash player) has an option to enable the Google Talk plugin. It
|
|
||||||
can be set in <filename>configuration.nix</filename> as follows: <filename>
|
|
||||||
nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<warning>
|
|
||||||
<para>
|
|
||||||
Unfortunately, Nixpkgs currently lacks a way to query available
|
|
||||||
configuration options.
|
|
||||||
</para>
|
|
||||||
</warning>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Apart from high-level options, it’s possible to tweak a package in almost
|
|
||||||
arbitrary ways, such as changing or disabling dependencies of a package. For
|
|
||||||
instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2.
|
|
||||||
If you want to build it against GTK 3, you can specify that as follows:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
|
|
||||||
</programlisting>
|
|
||||||
The function <varname>override</varname> performs the call to the Nix
|
|
||||||
function that produces Emacs, with the original arguments amended by the set
|
|
||||||
of arguments specified by you. So here the function argument
|
|
||||||
<varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing
|
|
||||||
Emacs to depend on GTK 3. (The parentheses are necessary because in Nix,
|
|
||||||
function application binds more weakly than list construction, so without
|
|
||||||
them, <xref linkend="opt-environment.systemPackages"/> would be a list with
|
|
||||||
two elements.)
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Even greater customisation is possible using the function
|
|
||||||
<varname>overrideAttrs</varname>. While the <varname>override</varname>
|
|
||||||
mechanism above overrides the arguments of a package function,
|
|
||||||
<varname>overrideAttrs</varname> allows changing the
|
|
||||||
<emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>.
|
|
||||||
This permits changing any aspect of the package, such as the source code. For
|
|
||||||
instance, if you want to override the source code of Emacs, you can say:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> = [
|
|
||||||
(pkgs.emacs.overrideAttrs (oldAttrs: {
|
|
||||||
name = "emacs-25.0-pre";
|
|
||||||
src = /path/to/my/emacs/tree;
|
|
||||||
}))
|
|
||||||
];
|
|
||||||
</programlisting>
|
|
||||||
Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by
|
|
||||||
<varname>pkgs.emacs</varname> and produces a new derivation in which the
|
|
||||||
original’s <literal>name</literal> and <literal>src</literal> attribute
|
|
||||||
have been replaced by the given values by re-calling
|
|
||||||
<literal>stdenv.mkDerivation</literal>. The original attributes are
|
|
||||||
accessible via the function argument, which is conventionally named
|
|
||||||
<varname>oldAttrs</varname>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The overrides shown above are not global. They do not affect the original
|
|
||||||
package; other packages in Nixpkgs continue to depend on the original rather
|
|
||||||
than the customised package. This means that if another package in your
|
|
||||||
system depends on the original package, you end up with two instances of the
|
|
||||||
package. If you want to have everything depend on your customised instance,
|
|
||||||
you can apply a <emphasis>global</emphasis> override as follows:
|
|
||||||
<screen>
|
|
||||||
nixpkgs.config.packageOverrides = pkgs:
|
|
||||||
{ emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
|
|
||||||
};
|
|
||||||
</screen>
|
|
||||||
The effect of this definition is essentially equivalent to modifying the
|
|
||||||
<literal>emacs</literal> attribute in the Nixpkgs source tree. Any package in
|
|
||||||
Nixpkgs that depends on <literal>emacs</literal> will be passed your
|
|
||||||
customised instance. (However, the value <literal>pkgs.emacs</literal> in
|
|
||||||
<varname>nixpkgs.config.packageOverrides</varname> refers to the original
|
|
||||||
rather than overridden instance, to prevent an infinite recursion.)
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -48,7 +48,7 @@ nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
|
||||||
<command>nixos-rebuild switch</command>.
|
<command>nixos-rebuild switch</command>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<xi:include href="customizing-packages.xml" />
|
<xi:include href="../from_md/configuration/customizing-packages.section.xml" />
|
||||||
|
|
||||||
<xi:include href="adding-custom-packages.xml" />
|
<xi:include href="../from_md/configuration/adding-custom-packages.section.xml" />
|
||||||
</section>
|
</section>
|
||||||
|
|
|
@ -53,6 +53,6 @@
|
||||||
"nofail" ];</literal>.
|
"nofail" ];</literal>.
|
||||||
</para>
|
</para>
|
||||||
</note>
|
</note>
|
||||||
<xi:include href="luks-file-systems.xml" />
|
<xi:include href="../from_md/configuration/luks-file-systems.section.xml" />
|
||||||
<xi:include href="../from_md/configuration/sshfs-file-systems.section.xml" />
|
<xi:include href="../from_md/configuration/sshfs-file-systems.section.xml" />
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
32
nixos/doc/manual/configuration/firewall.section.md
Normal file
32
nixos/doc/manual/configuration/firewall.section.md
Normal file
|
@ -0,0 +1,32 @@
|
||||||
|
# Firewall {#sec-firewall}
|
||||||
|
|
||||||
|
NixOS has a simple stateful firewall that blocks incoming connections
|
||||||
|
and other unexpected packets. The firewall applies to both IPv4 and IPv6
|
||||||
|
traffic. It is enabled by default. It can be disabled as follows:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.firewall.enable = false;
|
||||||
|
```
|
||||||
|
|
||||||
|
If the firewall is enabled, you can open specific TCP ports to the
|
||||||
|
outside world:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.firewall.allowedTCPPorts = [ 80 443 ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is
|
||||||
|
enabled (`services.openssh.enable = true`). UDP ports can be opened through
|
||||||
|
[](#opt-networking.firewall.allowedUDPPorts).
|
||||||
|
|
||||||
|
To open ranges of TCP ports:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.firewall.allowedTCPPortRanges = [
|
||||||
|
{ from = 4000; to = 4007; }
|
||||||
|
{ from = 8000; to = 8010; }
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
Similarly, UDP port ranges can be opened through
|
||||||
|
[](#opt-networking.firewall.allowedUDPPortRanges).
|
|
@ -1,37 +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-firewall">
|
|
||||||
<title>Firewall</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
NixOS has a simple stateful firewall that blocks incoming connections and
|
|
||||||
other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic.
|
|
||||||
It is enabled by default. It can be disabled as follows:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.firewall.enable"/> = false;
|
|
||||||
</programlisting>
|
|
||||||
If the firewall is enabled, you can open specific TCP ports to the outside
|
|
||||||
world:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 443 ];
|
|
||||||
</programlisting>
|
|
||||||
Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is
|
|
||||||
enabled (<option><xref linkend="opt-services.openssh.enable"/> =
|
|
||||||
true</option>). UDP ports can be opened through
|
|
||||||
<xref linkend="opt-networking.firewall.allowedUDPPorts"/>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
To open ranges of TCP ports:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.firewall.allowedTCPPortRanges"/> = [
|
|
||||||
{ from = 4000; to = 4007; }
|
|
||||||
{ from = 8000; to = 8010; }
|
|
||||||
];
|
|
||||||
</programlisting>
|
|
||||||
Similarly, UDP port ranges can be opened through
|
|
||||||
<xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
204
nixos/doc/manual/configuration/gpu-accel.chapter.md
Normal file
204
nixos/doc/manual/configuration/gpu-accel.chapter.md
Normal file
|
@ -0,0 +1,204 @@
|
||||||
|
# GPU acceleration {#sec-gpu-accel}
|
||||||
|
|
||||||
|
NixOS provides various APIs that benefit from GPU hardware acceleration,
|
||||||
|
such as VA-API and VDPAU for video playback; OpenGL and Vulkan for 3D
|
||||||
|
graphics; and OpenCL for general-purpose computing. This chapter
|
||||||
|
describes how to set up GPU hardware acceleration (as far as this is not
|
||||||
|
done automatically) and how to verify that hardware acceleration is
|
||||||
|
indeed used.
|
||||||
|
|
||||||
|
Most of the aforementioned APIs are agnostic with regards to which
|
||||||
|
display server is used. Consequently, these instructions should apply
|
||||||
|
both to the X Window System and Wayland compositors.
|
||||||
|
|
||||||
|
## OpenCL {#sec-gpu-accel-opencl}
|
||||||
|
|
||||||
|
[OpenCL](https://en.wikipedia.org/wiki/OpenCL) is a general compute API.
|
||||||
|
It is used by various applications such as Blender and Darktable to
|
||||||
|
accelerate certain operations.
|
||||||
|
|
||||||
|
OpenCL applications load drivers through the *Installable Client Driver*
|
||||||
|
(ICD) mechanism. In this mechanism, an ICD file specifies the path to
|
||||||
|
the OpenCL driver for a particular GPU family. In NixOS, there are two
|
||||||
|
ways to make ICD files visible to the ICD loader. The first is through
|
||||||
|
the `OCL_ICD_VENDORS` environment variable. This variable can contain a
|
||||||
|
directory which is scanned by the ICL loader for ICD files. For example:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ export \
|
||||||
|
OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/
|
||||||
|
```
|
||||||
|
|
||||||
|
The second mechanism is to add the OpenCL driver package to
|
||||||
|
[](#opt-hardware.opengl.extraPackages).
|
||||||
|
This links the ICD file under `/run/opengl-driver`, where it will be visible
|
||||||
|
to the ICD loader.
|
||||||
|
|
||||||
|
The proper installation of OpenCL drivers can be verified through the
|
||||||
|
`clinfo` command of the clinfo package. This command will report the
|
||||||
|
number of hardware devices that is found and give detailed information
|
||||||
|
for each device:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ clinfo | head -n3
|
||||||
|
Number of platforms 1
|
||||||
|
Platform Name AMD Accelerated Parallel Processing
|
||||||
|
Platform Vendor Advanced Micro Devices, Inc.
|
||||||
|
```
|
||||||
|
|
||||||
|
### AMD {#sec-gpu-accel-opencl-amd}
|
||||||
|
|
||||||
|
Modern AMD [Graphics Core
|
||||||
|
Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are
|
||||||
|
supported through the rocm-opencl-icd package. Adding this package to
|
||||||
|
[](#opt-hardware.opengl.extraPackages)
|
||||||
|
enables OpenCL support:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
hardware.opengl.extraPackages = [
|
||||||
|
rocm-opencl-icd
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
### Intel {#sec-gpu-accel-opencl-intel}
|
||||||
|
|
||||||
|
[Intel Gen8 and later
|
||||||
|
GPUs](https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8)
|
||||||
|
are supported by the Intel NEO OpenCL runtime that is provided by the
|
||||||
|
intel-compute-runtime package. For Gen7 GPUs, the deprecated Beignet
|
||||||
|
runtime can be used, which is provided by the beignet package. The
|
||||||
|
proprietary Intel OpenCL runtime, in the intel-ocl package, is an
|
||||||
|
alternative for Gen7 GPUs.
|
||||||
|
|
||||||
|
The intel-compute-runtime, beignet, or intel-ocl package can be added to
|
||||||
|
[](#opt-hardware.opengl.extraPackages)
|
||||||
|
to enable OpenCL support. For example, for Gen8 and later GPUs, the following
|
||||||
|
configuration can be used:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
hardware.opengl.extraPackages = [
|
||||||
|
intel-compute-runtime
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
## Vulkan {#sec-gpu-accel-vulkan}
|
||||||
|
|
||||||
|
[Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API)) is a graphics and
|
||||||
|
compute API for GPUs. It is used directly by games or indirectly though
|
||||||
|
compatibility layers like
|
||||||
|
[DXVK](https://github.com/doitsujin/dxvk/wiki).
|
||||||
|
|
||||||
|
By default, if [](#opt-hardware.opengl.driSupport)
|
||||||
|
is enabled, mesa is installed and provides Vulkan for supported hardware.
|
||||||
|
|
||||||
|
Similar to OpenCL, Vulkan drivers are loaded through the *Installable
|
||||||
|
Client Driver* (ICD) mechanism. ICD files for Vulkan are JSON files that
|
||||||
|
specify the path to the driver library and the supported Vulkan version.
|
||||||
|
All successfully loaded drivers are exposed to the application as
|
||||||
|
different GPUs. In NixOS, there are two ways to make ICD files visible
|
||||||
|
to Vulkan applications: an environment variable and a module option.
|
||||||
|
|
||||||
|
The first option is through the `VK_ICD_FILENAMES` environment variable.
|
||||||
|
This variable can contain multiple JSON files, separated by `:`. For
|
||||||
|
example:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ export \
|
||||||
|
VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json
|
||||||
|
```
|
||||||
|
|
||||||
|
The second mechanism is to add the Vulkan driver package to
|
||||||
|
[](#opt-hardware.opengl.extraPackages).
|
||||||
|
This links the ICD file under `/run/opengl-driver`, where it will be
|
||||||
|
visible to the ICD loader.
|
||||||
|
|
||||||
|
The proper installation of Vulkan drivers can be verified through the
|
||||||
|
`vulkaninfo` command of the vulkan-tools package. This command will
|
||||||
|
report the hardware devices and drivers found, in this example output
|
||||||
|
amdvlk and radv:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ vulkaninfo | grep GPU
|
||||||
|
GPU id : 0 (Unknown AMD GPU)
|
||||||
|
GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
|
||||||
|
...
|
||||||
|
GPU0:
|
||||||
|
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
|
||||||
|
deviceName = Unknown AMD GPU
|
||||||
|
GPU1:
|
||||||
|
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
|
||||||
|
```
|
||||||
|
|
||||||
|
A simple graphical application that uses Vulkan is `vkcube` from the
|
||||||
|
vulkan-tools package.
|
||||||
|
|
||||||
|
### AMD {#sec-gpu-accel-vulkan-amd}
|
||||||
|
|
||||||
|
Modern AMD [Graphics Core
|
||||||
|
Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are
|
||||||
|
supported through either radv, which is part of mesa, or the amdvlk
|
||||||
|
package. Adding the amdvlk package to
|
||||||
|
[](#opt-hardware.opengl.extraPackages)
|
||||||
|
makes amdvlk the default driver and hides radv and lavapipe from the device list.
|
||||||
|
A specific driver can be forced as follows:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
hardware.opengl.extraPackages = [
|
||||||
|
pkgs.amdvlk
|
||||||
|
];
|
||||||
|
|
||||||
|
# To enable Vulkan support for 32-bit applications, also add:
|
||||||
|
hardware.opengl.extraPackages32 = [
|
||||||
|
pkgs.driversi686Linux.amdvlk
|
||||||
|
];
|
||||||
|
|
||||||
|
# Force radv
|
||||||
|
environment.variables.AMD_VULKAN_ICD = "RADV";
|
||||||
|
# Or
|
||||||
|
environment.variables.VK_ICD_FILENAMES =
|
||||||
|
"/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common issues {#sec-gpu-accel-common-issues}
|
||||||
|
|
||||||
|
### User permissions {#sec-gpu-accel-common-issues-permissions}
|
||||||
|
|
||||||
|
Except where noted explicitly, it should not be necessary to adjust user
|
||||||
|
permissions to use these acceleration APIs. In the default
|
||||||
|
configuration, GPU devices have world-read/write permissions
|
||||||
|
(`/dev/dri/renderD*`) or are tagged as `uaccess` (`/dev/dri/card*`). The
|
||||||
|
access control lists of devices with the `uaccess` tag will be updated
|
||||||
|
automatically when a user logs in through `systemd-logind`. For example,
|
||||||
|
if the user *jane* is logged in, the access control list should look as
|
||||||
|
follows:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ getfacl /dev/dri/card0
|
||||||
|
# file: dev/dri/card0
|
||||||
|
# owner: root
|
||||||
|
# group: video
|
||||||
|
user::rw-
|
||||||
|
user:jane:rw-
|
||||||
|
group::rw-
|
||||||
|
mask::rw-
|
||||||
|
other::---
|
||||||
|
```
|
||||||
|
|
||||||
|
If you disabled (this functionality of) `systemd-logind`, you may need
|
||||||
|
to add the user to the `video` group and log in again.
|
||||||
|
|
||||||
|
### Mixing different versions of nixpkgs {#sec-gpu-accel-common-issues-mixing-nixpkgs}
|
||||||
|
|
||||||
|
The *Installable Client Driver* (ICD) mechanism used by OpenCL and
|
||||||
|
Vulkan loads runtimes into its address space using `dlopen`. Mixing an
|
||||||
|
ICD loader mechanism and runtimes from different version of nixpkgs may
|
||||||
|
not work. For example, if the ICD loader uses an older version of glibc
|
||||||
|
than the runtime, the runtime may not be loadable due to missing
|
||||||
|
symbols. Unfortunately, the loader will generally be quiet about such
|
||||||
|
issues.
|
||||||
|
|
||||||
|
If you suspect that you are running into library version mismatches
|
||||||
|
between an ICL loader and a runtime, you could run an application with
|
||||||
|
the `LD_DEBUG` variable set to get more diagnostic information. For
|
||||||
|
example, OpenCL can be tested with `LD_DEBUG=files clinfo`, which should
|
||||||
|
report missing symbols.
|
|
@ -1,262 +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-gpu-accel">
|
|
||||||
<title>GPU acceleration</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
NixOS provides various APIs that benefit from GPU hardware
|
|
||||||
acceleration, such as VA-API and VDPAU for video playback; OpenGL and
|
|
||||||
Vulkan for 3D graphics; and OpenCL for general-purpose computing.
|
|
||||||
This chapter describes how to set up GPU hardware acceleration (as far
|
|
||||||
as this is not done automatically) and how to verify that hardware
|
|
||||||
acceleration is indeed used.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Most of the aforementioned APIs are agnostic with regards to which
|
|
||||||
display server is used. Consequently, these instructions should apply
|
|
||||||
both to the X Window System and Wayland compositors.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<section xml:id="sec-gpu-accel-opencl">
|
|
||||||
<title>OpenCL</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<link xlink:href="https://en.wikipedia.org/wiki/OpenCL">OpenCL</link> is a
|
|
||||||
general compute API. It is used by various applications such as
|
|
||||||
Blender and Darktable to accelerate certain operations.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
OpenCL applications load drivers through the <emphasis>Installable Client
|
|
||||||
Driver</emphasis> (ICD) mechanism. In this mechanism, an ICD file
|
|
||||||
specifies the path to the OpenCL driver for a particular GPU family.
|
|
||||||
In NixOS, there are two ways to make ICD files visible to the ICD
|
|
||||||
loader. The first is through the <varname>OCL_ICD_VENDORS</varname>
|
|
||||||
environment variable. This variable can contain a directory which
|
|
||||||
is scanned by the ICL loader for ICD files. For example:
|
|
||||||
|
|
||||||
<screen><prompt>$</prompt> export \
|
|
||||||
OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The second mechanism is to add the OpenCL driver package to
|
|
||||||
<xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
|
|
||||||
ICD file under <filename>/run/opengl-driver</filename>, where it will
|
|
||||||
be visible to the ICD loader.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The proper installation of OpenCL drivers can be verified through
|
|
||||||
the <command>clinfo</command> command of the <package>clinfo</package>
|
|
||||||
package. This command will report the number of hardware devices
|
|
||||||
that is found and give detailed information for each device:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<screen><prompt>$</prompt> clinfo | head -n3
|
|
||||||
Number of platforms 1
|
|
||||||
Platform Name AMD Accelerated Parallel Processing
|
|
||||||
Platform Vendor Advanced Micro Devices, Inc.</screen>
|
|
||||||
|
|
||||||
<section xml:id="sec-gpu-accel-opencl-amd">
|
|
||||||
<title>AMD</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Modern AMD <link
|
|
||||||
xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
|
|
||||||
Core Next</link> (GCN) GPUs are supported through the
|
|
||||||
<package>rocm-opencl-icd</package> package. Adding this package to
|
|
||||||
<xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL
|
|
||||||
support:
|
|
||||||
|
|
||||||
<programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
|
|
||||||
rocm-opencl-icd
|
|
||||||
];</programlisting>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section xml:id="sec-gpu-accel-opencl-intel">
|
|
||||||
<title>Intel</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<link
|
|
||||||
xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8">Intel
|
|
||||||
Gen8 and later GPUs</link> are supported by the Intel NEO OpenCL
|
|
||||||
runtime that is provided by the
|
|
||||||
<package>intel-compute-runtime</package> package. For Gen7 GPUs,
|
|
||||||
the deprecated Beignet runtime can be used, which is provided
|
|
||||||
by the <package>beignet</package> package. The proprietary Intel
|
|
||||||
OpenCL runtime, in the <package>intel-ocl</package> package, is
|
|
||||||
an alternative for Gen7 GPUs.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <package>intel-compute-runtime</package>, <package>beignet</package>,
|
|
||||||
or <package>intel-ocl</package> package can be added to
|
|
||||||
<xref linkend="opt-hardware.opengl.extraPackages"/> to enable OpenCL
|
|
||||||
support. For example, for Gen8 and later GPUs, the following
|
|
||||||
configuration can be used:
|
|
||||||
|
|
||||||
<programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
|
|
||||||
intel-compute-runtime
|
|
||||||
];</programlisting>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section xml:id="sec-gpu-accel-vulkan">
|
|
||||||
<title>Vulkan</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<link xlink:href="https://en.wikipedia.org/wiki/Vulkan_(API)">Vulkan</link> is a
|
|
||||||
graphics and compute API for GPUs. It is used directly by games or indirectly though
|
|
||||||
compatibility layers like <link xlink:href="https://github.com/doitsujin/dxvk/wiki">DXVK</link>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, if <xref linkend="opt-hardware.opengl.driSupport"/> is enabled,
|
|
||||||
<package>mesa</package> is installed and provides Vulkan for supported hardware.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Similar to OpenCL, Vulkan drivers are loaded through the <emphasis>Installable Client
|
|
||||||
Driver</emphasis> (ICD) mechanism. ICD files for Vulkan are JSON files that specify
|
|
||||||
the path to the driver library and the supported Vulkan version. All successfully
|
|
||||||
loaded drivers are exposed to the application as different GPUs.
|
|
||||||
In NixOS, there are two ways to make ICD files visible to Vulkan applications: an
|
|
||||||
environment variable and a module option.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The first option is through the <varname>VK_ICD_FILENAMES</varname>
|
|
||||||
environment variable. This variable can contain multiple JSON files, separated by
|
|
||||||
<literal>:</literal>. For example:
|
|
||||||
|
|
||||||
<screen><prompt>$</prompt> export \
|
|
||||||
VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The second mechanism is to add the Vulkan driver package to
|
|
||||||
<xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
|
|
||||||
ICD file under <filename>/run/opengl-driver</filename>, where it will
|
|
||||||
be visible to the ICD loader.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The proper installation of Vulkan drivers can be verified through
|
|
||||||
the <command>vulkaninfo</command> command of the <package>vulkan-tools</package>
|
|
||||||
package. This command will report the hardware devices and drivers found,
|
|
||||||
in this example output amdvlk and radv:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<screen><prompt>$</prompt> vulkaninfo | grep GPU
|
|
||||||
GPU id : 0 (Unknown AMD GPU)
|
|
||||||
GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
|
|
||||||
...
|
|
||||||
GPU0:
|
|
||||||
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
|
|
||||||
deviceName = Unknown AMD GPU
|
|
||||||
GPU1:
|
|
||||||
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU</screen>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
A simple graphical application that uses Vulkan is <command>vkcube</command>
|
|
||||||
from the <package>vulkan-tools</package> package.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<section xml:id="sec-gpu-accel-vulkan-amd">
|
|
||||||
<title>AMD</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Modern AMD <link
|
|
||||||
xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
|
|
||||||
Core Next</link> (GCN) GPUs are supported through either radv, which is
|
|
||||||
part of <package>mesa</package>, or the <package>amdvlk</package> package.
|
|
||||||
Adding the <package>amdvlk</package> package to
|
|
||||||
<xref linkend="opt-hardware.opengl.extraPackages"/> makes amdvlk the
|
|
||||||
default driver and hides radv and lavapipe from the device list. A
|
|
||||||
specific driver can be forced as follows:
|
|
||||||
|
|
||||||
<programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
|
|
||||||
pkgs.<package>amdvlk</package>
|
|
||||||
];
|
|
||||||
|
|
||||||
# To enable Vulkan support for 32-bit applications, also add:
|
|
||||||
<xref linkend="opt-hardware.opengl.extraPackages32"/> = [
|
|
||||||
pkgs.driversi686Linux.<package>amdvlk</package>
|
|
||||||
];
|
|
||||||
|
|
||||||
# Force radv
|
|
||||||
<xref linkend="opt-environment.variables"/>.AMD_VULKAN_ICD = "RADV";
|
|
||||||
# Or
|
|
||||||
<xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES =
|
|
||||||
"/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section xml:id="sec-gpu-accel-common-issues">
|
|
||||||
<title>Common issues</title>
|
|
||||||
|
|
||||||
<section xml:id="sec-gpu-accel-common-issues-permissions">
|
|
||||||
<title>User permissions</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Except where noted explicitly, it should not be necessary to
|
|
||||||
adjust user permissions to use these acceleration APIs. In the default
|
|
||||||
configuration, GPU devices have world-read/write permissions
|
|
||||||
(<filename>/dev/dri/renderD*</filename>) or are tagged as
|
|
||||||
<code>uaccess</code> (<filename>/dev/dri/card*</filename>). The
|
|
||||||
access control lists of devices with the <varname>uaccess</varname>
|
|
||||||
tag will be updated automatically when a user logs in through
|
|
||||||
<command>systemd-logind</command>. For example, if the user
|
|
||||||
<emphasis>jane</emphasis> is logged in, the access control list
|
|
||||||
should look as follows:
|
|
||||||
|
|
||||||
<screen><prompt>$</prompt> getfacl /dev/dri/card0
|
|
||||||
# file: dev/dri/card0
|
|
||||||
# owner: root
|
|
||||||
# group: video
|
|
||||||
user::rw-
|
|
||||||
user:jane:rw-
|
|
||||||
group::rw-
|
|
||||||
mask::rw-
|
|
||||||
other::---</screen>
|
|
||||||
|
|
||||||
If you disabled (this functionality of) <command>systemd-logind</command>,
|
|
||||||
you may need to add the user to the <code>video</code> group and
|
|
||||||
log in again.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section xml:id="sec-gpu-accel-common-issues-mixing-nixpkgs">
|
|
||||||
<title>Mixing different versions of nixpkgs</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <emphasis>Installable Client Driver</emphasis> (ICD)
|
|
||||||
mechanism used by OpenCL and Vulkan loads runtimes into its address
|
|
||||||
space using <code>dlopen</code>. Mixing an ICD loader mechanism and
|
|
||||||
runtimes from different version of nixpkgs may not work. For example,
|
|
||||||
if the ICD loader uses an older version of <package>glibc</package>
|
|
||||||
than the runtime, the runtime may not be loadable due to
|
|
||||||
missing symbols. Unfortunately, the loader will generally be quiet
|
|
||||||
about such issues.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If you suspect that you are running into library version mismatches
|
|
||||||
between an ICL loader and a runtime, you could run an application with
|
|
||||||
the <code>LD_DEBUG</code> variable set to get more diagnostic
|
|
||||||
information. For example, OpenCL can be tested with
|
|
||||||
<code>LD_DEBUG=files clinfo</code>, which should report missing
|
|
||||||
symbols.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
</section>
|
|
||||||
</chapter>
|
|
35
nixos/doc/manual/configuration/ipv4-config.section.md
Normal file
35
nixos/doc/manual/configuration/ipv4-config.section.md
Normal file
|
@ -0,0 +1,35 @@
|
||||||
|
# IPv4 Configuration {#sec-ipv4}
|
||||||
|
|
||||||
|
By default, NixOS uses DHCP (specifically, `dhcpcd`) to automatically
|
||||||
|
configure network interfaces. However, you can configure an interface
|
||||||
|
manually as follows:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.interfaces.eth0.ipv4.addresses = [ {
|
||||||
|
address = "192.168.1.2";
|
||||||
|
prefixLength = 24;
|
||||||
|
} ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Typically you'll also want to set a default gateway and set of name
|
||||||
|
servers:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.defaultGateway = "192.168.1.1";
|
||||||
|
networking.nameservers = [ "8.8.8.8" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
::: {.note}
|
||||||
|
Statically configured interfaces are set up by the systemd service
|
||||||
|
`interface-name-cfg.service`. The default gateway and name server
|
||||||
|
configuration is performed by `network-setup.service`.
|
||||||
|
:::
|
||||||
|
|
||||||
|
The host name is set using [](#opt-networking.hostName):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.hostName = "cartman";
|
||||||
|
```
|
||||||
|
|
||||||
|
The default host name is `nixos`. Set it to the empty string (`""`) to
|
||||||
|
allow the DHCP server to provide the host name.
|
|
@ -1,43 +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-ipv4">
|
|
||||||
<title>IPv4 Configuration</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, NixOS uses DHCP (specifically, <command>dhcpcd</command>) to
|
|
||||||
automatically configure network interfaces. However, you can configure an
|
|
||||||
interface manually as follows:
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-networking.interfaces._name_.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ {
|
|
||||||
address = "192.168.1.2";
|
|
||||||
prefixLength = 24;
|
|
||||||
} ];
|
|
||||||
</programlisting>
|
|
||||||
Typically you’ll also want to set a default gateway and set of name
|
|
||||||
servers:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1";
|
|
||||||
<xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ];
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
Statically configured interfaces are set up by the systemd service
|
|
||||||
<replaceable>interface-name</replaceable><literal>-cfg.service</literal>.
|
|
||||||
The default gateway and name server configuration is performed by
|
|
||||||
<literal>network-setup.service</literal>.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The host name is set using <xref linkend="opt-networking.hostName"/>:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.hostName"/> = "cartman";
|
|
||||||
</programlisting>
|
|
||||||
The default host name is <literal>nixos</literal>. Set it to the empty string
|
|
||||||
(<literal>""</literal>) to allow the DHCP server to provide the host name.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
42
nixos/doc/manual/configuration/ipv6-config.section.md
Normal file
42
nixos/doc/manual/configuration/ipv6-config.section.md
Normal file
|
@ -0,0 +1,42 @@
|
||||||
|
# IPv6 Configuration {#sec-ipv6}
|
||||||
|
|
||||||
|
IPv6 is enabled by default. Stateless address autoconfiguration is used
|
||||||
|
to automatically assign IPv6 addresses to all interfaces, and Privacy
|
||||||
|
Extensions (RFC 4946) are enabled by default. You can adjust the default
|
||||||
|
for this by setting [](#opt-networking.tempAddresses). This option
|
||||||
|
may be overridden on a per-interface basis by
|
||||||
|
[](#opt-networking.interfaces._name_.tempAddress). You can disable
|
||||||
|
IPv6 support globally by setting:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.enableIPv6 = false;
|
||||||
|
```
|
||||||
|
|
||||||
|
You can disable IPv6 on a single interface using a normal sysctl (in
|
||||||
|
this example, we use interface `eth0`):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true;
|
||||||
|
```
|
||||||
|
|
||||||
|
As with IPv4 networking interfaces are automatically configured via
|
||||||
|
DHCPv6. You can configure an interface manually:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.interfaces.eth0.ipv6.addresses = [ {
|
||||||
|
address = "fe00:aa:bb:cc::2";
|
||||||
|
prefixLength = 64;
|
||||||
|
} ];
|
||||||
|
```
|
||||||
|
|
||||||
|
For configuring a gateway, optionally with explicitly specified
|
||||||
|
interface:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.defaultGateway6 = {
|
||||||
|
address = "fe00::1";
|
||||||
|
interface = "enp0s3";
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
See [](#sec-ipv4) for similar examples and additional information.
|
|
@ -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-ipv6">
|
|
||||||
<title>IPv6 Configuration</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
IPv6 is enabled by default. Stateless address autoconfiguration is used to
|
|
||||||
automatically assign IPv6 addresses to all interfaces, and Privacy
|
|
||||||
Extensions (RFC 4946) are enabled by default. You can adjust the default
|
|
||||||
for this by setting <xref linkend="opt-networking.tempAddresses"/>.
|
|
||||||
This option may be overridden on a per-interface basis by
|
|
||||||
<xref linkend="opt-networking.interfaces._name_.tempAddress"/>.
|
|
||||||
You can disable IPv6 support globally by setting:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.enableIPv6"/> = false;
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You can disable IPv6 on a single interface using a normal sysctl (in this
|
|
||||||
example, we use interface <varname>eth0</varname>):
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv6.conf.eth0.disable_ipv6" = true;
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
As with IPv4 networking interfaces are automatically configured via DHCPv6.
|
|
||||||
You can configure an interface manually:
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-networking.interfaces._name_.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ {
|
|
||||||
address = "fe00:aa:bb:cc::2";
|
|
||||||
prefixLength = 64;
|
|
||||||
} ];
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
For configuring a gateway, optionally with explicitly specified interface:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.defaultGateway6"/> = {
|
|
||||||
address = "fe00::1";
|
|
||||||
interface = "enp0s3";
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
See <xref linkend='sec-ipv4' /> for similar examples and additional
|
|
||||||
information.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
104
nixos/doc/manual/configuration/kubernetes.chapter.md
Normal file
104
nixos/doc/manual/configuration/kubernetes.chapter.md
Normal file
|
@ -0,0 +1,104 @@
|
||||||
|
# Kubernetes {#sec-kubernetes}
|
||||||
|
|
||||||
|
The NixOS Kubernetes module is a collective term for a handful of
|
||||||
|
individual submodules implementing the Kubernetes cluster components.
|
||||||
|
|
||||||
|
There are generally two ways of enabling Kubernetes on NixOS. One way is
|
||||||
|
to enable and configure cluster components appropriately by hand:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.kubernetes = {
|
||||||
|
apiserver.enable = true;
|
||||||
|
controllerManager.enable = true;
|
||||||
|
scheduler.enable = true;
|
||||||
|
addonManager.enable = true;
|
||||||
|
proxy.enable = true;
|
||||||
|
flannel.enable = true;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Another way is to assign cluster roles (\"master\" and/or \"node\") to
|
||||||
|
the host. This enables apiserver, controllerManager, scheduler,
|
||||||
|
addonManager, kube-proxy and etcd:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.kubernetes.roles = [ "master" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
While this will enable the kubelet and kube-proxy only:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.kubernetes.roles = [ "node" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Assigning both the master and node roles is usable if you want a single
|
||||||
|
node Kubernetes cluster for dev or testing purposes:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.kubernetes.roles = [ "master" "node" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: Assigning either role will also default both
|
||||||
|
[](#opt-services.kubernetes.flannel.enable)
|
||||||
|
and [](#opt-services.kubernetes.easyCerts)
|
||||||
|
to true. This sets up flannel as CNI and activates automatic PKI bootstrapping.
|
||||||
|
|
||||||
|
As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled
|
||||||
|
ports on kubernetes components. Thus, from NixOS 19.03 all plain HTTP
|
||||||
|
ports have been disabled by default. While opening insecure ports is
|
||||||
|
still possible, it is recommended not to bind these to other interfaces
|
||||||
|
than loopback. To re-enable the insecure port on the apiserver, see options:
|
||||||
|
[](#opt-services.kubernetes.apiserver.insecurePort) and
|
||||||
|
[](#opt-services.kubernetes.apiserver.insecureBindAddress)
|
||||||
|
|
||||||
|
::: {.note}
|
||||||
|
As of NixOS 19.03, it is mandatory to configure:
|
||||||
|
[](#opt-services.kubernetes.masterAddress).
|
||||||
|
The masterAddress must be resolveable and routeable by all cluster nodes.
|
||||||
|
In single node clusters, this can be set to `localhost`.
|
||||||
|
:::
|
||||||
|
|
||||||
|
Role-based access control (RBAC) authorization mode is enabled by
|
||||||
|
default. This means that anonymous requests to the apiserver secure port
|
||||||
|
will expectedly cause a permission denied error. All cluster components
|
||||||
|
must therefore be configured with x509 certificates for two-way tls
|
||||||
|
communication. The x509 certificate subject section determines the roles
|
||||||
|
and permissions granted by the apiserver to perform clusterwide or
|
||||||
|
namespaced operations. See also: [ Using RBAC
|
||||||
|
Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
|
||||||
|
|
||||||
|
The NixOS kubernetes module provides an option for automatic certificate
|
||||||
|
bootstrapping and configuration,
|
||||||
|
[](#opt-services.kubernetes.easyCerts).
|
||||||
|
The PKI bootstrapping process involves setting up a certificate authority (CA)
|
||||||
|
daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert
|
||||||
|
for the cluster, and uses the CA-cert for signing subordinate certs issued
|
||||||
|
to each of the cluster components. Subsequently, the certmgr daemon monitors
|
||||||
|
active certificates and renews them when needed. For single node Kubernetes
|
||||||
|
clusters, setting [](#opt-services.kubernetes.easyCerts)
|
||||||
|
= true is sufficient and no further action is required. For joining extra node
|
||||||
|
machines to an existing cluster on the other hand, establishing initial
|
||||||
|
trust is mandatory.
|
||||||
|
|
||||||
|
To add new nodes to the cluster: On any (non-master) cluster node where
|
||||||
|
[](#opt-services.kubernetes.easyCerts)
|
||||||
|
is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH.
|
||||||
|
Given a token on stdin, it will copy the token to the kubernetes secrets directory
|
||||||
|
and restart the certmgr service. As requested certificates are issued, the
|
||||||
|
script will restart kubernetes cluster components as needed for them to
|
||||||
|
pick up new keypairs.
|
||||||
|
|
||||||
|
::: {.note}
|
||||||
|
Multi-master (HA) clusters are not supported by the easyCerts module.
|
||||||
|
:::
|
||||||
|
|
||||||
|
In order to interact with an RBAC-enabled cluster as an administrator,
|
||||||
|
one needs to have cluster-admin privileges. By default, when easyCerts
|
||||||
|
is enabled, a cluster-admin kubeconfig file is generated and linked into
|
||||||
|
`/etc/kubernetes/cluster-admin.kubeconfig` as determined by
|
||||||
|
[](#opt-services.kubernetes.pki.etcClusterAdminKubeconfig).
|
||||||
|
`export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make
|
||||||
|
kubectl use this kubeconfig to access and authenticate the cluster. The
|
||||||
|
cluster-admin kubeconfig references an auto-generated keypair owned by
|
||||||
|
root. Thus, only root on the kubernetes master may obtain cluster-admin
|
||||||
|
rights by means of this file.
|
|
@ -1,112 +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-kubernetes">
|
|
||||||
<title>Kubernetes</title>
|
|
||||||
<para>
|
|
||||||
The NixOS Kubernetes module is a collective term for a handful of individual
|
|
||||||
submodules implementing the Kubernetes cluster components.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
There are generally two ways of enabling Kubernetes on NixOS. One way is to
|
|
||||||
enable and configure cluster components appropriately by hand:
|
|
||||||
<programlisting>
|
|
||||||
services.kubernetes = {
|
|
||||||
apiserver.enable = true;
|
|
||||||
controllerManager.enable = true;
|
|
||||||
scheduler.enable = true;
|
|
||||||
addonManager.enable = true;
|
|
||||||
proxy.enable = true;
|
|
||||||
flannel.enable = true;
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
Another way is to assign cluster roles ("master" and/or "node") to the host.
|
|
||||||
This enables apiserver, controllerManager, scheduler, addonManager,
|
|
||||||
kube-proxy and etcd:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-services.kubernetes.roles"/> = [ "master" ];
|
|
||||||
</programlisting>
|
|
||||||
While this will enable the kubelet and kube-proxy only:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-services.kubernetes.roles"/> = [ "node" ];
|
|
||||||
</programlisting>
|
|
||||||
Assigning both the master and node roles is usable if you want a single node
|
|
||||||
Kubernetes cluster for dev or testing purposes:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ];
|
|
||||||
</programlisting>
|
|
||||||
Note: Assigning either role will also default both
|
|
||||||
<xref linkend="opt-services.kubernetes.flannel.enable"/> and
|
|
||||||
<xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up
|
|
||||||
flannel as CNI and activates automatic PKI bootstrapping.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports
|
|
||||||
on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have
|
|
||||||
been disabled by default. While opening insecure ports is still possible, it
|
|
||||||
is recommended not to bind these to other interfaces than loopback. To
|
|
||||||
re-enable the insecure port on the apiserver, see options:
|
|
||||||
<xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and
|
|
||||||
<xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/>
|
|
||||||
</para>
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
As of NixOS 19.03, it is mandatory to configure:
|
|
||||||
<xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress
|
|
||||||
must be resolveable and routeable by all cluster nodes. In single node
|
|
||||||
clusters, this can be set to <literal>localhost</literal>.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
<para>
|
|
||||||
Role-based access control (RBAC) authorization mode is enabled by default.
|
|
||||||
This means that anonymous requests to the apiserver secure port will
|
|
||||||
expectedly cause a permission denied error. All cluster components must
|
|
||||||
therefore be configured with x509 certificates for two-way tls communication.
|
|
||||||
The x509 certificate subject section determines the roles and permissions
|
|
||||||
granted by the apiserver to perform clusterwide or namespaced operations. See
|
|
||||||
also:
|
|
||||||
<link
|
|
||||||
xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">
|
|
||||||
Using RBAC Authorization</link>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The NixOS kubernetes module provides an option for automatic certificate
|
|
||||||
bootstrapping and configuration,
|
|
||||||
<xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping
|
|
||||||
process involves setting up a certificate authority (CA) daemon (cfssl) on
|
|
||||||
the kubernetes master node. cfssl generates a CA-cert for the cluster, and
|
|
||||||
uses the CA-cert for signing subordinate certs issued to each of the cluster
|
|
||||||
components. Subsequently, the certmgr daemon monitors active certificates and
|
|
||||||
renews them when needed. For single node Kubernetes clusters, setting
|
|
||||||
<xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and
|
|
||||||
no further action is required. For joining extra node machines to an existing
|
|
||||||
cluster on the other hand, establishing initial trust is mandatory.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To add new nodes to the cluster: On any (non-master) cluster node where
|
|
||||||
<xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper
|
|
||||||
script <literal>nixos-kubernetes-node-join</literal> is available on PATH.
|
|
||||||
Given a token on stdin, it will copy the token to the kubernetes secrets
|
|
||||||
directory and restart the certmgr service. As requested certificates are
|
|
||||||
issued, the script will restart kubernetes cluster components as needed for
|
|
||||||
them to pick up new keypairs.
|
|
||||||
</para>
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
Multi-master (HA) clusters are not supported by the easyCerts module.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
<para>
|
|
||||||
In order to interact with an RBAC-enabled cluster as an administrator, one
|
|
||||||
needs to have cluster-admin privileges. By default, when easyCerts is
|
|
||||||
enabled, a cluster-admin kubeconfig file is generated and linked into
|
|
||||||
<literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as determined by
|
|
||||||
<xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig"/>.
|
|
||||||
<literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal>
|
|
||||||
will make kubectl use this kubeconfig to access and authenticate the cluster.
|
|
||||||
The cluster-admin kubeconfig references an auto-generated keypair owned by
|
|
||||||
root. Thus, only root on the kubernetes master may obtain cluster-admin
|
|
||||||
rights by means of this file.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
140
nixos/doc/manual/configuration/linux-kernel.chapter.md
Normal file
140
nixos/doc/manual/configuration/linux-kernel.chapter.md
Normal file
|
@ -0,0 +1,140 @@
|
||||||
|
# Linux Kernel {#sec-kernel-config}
|
||||||
|
|
||||||
|
You can override the Linux kernel and associated packages using the
|
||||||
|
option `boot.kernelPackages`. For instance, this selects the Linux 3.10
|
||||||
|
kernel:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10;
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that this not only replaces the kernel, but also packages that are
|
||||||
|
specific to the kernel version, such as the NVIDIA video drivers. This
|
||||||
|
ensures that driver packages are consistent with the kernel.
|
||||||
|
|
||||||
|
While `pkgs.linuxKernel.packages` contains all available kernel packages,
|
||||||
|
you may want to use one of the unversioned `pkgs.linuxPackages_*` aliases
|
||||||
|
such as `pkgs.linuxPackages_latest`, that are kept up to date with new
|
||||||
|
versions.
|
||||||
|
|
||||||
|
The default Linux kernel configuration should be fine for most users.
|
||||||
|
You can see the configuration of your current kernel with the following
|
||||||
|
command:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
zcat /proc/config.gz
|
||||||
|
```
|
||||||
|
|
||||||
|
If you want to change the kernel configuration, you can use the
|
||||||
|
`packageOverrides` feature (see [](#sec-customising-packages)). For
|
||||||
|
instance, to enable support for the kernel debugger KGDB:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
nixpkgs.config.packageOverrides = pkgs: pkgs.lib.recursiveUpdate pkgs {
|
||||||
|
linuxKernel.kernels.linux_5_10 = pkgs.linuxKernel.kernels.linux_5_10.override {
|
||||||
|
extraConfig = ''
|
||||||
|
KGDB y
|
||||||
|
'';
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
`extraConfig` takes a list of Linux kernel configuration options, one
|
||||||
|
per line. The name of the option should not include the prefix
|
||||||
|
`CONFIG_`. The option value is typically `y`, `n` or `m` (to build
|
||||||
|
something as a kernel module).
|
||||||
|
|
||||||
|
Kernel modules for hardware devices are generally loaded automatically
|
||||||
|
by `udev`. You can force a module to be loaded via
|
||||||
|
[](#opt-boot.kernelModules), e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
If the module is required early during the boot (e.g. to mount the root
|
||||||
|
file system), you can use [](#opt-boot.initrd.kernelModules):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.initrd.kernelModules = [ "cifs" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
This causes the specified modules and their dependencies to be added to
|
||||||
|
the initial ramdisk.
|
||||||
|
|
||||||
|
Kernel runtime parameters can be set through
|
||||||
|
[](#opt-boot.kernel.sysctl), e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
|
||||||
|
```
|
||||||
|
|
||||||
|
sets the kernel's TCP keepalive time to 120 seconds. To see the
|
||||||
|
available parameters, run `sysctl -a`.
|
||||||
|
|
||||||
|
## Customize your kernel {#sec-linux-config-customizing}
|
||||||
|
|
||||||
|
The first step before compiling the kernel is to generate an appropriate
|
||||||
|
`.config` configuration. Either you pass your own config via the
|
||||||
|
`configfile` setting of `linuxKernel.manualConfig`:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
custom-kernel = let base_kernel = linuxKernel.kernels.linux_4_9;
|
||||||
|
in super.linuxKernel.manualConfig {
|
||||||
|
inherit (super) stdenv hostPlatform;
|
||||||
|
inherit (base_kernel) src;
|
||||||
|
version = "${base_kernel.version}-custom";
|
||||||
|
|
||||||
|
configfile = /home/me/my_kernel_config;
|
||||||
|
allowImportFromDerivation = true;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
You can edit the config with this snippet (by default `make
|
||||||
|
menuconfig` won\'t work out of the box on nixos):
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
|
||||||
|
```
|
||||||
|
|
||||||
|
or you can let nixpkgs generate the configuration. Nixpkgs generates it
|
||||||
|
via answering the interactive kernel utility `make config`. The answers
|
||||||
|
depend on parameters passed to
|
||||||
|
`pkgs/os-specific/linux/kernel/generic.nix` (which you can influence by
|
||||||
|
overriding `extraConfig, autoModules,
|
||||||
|
modDirVersion, preferBuiltin, extraConfig`).
|
||||||
|
|
||||||
|
```nix
|
||||||
|
mptcp93.override ({
|
||||||
|
name="mptcp-local";
|
||||||
|
|
||||||
|
ignoreConfigErrors = true;
|
||||||
|
autoModules = false;
|
||||||
|
kernelPreferBuiltin = true;
|
||||||
|
|
||||||
|
enableParallelBuilding = true;
|
||||||
|
|
||||||
|
extraConfig = ''
|
||||||
|
DEBUG_KERNEL y
|
||||||
|
FRAME_POINTER y
|
||||||
|
KGDB y
|
||||||
|
KGDB_SERIAL_CONSOLE y
|
||||||
|
DEBUG_INFO y
|
||||||
|
'';
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Developing kernel modules {#sec-linux-config-developing-modules}
|
||||||
|
|
||||||
|
When developing kernel modules it\'s often convenient to run
|
||||||
|
edit-compile-run loop as quickly as possible. See below snippet as an
|
||||||
|
example of developing `mellanox` drivers.
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
|
||||||
|
$ nix-shell '<nixpkgs>' -A linuxPackages.kernel
|
||||||
|
$ unpackPhase
|
||||||
|
$ cd linux-*
|
||||||
|
$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
|
||||||
|
# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
|
||||||
|
```
|
|
@ -1,140 +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-kernel-config">
|
|
||||||
<title>Linux Kernel</title>
|
|
||||||
<para>
|
|
||||||
You can override the Linux kernel and associated packages using the option
|
|
||||||
<option>boot.kernelPackages</option>. For instance, this selects the Linux
|
|
||||||
3.10 kernel:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxKernel.packages.linux_3_10;
|
|
||||||
</programlisting>
|
|
||||||
Note that this not only replaces the kernel, but also packages that are
|
|
||||||
specific to the kernel version, such as the NVIDIA video drivers. This ensures that driver packages are consistent with the kernel.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
While <varname>pkgs.linuxKernel.packages</varname> contains all available kernel packages, you may want to use one of the unversioned <varname>pkgs.linuxPackages_*</varname> aliases such as <varname>pkgs.linuxPackages_latest</varname>, that are kept up to date with new versions.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The default Linux kernel configuration should be fine for most users. You can
|
|
||||||
see the configuration of your current kernel with the following command:
|
|
||||||
<programlisting>
|
|
||||||
zcat /proc/config.gz
|
|
||||||
</programlisting>
|
|
||||||
If you want to change the kernel configuration, you can use the
|
|
||||||
<option>packageOverrides</option> feature (see
|
|
||||||
<xref
|
|
||||||
linkend="sec-customising-packages" />). For instance, to enable support
|
|
||||||
for the kernel debugger KGDB:
|
|
||||||
<programlisting>
|
|
||||||
nixpkgs.config.packageOverrides = pkgs: pkgs.lib.recursiveUpdate pkgs {
|
|
||||||
linuxKernel.kernels.linux_5_10 = pkgs.linuxKernel.kernels.linux_5_10.override {
|
|
||||||
extraConfig = ''
|
|
||||||
KGDB y
|
|
||||||
'';
|
|
||||||
};
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
<varname>extraConfig</varname> takes a list of Linux kernel configuration
|
|
||||||
options, one per line. The name of the option should not include the prefix
|
|
||||||
<literal>CONFIG_</literal>. The option value is typically
|
|
||||||
<literal>y</literal>, <literal>n</literal> or <literal>m</literal> (to build
|
|
||||||
something as a kernel module).
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Kernel modules for hardware devices are generally loaded automatically by
|
|
||||||
<command>udev</command>. You can force a module to be loaded via
|
|
||||||
<xref linkend="opt-boot.kernelModules"/>, e.g.
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
|
|
||||||
</programlisting>
|
|
||||||
If the module is required early during the boot (e.g. to mount the root file
|
|
||||||
system), you can use <xref linkend="opt-boot.initrd.kernelModules"/>:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-boot.initrd.kernelModules"/> = [ "cifs" ];
|
|
||||||
</programlisting>
|
|
||||||
This causes the specified modules and their dependencies to be added to the
|
|
||||||
initial ramdisk.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Kernel runtime parameters can be set through
|
|
||||||
<xref linkend="opt-boot.kernel.sysctl"/>, e.g.
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120;
|
|
||||||
</programlisting>
|
|
||||||
sets the kernel’s TCP keepalive time to 120 seconds. To see the available
|
|
||||||
parameters, run <command>sysctl -a</command>.
|
|
||||||
</para>
|
|
||||||
<section xml:id="sec-linux-config-customizing">
|
|
||||||
<title>Customize your kernel</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The first step before compiling the kernel is to generate an appropriate
|
|
||||||
<literal>.config</literal> configuration. Either you pass your own config
|
|
||||||
via the <literal>configfile</literal> setting of
|
|
||||||
<literal>linuxKernel.manualConfig</literal>:
|
|
||||||
<screen><![CDATA[
|
|
||||||
custom-kernel = let base_kernel = linuxKernel.kernels.linux_4_9;
|
|
||||||
in super.linuxKernel.manualConfig {
|
|
||||||
inherit (super) stdenv hostPlatform;
|
|
||||||
inherit (base_kernel) src;
|
|
||||||
version = "${base_kernel.version}-custom";
|
|
||||||
|
|
||||||
configfile = /home/me/my_kernel_config;
|
|
||||||
allowImportFromDerivation = true;
|
|
||||||
};
|
|
||||||
]]></screen>
|
|
||||||
You can edit the config with this snippet (by default <command>make
|
|
||||||
menuconfig</command> won't work out of the box on nixos):
|
|
||||||
<screen><![CDATA[
|
|
||||||
nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
|
|
||||||
]]></screen>
|
|
||||||
or you can let nixpkgs generate the configuration. Nixpkgs generates it via
|
|
||||||
answering the interactive kernel utility <command>make config</command>. The
|
|
||||||
answers depend on parameters passed to
|
|
||||||
<filename>pkgs/os-specific/linux/kernel/generic.nix</filename> (which you
|
|
||||||
can influence by overriding <literal>extraConfig, autoModules,
|
|
||||||
modDirVersion, preferBuiltin, extraConfig</literal>).
|
|
||||||
<screen><![CDATA[
|
|
||||||
|
|
||||||
mptcp93.override ({
|
|
||||||
name="mptcp-local";
|
|
||||||
|
|
||||||
ignoreConfigErrors = true;
|
|
||||||
autoModules = false;
|
|
||||||
kernelPreferBuiltin = true;
|
|
||||||
|
|
||||||
enableParallelBuilding = true;
|
|
||||||
|
|
||||||
extraConfig = ''
|
|
||||||
DEBUG_KERNEL y
|
|
||||||
FRAME_POINTER y
|
|
||||||
KGDB y
|
|
||||||
KGDB_SERIAL_CONSOLE y
|
|
||||||
DEBUG_INFO y
|
|
||||||
'';
|
|
||||||
});
|
|
||||||
]]></screen>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
<section xml:id="sec-linux-config-developing-modules">
|
|
||||||
<title>Developing kernel modules</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
When developing kernel modules it's often convenient to run edit-compile-run
|
|
||||||
loop as quickly as possible. See below snippet as an example of developing
|
|
||||||
<literal>mellanox</literal> drivers.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
|
|
||||||
<prompt>$ </prompt>nix-shell '<nixpkgs>' -A linuxPackages.kernel
|
|
||||||
<prompt>$ </prompt>unpackPhase
|
|
||||||
<prompt>$ </prompt>cd linux-*
|
|
||||||
<prompt>$ </prompt>make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
|
|
||||||
<prompt># </prompt>insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
|
|
||||||
</screen>
|
|
||||||
</section>
|
|
||||||
</chapter>
|
|
77
nixos/doc/manual/configuration/luks-file-systems.section.md
Normal file
77
nixos/doc/manual/configuration/luks-file-systems.section.md
Normal file
|
@ -0,0 +1,77 @@
|
||||||
|
# LUKS-Encrypted File Systems {#sec-luks-file-systems}
|
||||||
|
|
||||||
|
NixOS supports file systems that are encrypted using *LUKS* (Linux
|
||||||
|
Unified Key Setup). For example, here is how you create an encrypted
|
||||||
|
Ext4 file system on the device
|
||||||
|
`/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d
|
||||||
|
|
||||||
|
WARNING!
|
||||||
|
========
|
||||||
|
This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably.
|
||||||
|
|
||||||
|
Are you sure? (Type uppercase yes): YES
|
||||||
|
Enter LUKS passphrase: ***
|
||||||
|
Verify passphrase: ***
|
||||||
|
|
||||||
|
# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
|
||||||
|
Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***
|
||||||
|
|
||||||
|
# mkfs.ext4 /dev/mapper/crypted
|
||||||
|
```
|
||||||
|
|
||||||
|
The LUKS volume should be automatically picked up by
|
||||||
|
`nixos-generate-config`, but you might want to verify that your
|
||||||
|
`hardware-configuration.nix` looks correct. To manually ensure that the
|
||||||
|
system is automatically mounted at boot time as `/`, add the following
|
||||||
|
to `configuration.nix`:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
|
||||||
|
fileSystems."/".device = "/dev/mapper/crypted";
|
||||||
|
```
|
||||||
|
|
||||||
|
Should grub be used as bootloader, and `/boot` is located on an
|
||||||
|
encrypted partition, it is necessary to add the following grub option:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.loader.grub.enableCryptodisk = true;
|
||||||
|
```
|
||||||
|
|
||||||
|
## FIDO2 {#sec-luks-file-systems-fido2}
|
||||||
|
|
||||||
|
NixOS also supports unlocking your LUKS-Encrypted file system using a
|
||||||
|
FIDO2 compatible token. In the following example, we will create a new
|
||||||
|
FIDO2 credential and add it as a new key to our existing device
|
||||||
|
`/dev/sda2`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# export FIDO2_LABEL="/dev/sda2 @ $HOSTNAME"
|
||||||
|
# fido2luks credential "$FIDO2_LABEL"
|
||||||
|
f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
|
||||||
|
|
||||||
|
# fido2luks -i add-key /dev/sda2 f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
|
||||||
|
Password:
|
||||||
|
Password (again):
|
||||||
|
Old password:
|
||||||
|
Old password (again):
|
||||||
|
Added to key to device /dev/sda2, slot: 2
|
||||||
|
```
|
||||||
|
|
||||||
|
To ensure that this file system is decrypted using the FIDO2 compatible
|
||||||
|
key, add the following to `configuration.nix`:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.initrd.luks.fido2Support = true;
|
||||||
|
boot.initrd.luks.devices."/dev/sda2".fido2.credential = "f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7";
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also use the FIDO2 passwordless setup, but for security reasons,
|
||||||
|
you might want to enable it only when your device is PIN protected, such
|
||||||
|
as [Trezor](https://trezor.io/).
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = true;
|
||||||
|
```
|
|
@ -1,78 +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-luks-file-systems">
|
|
||||||
<title>LUKS-Encrypted File Systems</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
NixOS supports file systems that are encrypted using
|
|
||||||
<emphasis>LUKS</emphasis> (Linux Unified Key Setup). For example, here is how
|
|
||||||
you create an encrypted Ext4 file system on the device
|
|
||||||
<filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>cryptsetup luksFormat <replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable>
|
|
||||||
|
|
||||||
WARNING!
|
|
||||||
========
|
|
||||||
This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably.
|
|
||||||
|
|
||||||
Are you sure? (Type uppercase yes): YES
|
|
||||||
Enter LUKS passphrase: ***
|
|
||||||
Verify passphrase: ***
|
|
||||||
|
|
||||||
<prompt># </prompt>cryptsetup luksOpen <replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable> <replaceable>crypted</replaceable>
|
|
||||||
Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***
|
|
||||||
|
|
||||||
<prompt># </prompt>mkfs.ext4 /dev/mapper/<replaceable>crypted</replaceable>
|
|
||||||
</screen>
|
|
||||||
The LUKS volume should be automatically picked up by
|
|
||||||
<command>nixos-generate-config</command>, but you might want to verify that your
|
|
||||||
<filename>hardware-configuration.nix</filename> looks correct.
|
|
||||||
|
|
||||||
To manually ensure that the system is automatically mounted at boot time as
|
|
||||||
<filename>/</filename>, add the following to
|
|
||||||
<filename>configuration.nix</filename>:
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-boot.initrd.luks.devices._name_.device">boot.initrd.luks.devices.crypted.device</link> = "<replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable>";
|
|
||||||
<xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/<replaceable>crypted</replaceable>";
|
|
||||||
</programlisting>
|
|
||||||
Should grub be used as bootloader, and <filename>/boot</filename> is located
|
|
||||||
on an encrypted partition, it is necessary to add the following grub option:
|
|
||||||
<programlisting><xref linkend="opt-boot.loader.grub.enableCryptodisk"/> = true;</programlisting>
|
|
||||||
</para>
|
|
||||||
<section xml:id="sec-luks-file-systems-fido2">
|
|
||||||
<title>FIDO2</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
NixOS also supports unlocking your LUKS-Encrypted file system using a FIDO2 compatible token. In the following example, we will create a new FIDO2 credential
|
|
||||||
and add it as a new key to our existing device <filename>/dev/sda2</filename>:
|
|
||||||
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>export FIDO2_LABEL="<replaceable>/dev/sda2</replaceable> @ $HOSTNAME"
|
|
||||||
<prompt># </prompt>fido2luks credential "$FIDO2_LABEL"
|
|
||||||
f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
|
|
||||||
|
|
||||||
<prompt># </prompt>fido2luks -i add-key <replaceable>/dev/sda2</replaceable> <replaceable>f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7</replaceable>
|
|
||||||
Password:
|
|
||||||
Password (again):
|
|
||||||
Old password:
|
|
||||||
Old password (again):
|
|
||||||
Added to key to device /dev/sda2, slot: 2
|
|
||||||
</screen>
|
|
||||||
|
|
||||||
To ensure that this file system is decrypted using the FIDO2 compatible key, add the following to <filename>configuration.nix</filename>:
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-boot.initrd.luks.fido2Support">boot.initrd.luks.fido2Support</link> = true;
|
|
||||||
<link linkend="opt-boot.initrd.luks.devices._name_.fido2.credential">boot.initrd.luks.devices."<replaceable>/dev/sda2</replaceable>".fido2.credential</link> = "<replaceable>f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7</replaceable>";
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
You can also use the FIDO2 passwordless setup, but for security reasons, you might want to enable it only when your device is PIN protected, such as <link xlink:href="https://trezor.io/">Trezor</link>.
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-boot.initrd.luks.devices._name_.fido2.passwordLess">boot.initrd.luks.devices."<replaceable>/dev/sda2</replaceable>".fido2.passwordLess</link> = true;
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
</section>
|
|
133
nixos/doc/manual/configuration/modularity.section.md
Normal file
133
nixos/doc/manual/configuration/modularity.section.md
Normal file
|
@ -0,0 +1,133 @@
|
||||||
|
# Modularity {#sec-modularity}
|
||||||
|
|
||||||
|
The NixOS configuration mechanism is modular. If your
|
||||||
|
`configuration.nix` becomes too big, you can split it into multiple
|
||||||
|
files. Likewise, if you have multiple NixOS configurations (e.g. for
|
||||||
|
different computers) with some commonality, you can move the common
|
||||||
|
configuration into a shared file.
|
||||||
|
|
||||||
|
Modules have exactly the same syntax as `configuration.nix`. In fact,
|
||||||
|
`configuration.nix` is itself a module. You can use other modules by
|
||||||
|
including them from `configuration.nix`, e.g.:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
|
||||||
|
{ imports = [ ./vpn.nix ./kde.nix ];
|
||||||
|
services.httpd.enable = true;
|
||||||
|
environment.systemPackages = [ pkgs.emacs ];
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Here, we include two modules from the same directory, `vpn.nix` and
|
||||||
|
`kde.nix`. The latter might look like this:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
|
||||||
|
{ services.xserver.enable = true;
|
||||||
|
services.xserver.displayManager.sddm.enable = true;
|
||||||
|
services.xserver.desktopManager.plasma5.enable = true;
|
||||||
|
environment.systemPackages = [ pkgs.vim ];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that both `configuration.nix` and `kde.nix` define the option
|
||||||
|
[](#opt-environment.systemPackages). When multiple modules define an
|
||||||
|
option, NixOS will try to *merge* the definitions. In the case of
|
||||||
|
[](#opt-environment.systemPackages), that's easy: the lists of
|
||||||
|
packages can simply be concatenated. The value in `configuration.nix` is
|
||||||
|
merged last, so for list-type options, it will appear at the end of the
|
||||||
|
merged list. If you want it to appear first, you can use `mkBefore`:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
boot.kernelModules = mkBefore [ "kvm-intel" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
This causes the `kvm-intel` kernel module to be loaded before any other
|
||||||
|
kernel modules.
|
||||||
|
|
||||||
|
For other types of options, a merge may not be possible. For instance,
|
||||||
|
if two modules define [](#opt-services.httpd.adminAddr),
|
||||||
|
`nixos-rebuild` will give an error:
|
||||||
|
|
||||||
|
```plain
|
||||||
|
The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.
|
||||||
|
```
|
||||||
|
|
||||||
|
When that happens, it's possible to force one definition take precedence
|
||||||
|
over the others:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";
|
||||||
|
```
|
||||||
|
|
||||||
|
When using multiple modules, you may need to access configuration values
|
||||||
|
defined in other modules. This is what the `config` function argument is
|
||||||
|
for: it contains the complete, merged system configuration. That is,
|
||||||
|
`config` is the result of combining the configurations returned by every
|
||||||
|
module [^1] . For example, here is a module that adds some packages to
|
||||||
|
[](#opt-environment.systemPackages) only if
|
||||||
|
[](#opt-services.xserver.enable) is set to `true` somewhere else:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
|
||||||
|
{ environment.systemPackages =
|
||||||
|
if config.services.xserver.enable then
|
||||||
|
[ pkgs.firefox
|
||||||
|
pkgs.thunderbird
|
||||||
|
]
|
||||||
|
else
|
||||||
|
[ ];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
With multiple modules, it may not be obvious what the final value of a
|
||||||
|
configuration option is. The command `nixos-option` allows you to find
|
||||||
|
out:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nixos-option services.xserver.enable
|
||||||
|
true
|
||||||
|
|
||||||
|
$ nixos-option boot.kernelModules
|
||||||
|
[ "tun" "ipv6" "loop" ... ]
|
||||||
|
```
|
||||||
|
|
||||||
|
Interactive exploration of the configuration is possible using `nix
|
||||||
|
repl`, a read-eval-print loop for Nix expressions. A typical use:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ nix repl '<nixpkgs/nixos>'
|
||||||
|
|
||||||
|
nix-repl> config.networking.hostName
|
||||||
|
"mandark"
|
||||||
|
|
||||||
|
nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts
|
||||||
|
[ "example.org" "example.gov" ]
|
||||||
|
```
|
||||||
|
|
||||||
|
While abstracting your configuration, you may find it useful to generate
|
||||||
|
modules using code, instead of writing files. The example below would
|
||||||
|
have the same effect as importing a file which sets those options.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, pkgs, ... }:
|
||||||
|
|
||||||
|
let netConfig = hostName: {
|
||||||
|
networking.hostName = hostName;
|
||||||
|
networking.useDHCP = false;
|
||||||
|
};
|
||||||
|
|
||||||
|
in
|
||||||
|
|
||||||
|
{ imports = [ (netConfig "nixos.localdomain") ]; }
|
||||||
|
```
|
||||||
|
|
||||||
|
[^1]: If you're wondering how it's possible that the (indirect) *result*
|
||||||
|
of a function is passed as an *input* to that same function: that's
|
||||||
|
because Nix is a "lazy" language --- it only computes values when
|
||||||
|
they are needed. This works as long as no individual configuration
|
||||||
|
value depends on itself.
|
|
@ -1,146 +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-modularity">
|
|
||||||
<title>Modularity</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The NixOS configuration mechanism is modular. If your
|
|
||||||
<filename>configuration.nix</filename> becomes too big, you can split it into
|
|
||||||
multiple files. Likewise, if you have multiple NixOS configurations (e.g. for
|
|
||||||
different computers) with some commonality, you can move the common
|
|
||||||
configuration into a shared file.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Modules have exactly the same syntax as
|
|
||||||
<filename>configuration.nix</filename>. In fact,
|
|
||||||
<filename>configuration.nix</filename> is itself a module. You can use other
|
|
||||||
modules by including them from <filename>configuration.nix</filename>, e.g.:
|
|
||||||
<programlisting>
|
|
||||||
{ config, pkgs, ... }:
|
|
||||||
|
|
||||||
{ imports = [ ./vpn.nix ./kde.nix ];
|
|
||||||
<xref linkend="opt-services.httpd.enable"/> = true;
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.emacs ];
|
|
||||||
<replaceable>...</replaceable>
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
Here, we include two modules from the same directory,
|
|
||||||
<filename>vpn.nix</filename> and <filename>kde.nix</filename>. The latter
|
|
||||||
might look like this:
|
|
||||||
<programlisting>
|
|
||||||
{ config, pkgs, ... }:
|
|
||||||
|
|
||||||
{ <xref linkend="opt-services.xserver.enable"/> = true;
|
|
||||||
<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;
|
|
||||||
<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.vim ];
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
Note that both <filename>configuration.nix</filename> and
|
|
||||||
<filename>kde.nix</filename> define the option
|
|
||||||
<xref linkend="opt-environment.systemPackages"/>. When multiple modules
|
|
||||||
define an option, NixOS will try to <emphasis>merge</emphasis> the
|
|
||||||
definitions. In the case of <xref linkend="opt-environment.systemPackages"/>,
|
|
||||||
that’s easy: the lists of packages can simply be concatenated. The value in
|
|
||||||
<filename>configuration.nix</filename> is merged last, so for list-type
|
|
||||||
options, it will appear at the end of the merged list. If you want it to
|
|
||||||
appear first, you can use <varname>mkBefore</varname>:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-boot.kernelModules"/> = mkBefore [ "kvm-intel" ];
|
|
||||||
</programlisting>
|
|
||||||
This causes the <literal>kvm-intel</literal> kernel module to be loaded
|
|
||||||
before any other kernel modules.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
For other types of options, a merge may not be possible. For instance, if two
|
|
||||||
modules define <xref linkend="opt-services.httpd.adminAddr"/>,
|
|
||||||
<command>nixos-rebuild</command> will give an error:
|
|
||||||
<screen>
|
|
||||||
The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.
|
|
||||||
</screen>
|
|
||||||
When that happens, it’s possible to force one definition take precedence
|
|
||||||
over the others:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-services.httpd.adminAddr"/> = pkgs.lib.mkForce "bob@example.org";
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
When using multiple modules, you may need to access configuration values
|
|
||||||
defined in other modules. This is what the <varname>config</varname> function
|
|
||||||
argument is for: it contains the complete, merged system configuration. That
|
|
||||||
is, <varname>config</varname> is the result of combining the configurations
|
|
||||||
returned by every module
|
|
||||||
<footnote xml:id="footnote-nix-is-lazy">
|
|
||||||
<para>
|
|
||||||
If you’re wondering how it’s possible that the (indirect)
|
|
||||||
<emphasis>result</emphasis> of a function is passed as an
|
|
||||||
<emphasis>input</emphasis> to that same function: that’s because Nix is a
|
|
||||||
“lazy” language — it only computes values when they are needed. This
|
|
||||||
works as long as no individual configuration value depends on itself.
|
|
||||||
</para>
|
|
||||||
</footnote>
|
|
||||||
. For example, here is a module that adds some packages to
|
|
||||||
<xref linkend="opt-environment.systemPackages"/> only if
|
|
||||||
<xref linkend="opt-services.xserver.enable"/> is set to
|
|
||||||
<literal>true</literal> somewhere else:
|
|
||||||
<programlisting>
|
|
||||||
{ config, pkgs, ... }:
|
|
||||||
|
|
||||||
{ <xref linkend="opt-environment.systemPackages"/> =
|
|
||||||
if config.<xref linkend="opt-services.xserver.enable"/> then
|
|
||||||
[ pkgs.firefox
|
|
||||||
pkgs.thunderbird
|
|
||||||
]
|
|
||||||
else
|
|
||||||
[ ];
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
With multiple modules, it may not be obvious what the final value of a
|
|
||||||
configuration option is. The command <option>nixos-option</option> allows you
|
|
||||||
to find out:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nixos-option <xref linkend="opt-services.xserver.enable"/>
|
|
||||||
true
|
|
||||||
|
|
||||||
<prompt>$ </prompt>nixos-option <xref linkend="opt-boot.kernelModules"/>
|
|
||||||
[ "tun" "ipv6" "loop" <replaceable>...</replaceable> ]
|
|
||||||
</screen>
|
|
||||||
Interactive exploration of the configuration is possible using <command>nix
|
|
||||||
repl</command>, a read-eval-print loop for Nix expressions. A typical use:
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt>nix repl '<nixpkgs/nixos>'
|
|
||||||
|
|
||||||
<prompt>nix-repl> </prompt>config.<xref linkend="opt-networking.hostName"/>
|
|
||||||
"mandark"
|
|
||||||
|
|
||||||
<prompt>nix-repl> </prompt>map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/>
|
|
||||||
[ "example.org" "example.gov" ]
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
While abstracting your configuration, you may find it useful to generate
|
|
||||||
modules using code, instead of writing files. The example below would have
|
|
||||||
the same effect as importing a file which sets those options.
|
|
||||||
<programlisting>
|
|
||||||
{ config, pkgs, ... }:
|
|
||||||
|
|
||||||
let netConfig = hostName: {
|
|
||||||
networking.hostName = hostName;
|
|
||||||
networking.useDHCP = false;
|
|
||||||
};
|
|
||||||
|
|
||||||
in
|
|
||||||
|
|
||||||
{ imports = [ (netConfig "nixos.localdomain") ]; }
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
42
nixos/doc/manual/configuration/network-manager.section.md
Normal file
42
nixos/doc/manual/configuration/network-manager.section.md
Normal file
|
@ -0,0 +1,42 @@
|
||||||
|
# NetworkManager {#sec-networkmanager}
|
||||||
|
|
||||||
|
To facilitate network configuration, some desktop environments use
|
||||||
|
NetworkManager. You can enable NetworkManager by setting:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.networkmanager.enable = true;
|
||||||
|
```
|
||||||
|
|
||||||
|
some desktop managers (e.g., GNOME) enable NetworkManager automatically
|
||||||
|
for you.
|
||||||
|
|
||||||
|
All users that should have permission to change network settings must
|
||||||
|
belong to the `networkmanager` group:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
users.users.alice.extraGroups = [ "networkmanager" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
NetworkManager is controlled using either `nmcli` or `nmtui`
|
||||||
|
(curses-based terminal user interface). See their manual pages for
|
||||||
|
details on their usage. Some desktop environments (GNOME, KDE) have
|
||||||
|
their own configuration tools for NetworkManager. On XFCE, there is no
|
||||||
|
configuration tool for NetworkManager by default: by enabling
|
||||||
|
[](#opt-programs.nm-applet.enable), the graphical applet will be
|
||||||
|
installed and will launch automatically when the graphical session is
|
||||||
|
started.
|
||||||
|
|
||||||
|
::: {.note}
|
||||||
|
`networking.networkmanager` and `networking.wireless` (WPA Supplicant)
|
||||||
|
can be used together if desired. To do this you need to instruct
|
||||||
|
NetworkManager to ignore those interfaces like:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
networking.networkmanager.unmanaged = [
|
||||||
|
"*" "except:type:wwan" "except:type:gsm"
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
Refer to the option description for the exact syntax and references to
|
||||||
|
external documentation.
|
||||||
|
:::
|
|
@ -1,48 +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-networkmanager">
|
|
||||||
<title>NetworkManager</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
To facilitate network configuration, some desktop environments use
|
|
||||||
NetworkManager. You can enable NetworkManager by setting:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.networkmanager.enable"/> = true;
|
|
||||||
</programlisting>
|
|
||||||
some desktop managers (e.g., GNOME) enable NetworkManager automatically for
|
|
||||||
you.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
All users that should have permission to change network settings must belong
|
|
||||||
to the <code>networkmanager</code> group:
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-users.users._name_.extraGroups">users.users.alice.extraGroups</link> = [ "networkmanager" ];
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
NetworkManager is controlled using either <command>nmcli</command> or
|
|
||||||
<command>nmtui</command> (curses-based terminal user interface). See their
|
|
||||||
manual pages for details on their usage. Some desktop environments (GNOME,
|
|
||||||
KDE) have their own configuration tools for NetworkManager. On XFCE, there is
|
|
||||||
no configuration tool for NetworkManager by default: by enabling <xref linkend="opt-programs.nm-applet.enable"/>, the
|
|
||||||
graphical applet will be installed and will launch automatically when the graphical session is started.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
<code>networking.networkmanager</code> and <code>networking.wireless</code>
|
|
||||||
(WPA Supplicant) can be used together if desired. To do this you need to instruct
|
|
||||||
NetworkManager to ignore those interfaces like:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-networking.networkmanager.unmanaged"/> = [
|
|
||||||
"*" "except:type:wwan" "except:type:gsm"
|
|
||||||
];
|
|
||||||
</programlisting>
|
|
||||||
Refer to the option description for the exact syntax and references to external documentation.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
</section>
|
|
|
@ -8,13 +8,13 @@
|
||||||
This section describes how to configure networking components on your NixOS
|
This section describes how to configure networking components on your NixOS
|
||||||
machine.
|
machine.
|
||||||
</para>
|
</para>
|
||||||
<xi:include href="network-manager.xml" />
|
<xi:include href="../from_md/configuration/network-manager.section.xml" />
|
||||||
<xi:include href="ssh.xml" />
|
<xi:include href="../from_md/configuration/ssh.section.xml" />
|
||||||
<xi:include href="ipv4-config.xml" />
|
<xi:include href="../from_md/configuration/ipv4-config.section.xml" />
|
||||||
<xi:include href="ipv6-config.xml" />
|
<xi:include href="../from_md/configuration/ipv6-config.section.xml" />
|
||||||
<xi:include href="firewall.xml" />
|
<xi:include href="../from_md/configuration/firewall.section.xml" />
|
||||||
<xi:include href="wireless.xml" />
|
<xi:include href="../from_md/configuration/wireless.section.xml" />
|
||||||
<xi:include href="ad-hoc-network-config.xml" />
|
<xi:include href="../from_md/configuration/ad-hoc-network-config.section.xml" />
|
||||||
<xi:include href="renaming-interfaces.xml" />
|
<xi:include href="../from_md/configuration/renaming-interfaces.section.xml" />
|
||||||
<!-- TODO: OpenVPN, NAT -->
|
<!-- TODO: OpenVPN, NAT -->
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
|
@ -27,5 +27,5 @@
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
<xi:include href="declarative-packages.xml" />
|
<xi:include href="declarative-packages.xml" />
|
||||||
<xi:include href="ad-hoc-packages.xml" />
|
<xi:include href="../from_md/configuration/ad-hoc-packages.section.xml" />
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
|
@ -25,15 +25,15 @@
|
||||||
What follows is a brief explanation on the purpose and use-case for each
|
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.
|
profile. Detailing each option configured by each one is out of scope.
|
||||||
</para>
|
</para>
|
||||||
<xi:include href="profiles/all-hardware.xml" />
|
<xi:include href="../from_md/configuration/profiles/all-hardware.section.xml" />
|
||||||
<xi:include href="profiles/base.xml" />
|
<xi:include href="../from_md/configuration/profiles/base.section.xml" />
|
||||||
<xi:include href="profiles/clone-config.xml" />
|
<xi:include href="../from_md/configuration/profiles/clone-config.section.xml" />
|
||||||
<xi:include href="profiles/demo.xml" />
|
<xi:include href="../from_md/configuration/profiles/demo.section.xml" />
|
||||||
<xi:include href="profiles/docker-container.xml" />
|
<xi:include href="../from_md/configuration/profiles/docker-container.section.xml" />
|
||||||
<xi:include href="profiles/graphical.xml" />
|
<xi:include href="../from_md/configuration/profiles/graphical.section.xml" />
|
||||||
<xi:include href="profiles/hardened.xml" />
|
<xi:include href="../from_md/configuration/profiles/hardened.section.xml" />
|
||||||
<xi:include href="profiles/headless.xml" />
|
<xi:include href="../from_md/configuration/profiles/headless.section.xml" />
|
||||||
<xi:include href="profiles/installation-device.xml" />
|
<xi:include href="../from_md/configuration/profiles/installation-device.section.xml" />
|
||||||
<xi:include href="profiles/minimal.xml" />
|
<xi:include href="../from_md/configuration/profiles/minimal.section.xml" />
|
||||||
<xi:include href="profiles/qemu-guest.xml" />
|
<xi:include href="../from_md/configuration/profiles/qemu-guest.section.xml" />
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
|
@ -0,0 +1,11 @@
|
||||||
|
# All Hardware {#sec-profile-all-hardware}
|
||||||
|
|
||||||
|
Enables all hardware supported by NixOS: i.e., all firmware is included, and
|
||||||
|
all devices from which one may boot are enabled in the initrd. Its primary
|
||||||
|
use is in the NixOS installation CDs.
|
||||||
|
|
||||||
|
The enabled kernel modules include support for SATA and PATA, SCSI
|
||||||
|
(partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and
|
||||||
|
Hyper-V. Additionally, [](#opt-hardware.enableAllFirmware) is
|
||||||
|
enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically
|
||||||
|
installed.
|
|
@ -1,21 +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-profile-all-hardware">
|
|
||||||
<title>All Hardware</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Enables all hardware supported by NixOS: i.e., all firmware is included, and
|
|
||||||
all devices from which one may boot are enabled in the initrd. Its primary
|
|
||||||
use is in the NixOS installation CDs.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The enabled kernel modules include support for SATA and PATA, SCSI
|
|
||||||
(partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and
|
|
||||||
Hyper-V. Additionally, <xref linkend="opt-hardware.enableAllFirmware"/> is
|
|
||||||
enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically
|
|
||||||
installed.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
7
nixos/doc/manual/configuration/profiles/base.section.md
Normal file
7
nixos/doc/manual/configuration/profiles/base.section.md
Normal file
|
@ -0,0 +1,7 @@
|
||||||
|
# Base {#sec-profile-base}
|
||||||
|
|
||||||
|
Defines the software packages included in the "minimal" installation CD. It
|
||||||
|
installs several utilities useful in a simple recovery or install media, such
|
||||||
|
as a text-mode web browser, and tools for manipulating block devices,
|
||||||
|
networking, hardware diagnostics, and filesystems (with their respective
|
||||||
|
kernel modules).
|
|
@ -1,15 +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-profile-base">
|
|
||||||
<title>Base</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Defines the software packages included in the "minimal" installation CD. It
|
|
||||||
installs several utilities useful in a simple recovery or install media, such
|
|
||||||
as a text-mode web browser, and tools for manipulating block devices,
|
|
||||||
networking, hardware diagnostics, and filesystems (with their respective
|
|
||||||
kernel modules).
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -0,0 +1,11 @@
|
||||||
|
# Clone Config {#sec-profile-clone-config}
|
||||||
|
|
||||||
|
This profile is used in installer images. It provides an editable
|
||||||
|
configuration.nix that imports all the modules that were also used when
|
||||||
|
creating the image in the first place. As a result it allows users to edit
|
||||||
|
and rebuild the live-system.
|
||||||
|
|
||||||
|
On images where the installation media also becomes an installation target,
|
||||||
|
copying over `configuration.nix` should be disabled by
|
||||||
|
setting `installer.cloneConfig` to `false`.
|
||||||
|
For example, this is done in `sd-image-aarch64-installer.nix`.
|
|
@ -1,21 +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-profile-clone-config">
|
|
||||||
<title>Clone Config</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This profile is used in installer images. It provides an editable
|
|
||||||
configuration.nix that imports all the modules that were also used when
|
|
||||||
creating the image in the first place. As a result it allows users to edit
|
|
||||||
and rebuild the live-system.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
On images where the installation media also becomes an installation target,
|
|
||||||
copying over <literal>configuration.nix</literal> should be disabled by
|
|
||||||
setting <literal>installer.cloneConfig</literal> to <literal>false</literal>.
|
|
||||||
For example, this is done in <literal>sd-image-aarch64-installer.nix</literal>.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
4
nixos/doc/manual/configuration/profiles/demo.section.md
Normal file
4
nixos/doc/manual/configuration/profiles/demo.section.md
Normal file
|
@ -0,0 +1,4 @@
|
||||||
|
# Demo {#sec-profile-demo}
|
||||||
|
|
||||||
|
This profile just enables a `demo` user, with password `demo`, uid `1000`, `wheel` group and
|
||||||
|
[autologin in the SDDM display manager](#opt-services.xserver.displayManager.autoLogin).
|
|
@ -1,14 +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-profile-demo">
|
|
||||||
<title>Demo</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This profile just enables a <systemitem class="username">demo</systemitem>
|
|
||||||
user, with password <literal>demo</literal>, uid <literal>1000</literal>,
|
|
||||||
<systemitem class="groupname">wheel</systemitem> group and
|
|
||||||
<link linkend="opt-services.xserver.displayManager.autoLogin">autologin in the SDDM display manager</link>.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -0,0 +1,7 @@
|
||||||
|
# Docker Container {#sec-profile-docker-container}
|
||||||
|
|
||||||
|
This is the profile from which the Docker images are generated. It prepares a
|
||||||
|
working system by importing the [Minimal](#sec-profile-minimal) and
|
||||||
|
[Clone Config](#sec-profile-clone-config) profiles, and
|
||||||
|
setting appropriate configuration options that are useful inside a container
|
||||||
|
context, like [](#opt-boot.isContainer).
|
|
@ -1,16 +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-profile-docker-container">
|
|
||||||
<title>Docker Container</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This is the profile from which the Docker images are generated. It prepares a
|
|
||||||
working system by importing the
|
|
||||||
<link linkend="sec-profile-minimal">Minimal</link> and
|
|
||||||
<link linkend="sec-profile-clone-config">Clone Config</link> profiles, and
|
|
||||||
setting appropriate configuration options that are useful inside a container
|
|
||||||
context, like <xref linkend="opt-boot.isContainer"/>.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
10
nixos/doc/manual/configuration/profiles/graphical.section.md
Normal file
10
nixos/doc/manual/configuration/profiles/graphical.section.md
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# Graphical {#sec-profile-graphical}
|
||||||
|
|
||||||
|
Defines a NixOS configuration with the Plasma 5 desktop. It's used by the
|
||||||
|
graphical installation CD.
|
||||||
|
|
||||||
|
It sets [](#opt-services.xserver.enable),
|
||||||
|
[](#opt-services.xserver.displayManager.sddm.enable),
|
||||||
|
[](#opt-services.xserver.desktopManager.plasma5.enable),
|
||||||
|
and [](#opt-services.xserver.libinput.enable) to true. It also
|
||||||
|
includes glxinfo and firefox in the system packages list.
|
|
@ -1,20 +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-profile-graphical">
|
|
||||||
<title>Graphical</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Defines a NixOS configuration with the Plasma 5 desktop. It's used by the
|
|
||||||
graphical installation CD.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
It sets <xref linkend="opt-services.xserver.enable"/>,
|
|
||||||
<xref linkend="opt-services.xserver.displayManager.sddm.enable"/>,
|
|
||||||
<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/>, and
|
|
||||||
<xref linkend="opt-services.xserver.libinput.enable"/> to true. It also
|
|
||||||
includes glxinfo and firefox in the system packages list.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
20
nixos/doc/manual/configuration/profiles/hardened.section.md
Normal file
20
nixos/doc/manual/configuration/profiles/hardened.section.md
Normal file
|
@ -0,0 +1,20 @@
|
||||||
|
# Hardened {#sec-profile-hardened}
|
||||||
|
|
||||||
|
A profile with most (vanilla) hardening options enabled by default,
|
||||||
|
potentially at the cost of stability, features and performance.
|
||||||
|
|
||||||
|
This includes a hardened kernel, and limiting the system information
|
||||||
|
available to processes through the `/sys` and
|
||||||
|
`/proc` filesystems. It also disables the User Namespaces
|
||||||
|
feature of the kernel, which stops Nix from being able to build anything
|
||||||
|
(this particular setting can be overriden via
|
||||||
|
[](#opt-security.allowUserNamespaces)). See the
|
||||||
|
[profile source](https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix)
|
||||||
|
for further detail on which settings are altered.
|
||||||
|
|
||||||
|
::: {.warning}
|
||||||
|
This profile enables options that are known to affect system
|
||||||
|
stability. If you experience any stability issues when using the
|
||||||
|
profile, try disabling it. If you report an issue and use this
|
||||||
|
profile, always mention that you do.
|
||||||
|
:::
|
|
@ -1,32 +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-profile-hardened">
|
|
||||||
<title>Hardened</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
A profile with most (vanilla) hardening options enabled by default,
|
|
||||||
potentially at the cost of stability, features and performance.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This includes a hardened kernel, and limiting the system information
|
|
||||||
available to processes through the <filename>/sys</filename> and
|
|
||||||
<filename>/proc</filename> filesystems. It also disables the User Namespaces
|
|
||||||
feature of the kernel, which stops Nix from being able to build anything
|
|
||||||
(this particular setting can be overriden via
|
|
||||||
<xref linkend="opt-security.allowUserNamespaces"/>). See the
|
|
||||||
<literal
|
|
||||||
xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix">
|
|
||||||
profile source</literal> for further detail on which settings are altered.
|
|
||||||
</para>
|
|
||||||
<warning>
|
|
||||||
<para>
|
|
||||||
This profile enables options that are known to affect system
|
|
||||||
stability. If you experience any stability issues when using the
|
|
||||||
profile, try disabling it. If you report an issue and use this
|
|
||||||
profile, always mention that you do.
|
|
||||||
</para>
|
|
||||||
</warning>
|
|
||||||
</section>
|
|
|
@ -0,0 +1,9 @@
|
||||||
|
# Headless {#sec-profile-headless}
|
||||||
|
|
||||||
|
Common configuration for headless machines (e.g., Amazon EC2 instances).
|
||||||
|
|
||||||
|
Disables [sound](#opt-sound.enable),
|
||||||
|
[vesa](#opt-boot.vesa), serial consoles,
|
||||||
|
[emergency mode](#opt-systemd.enableEmergencyMode),
|
||||||
|
[grub splash images](#opt-boot.loader.grub.splashImage)
|
||||||
|
and configures the kernel to reboot automatically on panic.
|
|
@ -1,19 +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-profile-headless">
|
|
||||||
<title>Headless</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Common configuration for headless machines (e.g., Amazon EC2 instances).
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Disables <link linkend="opt-sound.enable">sound</link>,
|
|
||||||
<link linkend="opt-boot.vesa">vesa</link>, serial consoles,
|
|
||||||
<link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>,
|
|
||||||
<link linkend="opt-boot.loader.grub.splashImage">grub splash images</link>
|
|
||||||
and configures the kernel to reboot automatically on panic.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -0,0 +1,24 @@
|
||||||
|
# Installation Device {#sec-profile-installation-device}
|
||||||
|
|
||||||
|
Provides a basic configuration for installation devices like CDs.
|
||||||
|
This enables redistributable firmware, includes the
|
||||||
|
[Clone Config profile](#sec-profile-clone-config)
|
||||||
|
and a copy of the Nixpkgs channel, so `nixos-install`
|
||||||
|
works out of the box.
|
||||||
|
|
||||||
|
Documentation for [Nixpkgs](#opt-documentation.enable)
|
||||||
|
and [NixOS](#opt-documentation.nixos.enable) are
|
||||||
|
forcefully enabled (to override the
|
||||||
|
[Minimal profile](#sec-profile-minimal) preference); the
|
||||||
|
NixOS manual is shown automatically on TTY 8, udisks is disabled.
|
||||||
|
Autologin is enabled as `nixos` user, while passwordless
|
||||||
|
login as both `root` and `nixos` is possible.
|
||||||
|
Passwordless `sudo` is enabled too.
|
||||||
|
[wpa_supplicant](#opt-networking.wireless.enable) is
|
||||||
|
enabled, but configured to not autostart.
|
||||||
|
|
||||||
|
It is explained how to login, start the ssh server, and if available,
|
||||||
|
how to start the display manager.
|
||||||
|
|
||||||
|
Several settings are tweaked so that the installer has a better chance of
|
||||||
|
succeeding under low-memory environments.
|
|
@ -1,36 +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-profile-installation-device">
|
|
||||||
<title>Installation Device</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Provides a basic configuration for installation devices like CDs.
|
|
||||||
This enables redistributable firmware, includes the
|
|
||||||
<link linkend="sec-profile-clone-config">Clone Config profile</link>
|
|
||||||
and a copy of the Nixpkgs channel, so <command>nixos-install</command>
|
|
||||||
works out of the box.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Documentation for <link linkend="opt-documentation.enable">Nixpkgs</link>
|
|
||||||
and <link linkend="opt-documentation.nixos.enable">NixOS</link> are
|
|
||||||
forcefully enabled (to override the
|
|
||||||
<link linkend="sec-profile-minimal">Minimal profile</link> preference); the
|
|
||||||
NixOS manual is shown automatically on TTY 8, udisks is disabled.
|
|
||||||
Autologin is enabled as <literal>nixos</literal> user, while passwordless
|
|
||||||
login as both <literal>root</literal> and <literal>nixos</literal> is possible.
|
|
||||||
Passwordless <command>sudo</command> is enabled too.
|
|
||||||
<link linkend="opt-networking.wireless.enable">wpa_supplicant</link> is
|
|
||||||
enabled, but configured to not autostart.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
It is explained how to login, start the ssh server, and if available,
|
|
||||||
how to start the display manager.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Several settings are tweaked so that the installer has a better chance of
|
|
||||||
succeeding under low-memory environments.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -0,0 +1,9 @@
|
||||||
|
# Minimal {#sec-profile-minimal}
|
||||||
|
|
||||||
|
This profile defines a small NixOS configuration. It does not contain any
|
||||||
|
graphical stuff. It's a very short file that enables
|
||||||
|
[noXlibs](#opt-environment.noXlibs), sets
|
||||||
|
[](#opt-i18n.supportedLocales) to
|
||||||
|
only support the user-selected locale,
|
||||||
|
[disables packages' documentation](#opt-documentation.enable),
|
||||||
|
and [disables sound](#opt-sound.enable).
|
|
@ -1,17 +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-profile-minimal">
|
|
||||||
<title>Minimal</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This profile defines a small NixOS configuration. It does not contain any
|
|
||||||
graphical stuff. It's a very short file that enables
|
|
||||||
<link linkend="opt-environment.noXlibs">noXlibs</link>, sets
|
|
||||||
<link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> to
|
|
||||||
only support the user-selected locale,
|
|
||||||
<link linkend="opt-documentation.enable">disables packages' documentation
|
|
||||||
</link>, and <link linkend="opt-sound.enable">disables sound</link>.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -0,0 +1,7 @@
|
||||||
|
# QEMU Guest {#sec-profile-qemu-guest}
|
||||||
|
|
||||||
|
This profile contains common configuration for virtual machines running under
|
||||||
|
QEMU (using virtio).
|
||||||
|
|
||||||
|
It makes virtio modules available on the initrd and sets the system time from
|
||||||
|
the hardware clock to work around a bug in qemu-kvm.
|
|
@ -1,17 +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-profile-qemu-guest">
|
|
||||||
<title>QEMU Guest</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This profile contains common configuration for virtual machines running under
|
|
||||||
QEMU (using virtio).
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
It makes virtio modules available on the initrd and sets the system time from
|
|
||||||
the hardware clock to work around a bug in qemu-kvm.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -0,0 +1,51 @@
|
||||||
|
# Renaming network interfaces {#sec-rename-ifs}
|
||||||
|
|
||||||
|
NixOS uses the udev [predictable naming
|
||||||
|
scheme](https://systemd.io/PREDICTABLE_INTERFACE_NAMES/) to assign names
|
||||||
|
to network interfaces. This means that by default cards are not given
|
||||||
|
the traditional names like `eth0` or `eth1`, whose order can change
|
||||||
|
unpredictably across reboots. Instead, relying on physical locations and
|
||||||
|
firmware information, the scheme produces names like `ens1`, `enp2s0`,
|
||||||
|
etc.
|
||||||
|
|
||||||
|
These names are predictable but less memorable and not necessarily
|
||||||
|
stable: for example installing new hardware or changing firmware
|
||||||
|
settings can result in a [name
|
||||||
|
change](https://github.com/systemd/systemd/issues/3715#issue-165347602).
|
||||||
|
If this is undesirable, for example if you have a single ethernet card,
|
||||||
|
you can revert to the traditional scheme by setting
|
||||||
|
[](#opt-networking.usePredictableInterfaceNames)
|
||||||
|
to `false`.
|
||||||
|
|
||||||
|
## Assigning custom names {#sec-custom-ifnames}
|
||||||
|
|
||||||
|
In case there are multiple interfaces of the same type, it's better to
|
||||||
|
assign custom names based on the device hardware address. For example,
|
||||||
|
we assign the name `wan` to the interface with MAC address
|
||||||
|
`52:54:00:12:01:01` using a netword link unit:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
systemd.network.links."10-wan" = {
|
||||||
|
matchConfig.MACAddress = "52:54:00:12:01:01";
|
||||||
|
linkConfig.Name = "wan";
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that links are directly read by udev, *not networkd*, and will work
|
||||||
|
even if networkd is disabled.
|
||||||
|
|
||||||
|
Alternatively, we can use a plain old udev rule:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.udev.initrdRules = ''
|
||||||
|
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
|
||||||
|
ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
|
||||||
|
'';
|
||||||
|
```
|
||||||
|
|
||||||
|
::: {.warning}
|
||||||
|
The rule must be installed in the initrd using
|
||||||
|
`services.udev.initrdRules`, not the usual `services.udev.extraRules`
|
||||||
|
option. This is to avoid race conditions with other programs controlling
|
||||||
|
the interface.
|
||||||
|
:::
|
|
@ -1,67 +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-rename-ifs">
|
|
||||||
<title>Renaming network interfaces</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
NixOS uses the udev
|
|
||||||
<link xlink:href="https://systemd.io/PREDICTABLE_INTERFACE_NAMES/">predictable naming scheme</link>
|
|
||||||
to assign names to network interfaces. This means that by default
|
|
||||||
cards are not given the traditional names like
|
|
||||||
<literal>eth0</literal> or <literal>eth1</literal>, whose order can
|
|
||||||
change unpredictably across reboots. Instead, relying on physical
|
|
||||||
locations and firmware information, the scheme produces names like
|
|
||||||
<literal>ens1</literal>, <literal>enp2s0</literal>, etc.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
These names are predictable but less memorable and not necessarily
|
|
||||||
stable: for example installing new hardware or changing firmware
|
|
||||||
settings can result in a
|
|
||||||
<link xlink:href="https://github.com/systemd/systemd/issues/3715#issue-165347602">name change</link>.
|
|
||||||
If this is undesirable, for example if you have a single ethernet
|
|
||||||
card, you can revert to the traditional scheme by setting
|
|
||||||
<xref linkend="opt-networking.usePredictableInterfaceNames"/> to
|
|
||||||
<literal>false</literal>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<section xml:id="sec-custom-ifnames">
|
|
||||||
<title>Assigning custom names</title>
|
|
||||||
<para>
|
|
||||||
In case there are multiple interfaces of the same type, it’s better to
|
|
||||||
assign custom names based on the device hardware address. For
|
|
||||||
example, we assign the name <literal>wan</literal> to the interface
|
|
||||||
with MAC address <literal>52:54:00:12:01:01</literal> using a
|
|
||||||
netword link unit:
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-systemd.network.links">systemd.network.links."10-wan"</link> = {
|
|
||||||
matchConfig.MACAddress = "52:54:00:12:01:01";
|
|
||||||
linkConfig.Name = "wan";
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
<para>
|
|
||||||
Note that links are directly read by udev, <emphasis>not networkd</emphasis>,
|
|
||||||
and will work even if networkd is disabled.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Alternatively, we can use a plain old udev rule:
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-services.udev.initrdRules">services.udev.initrdRules</link> = ''
|
|
||||||
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
|
|
||||||
ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
|
|
||||||
'';
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
<warning><para>
|
|
||||||
The rule must be installed in the initrd using
|
|
||||||
<literal>services.udev.initrdRules</literal>, not the usual
|
|
||||||
<literal>services.udev.extraRules</literal> option. This is to avoid race
|
|
||||||
conditions with other programs controlling the interface.
|
|
||||||
</para></warning>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
</section>
|
|
19
nixos/doc/manual/configuration/ssh.section.md
Normal file
19
nixos/doc/manual/configuration/ssh.section.md
Normal file
|
@ -0,0 +1,19 @@
|
||||||
|
# Secure Shell Access {#sec-ssh}
|
||||||
|
|
||||||
|
Secure shell (SSH) access to your machine can be enabled by setting:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.openssh.enable = true;
|
||||||
|
```
|
||||||
|
|
||||||
|
By default, root logins using a password are disallowed. They can be
|
||||||
|
disabled entirely by setting
|
||||||
|
[](#opt-services.openssh.permitRootLogin) to `"no"`.
|
||||||
|
|
||||||
|
You can declaratively specify authorised RSA/DSA public keys for a user
|
||||||
|
as follows:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
users.users.alice.openssh.authorizedKeys.keys =
|
||||||
|
[ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
|
||||||
|
```
|
|
@ -1,27 +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-ssh">
|
|
||||||
<title>Secure Shell Access</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Secure shell (SSH) access to your machine can be enabled by setting:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-services.openssh.enable"/> = true;
|
|
||||||
</programlisting>
|
|
||||||
By default, root logins using a password are disallowed. They can be disabled
|
|
||||||
entirely by setting <xref linkend="opt-services.openssh.permitRootLogin"/> to
|
|
||||||
<literal>"no"</literal>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You can declaratively specify authorised RSA/DSA public keys for a user as
|
|
||||||
follows:
|
|
||||||
<!-- FIXME: this might not work if the user is unmanaged. -->
|
|
||||||
<programlisting>
|
|
||||||
<link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.alice.openssh.authorizedKeys.keys</link> =
|
|
||||||
[ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
|
@ -34,7 +34,7 @@ SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation
|
||||||
To keep the key safe, change the ownership to `root:root` and make sure the permissions are `600`:
|
To keep the key safe, change the ownership to `root:root` and make sure the permissions are `600`:
|
||||||
OpenSSH normally refuses to use the key if it's not well-protected.
|
OpenSSH normally refuses to use the key if it's not well-protected.
|
||||||
|
|
||||||
The file system can be configured in NixOS via the usual [fileSystems](options.html#opt-fileSystems) option.
|
The file system can be configured in NixOS via the usual [fileSystems](#opt-fileSystems) option.
|
||||||
Here's a typical setup:
|
Here's a typical setup:
|
||||||
```nix
|
```nix
|
||||||
{
|
{
|
||||||
|
|
102
nixos/doc/manual/configuration/subversion.chapter.md
Normal file
102
nixos/doc/manual/configuration/subversion.chapter.md
Normal file
|
@ -0,0 +1,102 @@
|
||||||
|
# Subversion {#module-services-subversion}
|
||||||
|
|
||||||
|
[Subversion](https://subversion.apache.org/) is a centralized
|
||||||
|
version-control system. It can use a [variety of
|
||||||
|
protocols](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing)
|
||||||
|
for communication between client and server.
|
||||||
|
|
||||||
|
## Subversion inside Apache HTTP {#module-services-subversion-apache-httpd}
|
||||||
|
|
||||||
|
This section focuses on configuring a web-based server on top of the
|
||||||
|
Apache HTTP server, which uses
|
||||||
|
[WebDAV](http://www.webdav.org/)/[DeltaV](http://www.webdav.org/deltav/WWW10/deltav-intro.htm)
|
||||||
|
for communication.
|
||||||
|
|
||||||
|
For more information on the general setup, please refer to the [the
|
||||||
|
appropriate section of the Subversion
|
||||||
|
book](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd).
|
||||||
|
|
||||||
|
To configure, include in `/etc/nixos/configuration.nix` code to activate
|
||||||
|
Apache HTTP, setting [](#opt-services.httpd.adminAddr)
|
||||||
|
appropriately:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.httpd.enable = true;
|
||||||
|
services.httpd.adminAddr = ...;
|
||||||
|
networking.firewall.allowedTCPPorts = [ 80 443 ];
|
||||||
|
```
|
||||||
|
|
||||||
|
For a simple Subversion server with basic authentication, configure the
|
||||||
|
Subversion module for Apache as follows, setting `hostName` and
|
||||||
|
`documentRoot` appropriately, and `SVNParentPath` to the parent
|
||||||
|
directory of the repositories, `AuthzSVNAccessFile` to the location of
|
||||||
|
the `.authz` file describing access permission, and `AuthUserFile` to
|
||||||
|
the password file.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.httpd.extraModules = [
|
||||||
|
# note that order is *super* important here
|
||||||
|
{ name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }
|
||||||
|
{ name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }
|
||||||
|
];
|
||||||
|
services.httpd.virtualHosts = {
|
||||||
|
"svn" = {
|
||||||
|
hostName = HOSTNAME;
|
||||||
|
documentRoot = DOCUMENTROOT;
|
||||||
|
locations."/svn".extraConfig = ''
|
||||||
|
DAV svn
|
||||||
|
SVNParentPath REPO_PARENT
|
||||||
|
AuthzSVNAccessFile ACCESS_FILE
|
||||||
|
AuthName "SVN Repositories"
|
||||||
|
AuthType Basic
|
||||||
|
AuthUserFile PASSWORD_FILE
|
||||||
|
Require valid-user
|
||||||
|
'';
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The key `"svn"` is just a symbolic name identifying the virtual host.
|
||||||
|
The `"/svn"` in `locations."/svn".extraConfig` is the path underneath
|
||||||
|
which the repositories will be served.
|
||||||
|
|
||||||
|
[This page](https://wiki.archlinux.org/index.php/Subversion) explains
|
||||||
|
how to set up the Subversion configuration itself. This boils down to
|
||||||
|
the following:
|
||||||
|
|
||||||
|
Underneath `REPO_PARENT` repositories can be set up as follows:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ svn create REPO_NAME
|
||||||
|
```
|
||||||
|
|
||||||
|
Repository files need to be accessible by `wwwrun`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ chown -R wwwrun:wwwrun REPO_PARENT
|
||||||
|
```
|
||||||
|
|
||||||
|
The password file `PASSWORD_FILE` can be created as follows:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ htpasswd -cs PASSWORD_FILE USER_NAME
|
||||||
|
```
|
||||||
|
|
||||||
|
Additional users can be set up similarly, omitting the `c` flag:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ htpasswd -s PASSWORD_FILE USER_NAME
|
||||||
|
```
|
||||||
|
|
||||||
|
The file describing access permissions `ACCESS_FILE` will look something
|
||||||
|
like the following:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
[/]
|
||||||
|
* = r
|
||||||
|
|
||||||
|
[REPO_NAME:/]
|
||||||
|
USER_NAME = rw
|
||||||
|
```
|
||||||
|
|
||||||
|
The Subversion repositories will be accessible as
|
||||||
|
`http://HOSTNAME/svn/REPO_NAME`.
|
|
@ -1,140 +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="module-services-subversion">
|
|
||||||
<title>Subversion</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<link xlink:href="https://subversion.apache.org/">Subversion</link>
|
|
||||||
is a centralized version-control system. It can use a <link
|
|
||||||
xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety
|
|
||||||
of protocols</link> for communication between client and server.
|
|
||||||
</para>
|
|
||||||
<section xml:id="module-services-subversion-apache-httpd">
|
|
||||||
<title>Subversion inside Apache HTTP</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This section focuses on configuring a web-based server on top of
|
|
||||||
the Apache HTTP server, which uses
|
|
||||||
<link xlink:href="http://www.webdav.org/">WebDAV</link>/<link
|
|
||||||
xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link>
|
|
||||||
for communication.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>For more information on the general setup, please refer to
|
|
||||||
the <link
|
|
||||||
xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the
|
|
||||||
appropriate section of the Subversion book</link>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>To configure, include in
|
|
||||||
<literal>/etc/nixos/configuration.nix</literal> code to activate
|
|
||||||
Apache HTTP, setting <xref linkend="opt-services.httpd.adminAddr" />
|
|
||||||
appropriately:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
services.httpd.enable = true;
|
|
||||||
services.httpd.adminAddr = ...;
|
|
||||||
networking.firewall.allowedTCPPorts = [ 80 443 ];
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>For a simple Subversion server with basic authentication,
|
|
||||||
configure the Subversion module for Apache as follows, setting
|
|
||||||
<literal>hostName</literal> and <literal>documentRoot</literal>
|
|
||||||
appropriately, and <literal>SVNParentPath</literal> to the parent
|
|
||||||
directory of the repositories,
|
|
||||||
<literal>AuthzSVNAccessFile</literal> to the location of the
|
|
||||||
<code>.authz</code> file describing access permission, and
|
|
||||||
<literal>AuthUserFile</literal> to the password file.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
services.httpd.extraModules = [
|
|
||||||
# note that order is *super* important here
|
|
||||||
{ name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }
|
|
||||||
{ name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }
|
|
||||||
];
|
|
||||||
services.httpd.virtualHosts = {
|
|
||||||
"svn" = {
|
|
||||||
hostName = HOSTNAME;
|
|
||||||
documentRoot = DOCUMENTROOT;
|
|
||||||
locations."/svn".extraConfig = ''
|
|
||||||
DAV svn
|
|
||||||
SVNParentPath REPO_PARENT
|
|
||||||
AuthzSVNAccessFile ACCESS_FILE
|
|
||||||
AuthName "SVN Repositories"
|
|
||||||
AuthType Basic
|
|
||||||
AuthUserFile PASSWORD_FILE
|
|
||||||
Require valid-user
|
|
||||||
'';
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The key <code>"svn"</code> is just a symbolic name identifying the
|
|
||||||
virtual host. The <code>"/svn"</code> in
|
|
||||||
<code>locations."/svn".extraConfig</code> is the path underneath
|
|
||||||
which the repositories will be served.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para><link
|
|
||||||
xlink:href="https://wiki.archlinux.org/index.php/Subversion">This
|
|
||||||
page</link> explains how to set up the Subversion configuration
|
|
||||||
itself. This boils down to the following:
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Underneath <literal>REPO_PARENT</literal> repositories can be set up
|
|
||||||
as follows:
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt> svn create REPO_NAME
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
<para>Repository files need to be accessible by
|
|
||||||
<literal>wwwrun</literal>:
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt> chown -R wwwrun:wwwrun REPO_PARENT
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The password file <literal>PASSWORD_FILE</literal> can be created as follows:
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt> htpasswd -cs PASSWORD_FILE USER_NAME
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Additional users can be set up similarly, omitting the
|
|
||||||
<code>c</code> flag:
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<screen>
|
|
||||||
<prompt>$ </prompt> htpasswd -s PASSWORD_FILE USER_NAME
|
|
||||||
</screen>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The file describing access permissions
|
|
||||||
<literal>ACCESS_FILE</literal> will look something like
|
|
||||||
the following:
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
[/]
|
|
||||||
* = r
|
|
||||||
|
|
||||||
[REPO_NAME:/]
|
|
||||||
USER_NAME = rw
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>The Subversion repositories will be accessible as <code>http://HOSTNAME/svn/REPO_NAME</code>.</para>
|
|
||||||
</section>
|
|
||||||
</chapter>
|
|
46
nixos/doc/manual/configuration/summary.section.md
Normal file
46
nixos/doc/manual/configuration/summary.section.md
Normal file
|
@ -0,0 +1,46 @@
|
||||||
|
# Syntax Summary {#sec-nix-syntax-summary}
|
||||||
|
|
||||||
|
Below is a summary of the most important syntactic constructs in the Nix
|
||||||
|
expression language. It's not complete. In particular, there are many
|
||||||
|
other built-in functions. See the [Nix
|
||||||
|
manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions) for
|
||||||
|
the rest.
|
||||||
|
|
||||||
|
| Example | Description |
|
||||||
|
|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| *Basic values* | |
|
||||||
|
| `"Hello world"` | A string |
|
||||||
|
| `"${pkgs.bash}/bin/sh"` | A string containing an expression (expands to `"/nix/store/hash-bash-version/bin/sh"`) |
|
||||||
|
| `true`, `false` | Booleans |
|
||||||
|
| `123` | An integer |
|
||||||
|
| `./foo.png` | A path (relative to the containing Nix expression) |
|
||||||
|
| *Compound values* | |
|
||||||
|
| `{ x = 1; y = 2; }` | A set with attributes named `x` and `y` |
|
||||||
|
| `{ foo.bar = 1; }` | A nested set, equivalent to `{ foo = { bar = 1; }; }` |
|
||||||
|
| `rec { x = "foo"; y = x + "bar"; }` | A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }` |
|
||||||
|
| `[ "foo" "bar" ]` | A list with two elements |
|
||||||
|
| *Operators* | |
|
||||||
|
| `"foo" + "bar"` | String concatenation |
|
||||||
|
| `1 + 2` | Integer addition |
|
||||||
|
| `"foo" == "f" + "oo"` | Equality test (evaluates to `true`) |
|
||||||
|
| `"foo" != "bar"` | Inequality test (evaluates to `true`) |
|
||||||
|
| `!true` | Boolean negation |
|
||||||
|
| `{ x = 1; y = 2; }.x` | Attribute selection (evaluates to `1`) |
|
||||||
|
| `{ x = 1; y = 2; }.z or 3` | Attribute selection with default (evaluates to `3`) |
|
||||||
|
| `{ x = 1; y = 2; } // { z = 3; }` | Merge two sets (attributes in the right-hand set taking precedence) |
|
||||||
|
| *Control structures* | |
|
||||||
|
| `if 1 + 1 == 2 then "yes!" else "no!"` | Conditional expression |
|
||||||
|
| `assert 1 + 1 == 2; "yes!"` | Assertion check (evaluates to `"yes!"`). See [](#sec-assertions) for using assertions in modules |
|
||||||
|
| `let x = "foo"; y = "bar"; in x + y` | Variable definition |
|
||||||
|
| `with pkgs.lib; head [ 1 2 3 ]` | Add all attributes from the given set to the scope (evaluates to `1`) |
|
||||||
|
| *Functions (lambdas)* | |
|
||||||
|
| `x: x + 1` | A function that expects an integer and returns it increased by 1 |
|
||||||
|
| `(x: x + 1) 100` | A function call (evaluates to 101) |
|
||||||
|
| `let inc = x: x + 1; in inc (inc (inc 100))` | A function bound to a variable and subsequently called by name (evaluates to 103) |
|
||||||
|
| `{ x, y }: x + y` | A function that expects a set with required attributes `x` and `y` and concatenates them |
|
||||||
|
| `{ x, y ? "bar" }: x + y` | A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y` |
|
||||||
|
| `{ x, y, ... }: x + y` | A function that expects a set with required attributes `x` and `y` and ignores any other attributes |
|
||||||
|
| `{ x, y } @ args: x + y` | A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args` |
|
||||||
|
| *Built-in functions* | |
|
||||||
|
| `import ./foo.nix` | Load and return Nix expression in given file |
|
||||||
|
| `map (x: x + x) [ 1 2 3 ]` | Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`) |
|
|
@ -1,227 +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-nix-syntax-summary">
|
|
||||||
<title>Syntax Summary</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Below is a summary of the most important syntactic constructs in the Nix
|
|
||||||
expression language. It’s not complete. In particular, there are many other
|
|
||||||
built-in functions. See the
|
|
||||||
<link
|
|
||||||
xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
|
|
||||||
manual</link> for the rest.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<informaltable frame='none'>
|
|
||||||
<tgroup cols='2'>
|
|
||||||
<colspec colname='c1' rowsep='1' colsep='1' />
|
|
||||||
<colspec colname='c2' rowsep='1' />
|
|
||||||
<thead>
|
|
||||||
<row>
|
|
||||||
<entry>Example</entry>
|
|
||||||
<entry>Description</entry>
|
|
||||||
</row>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<row>
|
|
||||||
<entry namest="c1" nameend="c2"><emphasis>Basic values</emphasis>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>"Hello world"</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A string</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>"${pkgs.bash}/bin/sh"</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A string containing an expression (expands to <literal>"/nix/store/<replaceable>hash</replaceable>-bash-<replaceable>version</replaceable>/bin/sh"</literal>)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>true</literal>, <literal>false</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Booleans</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>123</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>An integer</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>./foo.png</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A path (relative to the containing Nix expression)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry namest="c1" nameend="c2"><emphasis>Compound values</emphasis>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ x = 1; y = 2; }</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A set with attributes named <literal>x</literal> and <literal>y</literal>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ foo.bar = 1; }</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A nested set, equivalent to <literal>{ foo = { bar = 1; }; }</literal>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>rec { x = "foo"; y = x + "bar"; }</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A recursive set, equivalent to <literal>{ x = "foo"; y = "foobar"; }</literal>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>[ "foo" "bar" ]</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A list with two elements</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry namest="c1" nameend="c2"><emphasis>Operators</emphasis>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>"foo" + "bar"</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>String concatenation</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>1 + 2</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Integer addition</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>"foo" == "f" + "oo"</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Equality test (evaluates to <literal>true</literal>)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>"foo" != "bar"</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Inequality test (evaluates to <literal>true</literal>)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>!true</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Boolean negation</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ x = 1; y = 2; }.x</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Attribute selection (evaluates to <literal>1</literal>)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ x = 1; y = 2; }.z or 3</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Attribute selection with default (evaluates to <literal>3</literal>)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ x = 1; y = 2; } // { z = 3; }</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Merge two sets (attributes in the right-hand set taking precedence)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry namest="c1" nameend="c2"><emphasis>Control structures</emphasis>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>if 1 + 1 == 2 then "yes!" else "no!"</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Conditional expression</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>assert 1 + 1 == 2; "yes!"</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Assertion check (evaluates to <literal>"yes!"</literal>). See <xref
|
|
||||||
linkend="sec-assertions"/> for using assertions in modules</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>let x = "foo"; y = "bar"; in x + y</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Variable definition</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>with pkgs.lib; head [ 1 2 3 ]</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Add all attributes from the given set to the scope
|
|
||||||
(evaluates to <literal>1</literal>)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry namest="c1" nameend="c2"><emphasis>Functions (lambdas)</emphasis>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>x: x + 1</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A function that expects an integer and returns it increased by 1</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>(x: x + 1) 100</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A function call (evaluates to 101)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>let inc = x: x + 1; in inc (inc (inc 100))</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A function bound to a variable and subsequently called by name (evaluates to 103)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ x, y }: x + y</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A function that expects a set with required attributes
|
|
||||||
<literal>x</literal> and <literal>y</literal> and concatenates
|
|
||||||
them</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ x, y ? "bar" }: x + y</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A function that expects a set with required attribute
|
|
||||||
<literal>x</literal> and optional <literal>y</literal>, using
|
|
||||||
<literal>"bar"</literal> as default value for
|
|
||||||
<literal>y</literal>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ x, y, ... }: x + y</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A function that expects a set with required attributes
|
|
||||||
<literal>x</literal> and <literal>y</literal> and ignores any
|
|
||||||
other attributes</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>{ x, y } @ args: x + y</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>A function that expects a set with required attributes
|
|
||||||
<literal>x</literal> and <literal>y</literal>, and binds the
|
|
||||||
whole set to <literal>args</literal>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry namest="c1" nameend="c2"><emphasis>Built-in functions</emphasis>
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>import ./foo.nix</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Load and return Nix expression in given file</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry><literal>map (x: x + x) [ 1 2 3 ]</literal>
|
|
||||||
</entry>
|
|
||||||
<entry>Apply a function to every element of a list (evaluates to <literal>[ 2 4 6 ]</literal>)</entry>
|
|
||||||
</row>
|
|
||||||
<!--
|
|
||||||
<row>
|
|
||||||
<entry><literal>throw "Urgh"</literal></entry>
|
|
||||||
<entry>Raise an error condition</entry>
|
|
||||||
</row>
|
|
||||||
-->
|
|
||||||
</tbody>
|
|
||||||
</tgroup>
|
|
||||||
</informaltable>
|
|
||||||
</section>
|
|
92
nixos/doc/manual/configuration/user-mgmt.chapter.md
Normal file
92
nixos/doc/manual/configuration/user-mgmt.chapter.md
Normal file
|
@ -0,0 +1,92 @@
|
||||||
|
# User Management {#sec-user-management}
|
||||||
|
|
||||||
|
NixOS supports both declarative and imperative styles of user
|
||||||
|
management. In the declarative style, users are specified in
|
||||||
|
`configuration.nix`. For instance, the following states that a user
|
||||||
|
account named `alice` shall exist:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
users.users.alice = {
|
||||||
|
isNormalUser = true;
|
||||||
|
home = "/home/alice";
|
||||||
|
description = "Alice Foobar";
|
||||||
|
extraGroups = [ "wheel" "networkmanager" ];
|
||||||
|
openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that `alice` is a member of the `wheel` and `networkmanager`
|
||||||
|
groups, which allows her to use `sudo` to execute commands as `root` and
|
||||||
|
to configure the network, respectively. Also note the SSH public key
|
||||||
|
that allows remote logins with the corresponding private key. Users
|
||||||
|
created in this way do not have a password by default, so they cannot
|
||||||
|
log in via mechanisms that require a password. However, you can use the
|
||||||
|
`passwd` program to set a password, which is retained across invocations
|
||||||
|
of `nixos-rebuild`.
|
||||||
|
|
||||||
|
If you set [](#opt-users.mutableUsers) to
|
||||||
|
false, then the contents of `/etc/passwd` and `/etc/group` will be congruent
|
||||||
|
to your NixOS configuration. For instance, if you remove a user from
|
||||||
|
[](#opt-users.users) and run nixos-rebuild, the user
|
||||||
|
account will cease to exist. Also, imperative commands for managing users and
|
||||||
|
groups, such as useradd, are no longer available. Passwords may still be
|
||||||
|
assigned by setting the user\'s
|
||||||
|
[hashedPassword](#opt-users.users._name_.hashedPassword) option. A
|
||||||
|
hashed password can be generated using `mkpasswd -m
|
||||||
|
sha-512`.
|
||||||
|
|
||||||
|
A user ID (uid) is assigned automatically. You can also specify a uid
|
||||||
|
manually by adding
|
||||||
|
|
||||||
|
```nix
|
||||||
|
uid = 1000;
|
||||||
|
```
|
||||||
|
|
||||||
|
to the user specification.
|
||||||
|
|
||||||
|
Groups can be specified similarly. The following states that a group
|
||||||
|
named `students` shall exist:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
users.groups.students.gid = 1000;
|
||||||
|
```
|
||||||
|
|
||||||
|
As with users, the group ID (gid) is optional and will be assigned
|
||||||
|
automatically if it's missing.
|
||||||
|
|
||||||
|
In the imperative style, users and groups are managed by commands such
|
||||||
|
as `useradd`, `groupmod` and so on. For instance, to create a user
|
||||||
|
account named `alice`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# useradd -m alice
|
||||||
|
```
|
||||||
|
|
||||||
|
To make all nix tools available to this new user use \`su - USER\` which
|
||||||
|
opens a login shell (==shell that loads the profile) for given user.
|
||||||
|
This will create the \~/.nix-defexpr symlink. So run:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# su - alice -c "true"
|
||||||
|
```
|
||||||
|
|
||||||
|
The flag `-m` causes the creation of a home directory for the new user,
|
||||||
|
which is generally what you want. The user does not have an initial
|
||||||
|
password and therefore cannot log in. A password can be set using the
|
||||||
|
`passwd` utility:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# passwd alice
|
||||||
|
Enter new UNIX password: ***
|
||||||
|
Retype new UNIX password: ***
|
||||||
|
```
|
||||||
|
|
||||||
|
A user can be deleted using `userdel`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
# userdel -r alice
|
||||||
|
```
|
||||||
|
|
||||||
|
The flag `-r` deletes the user's home directory. Accounts can be
|
||||||
|
modified using `usermod`. Unix groups can be managed using `groupadd`,
|
||||||
|
`groupmod` and `groupdel`.
|
|
@ -1,88 +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-user-management">
|
|
||||||
<title>User Management</title>
|
|
||||||
<para>
|
|
||||||
NixOS supports both declarative and imperative styles of user management. In
|
|
||||||
the declarative style, users are specified in
|
|
||||||
<filename>configuration.nix</filename>. For instance, the following states
|
|
||||||
that a user account named <literal>alice</literal> shall exist:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-users.users"/>.alice = {
|
|
||||||
<link linkend="opt-users.users._name_.isNormalUser">isNormalUser</link> = true;
|
|
||||||
<link linkend="opt-users.users._name_.home">home</link> = "/home/alice";
|
|
||||||
<link linkend="opt-users.users._name_.description">description</link> = "Alice Foobar";
|
|
||||||
<link linkend="opt-users.users._name_.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ];
|
|
||||||
<link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
Note that <literal>alice</literal> is a member of the
|
|
||||||
<literal>wheel</literal> and <literal>networkmanager</literal> groups, which
|
|
||||||
allows her to use <command>sudo</command> to execute commands as
|
|
||||||
<literal>root</literal> and to configure the network, respectively. Also note
|
|
||||||
the SSH public key that allows remote logins with the corresponding private
|
|
||||||
key. Users created in this way do not have a password by default, so they
|
|
||||||
cannot log in via mechanisms that require a password. However, you can use
|
|
||||||
the <command>passwd</command> program to set a password, which is retained
|
|
||||||
across invocations of <command>nixos-rebuild</command>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If you set <xref linkend="opt-users.mutableUsers"/> to false, then the
|
|
||||||
contents of <literal>/etc/passwd</literal> and <literal>/etc/group</literal>
|
|
||||||
will be congruent to your NixOS configuration. For instance, if you remove a
|
|
||||||
user from <xref linkend="opt-users.users"/> and run nixos-rebuild, the user
|
|
||||||
account will cease to exist. Also, imperative commands for managing users and
|
|
||||||
groups, such as useradd, are no longer available. Passwords may still be
|
|
||||||
assigned by setting the user's
|
|
||||||
<link linkend="opt-users.users._name_.hashedPassword">hashedPassword</link>
|
|
||||||
option. A hashed password can be generated using <command>mkpasswd -m
|
|
||||||
sha-512</command>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
A user ID (uid) is assigned automatically. You can also specify a uid
|
|
||||||
manually by adding
|
|
||||||
<programlisting>
|
|
||||||
uid = 1000;
|
|
||||||
</programlisting>
|
|
||||||
to the user specification.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Groups can be specified similarly. The following states that a group named
|
|
||||||
<literal>students</literal> shall exist:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-users.groups"/>.students.gid = 1000;
|
|
||||||
</programlisting>
|
|
||||||
As with users, the group ID (gid) is optional and will be assigned
|
|
||||||
automatically if it’s missing.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
In the imperative style, users and groups are managed by commands such as
|
|
||||||
<command>useradd</command>, <command>groupmod</command> and so on. For
|
|
||||||
instance, to create a user account named <literal>alice</literal>:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>useradd -m <replaceable>alice</replaceable></screen>
|
|
||||||
To make all nix tools available to this new user use `su - USER` which opens
|
|
||||||
a login shell (==shell that loads the profile) for given user. This will
|
|
||||||
create the ~/.nix-defexpr symlink. So run:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>su - <replaceable>alice</replaceable> -c "true"</screen>
|
|
||||||
The flag <option>-m</option> causes the creation of a home directory for the
|
|
||||||
new user, which is generally what you want. The user does not have an initial
|
|
||||||
password and therefore cannot log in. A password can be set using the
|
|
||||||
<command>passwd</command> utility:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>passwd <replaceable>alice</replaceable>
|
|
||||||
Enter new UNIX password: ***
|
|
||||||
Retype new UNIX password: ***
|
|
||||||
</screen>
|
|
||||||
A user can be deleted using <command>userdel</command>:
|
|
||||||
<screen>
|
|
||||||
<prompt># </prompt>userdel -r <replaceable>alice</replaceable></screen>
|
|
||||||
The flag <option>-r</option> deletes the user’s home directory. Accounts
|
|
||||||
can be modified using <command>usermod</command>. Unix groups can be managed
|
|
||||||
using <command>groupadd</command>, <command>groupmod</command> and
|
|
||||||
<command>groupdel</command>.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
27
nixos/doc/manual/configuration/wayland.chapter.md
Normal file
27
nixos/doc/manual/configuration/wayland.chapter.md
Normal file
|
@ -0,0 +1,27 @@
|
||||||
|
# Wayland {#sec-wayland}
|
||||||
|
|
||||||
|
While X11 (see [](#sec-x11)) is still the primary display technology
|
||||||
|
on NixOS, Wayland support is steadily improving. Where X11 separates the
|
||||||
|
X Server and the window manager, on Wayland those are combined: a
|
||||||
|
Wayland Compositor is like an X11 window manager, but also embeds the
|
||||||
|
Wayland \'Server\' functionality. This means it is sufficient to install
|
||||||
|
a Wayland Compositor such as sway without separately enabling a Wayland
|
||||||
|
server:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
programs.sway.enable = true;
|
||||||
|
```
|
||||||
|
|
||||||
|
This installs the sway compositor along with some essential utilities.
|
||||||
|
Now you can start sway from the TTY console.
|
||||||
|
|
||||||
|
If you are using a wlroots-based compositor, like sway, and want to be
|
||||||
|
able to share your screen, you might want to activate this option:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
xdg.portal.wlr.enable = true;
|
||||||
|
```
|
||||||
|
|
||||||
|
and configure Pipewire using
|
||||||
|
[](#opt-services.pipewire.enable)
|
||||||
|
and related options.
|
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue