Merge pull request #129121 from bobby285271/pr13
nixos/doc: convert Chapter 7, 9, 10, 11, 12, 14, 15, 48 to CommonMark
This commit is contained in:
Jörg Thalheim
GitHub
commit
4015c275ca
|
|
@ -15,17 +15,17 @@
|
|||
</partintro>
|
||||
<xi:include href="config-syntax.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="x-windows.xml" />
|
||||
<xi:include href="wayland.xml" />
|
||||
<xi:include href="gpu-accel.xml" />
|
||||
<xi:include href="xfce.xml" />
|
||||
<xi:include href="../from_md/configuration/x-windows.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/wayland.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/xfce.chapter.xml" />
|
||||
<xi:include href="networking.xml" />
|
||||
<xi:include href="linux-kernel.xml" />
|
||||
<xi:include href="subversion.xml" />
|
||||
<xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/subversion.chapter.xml" />
|
||||
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
|
||||
<xi:include href="profiles.xml" />
|
||||
<xi:include href="kubernetes.xml" />
|
||||
<xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
|
||||
<!-- Apache; libvirtd virtualisation -->
|
||||
</part>
|
||||
|
|
|
|||
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>
|
||||
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>
|
||||
135
nixos/doc/manual/configuration/linux-kernel.chapter.md
Normal file
135
nixos/doc/manual/configuration/linux-kernel.chapter.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
# 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.linuxPackages_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.
|
||||
|
||||
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:
|
||||
{ linux_3_4 = pkgs.linux_3_4.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 `linuxManualConfig`:
|
||||
|
||||
```nix
|
||||
custom-kernel = super.linuxManualConfig {
|
||||
inherit (super) stdenv hostPlatform;
|
||||
inherit (linux_4_9) src;
|
||||
version = "${linux_4_9.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,138 +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.linuxPackages_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>
|
||||
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:
|
||||
{ linux_3_4 = pkgs.linux_3_4.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>linuxManualConfig</literal>:
|
||||
<screen><![CDATA[
|
||||
custom-kernel = super.linuxManualConfig {
|
||||
inherit (super) stdenv hostPlatform;
|
||||
inherit (linux_4_9) src;
|
||||
version = "${linux_4_9.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>
|
||||
|
|
@ -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`:
|
||||
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:
|
||||
```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>
|
||||
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.
|
||||
|
|
@ -1,33 +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-wayland">
|
||||
<title>Wayland</title>
|
||||
|
||||
<para>
|
||||
While X11 (see <xref linkend="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 <package>sway</package> without
|
||||
separately enabling a Wayland server:
|
||||
<programlisting>
|
||||
<xref linkend="opt-programs.sway.enable"/> = true;
|
||||
</programlisting>
|
||||
This installs the <package>sway</package> compositor along with some
|
||||
essential utilities. Now you can start <package>sway</package> from the TTY
|
||||
console.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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:
|
||||
<programlisting>
|
||||
<xref linkend="opt-xdg.portal.wlr.enable"/> = true;
|
||||
</programlisting>
|
||||
and configure Pipewire using <xref linkend="opt-services.pipewire.enable"/>
|
||||
and related options.
|
||||
</para>
|
||||
</chapter>
|
||||
337
nixos/doc/manual/configuration/x-windows.chapter.md
Normal file
337
nixos/doc/manual/configuration/x-windows.chapter.md
Normal file
|
|
@ -0,0 +1,337 @@
|
|||
# X Window System {#sec-x11}
|
||||
|
||||
The X Window System (X11) provides the basis of NixOS' graphical user
|
||||
interface. It can be enabled as follows:
|
||||
|
||||
```nix
|
||||
services.xserver.enable = true;
|
||||
```
|
||||
|
||||
The X server will automatically detect and use the appropriate video
|
||||
driver from a set of X.org drivers (such as `vesa` and `intel`). You can
|
||||
also specify a driver manually, e.g.
|
||||
|
||||
```nix
|
||||
services.xserver.videoDrivers = [ "r128" ];
|
||||
```
|
||||
|
||||
to enable X.org's `xf86-video-r128` driver.
|
||||
|
||||
You also need to enable at least one desktop or window manager.
|
||||
Otherwise, you can only log into a plain undecorated `xterm` window.
|
||||
Thus you should pick one or more of the following lines:
|
||||
|
||||
```nix
|
||||
services.xserver.desktopManager.plasma5.enable = true;
|
||||
services.xserver.desktopManager.xfce.enable = true;
|
||||
services.xserver.desktopManager.gnome.enable = true;
|
||||
services.xserver.desktopManager.mate.enable = true;
|
||||
services.xserver.windowManager.xmonad.enable = true;
|
||||
services.xserver.windowManager.twm.enable = true;
|
||||
services.xserver.windowManager.icewm.enable = true;
|
||||
services.xserver.windowManager.i3.enable = true;
|
||||
services.xserver.windowManager.herbstluftwm.enable = true;
|
||||
```
|
||||
|
||||
NixOS's default *display manager* (the program that provides a graphical
|
||||
login prompt and manages the X server) is LightDM. You can select an
|
||||
alternative one by picking one of the following lines:
|
||||
|
||||
```nix
|
||||
services.xserver.displayManager.sddm.enable = true;
|
||||
services.xserver.displayManager.gdm.enable = true;
|
||||
```
|
||||
|
||||
You can set the keyboard layout (and optionally the layout variant):
|
||||
|
||||
```nix
|
||||
services.xserver.layout = "de";
|
||||
services.xserver.xkbVariant = "neo";
|
||||
```
|
||||
|
||||
The X server is started automatically at boot time. If you don't want
|
||||
this to happen, you can set:
|
||||
|
||||
```nix
|
||||
services.xserver.autorun = false;
|
||||
```
|
||||
|
||||
The X server can then be started manually:
|
||||
|
||||
```ShellSession
|
||||
# systemctl start display-manager.service
|
||||
```
|
||||
|
||||
On 64-bit systems, if you want OpenGL for 32-bit programs such as in
|
||||
Wine, you should also set the following:
|
||||
|
||||
```nix
|
||||
hardware.opengl.driSupport32Bit = true;
|
||||
```
|
||||
|
||||
## Auto-login {#sec-x11-auto-login .unnumbered}
|
||||
|
||||
The x11 login screen can be skipped entirely, automatically logging you
|
||||
into your window manager and desktop environment when you boot your
|
||||
computer.
|
||||
|
||||
This is especially helpful if you have disk encryption enabled. Since
|
||||
you already have to provide a password to decrypt your disk, entering a
|
||||
second password to login can be redundant.
|
||||
|
||||
To enable auto-login, you need to define your default window manager and
|
||||
desktop environment. If you wanted no desktop environment and i3 as your
|
||||
your window manager, you\'d define:
|
||||
|
||||
```nix
|
||||
services.xserver.displayManager.defaultSession = "none+i3";
|
||||
```
|
||||
|
||||
Every display manager in NixOS supports auto-login, here is an example
|
||||
using lightdm for a user `alice`:
|
||||
|
||||
```nix
|
||||
services.xserver.displayManager.lightdm.enable = true;
|
||||
services.xserver.displayManager.autoLogin.enable = true;
|
||||
services.xserver.displayManager.autoLogin.user = "alice";
|
||||
```
|
||||
|
||||
## Intel Graphics drivers {#sec-x11--graphics-cards-intel .unnumbered}
|
||||
|
||||
There are two choices for Intel Graphics drivers in X.org: `modesetting`
|
||||
(included in the xorg-server itself) and `intel` (provided by the
|
||||
package xf86-video-intel).
|
||||
|
||||
The default and recommended is `modesetting`. It is a generic driver
|
||||
which uses the kernel [mode
|
||||
setting](https://en.wikipedia.org/wiki/Mode_setting) (KMS) mechanism. It
|
||||
supports Glamor (2D graphics acceleration via OpenGL) and is actively
|
||||
maintained but may perform worse in some cases (like in old chipsets).
|
||||
|
||||
The second driver, `intel`, is specific to Intel GPUs, but not
|
||||
recommended by most distributions: it lacks several modern features (for
|
||||
example, it doesn\'t support Glamor) and the package hasn\'t been
|
||||
officially updated since 2015.
|
||||
|
||||
The results vary depending on the hardware, so you may have to try both
|
||||
drivers. Use the option
|
||||
[](#opt-services.xserver.videoDrivers)
|
||||
to set one. The recommended configuration for modern systems is:
|
||||
|
||||
```nix
|
||||
services.xserver.videoDrivers = [ "modesetting" ];
|
||||
services.xserver.useGlamor = true;
|
||||
```
|
||||
|
||||
If you experience screen tearing no matter what, this configuration was
|
||||
reported to resolve the issue:
|
||||
|
||||
```nix
|
||||
services.xserver.videoDrivers = [ "intel" ];
|
||||
services.xserver.deviceSection = ''
|
||||
Option "DRI" "2"
|
||||
Option "TearFree" "true"
|
||||
'';
|
||||
```
|
||||
|
||||
Note that this will likely downgrade the performance compared to
|
||||
`modesetting` or `intel` with DRI 3 (default).
|
||||
|
||||
## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia .unnumbered}
|
||||
|
||||
NVIDIA provides a proprietary driver for its graphics cards that has
|
||||
better 3D performance than the X.org drivers. It is not enabled by
|
||||
default because it's not free software. You can enable it as follows:
|
||||
|
||||
```nix
|
||||
services.xserver.videoDrivers = [ "nvidia" ];
|
||||
```
|
||||
|
||||
Or if you have an older card, you may have to use one of the legacy
|
||||
drivers:
|
||||
|
||||
```nix
|
||||
services.xserver.videoDrivers = [ "nvidiaLegacy390" ];
|
||||
services.xserver.videoDrivers = [ "nvidiaLegacy340" ];
|
||||
services.xserver.videoDrivers = [ "nvidiaLegacy304" ];
|
||||
```
|
||||
|
||||
You may need to reboot after enabling this driver to prevent a clash
|
||||
with other kernel modules.
|
||||
|
||||
## Proprietary AMD drivers {#sec-x11--graphics-cards-amd .unnumbered}
|
||||
|
||||
AMD provides a proprietary driver for its graphics cards that is not
|
||||
enabled by default because it's not Free Software, is often broken in
|
||||
nixpkgs and as of this writing doesn\'t offer more features or
|
||||
performance. If you still want to use it anyway, you need to explicitly
|
||||
set:
|
||||
|
||||
```nix
|
||||
services.xserver.videoDrivers = [ "amdgpu-pro" ];
|
||||
```
|
||||
|
||||
You will need to reboot after enabling this driver to prevent a clash
|
||||
with other kernel modules.
|
||||
|
||||
## Touchpads {#sec-x11-touchpads .unnumbered}
|
||||
|
||||
Support for Synaptics touchpads (found in many laptops such as the Dell
|
||||
Latitude series) can be enabled as follows:
|
||||
|
||||
```nix
|
||||
services.xserver.libinput.enable = true;
|
||||
```
|
||||
|
||||
The driver has many options (see [](#ch-options)).
|
||||
For instance, the following disables tap-to-click behavior:
|
||||
|
||||
```nix
|
||||
services.xserver.libinput.touchpad.tapping = false;
|
||||
```
|
||||
|
||||
Note: the use of `services.xserver.synaptics` is deprecated since NixOS
|
||||
17.09.
|
||||
|
||||
## GTK/Qt themes {#sec-x11-gtk-and-qt-themes .unnumbered}
|
||||
|
||||
GTK themes can be installed either to user profile or system-wide (via
|
||||
`environment.systemPackages`). To make Qt 5 applications look similar to
|
||||
GTK ones, you can use the following configuration:
|
||||
|
||||
```nix
|
||||
qt5.enable = true;
|
||||
qt5.platformTheme = "gtk2";
|
||||
qt5.style = "gtk2";
|
||||
```
|
||||
|
||||
## Custom XKB layouts {#custom-xkb-layouts .unnumbered}
|
||||
|
||||
It is possible to install custom [ XKB
|
||||
](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts
|
||||
using the option `services.xserver.extraLayouts`.
|
||||
|
||||
As a first example, we are going to create a layout based on the basic
|
||||
US layout, with an additional layer to type some greek symbols by
|
||||
pressing the right-alt key.
|
||||
|
||||
Create a file called `us-greek` with the following content (under a
|
||||
directory called `symbols`; it\'s an XKB peculiarity that will help with
|
||||
testing):
|
||||
|
||||
```nix
|
||||
xkb_symbols "us-greek"
|
||||
{
|
||||
include "us(basic)" // includes the base US keys
|
||||
include "level3(ralt_switch)" // configures right alt as a third level switch
|
||||
|
||||
key <LatA> { [ a, A, Greek_alpha ] };
|
||||
key <LatB> { [ b, B, Greek_beta ] };
|
||||
key <LatG> { [ g, G, Greek_gamma ] };
|
||||
key <LatD> { [ d, D, Greek_delta ] };
|
||||
key <LatZ> { [ z, Z, Greek_zeta ] };
|
||||
};
|
||||
```
|
||||
|
||||
A minimal layout specification must include the following:
|
||||
|
||||
```nix
|
||||
services.xserver.extraLayouts.us-greek = {
|
||||
description = "US layout with alt-gr greek";
|
||||
languages = [ "eng" ];
|
||||
symbolsFile = /yourpath/symbols/us-greek;
|
||||
};
|
||||
```
|
||||
|
||||
::: {.note}
|
||||
The name (after `extraLayouts.`) should match the one given to the
|
||||
`xkb_symbols` block.
|
||||
:::
|
||||
|
||||
Applying this customization requires rebuilding several packages, and a
|
||||
broken XKB file can lead to the X session crashing at login. Therefore,
|
||||
you\'re strongly advised to **test your layout before applying it**:
|
||||
|
||||
```ShellSession
|
||||
$ nix-shell -p xorg.xkbcomp
|
||||
$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
|
||||
```
|
||||
|
||||
You can inspect the predefined XKB files for examples:
|
||||
|
||||
```ShellSession
|
||||
$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
|
||||
```
|
||||
|
||||
Once the configuration is applied, and you did a logout/login cycle, the
|
||||
layout should be ready to use. You can try it by e.g. running
|
||||
`setxkbmap us-greek` and then type `<alt>+a` (it may not get applied in
|
||||
your terminal straight away). To change the default, the usual
|
||||
`services.xserver.layout` option can still be used.
|
||||
|
||||
A layout can have several other components besides `xkb_symbols`, for
|
||||
example we will define new keycodes for some multimedia key and bind
|
||||
these to some symbol.
|
||||
|
||||
Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys
|
||||
of interest, then create a `media-key` file to hold the keycodes
|
||||
definitions
|
||||
|
||||
```nix
|
||||
xkb_keycodes "media"
|
||||
{
|
||||
<volUp> = 123;
|
||||
<volDown> = 456;
|
||||
}
|
||||
```
|
||||
|
||||
Now use the newly define keycodes in `media-sym`:
|
||||
|
||||
```nix
|
||||
xkb_symbols "media"
|
||||
{
|
||||
key.type = "ONE_LEVEL";
|
||||
key <volUp> { [ XF86AudioLowerVolume ] };
|
||||
key <volDown> { [ XF86AudioRaiseVolume ] };
|
||||
}
|
||||
```
|
||||
|
||||
As before, to install the layout do
|
||||
|
||||
```nix
|
||||
services.xserver.extraLayouts.media = {
|
||||
description = "Multimedia keys remapping";
|
||||
languages = [ "eng" ];
|
||||
symbolsFile = /path/to/media-key;
|
||||
keycodesFile = /path/to/media-sym;
|
||||
};
|
||||
```
|
||||
|
||||
::: {.note}
|
||||
The function `pkgs.writeText <filename> <content>` can be useful if you
|
||||
prefer to keep the layout definitions inside the NixOS configuration.
|
||||
:::
|
||||
|
||||
Unfortunately, the Xorg server does not (currently) support setting a
|
||||
keymap directly but relies instead on XKB rules to select the matching
|
||||
components (keycodes, types, \...) of a layout. This means that
|
||||
components other than symbols won\'t be loaded by default. As a
|
||||
workaround, you can set the keymap using `setxkbmap` at the start of the
|
||||
session with:
|
||||
|
||||
```nix
|
||||
services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
|
||||
```
|
||||
|
||||
If you are manually starting the X server, you should set the argument
|
||||
`-xkbdir /etc/X11/xkb`, otherwise X won\'t find your layout files. For
|
||||
example with `xinit` run
|
||||
|
||||
```ShellSession
|
||||
$ xinit -- -xkbdir /etc/X11/xkb
|
||||
```
|
||||
|
||||
To learn how to write layouts take a look at the XKB [documentation
|
||||
](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts).
|
||||
More example layouts can also be found [here
|
||||
](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples).
|
||||
|
|
@ -1,355 +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-x11">
|
||||
<title>X Window System</title>
|
||||
<para>
|
||||
The X Window System (X11) provides the basis of NixOS’ graphical user
|
||||
interface. It can be enabled as follows:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.enable"/> = true;
|
||||
</programlisting>
|
||||
The X server will automatically detect and use the appropriate video driver
|
||||
from a set of X.org drivers (such as <literal>vesa</literal> and
|
||||
<literal>intel</literal>). You can also specify a driver manually, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ];
|
||||
</programlisting>
|
||||
to enable X.org’s <literal>xf86-video-r128</literal> driver.
|
||||
</para>
|
||||
<para>
|
||||
You also need to enable at least one desktop or window manager. Otherwise,
|
||||
you can only log into a plain undecorated <command>xterm</command> window.
|
||||
Thus you should pick one or more of the following lines:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.desktopManager.gnome.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.desktopManager.mate.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.windowManager.icewm.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.windowManager.i3.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.windowManager.herbstluftwm.enable"/> = true;
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
NixOS’s default <emphasis>display manager</emphasis> (the program that
|
||||
provides a graphical login prompt and manages the X server) is LightDM. You
|
||||
can select an alternative one by picking one of the following lines:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.displayManager.gdm.enable"/> = true;
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
You can set the keyboard layout (and optionally the layout variant):
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.layout"/> = "de";
|
||||
<xref linkend="opt-services.xserver.xkbVariant"/> = "neo";
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
The X server is started automatically at boot time. If you don’t want this
|
||||
to happen, you can set:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.autorun"/> = false;
|
||||
</programlisting>
|
||||
The X server can then be started manually:
|
||||
<screen>
|
||||
<prompt># </prompt>systemctl start display-manager.service
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine,
|
||||
you should also set the following:
|
||||
<programlisting>
|
||||
<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true;
|
||||
</programlisting>
|
||||
</para>
|
||||
<simplesect xml:id="sec-x11-auto-login">
|
||||
<title>Auto-login</title>
|
||||
<para>
|
||||
The x11 login screen can be skipped entirely, automatically logging you into
|
||||
your window manager and desktop environment when you boot your computer.
|
||||
</para>
|
||||
<para>
|
||||
This is especially helpful if you have disk encryption enabled. Since you
|
||||
already have to provide a password to decrypt your disk, entering a second
|
||||
password to login can be redundant.
|
||||
</para>
|
||||
<para>
|
||||
To enable auto-login, you need to define your default window manager and
|
||||
desktop environment. If you wanted no desktop environment and i3 as your your
|
||||
window manager, you'd define:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.displayManager.defaultSession"/> = "none+i3";
|
||||
</programlisting>
|
||||
Every display manager in NixOS supports auto-login, here is an example
|
||||
using lightdm for a user <literal>alice</literal>:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.displayManager.lightdm.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.displayManager.autoLogin.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.displayManager.autoLogin.user"/> = "alice";
|
||||
</programlisting>
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect xml:id="sec-x11--graphics-cards-intel">
|
||||
<title>Intel Graphics drivers</title>
|
||||
<para>
|
||||
There are two choices for Intel Graphics drivers in X.org:
|
||||
<literal>modesetting</literal> (included in the <package>xorg-server</package> itself)
|
||||
and <literal>intel</literal> (provided by the package <package>xf86-video-intel</package>).
|
||||
</para>
|
||||
<para>
|
||||
The default and recommended is <literal>modesetting</literal>.
|
||||
It is a generic driver which uses the kernel
|
||||
<link xlink:href="https://en.wikipedia.org/wiki/Mode_setting">mode setting</link>
|
||||
(KMS) mechanism. It supports Glamor (2D graphics acceleration via OpenGL)
|
||||
and is actively maintained but may perform worse in some cases (like in old chipsets).
|
||||
</para>
|
||||
<para>
|
||||
The second driver, <literal>intel</literal>, is specific to Intel GPUs,
|
||||
but not recommended by most distributions: it lacks several modern features
|
||||
(for example, it doesn't support Glamor) and the package hasn't been officially
|
||||
updated since 2015.
|
||||
</para>
|
||||
<para>
|
||||
The results vary depending on the hardware, so you may have to try both drivers.
|
||||
Use the option <xref linkend="opt-services.xserver.videoDrivers"/> to set one.
|
||||
The recommended configuration for modern systems is:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.videoDrivers"/> = [ "modesetting" ];
|
||||
<xref linkend="opt-services.xserver.useGlamor"/> = true;
|
||||
</programlisting>
|
||||
If you experience screen tearing no matter what, this configuration was
|
||||
reported to resolve the issue:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.videoDrivers"/> = [ "intel" ];
|
||||
<xref linkend="opt-services.xserver.deviceSection"/> = ''
|
||||
Option "DRI" "2"
|
||||
Option "TearFree" "true"
|
||||
'';
|
||||
</programlisting>
|
||||
Note that this will likely downgrade the performance compared to
|
||||
<literal>modesetting</literal> or <literal>intel</literal> with DRI 3 (default).
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect xml:id="sec-x11-graphics-cards-nvidia">
|
||||
<title>Proprietary NVIDIA drivers</title>
|
||||
<para>
|
||||
NVIDIA provides a proprietary driver for its graphics cards that has better
|
||||
3D performance than the X.org drivers. It is not enabled by default because
|
||||
it’s not free software. You can enable it as follows:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ];
|
||||
</programlisting>
|
||||
Or if you have an older card, you may have to use one of the legacy drivers:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy390" ];
|
||||
<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ];
|
||||
<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ];
|
||||
</programlisting>
|
||||
You may need to reboot after enabling this driver to prevent a clash with
|
||||
other kernel modules.
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect xml:id="sec-x11--graphics-cards-amd">
|
||||
<title>Proprietary AMD drivers</title>
|
||||
<para>
|
||||
AMD provides a proprietary driver for its graphics cards that is not
|
||||
enabled by default because it’s not Free Software, is often broken
|
||||
in nixpkgs and as of this writing doesn't offer more features or
|
||||
performance. If you still want to use it anyway, you need to explicitly set:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.videoDrivers"/> = [ "amdgpu-pro" ];
|
||||
</programlisting>
|
||||
You will need to reboot after enabling this driver to prevent a clash with
|
||||
other kernel modules.
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect xml:id="sec-x11-touchpads">
|
||||
<title>Touchpads</title>
|
||||
<para>
|
||||
Support for Synaptics touchpads (found in many laptops such as the Dell
|
||||
Latitude series) can be enabled as follows:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.libinput.enable"/> = true;
|
||||
</programlisting>
|
||||
The driver has many options (see <xref linkend="ch-options"/>). For
|
||||
instance, the following disables tap-to-click behavior:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.libinput.touchpad.tapping"/> = false;
|
||||
</programlisting>
|
||||
Note: the use of <literal>services.xserver.synaptics</literal> is deprecated
|
||||
since NixOS 17.09.
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect xml:id="sec-x11-gtk-and-qt-themes">
|
||||
<title>GTK/Qt themes</title>
|
||||
<para>
|
||||
GTK themes can be installed either to user profile or system-wide (via
|
||||
<literal>environment.systemPackages</literal>). To make Qt 5 applications
|
||||
look similar to GTK ones, you can use the following configuration:
|
||||
<programlisting>
|
||||
<xref linkend="opt-qt5.enable"/> = true;
|
||||
<xref linkend="opt-qt5.platformTheme"/> = "gtk2";
|
||||
<xref linkend="opt-qt5.style"/> = "gtk2";
|
||||
</programlisting>
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect xml:id="custom-xkb-layouts">
|
||||
<title>Custom XKB layouts</title>
|
||||
<para>
|
||||
It is possible to install custom
|
||||
<link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">
|
||||
XKB
|
||||
</link>
|
||||
keyboard layouts using the option
|
||||
<option><link linkend="opt-services.xserver.extraLayouts">
|
||||
services.xserver.extraLayouts</link></option>.
|
||||
</para>
|
||||
<para>
|
||||
As a first example, we are going to create a layout based on the basic US
|
||||
layout, with an additional layer to type some greek symbols by pressing the
|
||||
right-alt key.
|
||||
</para>
|
||||
<para>
|
||||
Create a file called <literal>us-greek</literal> with the following
|
||||
content (under a directory called <literal>symbols</literal>; it's
|
||||
an XKB peculiarity that will help with testing):
|
||||
</para>
|
||||
<programlisting>
|
||||
xkb_symbols "us-greek"
|
||||
{
|
||||
include "us(basic)" // includes the base US keys
|
||||
include "level3(ralt_switch)" // configures right alt as a third level switch
|
||||
|
||||
key <LatA> { [ a, A, Greek_alpha ] };
|
||||
key <LatB> { [ b, B, Greek_beta ] };
|
||||
key <LatG> { [ g, G, Greek_gamma ] };
|
||||
key <LatD> { [ d, D, Greek_delta ] };
|
||||
key <LatZ> { [ z, Z, Greek_zeta ] };
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
A minimal layout specification must include the following:
|
||||
</para>
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = {
|
||||
description = "US layout with alt-gr greek";
|
||||
languages = [ "eng" ];
|
||||
symbolsFile = /yourpath/symbols/us-greek;
|
||||
};
|
||||
</programlisting>
|
||||
<note>
|
||||
<para>
|
||||
The name (after <literal>extraLayouts.</literal>) should match the one given to the
|
||||
<literal>xkb_symbols</literal> block.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Applying this customization requires rebuilding several packages,
|
||||
and a broken XKB file can lead to the X session crashing at login.
|
||||
Therefore, you're strongly advised to <emphasis role="strong">test
|
||||
your layout before applying it</emphasis>:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-shell -p xorg.xkbcomp
|
||||
<prompt>$ </prompt>setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
You can inspect the predefined XKB files for examples:
|
||||
<screen>
|
||||
<prompt>$ </prompt>echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
Once the configuration is applied, and you did a logout/login
|
||||
cycle, the layout should be ready to use. You can try it by e.g.
|
||||
running <literal>setxkbmap us-greek</literal> and then type
|
||||
<literal><alt>+a</literal> (it may not get applied in your
|
||||
terminal straight away). To change the default, the usual
|
||||
<option>
|
||||
<link linkend="opt-services.xserver.layout">
|
||||
services.xserver.layout
|
||||
</link>
|
||||
</option>
|
||||
option can still be used.
|
||||
</para>
|
||||
<para>
|
||||
A layout can have several other components besides
|
||||
<literal>xkb_symbols</literal>, for example we will define new
|
||||
keycodes for some multimedia key and bind these to some symbol.
|
||||
</para>
|
||||
<para>
|
||||
Use the <emphasis>xev</emphasis> utility from
|
||||
<literal>pkgs.xorg.xev</literal> to find the codes of the keys of
|
||||
interest, then create a <literal>media-key</literal> file to hold
|
||||
the keycodes definitions
|
||||
</para>
|
||||
<programlisting>
|
||||
xkb_keycodes "media"
|
||||
{
|
||||
<volUp> = 123;
|
||||
<volDown> = 456;
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
Now use the newly define keycodes in <literal>media-sym</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
xkb_symbols "media"
|
||||
{
|
||||
key.type = "ONE_LEVEL";
|
||||
key <volUp> { [ XF86AudioLowerVolume ] };
|
||||
key <volDown> { [ XF86AudioRaiseVolume ] };
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
As before, to install the layout do
|
||||
</para>
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.extraLayouts"/>.media = {
|
||||
description = "Multimedia keys remapping";
|
||||
languages = [ "eng" ];
|
||||
symbolsFile = /path/to/media-key;
|
||||
keycodesFile = /path/to/media-sym;
|
||||
};
|
||||
</programlisting>
|
||||
<note>
|
||||
<para>
|
||||
The function <literal>pkgs.writeText <filename> <content>
|
||||
</literal> can be useful if you prefer to keep the layout definitions
|
||||
inside the NixOS configuration.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Unfortunately, the Xorg server does not (currently) support setting a
|
||||
keymap directly but relies instead on XKB rules to select the matching
|
||||
components (keycodes, types, ...) of a layout. This means that components
|
||||
other than symbols won't be loaded by default. As a workaround, you
|
||||
can set the keymap using <literal>setxkbmap</literal> at the start of the
|
||||
session with:
|
||||
</para>
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media";
|
||||
</programlisting>
|
||||
<para>
|
||||
If you are manually starting the X server, you should set the argument
|
||||
<literal>-xkbdir /etc/X11/xkb</literal>, otherwise X won't find your layout files.
|
||||
For example with <command>xinit</command> run
|
||||
<screen><prompt>$ </prompt>xinit -- -xkbdir /etc/X11/xkb</screen>
|
||||
</para>
|
||||
<para>
|
||||
To learn how to write layouts take a look at the XKB
|
||||
<link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">
|
||||
documentation
|
||||
</link>. More example layouts can also be found
|
||||
<link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">
|
||||
here
|
||||
</link>.
|
||||
</para>
|
||||
</simplesect>
|
||||
</chapter>
|
||||
52
nixos/doc/manual/configuration/xfce.chapter.md
Normal file
52
nixos/doc/manual/configuration/xfce.chapter.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
# Xfce Desktop Environment {#sec-xfce}
|
||||
|
||||
To enable the Xfce Desktop Environment, set
|
||||
|
||||
```nix
|
||||
services.xserver.desktopManager.xfce.enable = true;
|
||||
services.xserver.displayManager.defaultSession = "xfce";
|
||||
```
|
||||
|
||||
Optionally, *picom* can be enabled for nice graphical effects, some
|
||||
example settings:
|
||||
|
||||
```nix
|
||||
services.picom = {
|
||||
enable = true;
|
||||
fade = true;
|
||||
inactiveOpacity = 0.9;
|
||||
shadow = true;
|
||||
fadeDelta = 4;
|
||||
};
|
||||
```
|
||||
|
||||
Some Xfce programs are not installed automatically. To install them
|
||||
manually (system wide), put them into your
|
||||
[](#opt-environment.systemPackages) from `pkgs.xfce`.
|
||||
|
||||
## Thunar Plugins {#sec-xfce-thunar-plugins .unnumbered}
|
||||
|
||||
If you\'d like to add extra plugins to Thunar, add them to
|
||||
[](#opt-services.xserver.desktopManager.xfce.thunarPlugins).
|
||||
You shouldn\'t just add them to [](#opt-environment.systemPackages).
|
||||
|
||||
## Troubleshooting {#sec-xfce-troubleshooting .unnumbered}
|
||||
|
||||
Even after enabling udisks2, volume management might not work. Thunar
|
||||
and/or the desktop takes time to show up. Thunar will spit out this kind
|
||||
of message on start (look at `journalctl --user -b`).
|
||||
|
||||
```plain
|
||||
Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported
|
||||
```
|
||||
|
||||
This is caused by some needed GNOME services not running. This is all
|
||||
fixed by enabling \"Launch GNOME services on startup\" in the Advanced
|
||||
tab of the Session and Startup settings panel. Alternatively, you can
|
||||
run this command to do the same thing.
|
||||
|
||||
```ShellSession
|
||||
$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
|
||||
```
|
||||
|
||||
A log-out and re-log will be needed for this to take effect.
|
||||
|
|
@ -1,59 +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-xfce">
|
||||
<title>Xfce Desktop Environment</title>
|
||||
<para>
|
||||
To enable the Xfce Desktop Environment, set
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.desktopManager.xfce.enable" /> = true;
|
||||
<xref linkend="opt-services.xserver.displayManager.defaultSession" /> = "xfce";
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Optionally, <emphasis>picom</emphasis> can be enabled for nice graphical
|
||||
effects, some example settings:
|
||||
<programlisting>
|
||||
<link linkend="opt-services.picom.enable">services.picom</link> = {
|
||||
<link linkend="opt-services.picom.enable">enable</link> = true;
|
||||
<link linkend="opt-services.picom.fade">fade</link> = true;
|
||||
<link linkend="opt-services.picom.inactiveOpacity">inactiveOpacity</link> = 0.9;
|
||||
<link linkend="opt-services.picom.shadow">shadow</link> = true;
|
||||
<link linkend="opt-services.picom.fadeDelta">fadeDelta</link> = 4;
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Some Xfce programs are not installed automatically. To install them manually
|
||||
(system wide), put them into your
|
||||
<xref linkend="opt-environment.systemPackages"/> from <literal>pkgs.xfce</literal>.
|
||||
</para>
|
||||
<simplesect xml:id="sec-xfce-thunar-plugins">
|
||||
<title>Thunar Plugins</title>
|
||||
<para>
|
||||
If you'd like to add extra plugins to Thunar, add them to
|
||||
<xref linkend="opt-services.xserver.desktopManager.xfce.thunarPlugins"/>.
|
||||
You shouldn't just add them to <xref linkend="opt-environment.systemPackages"/>.
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect xml:id="sec-xfce-troubleshooting">
|
||||
<title>Troubleshooting</title>
|
||||
<para>
|
||||
Even after enabling udisks2, volume management might not work. Thunar and/or
|
||||
the desktop takes time to show up. Thunar will spit out this kind of message
|
||||
on start (look at <command>journalctl --user -b</command>).
|
||||
<programlisting>
|
||||
Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported
|
||||
</programlisting>
|
||||
This is caused by some needed GNOME services not running. This is all fixed
|
||||
by enabling "Launch GNOME services on startup" in the Advanced tab of the
|
||||
Session and Startup settings panel. Alternatively, you can run this command
|
||||
to do the same thing.
|
||||
<programlisting>
|
||||
<prompt>$ </prompt>xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
|
||||
</programlisting>
|
||||
A log-out and re-log will be needed for this to take effect.
|
||||
</para>
|
||||
</simplesect>
|
||||
</chapter>
|
||||
239
nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
Normal file
239
nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
Normal file
|
|
@ -0,0 +1,239 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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
|
||||
<literal>OCL_ICD_VENDORS</literal> environment variable. This
|
||||
variable can contain a directory which is scanned by the ICL
|
||||
loader for ICD files. For example:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ export \
|
||||
OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/
|
||||
</programlisting>
|
||||
<para>
|
||||
The second mechanism is to add the OpenCL driver package to
|
||||
<xref linkend="opt-hardware.opengl.extraPackages" />. This links
|
||||
the ICD file under <literal>/run/opengl-driver</literal>, where it
|
||||
will be visible to the ICD loader.
|
||||
</para>
|
||||
<para>
|
||||
The proper installation of OpenCL drivers can be verified through
|
||||
the <literal>clinfo</literal> command of the clinfo package. This
|
||||
command will report the number of hardware devices that is found
|
||||
and give detailed information for each device:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ clinfo | head -n3
|
||||
Number of platforms 1
|
||||
Platform Name AMD Accelerated Parallel Processing
|
||||
Platform Vendor Advanced Micro Devices, Inc.
|
||||
</programlisting>
|
||||
<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
|
||||
rocm-opencl-icd package. Adding this package to
|
||||
<xref linkend="opt-hardware.opengl.extraPackages" /> enables
|
||||
OpenCL support:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
hardware.opengl.extraPackages = [
|
||||
rocm-opencl-icd
|
||||
];
|
||||
</programlisting>
|
||||
</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 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.
|
||||
</para>
|
||||
<para>
|
||||
The intel-compute-runtime, beignet, or intel-ocl 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:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
hardware.opengl.extraPackages = [
|
||||
intel-compute-runtime
|
||||
];
|
||||
</programlisting>
|
||||
</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, mesa 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
|
||||
<literal>VK_ICD_FILENAMES</literal> environment variable. This
|
||||
variable can contain multiple JSON files, separated by
|
||||
<literal>:</literal>. For example:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ export \
|
||||
VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json
|
||||
</programlisting>
|
||||
<para>
|
||||
The second mechanism is to add the Vulkan driver package to
|
||||
<xref linkend="opt-hardware.opengl.extraPackages" />. This links
|
||||
the ICD file under <literal>/run/opengl-driver</literal>, where it
|
||||
will be visible to the ICD loader.
|
||||
</para>
|
||||
<para>
|
||||
The proper installation of Vulkan drivers can be verified through
|
||||
the <literal>vulkaninfo</literal> command of the vulkan-tools
|
||||
package. This command will report the hardware devices and drivers
|
||||
found, in this example output amdvlk and radv:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ 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
|
||||
</programlisting>
|
||||
<para>
|
||||
A simple graphical application that uses Vulkan is
|
||||
<literal>vkcube</literal> from the vulkan-tools 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 mesa, or the amdvlk package. Adding the amdvlk
|
||||
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:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
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";
|
||||
</programlisting>
|
||||
</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 (<literal>/dev/dri/renderD*</literal>) or are tagged
|
||||
as <literal>uaccess</literal>
|
||||
(<literal>/dev/dri/card*</literal>). The access control lists of
|
||||
devices with the <literal>uaccess</literal> tag will be updated
|
||||
automatically when a user logs in through
|
||||
<literal>systemd-logind</literal>. For example, if the user
|
||||
<emphasis>jane</emphasis> is logged in, the access control list
|
||||
should look as follows:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ getfacl /dev/dri/card0
|
||||
# file: dev/dri/card0
|
||||
# owner: root
|
||||
# group: video
|
||||
user::rw-
|
||||
user:jane:rw-
|
||||
group::rw-
|
||||
mask::rw-
|
||||
other::---
|
||||
</programlisting>
|
||||
<para>
|
||||
If you disabled (this functionality of)
|
||||
<literal>systemd-logind</literal>, you may need to add the user
|
||||
to the <literal>video</literal> 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 <literal>dlopen</literal>. 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.
|
||||
</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 <literal>LD_DEBUG</literal> variable set to
|
||||
get more diagnostic information. For example, OpenCL can be
|
||||
tested with <literal>LD_DEBUG=files clinfo</literal>, which
|
||||
should report missing symbols.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
126
nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml
Normal file
126
nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.kubernetes = {
|
||||
apiserver.enable = true;
|
||||
controllerManager.enable = true;
|
||||
scheduler.enable = true;
|
||||
addonManager.enable = true;
|
||||
proxy.enable = true;
|
||||
flannel.enable = true;
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
Another way is to assign cluster roles ("master" and/or
|
||||
"node") to the host. This enables apiserver,
|
||||
controllerManager, scheduler, addonManager, kube-proxy and etcd:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.kubernetes.roles = [ "master" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
While this will enable the kubelet and kube-proxy only:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.kubernetes.roles = [ "node" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
Assigning both the master and node roles is usable if you want a
|
||||
single node Kubernetes cluster for dev or testing purposes:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.kubernetes.roles = [ "master" "node" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
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>
|
||||
150
nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
Normal file
150
nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-kernel-config">
|
||||
<title>Linux Kernel</title>
|
||||
<para>
|
||||
You can override the Linux kernel and associated packages using the
|
||||
option <literal>boot.kernelPackages</literal>. For instance, this
|
||||
selects the Linux 3.10 kernel:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
boot.kernelPackages = pkgs.linuxPackages_3_10;
|
||||
</programlisting>
|
||||
<para>
|
||||
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>
|
||||
The default Linux kernel configuration should be fine for most
|
||||
users. You can see the configuration of your current kernel with the
|
||||
following command:
|
||||
</para>
|
||||
<programlisting>
|
||||
zcat /proc/config.gz
|
||||
</programlisting>
|
||||
<para>
|
||||
If you want to change the kernel configuration, you can use the
|
||||
<literal>packageOverrides</literal> feature (see
|
||||
<xref linkend="sec-customising-packages" />). For instance, to
|
||||
enable support for the kernel debugger KGDB:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
nixpkgs.config.packageOverrides = pkgs:
|
||||
{ linux_3_4 = pkgs.linux_3_4.override {
|
||||
extraConfig =
|
||||
''
|
||||
KGDB y
|
||||
'';
|
||||
};
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
<literal>extraConfig</literal> 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 <literal>udev</literal>. You can force a module to
|
||||
be loaded via <xref linkend="opt-boot.kernelModules" />, e.g.
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
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" />:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
boot.initrd.kernelModules = [ "cifs" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
|
||||
</programlisting>
|
||||
<para>
|
||||
sets the kernel’s TCP keepalive time to 120 seconds. To see the
|
||||
available parameters, run <literal>sysctl -a</literal>.
|
||||
</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>linuxManualConfig</literal>:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
custom-kernel = super.linuxManualConfig {
|
||||
inherit (super) stdenv hostPlatform;
|
||||
inherit (linux_4_9) src;
|
||||
version = "${linux_4_9.version}-custom";
|
||||
|
||||
configfile = /home/me/my_kernel_config;
|
||||
allowImportFromDerivation = true;
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
You can edit the config with this snippet (by default
|
||||
<literal>make menuconfig</literal> won't work out of the box on
|
||||
nixos):
|
||||
</para>
|
||||
<programlisting>
|
||||
nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
|
||||
</programlisting>
|
||||
<para>
|
||||
or you can let nixpkgs generate the configuration. Nixpkgs
|
||||
generates it via answering the interactive kernel utility
|
||||
<literal>make config</literal>. The answers depend on parameters
|
||||
passed to
|
||||
<literal>pkgs/os-specific/linux/kernel/generic.nix</literal>
|
||||
(which you can influence by overriding
|
||||
<literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>).
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
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
|
||||
'';
|
||||
});
|
||||
</programlisting>
|
||||
</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>
|
||||
<programlisting>
|
||||
$ 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
|
||||
</programlisting>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
@ -51,8 +51,8 @@ SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation
|
|||
</para>
|
||||
<para>
|
||||
The file system can be configured in NixOS via the usual
|
||||
<link xlink:href="options.html#opt-fileSystems">fileSystems</link>
|
||||
option. Here’s a typical setup:
|
||||
<link linkend="opt-fileSystems">fileSystems</link> option. Here’s
|
||||
a typical setup:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
{
|
||||
|
|
|
|||
121
nixos/doc/manual/from_md/configuration/subversion.chapter.xml
Normal file
121
nixos/doc/manual/from_md/configuration/subversion.chapter.xml
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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>
|
||||
<programlisting language="bash">
|
||||
services.httpd.enable = true;
|
||||
services.httpd.adminAddr = ...;
|
||||
networking.firewall.allowedTCPPorts = [ 80 443 ];
|
||||
</programlisting>
|
||||
<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
|
||||
<literal>.authz</literal> file describing access permission, and
|
||||
<literal>AuthUserFile</literal> to the password file.
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
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>
|
||||
The key <literal>"svn"</literal> is just a symbolic name
|
||||
identifying the virtual host. The
|
||||
<literal>"/svn"</literal> in
|
||||
<literal>locations."/svn".extraConfig</literal> 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>
|
||||
<programlisting>
|
||||
$ svn create REPO_NAME
|
||||
</programlisting>
|
||||
<para>
|
||||
Repository files need to be accessible by
|
||||
<literal>wwwrun</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ chown -R wwwrun:wwwrun REPO_PARENT
|
||||
</programlisting>
|
||||
<para>
|
||||
The password file <literal>PASSWORD_FILE</literal> can be created
|
||||
as follows:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ htpasswd -cs PASSWORD_FILE USER_NAME
|
||||
</programlisting>
|
||||
<para>
|
||||
Additional users can be set up similarly, omitting the
|
||||
<literal>c</literal> flag:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ htpasswd -s PASSWORD_FILE USER_NAME
|
||||
</programlisting>
|
||||
<para>
|
||||
The file describing access permissions
|
||||
<literal>ACCESS_FILE</literal> will look something like the
|
||||
following:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
[/]
|
||||
* = r
|
||||
|
||||
[REPO_NAME:/]
|
||||
USER_NAME = rw
|
||||
</programlisting>
|
||||
<para>
|
||||
The Subversion repositories will be accessible as
|
||||
<literal>http://HOSTNAME/svn/REPO_NAME</literal>.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
105
nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml
Normal file
105
nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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
|
||||
<literal>configuration.nix</literal>. For instance, the following
|
||||
states that a user account named <literal>alice</literal> shall
|
||||
exist:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
users.users.alice = {
|
||||
isNormalUser = true;
|
||||
home = "/home/alice";
|
||||
description = "Alice Foobar";
|
||||
extraGroups = [ "wheel" "networkmanager" ];
|
||||
openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
Note that <literal>alice</literal> is a member of the
|
||||
<literal>wheel</literal> and <literal>networkmanager</literal>
|
||||
groups, which allows her to use <literal>sudo</literal> 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
|
||||
<literal>passwd</literal> program to set a password, which is
|
||||
retained across invocations of <literal>nixos-rebuild</literal>.
|
||||
</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
|
||||
<literal>mkpasswd -m sha-512</literal>.
|
||||
</para>
|
||||
<para>
|
||||
A user ID (uid) is assigned automatically. You can also specify a
|
||||
uid manually by adding
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
uid = 1000;
|
||||
</programlisting>
|
||||
<para>
|
||||
to the user specification.
|
||||
</para>
|
||||
<para>
|
||||
Groups can be specified similarly. The following states that a group
|
||||
named <literal>students</literal> shall exist:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
users.groups.students.gid = 1000;
|
||||
</programlisting>
|
||||
<para>
|
||||
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 <literal>useradd</literal>, <literal>groupmod</literal> and
|
||||
so on. For instance, to create a user account named
|
||||
<literal>alice</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
# useradd -m alice
|
||||
</programlisting>
|
||||
<para>
|
||||
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:
|
||||
</para>
|
||||
<programlisting>
|
||||
# su - alice -c "true"
|
||||
</programlisting>
|
||||
<para>
|
||||
The flag <literal>-m</literal> 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 <literal>passwd</literal> utility:
|
||||
</para>
|
||||
<programlisting>
|
||||
# passwd alice
|
||||
Enter new UNIX password: ***
|
||||
Retype new UNIX password: ***
|
||||
</programlisting>
|
||||
<para>
|
||||
A user can be deleted using <literal>userdel</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
# userdel -r alice
|
||||
</programlisting>
|
||||
<para>
|
||||
The flag <literal>-r</literal> deletes the user’s home directory.
|
||||
Accounts can be modified using <literal>usermod</literal>. Unix
|
||||
groups can be managed using <literal>groupadd</literal>,
|
||||
<literal>groupmod</literal> and <literal>groupdel</literal>.
|
||||
</para>
|
||||
</chapter>
|
||||
31
nixos/doc/manual/from_md/configuration/wayland.chapter.xml
Normal file
31
nixos/doc/manual/from_md/configuration/wayland.chapter.xml
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-wayland">
|
||||
<title>Wayland</title>
|
||||
<para>
|
||||
While X11 (see <xref linkend="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:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
programs.sway.enable = true;
|
||||
</programlisting>
|
||||
<para>
|
||||
This installs the sway compositor along with some essential
|
||||
utilities. Now you can start sway from the TTY console.
|
||||
</para>
|
||||
<para>
|
||||
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:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
xdg.portal.wlr.enable = true;
|
||||
</programlisting>
|
||||
<para>
|
||||
and configure Pipewire using
|
||||
<xref linkend="opt-services.pipewire.enable" /> and related options.
|
||||
</para>
|
||||
</chapter>
|
||||
381
nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
Normal file
381
nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
Normal file
|
|
@ -0,0 +1,381 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-x11">
|
||||
<title>X Window System</title>
|
||||
<para>
|
||||
The X Window System (X11) provides the basis of NixOS’ graphical
|
||||
user interface. It can be enabled as follows:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.enable = true;
|
||||
</programlisting>
|
||||
<para>
|
||||
The X server will automatically detect and use the appropriate video
|
||||
driver from a set of X.org drivers (such as <literal>vesa</literal>
|
||||
and <literal>intel</literal>). You can also specify a driver
|
||||
manually, e.g.
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.videoDrivers = [ "r128" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
to enable X.org’s <literal>xf86-video-r128</literal> driver.
|
||||
</para>
|
||||
<para>
|
||||
You also need to enable at least one desktop or window manager.
|
||||
Otherwise, you can only log into a plain undecorated
|
||||
<literal>xterm</literal> window. Thus you should pick one or more of
|
||||
the following lines:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.desktopManager.plasma5.enable = true;
|
||||
services.xserver.desktopManager.xfce.enable = true;
|
||||
services.xserver.desktopManager.gnome.enable = true;
|
||||
services.xserver.desktopManager.mate.enable = true;
|
||||
services.xserver.windowManager.xmonad.enable = true;
|
||||
services.xserver.windowManager.twm.enable = true;
|
||||
services.xserver.windowManager.icewm.enable = true;
|
||||
services.xserver.windowManager.i3.enable = true;
|
||||
services.xserver.windowManager.herbstluftwm.enable = true;
|
||||
</programlisting>
|
||||
<para>
|
||||
NixOS’s default <emphasis>display manager</emphasis> (the program
|
||||
that provides a graphical login prompt and manages the X server) is
|
||||
LightDM. You can select an alternative one by picking one of the
|
||||
following lines:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.displayManager.sddm.enable = true;
|
||||
services.xserver.displayManager.gdm.enable = true;
|
||||
</programlisting>
|
||||
<para>
|
||||
You can set the keyboard layout (and optionally the layout variant):
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.layout = "de";
|
||||
services.xserver.xkbVariant = "neo";
|
||||
</programlisting>
|
||||
<para>
|
||||
The X server is started automatically at boot time. If you don’t
|
||||
want this to happen, you can set:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.autorun = false;
|
||||
</programlisting>
|
||||
<para>
|
||||
The X server can then be started manually:
|
||||
</para>
|
||||
<programlisting>
|
||||
# systemctl start display-manager.service
|
||||
</programlisting>
|
||||
<para>
|
||||
On 64-bit systems, if you want OpenGL for 32-bit programs such as in
|
||||
Wine, you should also set the following:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
hardware.opengl.driSupport32Bit = true;
|
||||
</programlisting>
|
||||
<section xml:id="sec-x11-auto-login">
|
||||
<title>Auto-login</title>
|
||||
<para>
|
||||
The x11 login screen can be skipped entirely, automatically
|
||||
logging you into your window manager and desktop environment when
|
||||
you boot your computer.
|
||||
</para>
|
||||
<para>
|
||||
This is especially helpful if you have disk encryption enabled.
|
||||
Since you already have to provide a password to decrypt your disk,
|
||||
entering a second password to login can be redundant.
|
||||
</para>
|
||||
<para>
|
||||
To enable auto-login, you need to define your default window
|
||||
manager and desktop environment. If you wanted no desktop
|
||||
environment and i3 as your your window manager, you'd define:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.displayManager.defaultSession = "none+i3";
|
||||
</programlisting>
|
||||
<para>
|
||||
Every display manager in NixOS supports auto-login, here is an
|
||||
example using lightdm for a user <literal>alice</literal>:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.displayManager.lightdm.enable = true;
|
||||
services.xserver.displayManager.autoLogin.enable = true;
|
||||
services.xserver.displayManager.autoLogin.user = "alice";
|
||||
</programlisting>
|
||||
</section>
|
||||
<section xml:id="sec-x11--graphics-cards-intel">
|
||||
<title>Intel Graphics drivers</title>
|
||||
<para>
|
||||
There are two choices for Intel Graphics drivers in X.org:
|
||||
<literal>modesetting</literal> (included in the xorg-server
|
||||
itself) and <literal>intel</literal> (provided by the package
|
||||
xf86-video-intel).
|
||||
</para>
|
||||
<para>
|
||||
The default and recommended is <literal>modesetting</literal>. It
|
||||
is a generic driver which uses the kernel
|
||||
<link xlink:href="https://en.wikipedia.org/wiki/Mode_setting">mode
|
||||
setting</link> (KMS) mechanism. It supports Glamor (2D graphics
|
||||
acceleration via OpenGL) and is actively maintained but may
|
||||
perform worse in some cases (like in old chipsets).
|
||||
</para>
|
||||
<para>
|
||||
The second driver, <literal>intel</literal>, is specific to Intel
|
||||
GPUs, but not recommended by most distributions: it lacks several
|
||||
modern features (for example, it doesn't support Glamor) and the
|
||||
package hasn't been officially updated since 2015.
|
||||
</para>
|
||||
<para>
|
||||
The results vary depending on the hardware, so you may have to try
|
||||
both drivers. Use the option
|
||||
<xref linkend="opt-services.xserver.videoDrivers" /> to set one.
|
||||
The recommended configuration for modern systems is:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.videoDrivers = [ "modesetting" ];
|
||||
services.xserver.useGlamor = true;
|
||||
</programlisting>
|
||||
<para>
|
||||
If you experience screen tearing no matter what, this
|
||||
configuration was reported to resolve the issue:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.videoDrivers = [ "intel" ];
|
||||
services.xserver.deviceSection = ''
|
||||
Option "DRI" "2"
|
||||
Option "TearFree" "true"
|
||||
'';
|
||||
</programlisting>
|
||||
<para>
|
||||
Note that this will likely downgrade the performance compared to
|
||||
<literal>modesetting</literal> or <literal>intel</literal> with
|
||||
DRI 3 (default).
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-x11-graphics-cards-nvidia">
|
||||
<title>Proprietary NVIDIA drivers</title>
|
||||
<para>
|
||||
NVIDIA provides a proprietary driver for its graphics cards that
|
||||
has better 3D performance than the X.org drivers. It is not
|
||||
enabled by default because it’s not free software. You can enable
|
||||
it as follows:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.videoDrivers = [ "nvidia" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
Or if you have an older card, you may have to use one of the
|
||||
legacy drivers:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.videoDrivers = [ "nvidiaLegacy390" ];
|
||||
services.xserver.videoDrivers = [ "nvidiaLegacy340" ];
|
||||
services.xserver.videoDrivers = [ "nvidiaLegacy304" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
You may need to reboot after enabling this driver to prevent a
|
||||
clash with other kernel modules.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-x11--graphics-cards-amd">
|
||||
<title>Proprietary AMD drivers</title>
|
||||
<para>
|
||||
AMD provides a proprietary driver for its graphics cards that is
|
||||
not enabled by default because it’s not Free Software, is often
|
||||
broken in nixpkgs and as of this writing doesn't offer more
|
||||
features or performance. If you still want to use it anyway, you
|
||||
need to explicitly set:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.videoDrivers = [ "amdgpu-pro" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
You will need to reboot after enabling this driver to prevent a
|
||||
clash with other kernel modules.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-x11-touchpads">
|
||||
<title>Touchpads</title>
|
||||
<para>
|
||||
Support for Synaptics touchpads (found in many laptops such as the
|
||||
Dell Latitude series) can be enabled as follows:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.libinput.enable = true;
|
||||
</programlisting>
|
||||
<para>
|
||||
The driver has many options (see <xref linkend="ch-options" />).
|
||||
For instance, the following disables tap-to-click behavior:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.libinput.touchpad.tapping = false;
|
||||
</programlisting>
|
||||
<para>
|
||||
Note: the use of <literal>services.xserver.synaptics</literal> is
|
||||
deprecated since NixOS 17.09.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-x11-gtk-and-qt-themes">
|
||||
<title>GTK/Qt themes</title>
|
||||
<para>
|
||||
GTK themes can be installed either to user profile or system-wide
|
||||
(via <literal>environment.systemPackages</literal>). To make Qt 5
|
||||
applications look similar to GTK ones, you can use the following
|
||||
configuration:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
qt5.enable = true;
|
||||
qt5.platformTheme = "gtk2";
|
||||
qt5.style = "gtk2";
|
||||
</programlisting>
|
||||
</section>
|
||||
<section xml:id="custom-xkb-layouts">
|
||||
<title>Custom XKB layouts</title>
|
||||
<para>
|
||||
It is possible to install custom
|
||||
<link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">
|
||||
XKB </link> keyboard layouts using the option
|
||||
<literal>services.xserver.extraLayouts</literal>.
|
||||
</para>
|
||||
<para>
|
||||
As a first example, we are going to create a layout based on the
|
||||
basic US layout, with an additional layer to type some greek
|
||||
symbols by pressing the right-alt key.
|
||||
</para>
|
||||
<para>
|
||||
Create a file called <literal>us-greek</literal> with the
|
||||
following content (under a directory called
|
||||
<literal>symbols</literal>; it's an XKB peculiarity that will help
|
||||
with testing):
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
xkb_symbols "us-greek"
|
||||
{
|
||||
include "us(basic)" // includes the base US keys
|
||||
include "level3(ralt_switch)" // configures right alt as a third level switch
|
||||
|
||||
key <LatA> { [ a, A, Greek_alpha ] };
|
||||
key <LatB> { [ b, B, Greek_beta ] };
|
||||
key <LatG> { [ g, G, Greek_gamma ] };
|
||||
key <LatD> { [ d, D, Greek_delta ] };
|
||||
key <LatZ> { [ z, Z, Greek_zeta ] };
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
A minimal layout specification must include the following:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.extraLayouts.us-greek = {
|
||||
description = "US layout with alt-gr greek";
|
||||
languages = [ "eng" ];
|
||||
symbolsFile = /yourpath/symbols/us-greek;
|
||||
};
|
||||
</programlisting>
|
||||
<note>
|
||||
<para>
|
||||
The name (after <literal>extraLayouts.</literal>) should match
|
||||
the one given to the <literal>xkb_symbols</literal> block.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Applying this customization requires rebuilding several packages,
|
||||
and a broken XKB file can lead to the X session crashing at login.
|
||||
Therefore, you're strongly advised to <emphasis role="strong">test
|
||||
your layout before applying it</emphasis>:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-shell -p xorg.xkbcomp
|
||||
$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
|
||||
</programlisting>
|
||||
<para>
|
||||
You can inspect the predefined XKB files for examples:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
|
||||
</programlisting>
|
||||
<para>
|
||||
Once the configuration is applied, and you did a logout/login
|
||||
cycle, the layout should be ready to use. You can try it by e.g.
|
||||
running <literal>setxkbmap us-greek</literal> and then type
|
||||
<literal><alt>+a</literal> (it may not get applied in your
|
||||
terminal straight away). To change the default, the usual
|
||||
<literal>services.xserver.layout</literal> option can still be
|
||||
used.
|
||||
</para>
|
||||
<para>
|
||||
A layout can have several other components besides
|
||||
<literal>xkb_symbols</literal>, for example we will define new
|
||||
keycodes for some multimedia key and bind these to some symbol.
|
||||
</para>
|
||||
<para>
|
||||
Use the <emphasis>xev</emphasis> utility from
|
||||
<literal>pkgs.xorg.xev</literal> to find the codes of the keys of
|
||||
interest, then create a <literal>media-key</literal> file to hold
|
||||
the keycodes definitions
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
xkb_keycodes "media"
|
||||
{
|
||||
<volUp> = 123;
|
||||
<volDown> = 456;
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
Now use the newly define keycodes in <literal>media-sym</literal>:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
xkb_symbols "media"
|
||||
{
|
||||
key.type = "ONE_LEVEL";
|
||||
key <volUp> { [ XF86AudioLowerVolume ] };
|
||||
key <volDown> { [ XF86AudioRaiseVolume ] };
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
As before, to install the layout do
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.extraLayouts.media = {
|
||||
description = "Multimedia keys remapping";
|
||||
languages = [ "eng" ];
|
||||
symbolsFile = /path/to/media-key;
|
||||
keycodesFile = /path/to/media-sym;
|
||||
};
|
||||
</programlisting>
|
||||
<note>
|
||||
<para>
|
||||
The function
|
||||
<literal>pkgs.writeText <filename> <content></literal>
|
||||
can be useful if you prefer to keep the layout definitions
|
||||
inside the NixOS configuration.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Unfortunately, the Xorg server does not (currently) support
|
||||
setting a keymap directly but relies instead on XKB rules to
|
||||
select the matching components (keycodes, types, ...) of a layout.
|
||||
This means that components other than symbols won't be loaded by
|
||||
default. As a workaround, you can set the keymap using
|
||||
<literal>setxkbmap</literal> at the start of the session with:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
|
||||
</programlisting>
|
||||
<para>
|
||||
If you are manually starting the X server, you should set the
|
||||
argument <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X
|
||||
won't find your layout files. For example with
|
||||
<literal>xinit</literal> run
|
||||
</para>
|
||||
<programlisting>
|
||||
$ xinit -- -xkbdir /etc/X11/xkb
|
||||
</programlisting>
|
||||
<para>
|
||||
To learn how to write layouts take a look at the XKB
|
||||
<link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">documentation
|
||||
</link>. More example layouts can also be found
|
||||
<link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">here
|
||||
</link>.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
62
nixos/doc/manual/from_md/configuration/xfce.chapter.xml
Normal file
62
nixos/doc/manual/from_md/configuration/xfce.chapter.xml
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-xfce">
|
||||
<title>Xfce Desktop Environment</title>
|
||||
<para>
|
||||
To enable the Xfce Desktop Environment, set
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.xserver.desktopManager.xfce.enable = true;
|
||||
services.xserver.displayManager.defaultSession = "xfce";
|
||||
</programlisting>
|
||||
<para>
|
||||
Optionally, <emphasis>picom</emphasis> can be enabled for nice
|
||||
graphical effects, some example settings:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
services.picom = {
|
||||
enable = true;
|
||||
fade = true;
|
||||
inactiveOpacity = 0.9;
|
||||
shadow = true;
|
||||
fadeDelta = 4;
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
Some Xfce programs are not installed automatically. To install them
|
||||
manually (system wide), put them into your
|
||||
<xref linkend="opt-environment.systemPackages" /> from
|
||||
<literal>pkgs.xfce</literal>.
|
||||
</para>
|
||||
<section xml:id="sec-xfce-thunar-plugins">
|
||||
<title>Thunar Plugins</title>
|
||||
<para>
|
||||
If you'd like to add extra plugins to Thunar, add them to
|
||||
<xref linkend="opt-services.xserver.desktopManager.xfce.thunarPlugins" />.
|
||||
You shouldn't just add them to
|
||||
<xref linkend="opt-environment.systemPackages" />.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-xfce-troubleshooting">
|
||||
<title>Troubleshooting</title>
|
||||
<para>
|
||||
Even after enabling udisks2, volume management might not work.
|
||||
Thunar and/or the desktop takes time to show up. Thunar will spit
|
||||
out this kind of message on start (look at
|
||||
<literal>journalctl --user -b</literal>).
|
||||
</para>
|
||||
<programlisting>
|
||||
Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported
|
||||
</programlisting>
|
||||
<para>
|
||||
This is caused by some needed GNOME services not running. This is
|
||||
all fixed by enabling "Launch GNOME services on startup"
|
||||
in the Advanced tab of the Session and Startup settings panel.
|
||||
Alternatively, you can run this command to do the same thing.
|
||||
</para>
|
||||
<programlisting>
|
||||
$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
|
||||
</programlisting>
|
||||
<para>
|
||||
A log-out and re-log will be needed for this to take effect.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
Loading…
Reference in a new issue