diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index 6949189b8883..2461a5de73ad 100644
--- a/nixos/doc/manual/configuration/configuration.xml
+++ b/nixos/doc/manual/configuration/configuration.xml
@@ -15,17 +15,17 @@
-
+
-
-
-
-
+
+
+
+
-
-
+
+
-
+
diff --git a/nixos/doc/manual/configuration/gpu-accel.chapter.md b/nixos/doc/manual/configuration/gpu-accel.chapter.md
new file mode 100644
index 000000000000..08b6af5d98ae
--- /dev/null
+++ b/nixos/doc/manual/configuration/gpu-accel.chapter.md
@@ -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 '' --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 '' --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.
diff --git a/nixos/doc/manual/configuration/gpu-accel.xml b/nixos/doc/manual/configuration/gpu-accel.xml
deleted file mode 100644
index 9aa9be86a061..000000000000
--- a/nixos/doc/manual/configuration/gpu-accel.xml
+++ /dev/null
@@ -1,262 +0,0 @@
-
- GPU acceleration
-
-
- 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
-
-
- 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:
-
- $ 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
- . 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:
-
-
- $ clinfo | head -n3
-Number of platforms 1
-Platform Name AMD Accelerated Parallel Processing
-Platform Vendor Advanced Micro Devices, Inc.
-
-
- AMD
-
-
- Modern AMD Graphics
- Core Next (GCN) GPUs are supported through the
- rocm-opencl-icd package. Adding this package to
- enables OpenCL
- support:
-
- = [
- rocm-opencl-icd
- ];
-
-
-
-
- Intel
-
-
- Intel
- Gen8 and later GPUs 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
- to enable OpenCL
- support. For example, for Gen8 and later GPUs, the following
- configuration can be used:
-
- = [
- intel-compute-runtime
- ];
-
-
-
-
-
-
- Vulkan
-
-
- Vulkan is a
- graphics and compute API for GPUs. It is used directly by games or indirectly though
- compatibility layers like DXVK.
-
-
-
- By default, if 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:
-
- $ 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
- . 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:
-
-
- $ 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
-
-
- Modern AMD Graphics
- Core Next (GCN) GPUs are supported through either radv, which is
- part of mesa, or the amdvlk package.
- Adding the amdvlk package to
- makes amdvlk the
- default driver and hides radv and lavapipe from the device list. A
- specific driver can be forced as follows:
-
- = [
- pkgs.amdvlk
- ];
-
- # To enable Vulkan support for 32-bit applications, also add:
- = [
- pkgs.driversi686Linux.amdvlk
- ];
-
- # Force radv
- .AMD_VULKAN_ICD = "RADV";
- # Or
- .VK_ICD_FILENAMES =
- "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";
-
-
-
-
-
-
- Common issues
-
-
- User 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:
-
- $ 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
-
-
- 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.
-
-
-
-
diff --git a/nixos/doc/manual/configuration/kubernetes.chapter.md b/nixos/doc/manual/configuration/kubernetes.chapter.md
new file mode 100644
index 000000000000..93787577be9b
--- /dev/null
+++ b/nixos/doc/manual/configuration/kubernetes.chapter.md
@@ -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.
diff --git a/nixos/doc/manual/configuration/kubernetes.xml b/nixos/doc/manual/configuration/kubernetes.xml
deleted file mode 100644
index 54a100e44795..000000000000
--- a/nixos/doc/manual/configuration/kubernetes.xml
+++ /dev/null
@@ -1,112 +0,0 @@
-
- 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:
-
-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:
-
- = [ "master" ];
-
- While this will enable the kubelet and kube-proxy only:
-
- = [ "node" ];
-
- Assigning both the master and node roles is usable if you want a single node
- Kubernetes cluster for dev or testing purposes:
-
- = [ "master" "node" ];
-
- Note: Assigning either role will also default both
- and
- 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:
- and
-
-
-
-
- As of NixOS 19.03, it is mandatory to configure:
- . 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.
-
-
- The NixOS kubernetes module provides an option for automatic certificate
- bootstrapping and configuration,
- . 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
- = 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
- 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.
-
-
-
- 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
- .
- 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.
-
-
diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md
new file mode 100644
index 000000000000..aad6d49c72c3
--- /dev/null
+++ b/nixos/doc/manual/configuration/linux-kernel.chapter.md
@@ -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 {}; 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 '' -A linuxPackages.kernel.dev
+$ nix-shell '' -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
+```
diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml
deleted file mode 100644
index 529ac1b1cd46..000000000000
--- a/nixos/doc/manual/configuration/linux-kernel.xml
+++ /dev/null
@@ -1,138 +0,0 @@
-
- Linux Kernel
-
- You can override the Linux kernel and associated packages using the option
- . For instance, this selects the Linux
- 3.10 kernel:
-
- = 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:
-
-zcat /proc/config.gz
-
- If you want to change the kernel configuration, you can use the
- feature (see
- ). For instance, to enable support
- for the kernel debugger KGDB:
-
-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
- , e.g.
-
- = [ "fuse" "kvm-intel" "coretemp" ];
-
- If the module is required early during the boot (e.g. to mount the root file
- system), you can use :
-
- = [ "cifs" ];
-
- This causes the specified modules and their dependencies to be added to the
- initial ramdisk.
-
-
- Kernel runtime parameters can be set through
- , e.g.
-
-."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
-
-
- 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:
-
- You can edit the config with this snippet (by default make
- menuconfig won't work out of the box on nixos):
- {}; 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).
-
-
-
-
- Developing kernel 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.
-
-
-
-$ 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
-
-
-
diff --git a/nixos/doc/manual/configuration/sshfs-file-systems.section.md b/nixos/doc/manual/configuration/sshfs-file-systems.section.md
index 4625fce03d58..4dd1b203a249 100644
--- a/nixos/doc/manual/configuration/sshfs-file-systems.section.md
+++ b/nixos/doc/manual/configuration/sshfs-file-systems.section.md
@@ -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
{
diff --git a/nixos/doc/manual/configuration/subversion.chapter.md b/nixos/doc/manual/configuration/subversion.chapter.md
new file mode 100644
index 000000000000..84f9c2703378
--- /dev/null
+++ b/nixos/doc/manual/configuration/subversion.chapter.md
@@ -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`.
diff --git a/nixos/doc/manual/configuration/subversion.xml b/nixos/doc/manual/configuration/subversion.xml
deleted file mode 100644
index 940d63cc4e6d..000000000000
--- a/nixos/doc/manual/configuration/subversion.xml
+++ /dev/null
@@ -1,140 +0,0 @@
-
- Subversion
-
-
- Subversion
- is a centralized version-control system. It can use a variety
- of protocols for communication between client and server.
-
-
- Subversion inside Apache HTTP
-
-
- This section focuses on configuring a web-based server on top of
- the Apache HTTP server, which uses
- WebDAV/DeltaV
- for communication.
-
-
- For more information on the general setup, please refer to
- the the
- appropriate section of the Subversion book.
-
-
- To configure, include in
- /etc/nixos/configuration.nix code to activate
- Apache HTTP, setting
- appropriately:
-
-
-
-
- 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.
-
-
-
-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 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:
-
-
-
-$ svn create REPO_NAME
-
-
- Repository files need to be accessible by
- wwwrun:
-
-
-
-$ chown -R wwwrun:wwwrun REPO_PARENT
-
-
-
- The password file PASSWORD_FILE can be created as follows:
-
-
-
-$ htpasswd -cs PASSWORD_FILE USER_NAME
-
-
-
- Additional users can be set up similarly, omitting the
- c flag:
-
-
-
-$ htpasswd -s PASSWORD_FILE USER_NAME
-
-
-
- The file describing access permissions
- ACCESS_FILE will look something like
- the following:
-
-
-
-[/]
-* = r
-
-[REPO_NAME:/]
-USER_NAME = rw
-
-
- The Subversion repositories will be accessible as http://HOSTNAME/svn/REPO_NAME.
-
-
diff --git a/nixos/doc/manual/configuration/user-mgmt.chapter.md b/nixos/doc/manual/configuration/user-mgmt.chapter.md
new file mode 100644
index 000000000000..37990664a8f1
--- /dev/null
+++ b/nixos/doc/manual/configuration/user-mgmt.chapter.md
@@ -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`.
diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml
deleted file mode 100644
index e83e7b75ef54..000000000000
--- a/nixos/doc/manual/configuration/user-mgmt.xml
+++ /dev/null
@@ -1,88 +0,0 @@
-
- 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:
-
-.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 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 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
- 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
-
-uid = 1000;
-
- to the user specification.
-
-
- Groups can be specified similarly. The following states that a group named
- students shall exist:
-
-.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:
-
-# 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:
-
-# su - alice -c "true"
- The flag 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:
-
-# passwd alice
-Enter new UNIX password: ***
-Retype new UNIX password: ***
-
- A user can be deleted using userdel:
-
-# userdel -r alice
- The flag deletes the user’s home directory. Accounts
- can be modified using usermod. Unix groups can be managed
- using groupadd, groupmod and
- groupdel.
-
-
diff --git a/nixos/doc/manual/configuration/wayland.chapter.md b/nixos/doc/manual/configuration/wayland.chapter.md
new file mode 100644
index 000000000000..a3a46aa3da6f
--- /dev/null
+++ b/nixos/doc/manual/configuration/wayland.chapter.md
@@ -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.
diff --git a/nixos/doc/manual/configuration/wayland.xml b/nixos/doc/manual/configuration/wayland.xml
deleted file mode 100644
index 2aefda3e22c0..000000000000
--- a/nixos/doc/manual/configuration/wayland.xml
+++ /dev/null
@@ -1,33 +0,0 @@
-
- Wayland
-
-
- While X11 (see ) 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:
-
- = 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:
-
- = true;
-
- and configure Pipewire using
- and related options.
-
-
diff --git a/nixos/doc/manual/configuration/x-windows.chapter.md b/nixos/doc/manual/configuration/x-windows.chapter.md
new file mode 100644
index 000000000000..2c80b786b267
--- /dev/null
+++ b/nixos/doc/manual/configuration/x-windows.chapter.md
@@ -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 { [ a, A, Greek_alpha ] };
+ key { [ b, B, Greek_beta ] };
+ key { [ g, G, Greek_gamma ] };
+ key { [ d, D, Greek_delta ] };
+ key { [ 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 '' -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 `+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"
+{
+ = 123;
+ = 456;
+}
+```
+
+Now use the newly define keycodes in `media-sym`:
+
+```nix
+xkb_symbols "media"
+{
+ key.type = "ONE_LEVEL";
+ key { [ XF86AudioLowerVolume ] };
+ key { [ 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 ` 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).
diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml
deleted file mode 100644
index f9121508d7d4..000000000000
--- a/nixos/doc/manual/configuration/x-windows.xml
+++ /dev/null
@@ -1,355 +0,0 @@
-
- X Window System
-
- The X Window System (X11) provides the basis of NixOS’ graphical user
- interface. It can be enabled as follows:
-
- = 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.
-
- = [ "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:
-
- = true;
- = true;
- = true;
- = true;
- = true;
- = true;
- = true;
- = true;
- = 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:
-
- = true;
- = true;
-
-
-
- You can set the keyboard layout (and optionally the layout variant):
-
- = "de";
- = "neo";
-
-
-
- The X server is started automatically at boot time. If you don’t want this
- to happen, you can set:
-
- = false;
-
- The X server can then be started manually:
-
-# 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:
-
- = true;
-
-
-
- Auto-login
-
- 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:
-
- = "none+i3";
-
- Every display manager in NixOS supports auto-login, here is an example
- using lightdm for a user alice:
-
- = true;
- = true;
- = "alice";
-
-
-
-
- Intel Graphics drivers
-
- 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
- (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 to set one.
- The recommended configuration for modern systems is:
-
- = [ "modesetting" ];
- = true;
-
- If you experience screen tearing no matter what, this configuration was
- reported to resolve the issue:
-
- = [ "intel" ];
- = ''
- 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
-
- 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:
-
- = [ "nvidia" ];
-
- Or if you have an older card, you may have to use one of the legacy drivers:
-
- = [ "nvidiaLegacy390" ];
- = [ "nvidiaLegacy340" ];
- = [ "nvidiaLegacy304" ];
-
- You may need to reboot after enabling this driver to prevent a clash with
- other kernel modules.
-
-
-
- Proprietary AMD drivers
-
- 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:
-
- = [ "amdgpu-pro" ];
-
- You will need to reboot after enabling this driver to prevent a clash with
- other kernel modules.
-
-
-
- Touchpads
-
- Support for Synaptics touchpads (found in many laptops such as the Dell
- Latitude series) can be enabled as follows:
-
- = true;
-
- The driver has many options (see ). For
- instance, the following disables tap-to-click behavior:
-
- = false;
-
- Note: the use of services.xserver.synaptics is deprecated
- since NixOS 17.09.
-
-
-
- GTK/Qt themes
-
- 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:
-
- = true;
- = "gtk2";
- = "gtk2";
-
-
-
-
- Custom XKB layouts
-
- It is possible to install custom
-
- XKB
-
- keyboard layouts using the option
- .
-
-
- 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):
-
-
-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:
-
-
-.us-greek = {
- description = "US layout with alt-gr greek";
- languages = [ "eng" ];
- symbolsFile = /yourpath/symbols/us-greek;
-};
-
-
-
- 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:
-
-$ nix-shell -p xorg.xkbcomp
-$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
-
-
-
- You can inspect the predefined XKB files for examples:
-
-$ 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
-
- 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
-
-
-xkb_keycodes "media"
-{
- <volUp> = 123;
- <volDown> = 456;
-}
-
-
- Now use the newly define keycodes in media-sym:
-
-
-xkb_symbols "media"
-{
- key.type = "ONE_LEVEL";
- key <volUp> { [ XF86AudioLowerVolume ] };
- key <volDown> { [ XF86AudioRaiseVolume ] };
-}
-
-
- As before, to install the layout do
-
-
-.media = {
- description = "Multimedia keys remapping";
- languages = [ "eng" ];
- symbolsFile = /path/to/media-key;
- keycodesFile = /path/to/media-sym;
-};
-
-
-
- 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:
-
-
- = "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
- $ xinit -- -xkbdir /etc/X11/xkb
-
-
- To learn how to write layouts take a look at the XKB
-
- documentation
- . More example layouts can also be found
-
- here
- .
-
-
-
diff --git a/nixos/doc/manual/configuration/xfce.chapter.md b/nixos/doc/manual/configuration/xfce.chapter.md
new file mode 100644
index 000000000000..b0ef6682aae8
--- /dev/null
+++ b/nixos/doc/manual/configuration/xfce.chapter.md
@@ -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.
diff --git a/nixos/doc/manual/configuration/xfce.xml b/nixos/doc/manual/configuration/xfce.xml
deleted file mode 100644
index abcf5f648a48..000000000000
--- a/nixos/doc/manual/configuration/xfce.xml
+++ /dev/null
@@ -1,59 +0,0 @@
-
- Xfce Desktop Environment
-
- To enable the Xfce Desktop Environment, set
-
- = true;
- = "xfce";
-
-
-
- Optionally, picom can be enabled for nice graphical
- effects, some example settings:
-
-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
- from pkgs.xfce.
-
-
- Thunar Plugins
-
- If you'd like to add extra plugins to Thunar, add them to
- .
- You shouldn't just add them to .
-
-
-
- Troubleshooting
-
- 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).
-
-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.
-
-$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
-
- A log-out and re-log will be needed for this to take effect.
-
-
-
diff --git a/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
new file mode 100644
index 000000000000..8e780c5dee95
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
@@ -0,0 +1,239 @@
+
+ GPU acceleration
+
+ 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
+
+ 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:
+
+
+$ 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
+ . 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:
+
+
+$ clinfo | head -n3
+Number of platforms 1
+Platform Name AMD Accelerated Parallel Processing
+Platform Vendor Advanced Micro Devices, Inc.
+
+
+ AMD
+
+ Modern AMD
+ Graphics
+ Core Next (GCN) GPUs are supported through the
+ rocm-opencl-icd package. Adding this package to
+ enables
+ OpenCL support:
+
+
+hardware.opengl.extraPackages = [
+ rocm-opencl-icd
+];
+
+
+
+ Intel
+
+ Intel
+ Gen8 and later GPUs 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 to
+ enable OpenCL support. For example, for Gen8 and later GPUs, the
+ following configuration can be used:
+
+
+hardware.opengl.extraPackages = [
+ intel-compute-runtime
+];
+
+
+
+
+ Vulkan
+
+ Vulkan
+ is a graphics and compute API for GPUs. It is used directly by
+ games or indirectly though compatibility layers like
+ DXVK.
+
+
+ By default, if
+ 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:
+
+
+$ 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
+ . 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:
+
+
+$ 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
+
+ Modern AMD
+ Graphics
+ Core Next (GCN) GPUs are supported through either radv,
+ which is part of mesa, or the amdvlk package. Adding the amdvlk
+ package to
+ makes amdvlk the default driver and hides radv and lavapipe from
+ the device list. A specific driver can be forced as follows:
+
+
+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
+
+ User 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:
+
+
+$ 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
+
+ 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.
+
+
+
+
diff --git a/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml
new file mode 100644
index 000000000000..83a50d7c49d1
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml
@@ -0,0 +1,126 @@
+
+ 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:
+
+
+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:
+
+
+services.kubernetes.roles = [ "master" ];
+
+
+ While this will enable the kubelet and kube-proxy only:
+
+
+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:
+
+
+services.kubernetes.roles = [ "master" "node" ];
+
+
+ Note: Assigning either role will also default both
+ and
+ 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:
+
+ and
+
+
+
+
+ As of NixOS 19.03, it is mandatory to configure:
+ . 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.
+
+
+ The NixOS kubernetes module provides an option for automatic
+ certificate bootstrapping and configuration,
+ . 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 = 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 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.
+
+
+
+ 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
+ .
+ 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.
+
+
diff --git a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
new file mode 100644
index 000000000000..f804d0a3b8c2
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
@@ -0,0 +1,150 @@
+
+ Linux Kernel
+
+ You can override the Linux kernel and associated packages using the
+ option boot.kernelPackages. For instance, this
+ selects the Linux 3.10 kernel:
+
+
+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:
+
+
+zcat /proc/config.gz
+
+
+ If you want to change the kernel configuration, you can use the
+ packageOverrides feature (see
+ ). For instance, to
+ enable support for the kernel debugger KGDB:
+
+
+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 , e.g.
+
+
+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
+ :
+
+
+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
+ , e.g.
+
+
+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
+
+ 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:
+
+
+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):
+
+
+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).
+
+
+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
+
+ 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.
+
+
+$ 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
+
+
+
diff --git a/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml b/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
index 6b317aa63e9a..5d74712f35dc 100644
--- a/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
+++ b/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
@@ -51,8 +51,8 @@ SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation
The file system can be configured in NixOS via the usual
- fileSystems
- option. Here’s a typical setup:
+ fileSystems option. Here’s
+ a typical setup:
{
diff --git a/nixos/doc/manual/from_md/configuration/subversion.chapter.xml b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml
new file mode 100644
index 000000000000..794c2c34e399
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml
@@ -0,0 +1,121 @@
+
+ Subversion
+
+ Subversion
+ is a centralized version-control system. It can use a
+ variety
+ of protocols for communication between client and server.
+
+
+ Subversion inside Apache HTTP
+
+ This section focuses on configuring a web-based server on top of
+ the Apache HTTP server, which uses
+ WebDAV/DeltaV
+ for communication.
+
+
+ For more information on the general setup, please refer to the
+ the
+ appropriate section of the Subversion book.
+
+
+ To configure, include in
+ /etc/nixos/configuration.nix code to activate
+ Apache HTTP, setting
+ appropriately:
+
+
+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.
+
+
+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 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:
+
+
+$ svn create REPO_NAME
+
+
+ Repository files need to be accessible by
+ wwwrun:
+
+
+$ chown -R wwwrun:wwwrun REPO_PARENT
+
+
+ The password file PASSWORD_FILE can be created
+ as follows:
+
+
+$ htpasswd -cs PASSWORD_FILE USER_NAME
+
+
+ Additional users can be set up similarly, omitting the
+ c flag:
+
+
+$ htpasswd -s PASSWORD_FILE USER_NAME
+
+
+ The file describing access permissions
+ ACCESS_FILE will look something like the
+ following:
+
+
+[/]
+* = r
+
+[REPO_NAME:/]
+USER_NAME = rw
+
+
+ The Subversion repositories will be accessible as
+ http://HOSTNAME/svn/REPO_NAME.
+
+
+
diff --git a/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml
new file mode 100644
index 000000000000..06492d5c2512
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml
@@ -0,0 +1,105 @@
+
+ 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:
+
+
+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 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
+ 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
+ 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
+
+
+uid = 1000;
+
+
+ to the user specification.
+
+
+ Groups can be specified similarly. The following states that a group
+ named students shall exist:
+
+
+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:
+
+
+# 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:
+
+
+# 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:
+
+
+# passwd alice
+Enter new UNIX password: ***
+Retype new UNIX password: ***
+
+
+ A user can be deleted using userdel:
+
+
+# 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.
+
+
diff --git a/nixos/doc/manual/from_md/configuration/wayland.chapter.xml b/nixos/doc/manual/from_md/configuration/wayland.chapter.xml
new file mode 100644
index 000000000000..1e90d4f31177
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/wayland.chapter.xml
@@ -0,0 +1,31 @@
+
+ Wayland
+
+ While X11 (see ) 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:
+
+
+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:
+
+
+xdg.portal.wlr.enable = true;
+
+
+ and configure Pipewire using
+ and related options.
+
+
diff --git a/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
new file mode 100644
index 000000000000..274d0d817bc1
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
@@ -0,0 +1,381 @@
+
+ X Window System
+
+ The X Window System (X11) provides the basis of NixOS’ graphical
+ user interface. It can be enabled as follows:
+
+
+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.
+
+
+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:
+
+
+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:
+
+
+services.xserver.displayManager.sddm.enable = true;
+services.xserver.displayManager.gdm.enable = true;
+
+
+ You can set the keyboard layout (and optionally the layout variant):
+
+
+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:
+
+
+services.xserver.autorun = false;
+
+
+ The X server can then be started manually:
+
+
+# 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:
+
+
+hardware.opengl.driSupport32Bit = true;
+
+
+ Auto-login
+
+ 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:
+
+
+services.xserver.displayManager.defaultSession = "none+i3";
+
+
+ Every display manager in NixOS supports auto-login, here is an
+ example using lightdm for a user alice:
+
+
+services.xserver.displayManager.lightdm.enable = true;
+services.xserver.displayManager.autoLogin.enable = true;
+services.xserver.displayManager.autoLogin.user = "alice";
+
+
+
+ Intel Graphics drivers
+
+ 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 (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
+ to set one.
+ The recommended configuration for modern systems is:
+
+
+services.xserver.videoDrivers = [ "modesetting" ];
+services.xserver.useGlamor = true;
+
+
+ If you experience screen tearing no matter what, this
+ configuration was reported to resolve the issue:
+
+
+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
+
+ 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:
+
+
+services.xserver.videoDrivers = [ "nvidia" ];
+
+
+ Or if you have an older card, you may have to use one of the
+ legacy drivers:
+
+
+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
+
+ 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:
+
+
+services.xserver.videoDrivers = [ "amdgpu-pro" ];
+
+
+ You will need to reboot after enabling this driver to prevent a
+ clash with other kernel modules.
+
+
+
+ Touchpads
+
+ Support for Synaptics touchpads (found in many laptops such as the
+ Dell Latitude series) can be enabled as follows:
+
+
+services.xserver.libinput.enable = true;
+
+
+ The driver has many options (see ).
+ For instance, the following disables tap-to-click behavior:
+
+
+services.xserver.libinput.touchpad.tapping = false;
+
+
+ Note: the use of services.xserver.synaptics is
+ deprecated since NixOS 17.09.
+
+
+
+ GTK/Qt themes
+
+ 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:
+
+
+qt5.enable = true;
+qt5.platformTheme = "gtk2";
+qt5.style = "gtk2";
+
+
+
+ Custom XKB layouts
+
+ It is possible to install custom
+
+ XKB 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):
+
+
+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:
+
+
+services.xserver.extraLayouts.us-greek = {
+ description = "US layout with alt-gr greek";
+ languages = [ "eng" ];
+ symbolsFile = /yourpath/symbols/us-greek;
+};
+
+
+
+ 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:
+
+
+$ nix-shell -p xorg.xkbcomp
+$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
+
+
+ You can inspect the predefined XKB files for examples:
+
+
+$ 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
+
+
+xkb_keycodes "media"
+{
+ <volUp> = 123;
+ <volDown> = 456;
+}
+
+
+ Now use the newly define keycodes in media-sym:
+
+
+xkb_symbols "media"
+{
+ key.type = "ONE_LEVEL";
+ key <volUp> { [ XF86AudioLowerVolume ] };
+ key <volDown> { [ XF86AudioRaiseVolume ] };
+}
+
+
+ As before, to install the layout do
+
+
+services.xserver.extraLayouts.media = {
+ description = "Multimedia keys remapping";
+ languages = [ "eng" ];
+ symbolsFile = /path/to/media-key;
+ keycodesFile = /path/to/media-sym;
+};
+
+
+
+ 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:
+
+
+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
+
+
+$ xinit -- -xkbdir /etc/X11/xkb
+
+
+ To learn how to write layouts take a look at the XKB
+ documentation
+ . More example layouts can also be found
+ here
+ .
+
+
+
diff --git a/nixos/doc/manual/from_md/configuration/xfce.chapter.xml b/nixos/doc/manual/from_md/configuration/xfce.chapter.xml
new file mode 100644
index 000000000000..f96ef2e8c483
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/xfce.chapter.xml
@@ -0,0 +1,62 @@
+
+ Xfce Desktop Environment
+
+ To enable the Xfce Desktop Environment, set
+
+
+services.xserver.desktopManager.xfce.enable = true;
+services.xserver.displayManager.defaultSession = "xfce";
+
+
+ Optionally, picom can be enabled for nice
+ graphical effects, some example settings:
+
+
+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
+ from
+ pkgs.xfce.
+
+
+ Thunar Plugins
+
+ If you'd like to add extra plugins to Thunar, add them to
+ .
+ You shouldn't just add them to
+ .
+
+
+
+ Troubleshooting
+
+ 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).
+
+
+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.
+
+
+$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
+
+
+ A log-out and re-log will be needed for this to take effect.
+
+
+