commit 4015c275ca9bacd2c821f3116232a50b74fb106d · pyrox.dev/nixpkgs

+8 -8

nixos/doc/manual/configuration/configuration.xml

···

       15
       15
        
        </partintro>

     

       16
       16
        
        <xi:include href="config-syntax.xml" />

     

       17
       17
        
        <xi:include href="package-mgmt.xml" />

     

       18
       18
       -
        <xi:include href="user-mgmt.xml" />

     

       18
       18
       +
        <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />

     

       19
       19
        
        <xi:include href="file-systems.xml" />

     

       20
       20
       -
        <xi:include href="x-windows.xml" />

     

       21
       21
       -
        <xi:include href="wayland.xml" />

     

       22
       22
       -
        <xi:include href="gpu-accel.xml" />

     

       23
       23
       -
        <xi:include href="xfce.xml" />

     

       20
       20
       +
        <xi:include href="../from_md/configuration/x-windows.chapter.xml" />

     

       21
       21
       +
        <xi:include href="../from_md/configuration/wayland.chapter.xml" />

     

       22
       22
       +
        <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />

     

       23
       23
       +
        <xi:include href="../from_md/configuration/xfce.chapter.xml" />

     

       24
       24
        
        <xi:include href="networking.xml" />

     

       25
       25
       -
        <xi:include href="linux-kernel.xml" />

     

       26
       26
       -
        <xi:include href="subversion.xml" />

     

       25
       25
       +
        <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />

     

       26
       26
       +
        <xi:include href="../from_md/configuration/subversion.chapter.xml" />

     

       27
       27
        
        <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />

     

       28
       28
        
        <xi:include href="profiles.xml" />

     

       29
       29
       -
        <xi:include href="kubernetes.xml" />

     

       29
       29
       +
        <xi:include href="../from_md/configuration/kubernetes.chapter.xml" />

     

       30
       30
        
       <!-- Apache; libvirtd virtualisation -->

     

       31
       31
        
       </part>

+204

nixos/doc/manual/configuration/gpu-accel.chapter.md

···

       1
       1
       +
       # GPU acceleration {#sec-gpu-accel}

     

       2
       2
       +
       

     

       3
       3
       +
       NixOS provides various APIs that benefit from GPU hardware acceleration,

     

       4
       4
       +
       such as VA-API and VDPAU for video playback; OpenGL and Vulkan for 3D

     

       5
       5
       +
       graphics; and OpenCL for general-purpose computing. This chapter

     

       6
       6
       +
       describes how to set up GPU hardware acceleration (as far as this is not

     

       7
       7
       +
       done automatically) and how to verify that hardware acceleration is

     

       8
       8
       +
       indeed used.

     

       9
       9
       +
       

     

       10
       10
       +
       Most of the aforementioned APIs are agnostic with regards to which

     

       11
       11
       +
       display server is used. Consequently, these instructions should apply

     

       12
       12
       +
       both to the X Window System and Wayland compositors.

     

       13
       13
       +
       

     

       14
       14
       +
       ## OpenCL {#sec-gpu-accel-opencl}

     

       15
       15
       +
       

     

       16
       16
       +
       [OpenCL](https://en.wikipedia.org/wiki/OpenCL) is a general compute API.

     

       17
       17
       +
       It is used by various applications such as Blender and Darktable to

     

       18
       18
       +
       accelerate certain operations.

     

       19
       19
       +
       

     

       20
       20
       +
       OpenCL applications load drivers through the *Installable Client Driver*

     

       21
       21
       +
       (ICD) mechanism. In this mechanism, an ICD file specifies the path to

     

       22
       22
       +
       the OpenCL driver for a particular GPU family. In NixOS, there are two

     

       23
       23
       +
       ways to make ICD files visible to the ICD loader. The first is through

     

       24
       24
       +
       the `OCL_ICD_VENDORS` environment variable. This variable can contain a

     

       25
       25
       +
       directory which is scanned by the ICL loader for ICD files. For example:

     

       26
       26
       +
       

     

       27
       27
       +
       ```ShellSession

     

       28
       28
       +
       $ export \

     

       29
       29
       +
         OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/

     

       30
       30
       +
       ```

     

       31
       31
       +
       

     

       32
       32
       +
       The second mechanism is to add the OpenCL driver package to

     

       33
       33
       +
       [](#opt-hardware.opengl.extraPackages).

     

       34
       34
       +
       This links the ICD file under `/run/opengl-driver`, where it will be visible

     

       35
       35
       +
       to the ICD loader.

     

       36
       36
       +
       

     

       37
       37
       +
       The proper installation of OpenCL drivers can be verified through the

     

       38
       38
       +
       `clinfo` command of the clinfo package. This command will report the

     

       39
       39
       +
       number of hardware devices that is found and give detailed information

     

       40
       40
       +
       for each device:

     

       41
       41
       +
       

     

       42
       42
       +
       ```ShellSession

     

       43
       43
       +
       $ clinfo | head -n3

     

       44
       44
       +
       Number of platforms  1

     

       45
       45
       +
       Platform Name        AMD Accelerated Parallel Processing

     

       46
       46
       +
       Platform Vendor      Advanced Micro Devices, Inc.

     

       47
       47
       +
       ```

     

       48
       48
       +
       

     

       49
       49
       +
       ### AMD {#sec-gpu-accel-opencl-amd}

     

       50
       50
       +
       

     

       51
       51
       +
       Modern AMD [Graphics Core

     

       52
       52
       +
       Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are

     

       53
       53
       +
       supported through the rocm-opencl-icd package. Adding this package to

     

       54
       54
       +
       [](#opt-hardware.opengl.extraPackages)

     

       55
       55
       +
       enables OpenCL support:

     

       56
       56
       +
       

     

       57
       57
       +
       ```nix

     

       58
       58
       +
       hardware.opengl.extraPackages = [

     

       59
       59
       +
         rocm-opencl-icd

     

       60
       60
       +
       ];

     

       61
       61
       +
       ```

     

       62
       62
       +
       

     

       63
       63
       +
       ### Intel {#sec-gpu-accel-opencl-intel}

     

       64
       64
       +
       

     

       65
       65
       +
       [Intel Gen8 and later

     

       66
       66
       +
       GPUs](https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8)

     

       67
       67
       +
       are supported by the Intel NEO OpenCL runtime that is provided by the

     

       68
       68
       +
       intel-compute-runtime package. For Gen7 GPUs, the deprecated Beignet

     

       69
       69
       +
       runtime can be used, which is provided by the beignet package. The

     

       70
       70
       +
       proprietary Intel OpenCL runtime, in the intel-ocl package, is an

     

       71
       71
       +
       alternative for Gen7 GPUs.

     

       72
       72
       +
       

     

       73
       73
       +
       The intel-compute-runtime, beignet, or intel-ocl package can be added to

     

       74
       74
       +
       [](#opt-hardware.opengl.extraPackages)

     

       75
       75
       +
       to enable OpenCL support. For example, for Gen8 and later GPUs, the following

     

       76
       76
       +
       configuration can be used:

     

       77
       77
       +
       

     

       78
       78
       +
       ```nix

     

       79
       79
       +
       hardware.opengl.extraPackages = [

     

       80
       80
       +
         intel-compute-runtime

     

       81
       81
       +
       ];

     

       82
       82
       +
       ```

     

       83
       83
       +
       

     

       84
       84
       +
       ## Vulkan {#sec-gpu-accel-vulkan}

     

       85
       85
       +
       

     

       86
       86
       +
       [Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API)) is a graphics and

     

       87
       87
       +
       compute API for GPUs. It is used directly by games or indirectly though

     

       88
       88
       +
       compatibility layers like

     

       89
       89
       +
       [DXVK](https://github.com/doitsujin/dxvk/wiki).

     

       90
       90
       +
       

     

       91
       91
       +
       By default, if [](#opt-hardware.opengl.driSupport)

     

       92
       92
       +
       is enabled, mesa is installed and provides Vulkan for supported hardware.

     

       93
       93
       +
       

     

       94
       94
       +
       Similar to OpenCL, Vulkan drivers are loaded through the *Installable

     

       95
       95
       +
       Client Driver* (ICD) mechanism. ICD files for Vulkan are JSON files that

     

       96
       96
       +
       specify the path to the driver library and the supported Vulkan version.

     

       97
       97
       +
       All successfully loaded drivers are exposed to the application as

     

       98
       98
       +
       different GPUs. In NixOS, there are two ways to make ICD files visible

     

       99
       99
       +
       to Vulkan applications: an environment variable and a module option.

     

       100
       100
       +
       

     

       101
       101
       +
       The first option is through the `VK_ICD_FILENAMES` environment variable.

     

       102
       102
       +
       This variable can contain multiple JSON files, separated by `:`. For

     

       103
       103
       +
       example:

     

       104
       104
       +
       

     

       105
       105
       +
       ```ShellSession

     

       106
       106
       +
       $ export \

     

       107
       107
       +
         VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json

     

       108
       108
       +
       ```

     

       109
       109
       +
       

     

       110
       110
       +
       The second mechanism is to add the Vulkan driver package to

     

       111
       111
       +
       [](#opt-hardware.opengl.extraPackages).

     

       112
       112
       +
       This links the ICD file under `/run/opengl-driver`, where it will be

     

       113
       113
       +
       visible to the ICD loader.

     

       114
       114
       +
       

     

       115
       115
       +
       The proper installation of Vulkan drivers can be verified through the

     

       116
       116
       +
       `vulkaninfo` command of the vulkan-tools package. This command will

     

       117
       117
       +
       report the hardware devices and drivers found, in this example output

     

       118
       118
       +
       amdvlk and radv:

     

       119
       119
       +
       

     

       120
       120
       +
       ```ShellSession

     

       121
       121
       +
       $ vulkaninfo | grep GPU

     

       122
       122
       +
                       GPU id  : 0 (Unknown AMD GPU)

     

       123
       123
       +
                       GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))

     

       124
       124
       +
            ...

     

       125
       125
       +
       GPU0:

     

       126
       126
       +
               deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU

     

       127
       127
       +
               deviceName     = Unknown AMD GPU

     

       128
       128
       +
       GPU1:

     

       129
       129
       +
               deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU

     

       130
       130
       +
       ```

     

       131
       131
       +
       

     

       132
       132
       +
       A simple graphical application that uses Vulkan is `vkcube` from the

     

       133
       133
       +
       vulkan-tools package.

     

       134
       134
       +
       

     

       135
       135
       +
       ### AMD {#sec-gpu-accel-vulkan-amd}

     

       136
       136
       +
       

     

       137
       137
       +
       Modern AMD [Graphics Core

     

       138
       138
       +
       Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are

     

       139
       139
       +
       supported through either radv, which is part of mesa, or the amdvlk

     

       140
       140
       +
       package. Adding the amdvlk package to

     

       141
       141
       +
       [](#opt-hardware.opengl.extraPackages)

     

       142
       142
       +
       makes amdvlk the default driver and hides radv and lavapipe from the device list.

     

       143
       143
       +
       A specific driver can be forced as follows:

     

       144
       144
       +
       

     

       145
       145
       +
       ```nix

     

       146
       146
       +
       hardware.opengl.extraPackages = [

     

       147
       147
       +
         pkgs.amdvlk

     

       148
       148
       +
       ];

     

       149
       149
       +
       

     

       150
       150
       +
       # To enable Vulkan support for 32-bit applications, also add:

     

       151
       151
       +
       hardware.opengl.extraPackages32 = [

     

       152
       152
       +
         pkgs.driversi686Linux.amdvlk

     

       153
       153
       +
       ];

     

       154
       154
       +
       

     

       155
       155
       +
       # Force radv

     

       156
       156
       +
       environment.variables.AMD_VULKAN_ICD = "RADV";

     

       157
       157
       +
       # Or

     

       158
       158
       +
       environment.variables.VK_ICD_FILENAMES =

     

       159
       159
       +
         "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";

     

       160
       160
       +
       ```

     

       161
       161
       +
       

     

       162
       162
       +
       ## Common issues {#sec-gpu-accel-common-issues}

     

       163
       163
       +
       

     

       164
       164
       +
       ### User permissions {#sec-gpu-accel-common-issues-permissions}

     

       165
       165
       +
       

     

       166
       166
       +
       Except where noted explicitly, it should not be necessary to adjust user

     

       167
       167
       +
       permissions to use these acceleration APIs. In the default

     

       168
       168
       +
       configuration, GPU devices have world-read/write permissions

     

       169
       169
       +
       (`/dev/dri/renderD*`) or are tagged as `uaccess` (`/dev/dri/card*`). The

     

       170
       170
       +
       access control lists of devices with the `uaccess` tag will be updated

     

       171
       171
       +
       automatically when a user logs in through `systemd-logind`. For example,

     

       172
       172
       +
       if the user *jane* is logged in, the access control list should look as

     

       173
       173
       +
       follows:

     

       174
       174
       +
       

     

       175
       175
       +
       ```ShellSession

     

       176
       176
       +
       $ getfacl /dev/dri/card0

     

       177
       177
       +
       # file: dev/dri/card0

     

       178
       178
       +
       # owner: root

     

       179
       179
       +
       # group: video

     

       180
       180
       +
       user::rw-

     

       181
       181
       +
       user:jane:rw-

     

       182
       182
       +
       group::rw-

     

       183
       183
       +
       mask::rw-

     

       184
       184
       +
       other::---

     

       185
       185
       +
       ```

     

       186
       186
       +
       

     

       187
       187
       +
       If you disabled (this functionality of) `systemd-logind`, you may need

     

       188
       188
       +
       to add the user to the `video` group and log in again.

     

       189
       189
       +
       

     

       190
       190
       +
       ### Mixing different versions of nixpkgs {#sec-gpu-accel-common-issues-mixing-nixpkgs}

     

       191
       191
       +
       

     

       192
       192
       +
       The *Installable Client Driver* (ICD) mechanism used by OpenCL and

     

       193
       193
       +
       Vulkan loads runtimes into its address space using `dlopen`. Mixing an

     

       194
       194
       +
       ICD loader mechanism and runtimes from different version of nixpkgs may

     

       195
       195
       +
       not work. For example, if the ICD loader uses an older version of glibc

     

       196
       196
       +
       than the runtime, the runtime may not be loadable due to missing

     

       197
       197
       +
       symbols. Unfortunately, the loader will generally be quiet about such

     

       198
       198
       +
       issues.

     

       199
       199
       +
       

     

       200
       200
       +
       If you suspect that you are running into library version mismatches

     

       201
       201
       +
       between an ICL loader and a runtime, you could run an application with

     

       202
       202
       +
       the `LD_DEBUG` variable set to get more diagnostic information. For

     

       203
       203
       +
       example, OpenCL can be tested with `LD_DEBUG=files clinfo`, which should

     

       204
       204
       +
       report missing symbols.

-262

nixos/doc/manual/configuration/gpu-accel.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-gpu-accel">

     

       6
       6
       -
         <title>GPU acceleration</title>

     

       7
       7
       -
       

     

       8
       8
       -
         <para>

     

       9
       9
       -
           NixOS provides various APIs that benefit from GPU hardware

     

       10
       10
       -
           acceleration, such as VA-API and VDPAU for video playback; OpenGL and

     

       11
       11
       -
           Vulkan for 3D graphics; and OpenCL for general-purpose computing.

     

       12
       12
       -
           This chapter describes how to set up GPU hardware acceleration (as far

     

       13
       13
       -
           as this is not done automatically) and how to verify that hardware

     

       14
       14
       -
           acceleration is indeed used.

     

       15
       15
       -
         </para>

     

       16
       16
       -
       

     

       17
       17
       -
         <para>

     

       18
       18
       -
           Most of the aforementioned APIs are agnostic with regards to which

     

       19
       19
       -
           display server is used. Consequently, these instructions should apply

     

       20
       20
       -
           both to the X Window System and Wayland compositors.

     

       21
       21
       -
         </para>

     

       22
       22
       -
       

     

       23
       23
       -
         <section xml:id="sec-gpu-accel-opencl">

     

       24
       24
       -
           <title>OpenCL</title>

     

       25
       25
       -
       

     

       26
       26
       -
           <para>

     

       27
       27
       -
             <link xlink:href="https://en.wikipedia.org/wiki/OpenCL">OpenCL</link> is a

     

       28
       28
       -
             general compute API. It is used by various applications such as

     

       29
       29
       -
             Blender and Darktable to accelerate certain operations.

     

       30
       30
       -
           </para>

     

       31
       31
       -
       

     

       32
       32
       -
           <para>

     

       33
       33
       -
             OpenCL applications load drivers through the <emphasis>Installable Client

     

       34
       34
       -
             Driver</emphasis> (ICD) mechanism. In this mechanism, an ICD file

     

       35
       35
       -
             specifies the path to the OpenCL driver for a particular GPU family.

     

       36
       36
       -
             In NixOS, there are two ways to make ICD files visible to the ICD

     

       37
       37
       -
             loader. The first is through the <varname>OCL_ICD_VENDORS</varname>

     

       38
       38
       -
             environment variable. This variable can contain a directory which

     

       39
       39
       -
             is scanned by the ICL loader for ICD files. For example:

     

       40
       40
       -
       

     

       41
       41
       -
             <screen><prompt>$</prompt> export \

     

       42
       42
       -
         OCL_ICD_VENDORS=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/</screen>

     

       43
       43
       -
           </para>

     

       44
       44
       -
       

     

       45
       45
       -
           <para>

     

       46
       46
       -
             The second mechanism is to add the OpenCL driver package to

     

       47
       47
       -
             <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the

     

       48
       48
       -
             ICD file under <filename>/run/opengl-driver</filename>, where it will

     

       49
       49
       -
             be visible to the ICD loader.

     

       50
       50
       -
           </para>

     

       51
       51
       -
       

     

       52
       52
       -
           <para>

     

       53
       53
       -
             The proper installation of OpenCL drivers can be verified through

     

       54
       54
       -
             the <command>clinfo</command> command of the <package>clinfo</package>

     

       55
       55
       -
             package. This command will report the number of hardware devices

     

       56
       56
       -
             that is found and give detailed information for each device:

     

       57
       57
       -
           </para>

     

       58
       58
       -
       

     

       59
       59
       -
           <screen><prompt>$</prompt> clinfo | head -n3

     

       60
       60
       -
       Number of platforms  1

     

       61
       61
       -
       Platform Name        AMD Accelerated Parallel Processing

     

       62
       62
       -
       Platform Vendor      Advanced Micro Devices, Inc.</screen>

     

       63
       63
       -
       

     

       64
       64
       -
           <section xml:id="sec-gpu-accel-opencl-amd">

     

       65
       65
       -
             <title>AMD</title>

     

       66
       66
       -
       

     

       67
       67
       -
             <para>

     

       68
       68
       -
              Modern AMD <link

     

       69
       69
       -
              xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics

     

       70
       70
       -
              Core Next</link> (GCN) GPUs are supported through the

     

       71
       71
       -
              <package>rocm-opencl-icd</package> package. Adding this package to

     

       72
       72
       -
              <xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL

     

       73
       73
       -
              support:

     

       74
       74
       -
       

     

       75
       75
       -
              <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [

     

       76
       76
       -
                rocm-opencl-icd

     

       77
       77
       -
              ];</programlisting>

     

       78
       78
       -
             </para>

     

       79
       79
       -
           </section>

     

       80
       80
       -
       

     

       81
       81
       -
           <section xml:id="sec-gpu-accel-opencl-intel">

     

       82
       82
       -
             <title>Intel</title>

     

       83
       83
       -
       

     

       84
       84
       -
             <para>

     

       85
       85
       -
              <link

     

       86
       86
       -
                xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8">Intel

     

       87
       87
       -
              Gen8 and later GPUs</link> are supported by the Intel NEO OpenCL

     

       88
       88
       -
              runtime that is provided by the

     

       89
       89
       -
              <package>intel-compute-runtime</package> package. For Gen7 GPUs,

     

       90
       90
       -
              the deprecated Beignet runtime can be used, which is provided

     

       91
       91
       -
              by the <package>beignet</package> package. The proprietary Intel

     

       92
       92
       -
              OpenCL runtime, in the <package>intel-ocl</package> package, is

     

       93
       93
       -
              an alternative for Gen7 GPUs.

     

       94
       94
       -
             </para>

     

       95
       95
       -
       

     

       96
       96
       -
             <para>

     

       97
       97
       -
              The <package>intel-compute-runtime</package>, <package>beignet</package>,

     

       98
       98
       -
              or <package>intel-ocl</package> package can be added to

     

       99
       99
       -
              <xref linkend="opt-hardware.opengl.extraPackages"/> to enable OpenCL

     

       100
       100
       -
              support. For example, for Gen8 and later GPUs, the following

     

       101
       101
       -
              configuration can be used:

     

       102
       102
       -
       

     

       103
       103
       -
             <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [

     

       104
       104
       -
               intel-compute-runtime

     

       105
       105
       -
             ];</programlisting>

     

       106
       106
       -
       

     

       107
       107
       -
             </para>

     

       108
       108
       -
           </section>

     

       109
       109
       -
         </section>

     

       110
       110
       -
       

     

       111
       111
       -
         <section xml:id="sec-gpu-accel-vulkan">

     

       112
       112
       -
           <title>Vulkan</title>

     

       113
       113
       -
       

     

       114
       114
       -
           <para>

     

       115
       115
       -
             <link xlink:href="https://en.wikipedia.org/wiki/Vulkan_(API)">Vulkan</link> is a

     

       116
       116
       -
             graphics and compute API for GPUs. It is used directly by games or indirectly though

     

       117
       117
       -
             compatibility layers like <link xlink:href="https://github.com/doitsujin/dxvk/wiki">DXVK</link>.

     

       118
       118
       -
           </para>

     

       119
       119
       -
       

     

       120
       120
       -
           <para>

     

       121
       121
       -
            By default, if <xref linkend="opt-hardware.opengl.driSupport"/> is enabled,

     

       122
       122
       -
            <package>mesa</package> is installed and provides Vulkan for supported hardware.

     

       123
       123
       -
           </para>

     

       124
       124
       -
       

     

       125
       125
       -
           <para>

     

       126
       126
       -
             Similar to OpenCL, Vulkan drivers are loaded through the <emphasis>Installable Client

     

       127
       127
       -
             Driver</emphasis> (ICD) mechanism. ICD files for Vulkan are JSON files that specify

     

       128
       128
       -
             the path to the driver library and the supported Vulkan version. All successfully

     

       129
       129
       -
             loaded drivers are exposed to the application as different GPUs.

     

       130
       130
       -
             In NixOS, there are two ways to make ICD files visible to Vulkan applications: an

     

       131
       131
       -
             environment variable and a module option.

     

       132
       132
       -
           </para>

     

       133
       133
       -
       

     

       134
       134
       -
           <para>

     

       135
       135
       -
             The first option is through the <varname>VK_ICD_FILENAMES</varname>

     

       136
       136
       -
             environment variable. This variable can contain multiple JSON files, separated by

     

       137
       137
       -
             <literal>:</literal>. For example:

     

       138
       138
       -
       

     

       139
       139
       -
             <screen><prompt>$</prompt> export \

     

       140
       140
       -
         VK_ICD_FILENAMES=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json</screen>

     

       141
       141
       -
           </para>

     

       142
       142
       -
       

     

       143
       143
       -
           <para>

     

       144
       144
       -
             The second mechanism is to add the Vulkan driver package to

     

       145
       145
       -
             <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the

     

       146
       146
       -
             ICD file under <filename>/run/opengl-driver</filename>, where it will

     

       147
       147
       -
             be visible to the ICD loader.

     

       148
       148
       -
           </para>

     

       149
       149
       -
       

     

       150
       150
       -
           <para>

     

       151
       151
       -
             The proper installation of Vulkan drivers can be verified through

     

       152
       152
       -
             the <command>vulkaninfo</command> command of the <package>vulkan-tools</package>

     

       153
       153
       -
             package. This command will report the hardware devices and drivers found,

     

       154
       154
       -
             in this example output amdvlk and radv:

     

       155
       155
       -
           </para>

     

       156
       156
       -
       

     

       157
       157
       -
           <screen><prompt>$</prompt> vulkaninfo | grep GPU

     

       158
       158
       -
                       GPU id  : 0 (Unknown AMD GPU)

     

       159
       159
       -
                       GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))

     

       160
       160
       -
            ...

     

       161
       161
       -
       GPU0:

     

       162
       162
       -
               deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU

     

       163
       163
       -
               deviceName     = Unknown AMD GPU

     

       164
       164
       -
       GPU1:

     

       165
       165
       -
               deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU</screen>

     

       166
       166
       -
       

     

       167
       167
       -
           <para>

     

       168
       168
       -
             A simple graphical application that uses Vulkan is <command>vkcube</command>

     

       169
       169
       -
             from the <package>vulkan-tools</package> package.

     

       170
       170
       -
           </para>

     

       171
       171
       -
       

     

       172
       172
       -
           <section xml:id="sec-gpu-accel-vulkan-amd">

     

       173
       173
       -
             <title>AMD</title>

     

       174
       174
       -
       

     

       175
       175
       -
             <para>

     

       176
       176
       -
              Modern AMD <link

     

       177
       177
       -
              xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics

     

       178
       178
       -
              Core Next</link> (GCN) GPUs are supported through either radv, which is

     

       179
       179
       -
              part of <package>mesa</package>, or the <package>amdvlk</package> package.

     

       180
       180
       -
              Adding the <package>amdvlk</package> package to

     

       181
       181
       -
              <xref linkend="opt-hardware.opengl.extraPackages"/> makes amdvlk the

     

       182
       182
       -
              default driver and hides radv and lavapipe from the device list. A

     

       183
       183
       -
              specific driver can be forced as follows:

     

       184
       184
       -
       

     

       185
       185
       -
              <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [

     

       186
       186
       -
                pkgs.<package>amdvlk</package>

     

       187
       187
       -
              ];

     

       188
       188
       -
       

     

       189
       189
       -
              # To enable Vulkan support for 32-bit applications, also add:

     

       190
       190
       -
              <xref linkend="opt-hardware.opengl.extraPackages32"/> = [

     

       191
       191
       -
                pkgs.driversi686Linux.<package>amdvlk</package>

     

       192
       192
       -
              ];

     

       193
       193
       -
       

     

       194
       194
       -
              # Force radv

     

       195
       195
       -
              <xref linkend="opt-environment.variables"/>.AMD_VULKAN_ICD = "RADV";

     

       196
       196
       -
              # Or

     

       197
       197
       -
              <xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES =

     

       198
       198
       -
                "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";

     

       199
       199
       -
              </programlisting>

     

       200
       200
       -
             </para>

     

       201
       201
       -
           </section>

     

       202
       202
       -
         </section>

     

       203
       203
       -
       

     

       204
       204
       -
         <section xml:id="sec-gpu-accel-common-issues">

     

       205
       205
       -
          <title>Common issues</title>

     

       206
       206
       -
       

     

       207
       207
       -
          <section xml:id="sec-gpu-accel-common-issues-permissions">

     

       208
       208
       -
           <title>User permissions</title>

     

       209
       209
       -
       

     

       210
       210
       -
           <para>

     

       211
       211
       -
            Except where noted explicitly, it should not be necessary to

     

       212
       212
       -
            adjust user permissions to use these acceleration APIs. In the default

     

       213
       213
       -
            configuration, GPU devices have world-read/write permissions

     

       214
       214
       -
            (<filename>/dev/dri/renderD*</filename>) or are tagged as

     

       215
       215
       -
            <code>uaccess</code> (<filename>/dev/dri/card*</filename>).  The

     

       216
       216
       -
            access control lists of devices with the <varname>uaccess</varname>

     

       217
       217
       -
            tag will be updated automatically when a user logs in through

     

       218
       218
       -
            <command>systemd-logind</command>. For example, if the user

     

       219
       219
       -
            <emphasis>jane</emphasis> is logged in, the access control list

     

       220
       220
       -
            should look as follows:

     

       221
       221
       -
       

     

       222
       222
       -
            <screen><prompt>$</prompt> getfacl /dev/dri/card0

     

       223
       223
       -
       # file: dev/dri/card0

     

       224
       224
       -
       # owner: root

     

       225
       225
       -
       # group: video

     

       226
       226
       -
       user::rw-

     

       227
       227
       -
       user:jane:rw-

     

       228
       228
       -
       group::rw-

     

       229
       229
       -
       mask::rw-

     

       230
       230
       -
       other::---</screen>

     

       231
       231
       -
       

     

       232
       232
       -
            If you disabled (this functionality of) <command>systemd-logind</command>,

     

       233
       233
       -
            you may need to add the user to the <code>video</code> group and

     

       234
       234
       -
            log in again.

     

       235
       235
       -
           </para>

     

       236
       236
       -
          </section>

     

       237
       237
       -
       

     

       238
       238
       -
          <section xml:id="sec-gpu-accel-common-issues-mixing-nixpkgs">

     

       239
       239
       -
           <title>Mixing different versions of nixpkgs</title>

     

       240
       240
       -
       

     

       241
       241
       -
           <para>

     

       242
       242
       -
            The <emphasis>Installable Client Driver</emphasis> (ICD)

     

       243
       243
       -
            mechanism used by OpenCL and Vulkan loads runtimes into its address

     

       244
       244
       -
            space using <code>dlopen</code>. Mixing an ICD loader mechanism and

     

       245
       245
       -
            runtimes from different version of nixpkgs may not work. For example,

     

       246
       246
       -
            if the ICD loader uses an older version of <package>glibc</package>

     

       247
       247
       -
            than the runtime, the runtime may not be loadable due to

     

       248
       248
       -
            missing symbols. Unfortunately, the loader will generally be quiet

     

       249
       249
       -
            about such issues.

     

       250
       250
       -
           </para>

     

       251
       251
       -
       

     

       252
       252
       -
           <para>

     

       253
       253
       -
            If you suspect that you are running into library version mismatches

     

       254
       254
       -
            between an ICL loader and a runtime, you could run an application with

     

       255
       255
       -
            the <code>LD_DEBUG</code> variable set to get more diagnostic

     

       256
       256
       -
            information. For example, OpenCL can be tested with

     

       257
       257
       -
            <code>LD_DEBUG=files clinfo</code>, which should report missing

     

       258
       258
       -
            symbols.

     

       259
       259
       -
           </para>

     

       260
       260
       -
          </section>

     

       261
       261
       -
         </section>

     

       262
       262
       -
       </chapter>

+104

nixos/doc/manual/configuration/kubernetes.chapter.md

···

       1
       1
       +
       # Kubernetes {#sec-kubernetes}

     

       2
       2
       +
       

     

       3
       3
       +
       The NixOS Kubernetes module is a collective term for a handful of

     

       4
       4
       +
       individual submodules implementing the Kubernetes cluster components.

     

       5
       5
       +
       

     

       6
       6
       +
       There are generally two ways of enabling Kubernetes on NixOS. One way is

     

       7
       7
       +
       to enable and configure cluster components appropriately by hand:

     

       8
       8
       +
       

     

       9
       9
       +
       ```nix

     

       10
       10
       +
       services.kubernetes = {

     

       11
       11
       +
         apiserver.enable = true;

     

       12
       12
       +
         controllerManager.enable = true;

     

       13
       13
       +
         scheduler.enable = true;

     

       14
       14
       +
         addonManager.enable = true;

     

       15
       15
       +
         proxy.enable = true;

     

       16
       16
       +
         flannel.enable = true;

     

       17
       17
       +
       };

     

       18
       18
       +
       ```

     

       19
       19
       +
       

     

       20
       20
       +
       Another way is to assign cluster roles (\"master\" and/or \"node\") to

     

       21
       21
       +
       the host. This enables apiserver, controllerManager, scheduler,

     

       22
       22
       +
       addonManager, kube-proxy and etcd:

     

       23
       23
       +
       

     

       24
       24
       +
       ```nix

     

       25
       25
       +
       services.kubernetes.roles = [ "master" ];

     

       26
       26
       +
       ```

     

       27
       27
       +
       

     

       28
       28
       +
       While this will enable the kubelet and kube-proxy only:

     

       29
       29
       +
       

     

       30
       30
       +
       ```nix

     

       31
       31
       +
       services.kubernetes.roles = [ "node" ];

     

       32
       32
       +
       ```

     

       33
       33
       +
       

     

       34
       34
       +
       Assigning both the master and node roles is usable if you want a single

     

       35
       35
       +
       node Kubernetes cluster for dev or testing purposes:

     

       36
       36
       +
       

     

       37
       37
       +
       ```nix

     

       38
       38
       +
       services.kubernetes.roles = [ "master" "node" ];

     

       39
       39
       +
       ```

     

       40
       40
       +
       

     

       41
       41
       +
       Note: Assigning either role will also default both

     

       42
       42
       +
       [](#opt-services.kubernetes.flannel.enable)

     

       43
       43
       +
       and [](#opt-services.kubernetes.easyCerts)

     

       44
       44
       +
       to true. This sets up flannel as CNI and activates automatic PKI bootstrapping.

     

       45
       45
       +
       

     

       46
       46
       +
       As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled

     

       47
       47
       +
       ports on kubernetes components. Thus, from NixOS 19.03 all plain HTTP

     

       48
       48
       +
       ports have been disabled by default. While opening insecure ports is

     

       49
       49
       +
       still possible, it is recommended not to bind these to other interfaces

     

       50
       50
       +
       than loopback. To re-enable the insecure port on the apiserver, see options:

     

       51
       51
       +
       [](#opt-services.kubernetes.apiserver.insecurePort) and

     

       52
       52
       +
       [](#opt-services.kubernetes.apiserver.insecureBindAddress)

     

       53
       53
       +
       

     

       54
       54
       +
       ::: {.note}

     

       55
       55
       +
       As of NixOS 19.03, it is mandatory to configure:

     

       56
       56
       +
       [](#opt-services.kubernetes.masterAddress).

     

       57
       57
       +
       The masterAddress must be resolveable and routeable by all cluster nodes.

     

       58
       58
       +
       In single node clusters, this can be set to `localhost`.

     

       59
       59
       +
       :::

     

       60
       60
       +
       

     

       61
       61
       +
       Role-based access control (RBAC) authorization mode is enabled by

     

       62
       62
       +
       default. This means that anonymous requests to the apiserver secure port

     

       63
       63
       +
       will expectedly cause a permission denied error. All cluster components

     

       64
       64
       +
       must therefore be configured with x509 certificates for two-way tls

     

       65
       65
       +
       communication. The x509 certificate subject section determines the roles

     

       66
       66
       +
       and permissions granted by the apiserver to perform clusterwide or

     

       67
       67
       +
       namespaced operations. See also: [ Using RBAC

     

       68
       68
       +
       Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).

     

       69
       69
       +
       

     

       70
       70
       +
       The NixOS kubernetes module provides an option for automatic certificate

     

       71
       71
       +
       bootstrapping and configuration,

     

       72
       72
       +
       [](#opt-services.kubernetes.easyCerts).

     

       73
       73
       +
       The PKI bootstrapping process involves setting up a certificate authority (CA)

     

       74
       74
       +
       daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert

     

       75
       75
       +
       for the cluster, and uses the CA-cert for signing subordinate certs issued

     

       76
       76
       +
       to each of the cluster components. Subsequently, the certmgr daemon monitors

     

       77
       77
       +
       active certificates and renews them when needed. For single node Kubernetes

     

       78
       78
       +
       clusters, setting [](#opt-services.kubernetes.easyCerts)

     

       79
       79
       +
       = true is sufficient and no further action is required. For joining extra node

     

       80
       80
       +
       machines to an existing cluster on the other hand, establishing initial

     

       81
       81
       +
       trust is mandatory.

     

       82
       82
       +
       

     

       83
       83
       +
       To add new nodes to the cluster: On any (non-master) cluster node where

     

       84
       84
       +
       [](#opt-services.kubernetes.easyCerts)

     

       85
       85
       +
       is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH.

     

       86
       86
       +
       Given a token on stdin, it will copy the token to the kubernetes secrets directory

     

       87
       87
       +
       and restart the certmgr service. As requested certificates are issued, the

     

       88
       88
       +
       script will restart kubernetes cluster components as needed for them to

     

       89
       89
       +
       pick up new keypairs.

     

       90
       90
       +
       

     

       91
       91
       +
       ::: {.note}

     

       92
       92
       +
       Multi-master (HA) clusters are not supported by the easyCerts module.

     

       93
       93
       +
       :::

     

       94
       94
       +
       

     

       95
       95
       +
       In order to interact with an RBAC-enabled cluster as an administrator,

     

       96
       96
       +
       one needs to have cluster-admin privileges. By default, when easyCerts

     

       97
       97
       +
       is enabled, a cluster-admin kubeconfig file is generated and linked into

     

       98
       98
       +
       `/etc/kubernetes/cluster-admin.kubeconfig` as determined by

     

       99
       99
       +
       [](#opt-services.kubernetes.pki.etcClusterAdminKubeconfig).

     

       100
       100
       +
       `export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make

     

       101
       101
       +
       kubectl use this kubeconfig to access and authenticate the cluster. The

     

       102
       102
       +
       cluster-admin kubeconfig references an auto-generated keypair owned by

     

       103
       103
       +
       root. Thus, only root on the kubernetes master may obtain cluster-admin

     

       104
       104
       +
       rights by means of this file.

-112

nixos/doc/manual/configuration/kubernetes.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-kubernetes">

     

       6
       6
       -
        <title>Kubernetes</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         The NixOS Kubernetes module is a collective term for a handful of individual

     

       9
       9
       -
         submodules implementing the Kubernetes cluster components.

     

       10
       10
       -
        </para>

     

       11
       11
       -
        <para>

     

       12
       12
       -
         There are generally two ways of enabling Kubernetes on NixOS. One way is to

     

       13
       13
       -
         enable and configure cluster components appropriately by hand:

     

       14
       14
       -
       <programlisting>

     

       15
       15
       -
       services.kubernetes = {

     

       16
       16
       -
         apiserver.enable = true;

     

       17
       17
       -
         controllerManager.enable = true;

     

       18
       18
       -
         scheduler.enable = true;

     

       19
       19
       -
         addonManager.enable = true;

     

       20
       20
       -
         proxy.enable = true;

     

       21
       21
       -
         flannel.enable = true;

     

       22
       22
       -
       };

     

       23
       23
       -
       </programlisting>

     

       24
       24
       -
         Another way is to assign cluster roles ("master" and/or "node") to the host.

     

       25
       25
       -
         This enables apiserver, controllerManager, scheduler, addonManager,

     

       26
       26
       -
         kube-proxy and etcd:

     

       27
       27
       -
       <programlisting>

     

       28
       28
       -
       <xref linkend="opt-services.kubernetes.roles"/> = [ "master" ];

     

       29
       29
       -
       </programlisting>

     

       30
       30
       -
         While this will enable the kubelet and kube-proxy only:

     

       31
       31
       -
       <programlisting>

     

       32
       32
       -
       <xref linkend="opt-services.kubernetes.roles"/> = [ "node" ];

     

       33
       33
       -
       </programlisting>

     

       34
       34
       -
         Assigning both the master and node roles is usable if you want a single node

     

       35
       35
       -
         Kubernetes cluster for dev or testing purposes:

     

       36
       36
       -
       <programlisting>

     

       37
       37
       -
       <xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ];

     

       38
       38
       -
       </programlisting>

     

       39
       39
       -
         Note: Assigning either role will also default both

     

       40
       40
       -
         <xref linkend="opt-services.kubernetes.flannel.enable"/> and

     

       41
       41
       -
         <xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up

     

       42
       42
       -
         flannel as CNI and activates automatic PKI bootstrapping.

     

       43
       43
       -
        </para>

     

       44
       44
       -
        <para>

     

       45
       45
       -
         As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports

     

       46
       46
       -
         on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have

     

       47
       47
       -
         been disabled by default. While opening insecure ports is still possible, it

     

       48
       48
       -
         is recommended not to bind these to other interfaces than loopback. To

     

       49
       49
       -
         re-enable the insecure port on the apiserver, see options:

     

       50
       50
       -
         <xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and

     

       51
       51
       -
         <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/>

     

       52
       52
       -
        </para>

     

       53
       53
       -
        <note>

     

       54
       54
       -
         <para>

     

       55
       55
       -
          As of NixOS 19.03, it is mandatory to configure:

     

       56
       56
       -
          <xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress

     

       57
       57
       -
          must be resolveable and routeable by all cluster nodes. In single node

     

       58
       58
       -
          clusters, this can be set to <literal>localhost</literal>.

     

       59
       59
       -
         </para>

     

       60
       60
       -
        </note>

     

       61
       61
       -
        <para>

     

       62
       62
       -
         Role-based access control (RBAC) authorization mode is enabled by default.

     

       63
       63
       -
         This means that anonymous requests to the apiserver secure port will

     

       64
       64
       -
         expectedly cause a permission denied error. All cluster components must

     

       65
       65
       -
         therefore be configured with x509 certificates for two-way tls communication.

     

       66
       66
       -
         The x509 certificate subject section determines the roles and permissions

     

       67
       67
       -
         granted by the apiserver to perform clusterwide or namespaced operations. See

     

       68
       68
       -
         also:

     

       69
       69
       -
         <link

     

       70
       70
       -
            xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">

     

       71
       71
       -
         Using RBAC Authorization</link>.

     

       72
       72
       -
        </para>

     

       73
       73
       -
        <para>

     

       74
       74
       -
         The NixOS kubernetes module provides an option for automatic certificate

     

       75
       75
       -
         bootstrapping and configuration,

     

       76
       76
       -
         <xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping

     

       77
       77
       -
         process involves setting up a certificate authority (CA) daemon (cfssl) on

     

       78
       78
       -
         the kubernetes master node. cfssl generates a CA-cert for the cluster, and

     

       79
       79
       -
         uses the CA-cert for signing subordinate certs issued to each of the cluster

     

       80
       80
       -
         components. Subsequently, the certmgr daemon monitors active certificates and

     

       81
       81
       -
         renews them when needed. For single node Kubernetes clusters, setting

     

       82
       82
       -
         <xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and

     

       83
       83
       -
         no further action is required. For joining extra node machines to an existing

     

       84
       84
       -
         cluster on the other hand, establishing initial trust is mandatory.

     

       85
       85
       -
        </para>

     

       86
       86
       -
        <para>

     

       87
       87
       -
         To add new nodes to the cluster: On any (non-master) cluster node where

     

       88
       88
       -
         <xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper

     

       89
       89
       -
         script <literal>nixos-kubernetes-node-join</literal> is available on PATH.

     

       90
       90
       -
         Given a token on stdin, it will copy the token to the kubernetes secrets

     

       91
       91
       -
         directory and restart the certmgr service. As requested certificates are

     

       92
       92
       -
         issued, the script will restart kubernetes cluster components as needed for

     

       93
       93
       -
         them to pick up new keypairs.

     

       94
       94
       -
        </para>

     

       95
       95
       -
        <note>

     

       96
       96
       -
         <para>

     

       97
       97
       -
          Multi-master (HA) clusters are not supported by the easyCerts module.

     

       98
       98
       -
         </para>

     

       99
       99
       -
        </note>

     

       100
       100
       -
        <para>

     

       101
       101
       -
         In order to interact with an RBAC-enabled cluster as an administrator, one

     

       102
       102
       -
         needs to have cluster-admin privileges. By default, when easyCerts is

     

       103
       103
       -
         enabled, a cluster-admin kubeconfig file is generated and linked into

     

       104
       104
       -
         <literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as determined by

     

       105
       105
       -
         <xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig"/>.

     

       106
       106
       -
         <literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal>

     

       107
       107
       -
         will make kubectl use this kubeconfig to access and authenticate the cluster.

     

       108
       108
       -
         The cluster-admin kubeconfig references an auto-generated keypair owned by

     

       109
       109
       -
         root. Thus, only root on the kubernetes master may obtain cluster-admin

     

       110
       110
       -
         rights by means of this file.

     

       111
       111
       -
        </para>

     

       112
       112
       -
       </chapter>

+135

nixos/doc/manual/configuration/linux-kernel.chapter.md

···

       1
       1
       +
       # Linux Kernel {#sec-kernel-config}

     

       2
       2
       +
       

     

       3
       3
       +
       You can override the Linux kernel and associated packages using the

     

       4
       4
       +
       option `boot.kernelPackages`. For instance, this selects the Linux 3.10

     

       5
       5
       +
       kernel:

     

       6
       6
       +
       

     

       7
       7
       +
       ```nix

     

       8
       8
       +
       boot.kernelPackages = pkgs.linuxPackages_3_10;

     

       9
       9
       +
       ```

     

       10
       10
       +
       

     

       11
       11
       +
       Note that this not only replaces the kernel, but also packages that are

     

       12
       12
       +
       specific to the kernel version, such as the NVIDIA video drivers. This

     

       13
       13
       +
       ensures that driver packages are consistent with the kernel.

     

       14
       14
       +
       

     

       15
       15
       +
       The default Linux kernel configuration should be fine for most users.

     

       16
       16
       +
       You can see the configuration of your current kernel with the following

     

       17
       17
       +
       command:

     

       18
       18
       +
       

     

       19
       19
       +
       ```ShellSession

     

       20
       20
       +
       zcat /proc/config.gz

     

       21
       21
       +
       ```

     

       22
       22
       +
       

     

       23
       23
       +
       If you want to change the kernel configuration, you can use the

     

       24
       24
       +
       `packageOverrides` feature (see [](#sec-customising-packages)). For

     

       25
       25
       +
       instance, to enable support for the kernel debugger KGDB:

     

       26
       26
       +
       

     

       27
       27
       +
       ```nix

     

       28
       28
       +
       nixpkgs.config.packageOverrides = pkgs:

     

       29
       29
       +
         { linux_3_4 = pkgs.linux_3_4.override {

     

       30
       30
       +
             extraConfig =

     

       31
       31
       +
               ''

     

       32
       32
       +
                 KGDB y

     

       33
       33
       +
               '';

     

       34
       34
       +
           };

     

       35
       35
       +
         };

     

       36
       36
       +
       ```

     

       37
       37
       +
       

     

       38
       38
       +
       `extraConfig` takes a list of Linux kernel configuration options, one

     

       39
       39
       +
       per line. The name of the option should not include the prefix

     

       40
       40
       +
       `CONFIG_`. The option value is typically `y`, `n` or `m` (to build

     

       41
       41
       +
       something as a kernel module).

     

       42
       42
       +
       

     

       43
       43
       +
       Kernel modules for hardware devices are generally loaded automatically

     

       44
       44
       +
       by `udev`. You can force a module to be loaded via

     

       45
       45
       +
       [](#opt-boot.kernelModules), e.g.

     

       46
       46
       +
       

     

       47
       47
       +
       ```nix

     

       48
       48
       +
       boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];

     

       49
       49
       +
       ```

     

       50
       50
       +
       

     

       51
       51
       +
       If the module is required early during the boot (e.g. to mount the root

     

       52
       52
       +
       file system), you can use [](#opt-boot.initrd.kernelModules):

     

       53
       53
       +
       

     

       54
       54
       +
       ```nix

     

       55
       55
       +
       boot.initrd.kernelModules = [ "cifs" ];

     

       56
       56
       +
       ```

     

       57
       57
       +
       

     

       58
       58
       +
       This causes the specified modules and their dependencies to be added to

     

       59
       59
       +
       the initial ramdisk.

     

       60
       60
       +
       

     

       61
       61
       +
       Kernel runtime parameters can be set through

     

       62
       62
       +
       [](#opt-boot.kernel.sysctl), e.g.

     

       63
       63
       +
       

     

       64
       64
       +
       ```nix

     

       65
       65
       +
       boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;

     

       66
       66
       +
       ```

     

       67
       67
       +
       

     

       68
       68
       +
       sets the kernel's TCP keepalive time to 120 seconds. To see the

     

       69
       69
       +
       available parameters, run `sysctl -a`.

     

       70
       70
       +
       

     

       71
       71
       +
       ## Customize your kernel {#sec-linux-config-customizing}

     

       72
       72
       +
       

     

       73
       73
       +
       The first step before compiling the kernel is to generate an appropriate

     

       74
       74
       +
       `.config` configuration. Either you pass your own config via the

     

       75
       75
       +
       `configfile` setting of `linuxManualConfig`:

     

       76
       76
       +
       

     

       77
       77
       +
       ```nix

     

       78
       78
       +
       custom-kernel = super.linuxManualConfig {

     

       79
       79
       +
         inherit (super) stdenv hostPlatform;

     

       80
       80
       +
         inherit (linux_4_9) src;

     

       81
       81
       +
         version = "${linux_4_9.version}-custom";

     

       82
       82
       +
       

     

       83
       83
       +
         configfile = /home/me/my_kernel_config;

     

       84
       84
       +
         allowImportFromDerivation = true;

     

       85
       85
       +
       };

     

       86
       86
       +
       ```

     

       87
       87
       +
       

     

       88
       88
       +
       You can edit the config with this snippet (by default `make

     

       89
       89
       +
          menuconfig` won\'t work out of the box on nixos):

     

       90
       90
       +
       

     

       91
       91
       +
       ```ShellSession

     

       92
       92
       +
       nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'

     

       93
       93
       +
       ```

     

       94
       94
       +
       

     

       95
       95
       +
       or you can let nixpkgs generate the configuration. Nixpkgs generates it

     

       96
       96
       +
       via answering the interactive kernel utility `make config`. The answers

     

       97
       97
       +
       depend on parameters passed to

     

       98
       98
       +
       `pkgs/os-specific/linux/kernel/generic.nix` (which you can influence by

     

       99
       99
       +
       overriding `extraConfig, autoModules,

     

       100
       100
       +
          modDirVersion, preferBuiltin, extraConfig`).

     

       101
       101
       +
       

     

       102
       102
       +
       ```nix

     

       103
       103
       +
       mptcp93.override ({

     

       104
       104
       +
         name="mptcp-local";

     

       105
       105
       +
       

     

       106
       106
       +
         ignoreConfigErrors = true;

     

       107
       107
       +
         autoModules = false;

     

       108
       108
       +
         kernelPreferBuiltin = true;

     

       109
       109
       +
       

     

       110
       110
       +
         enableParallelBuilding = true;

     

       111
       111
       +
       

     

       112
       112
       +
         extraConfig = ''

     

       113
       113
       +
           DEBUG_KERNEL y

     

       114
       114
       +
           FRAME_POINTER y

     

       115
       115
       +
           KGDB y

     

       116
       116
       +
           KGDB_SERIAL_CONSOLE y

     

       117
       117
       +
           DEBUG_INFO y

     

       118
       118
       +
         '';

     

       119
       119
       +
       });

     

       120
       120
       +
       ```

     

       121
       121
       +
       

     

       122
       122
       +
       ## Developing kernel modules {#sec-linux-config-developing-modules}

     

       123
       123
       +
       

     

       124
       124
       +
       When developing kernel modules it\'s often convenient to run

     

       125
       125
       +
       edit-compile-run loop as quickly as possible. See below snippet as an

     

       126
       126
       +
       example of developing `mellanox` drivers.

     

       127
       127
       +
       

     

       128
       128
       +
       ```ShellSession

     

       129
       129
       +
       $ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev

     

       130
       130
       +
       $ nix-shell '<nixpkgs>' -A linuxPackages.kernel

     

       131
       131
       +
       $ unpackPhase

     

       132
       132
       +
       $ cd linux-*

     

       133
       133
       +
       $ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules

     

       134
       134
       +
       # insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko

     

       135
       135
       +
       ```

-138

nixos/doc/manual/configuration/linux-kernel.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-kernel-config">

     

       6
       6
       -
        <title>Linux Kernel</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         You can override the Linux kernel and associated packages using the option

     

       9
       9
       -
         <option>boot.kernelPackages</option>. For instance, this selects the Linux

     

       10
       10
       -
         3.10 kernel:

     

       11
       11
       -
       <programlisting>

     

       12
       12
       -
       <xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10;

     

       13
       13
       -
       </programlisting>

     

       14
       14
       -
         Note that this not only replaces the kernel, but also packages that are

     

       15
       15
       -
         specific to the kernel version, such as the NVIDIA video drivers. This

     

       16
       16
       -
         ensures that driver packages are consistent with the kernel.

     

       17
       17
       -
        </para>

     

       18
       18
       -
        <para>

     

       19
       19
       -
         The default Linux kernel configuration should be fine for most users. You can

     

       20
       20
       -
         see the configuration of your current kernel with the following command:

     

       21
       21
       -
       <programlisting>

     

       22
       22
       -
       zcat /proc/config.gz

     

       23
       23
       -
       </programlisting>

     

       24
       24
       -
         If you want to change the kernel configuration, you can use the

     

       25
       25
       -
         <option>packageOverrides</option> feature (see

     

       26
       26
       -
         <xref

     

       27
       27
       -
       linkend="sec-customising-packages" />). For instance, to enable support

     

       28
       28
       -
         for the kernel debugger KGDB:

     

       29
       29
       -
       <programlisting>

     

       30
       30
       -
       nixpkgs.config.packageOverrides = pkgs:

     

       31
       31
       -
         { linux_3_4 = pkgs.linux_3_4.override {

     

       32
       32
       -
             extraConfig =

     

       33
       33
       -
               ''

     

       34
       34
       -
                 KGDB y

     

       35
       35
       -
               '';

     

       36
       36
       -
           };

     

       37
       37
       -
         };

     

       38
       38
       -
       </programlisting>

     

       39
       39
       -
         <varname>extraConfig</varname> takes a list of Linux kernel configuration

     

       40
       40
       -
         options, one per line. The name of the option should not include the prefix

     

       41
       41
       -
         <literal>CONFIG_</literal>. The option value is typically

     

       42
       42
       -
         <literal>y</literal>, <literal>n</literal> or <literal>m</literal> (to build

     

       43
       43
       -
         something as a kernel module).

     

       44
       44
       -
        </para>

     

       45
       45
       -
        <para>

     

       46
       46
       -
         Kernel modules for hardware devices are generally loaded automatically by

     

       47
       47
       -
         <command>udev</command>. You can force a module to be loaded via

     

       48
       48
       -
         <xref linkend="opt-boot.kernelModules"/>, e.g.

     

       49
       49
       -
       <programlisting>

     

       50
       50
       -
       <xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];

     

       51
       51
       -
       </programlisting>

     

       52
       52
       -
         If the module is required early during the boot (e.g. to mount the root file

     

       53
       53
       -
         system), you can use <xref linkend="opt-boot.initrd.kernelModules"/>:

     

       54
       54
       -
       <programlisting>

     

       55
       55
       -
       <xref linkend="opt-boot.initrd.kernelModules"/> = [ "cifs" ];

     

       56
       56
       -
       </programlisting>

     

       57
       57
       -
         This causes the specified modules and their dependencies to be added to the

     

       58
       58
       -
         initial ramdisk.

     

       59
       59
       -
        </para>

     

       60
       60
       -
        <para>

     

       61
       61
       -
         Kernel runtime parameters can be set through

     

       62
       62
       -
         <xref linkend="opt-boot.kernel.sysctl"/>, e.g.

     

       63
       63
       -
       <programlisting>

     

       64
       64
       -
       <xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120;

     

       65
       65
       -
       </programlisting>

     

       66
       66
       -
         sets the kernel’s TCP keepalive time to 120 seconds. To see the available

     

       67
       67
       -
         parameters, run <command>sysctl -a</command>.

     

       68
       68
       -
        </para>

     

       69
       69
       -
        <section xml:id="sec-linux-config-customizing">

     

       70
       70
       -
         <title>Customize your kernel</title>

     

       71
       71
       -
       

     

       72
       72
       -
         <para>

     

       73
       73
       -
          The first step before compiling the kernel is to generate an appropriate

     

       74
       74
       -
          <literal>.config</literal> configuration. Either you pass your own config

     

       75
       75
       -
          via the <literal>configfile</literal> setting of

     

       76
       76
       -
          <literal>linuxManualConfig</literal>:

     

       77
       77
       -
       <screen><![CDATA[

     

       78
       78
       -
         custom-kernel = super.linuxManualConfig {

     

       79
       79
       -
           inherit (super) stdenv hostPlatform;

     

       80
       80
       -
           inherit (linux_4_9) src;

     

       81
       81
       -
           version = "${linux_4_9.version}-custom";

     

       82
       82
       -
       

     

       83
       83
       -
           configfile = /home/me/my_kernel_config;

     

       84
       84
       -
           allowImportFromDerivation = true;

     

       85
       85
       -
         };

     

       86
       86
       -
         ]]></screen>

     

       87
       87
       -
          You can edit the config with this snippet (by default <command>make

     

       88
       88
       -
          menuconfig</command> won't work out of the box on nixos):

     

       89
       89
       -
       <screen><![CDATA[

     

       90
       90
       -
             nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'

     

       91
       91
       -
         ]]></screen>

     

       92
       92
       -
          or you can let nixpkgs generate the configuration. Nixpkgs generates it via

     

       93
       93
       -
          answering the interactive kernel utility <command>make config</command>. The

     

       94
       94
       -
          answers depend on parameters passed to

     

       95
       95
       -
          <filename>pkgs/os-specific/linux/kernel/generic.nix</filename> (which you

     

       96
       96
       -
          can influence by overriding <literal>extraConfig, autoModules,

     

       97
       97
       -
          modDirVersion, preferBuiltin, extraConfig</literal>).

     

       98
       98
       -
       <screen><![CDATA[

     

       99
       99
       -
       

     

       100
       100
       -
         mptcp93.override ({

     

       101
       101
       -
             name="mptcp-local";

     

       102
       102
       -
       

     

       103
       103
       -
             ignoreConfigErrors = true;

     

       104
       104
       -
             autoModules = false;

     

       105
       105
       -
             kernelPreferBuiltin = true;

     

       106
       106
       -
       

     

       107
       107
       -
             enableParallelBuilding = true;

     

       108
       108
       -
       

     

       109
       109
       -
             extraConfig = ''

     

       110
       110
       -
               DEBUG_KERNEL y

     

       111
       111
       -
               FRAME_POINTER y

     

       112
       112
       -
               KGDB y

     

       113
       113
       -
               KGDB_SERIAL_CONSOLE y

     

       114
       114
       -
               DEBUG_INFO y

     

       115
       115
       -
             '';

     

       116
       116
       -
           });

     

       117
       117
       -
         ]]></screen>

     

       118
       118
       -
         </para>

     

       119
       119
       -
        </section>

     

       120
       120
       -
        <section xml:id="sec-linux-config-developing-modules">

     

       121
       121
       -
         <title>Developing kernel modules</title>

     

       122
       122
       -
       

     

       123
       123
       -
         <para>

     

       124
       124
       -
          When developing kernel modules it's often convenient to run edit-compile-run

     

       125
       125
       -
          loop as quickly as possible. See below snippet as an example of developing

     

       126
       126
       -
          <literal>mellanox</literal> drivers.

     

       127
       127
       -
         </para>

     

       128
       128
       -
       

     

       129
       129
       -
       <screen>

     

       130
       130
       -
       <prompt>$ </prompt>nix-build '&lt;nixpkgs>' -A linuxPackages.kernel.dev

     

       131
       131
       -
       <prompt>$ </prompt>nix-shell '&lt;nixpkgs>' -A linuxPackages.kernel

     

       132
       132
       -
       <prompt>$ </prompt>unpackPhase

     

       133
       133
       -
       <prompt>$ </prompt>cd linux-*

     

       134
       134
       -
       <prompt>$ </prompt>make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules

     

       135
       135
       -
       <prompt># </prompt>insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko

     

       136
       136
       -
       </screen>

     

       137
       137
       -
        </section>

     

       138
       138
       -
       </chapter>

+1 -1

nixos/doc/manual/configuration/sshfs-file-systems.section.md

···

       34
       34
        
       To keep the key safe, change the ownership to `root:root` and make sure the permissions are `600`:

     

       35
       35
        
       OpenSSH normally refuses to use the key if it's not well-protected.

     

       36
       36
        
       

     

       37
       37
       -
       The file system can be configured in NixOS via the usual [fileSystems](options.html#opt-fileSystems) option.

     

       37
       37
       +
       The file system can be configured in NixOS via the usual [fileSystems](#opt-fileSystems) option.

     

       38
       38
        
       Here's a typical setup:

     

       39
       39
        
       ```nix

     

       40
       40
        
       {

+102

nixos/doc/manual/configuration/subversion.chapter.md

···

       1
       1
       +
       # Subversion {#module-services-subversion}

     

       2
       2
       +
       

     

       3
       3
       +
       [Subversion](https://subversion.apache.org/) is a centralized

     

       4
       4
       +
       version-control system. It can use a [variety of

     

       5
       5
       +
       protocols](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing)

     

       6
       6
       +
       for communication between client and server.

     

       7
       7
       +
       

     

       8
       8
       +
       ## Subversion inside Apache HTTP {#module-services-subversion-apache-httpd}

     

       9
       9
       +
       

     

       10
       10
       +
       This section focuses on configuring a web-based server on top of the

     

       11
       11
       +
       Apache HTTP server, which uses

     

       12
       12
       +
       [WebDAV](http://www.webdav.org/)/[DeltaV](http://www.webdav.org/deltav/WWW10/deltav-intro.htm)

     

       13
       13
       +
       for communication.

     

       14
       14
       +
       

     

       15
       15
       +
       For more information on the general setup, please refer to the [the

     

       16
       16
       +
       appropriate section of the Subversion

     

       17
       17
       +
       book](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd).

     

       18
       18
       +
       

     

       19
       19
       +
       To configure, include in `/etc/nixos/configuration.nix` code to activate

     

       20
       20
       +
       Apache HTTP, setting [](#opt-services.httpd.adminAddr)

     

       21
       21
       +
       appropriately:

     

       22
       22
       +
       

     

       23
       23
       +
       ```nix

     

       24
       24
       +
       services.httpd.enable = true;

     

       25
       25
       +
       services.httpd.adminAddr = ...;

     

       26
       26
       +
       networking.firewall.allowedTCPPorts = [ 80 443 ];

     

       27
       27
       +
       ```

     

       28
       28
       +
       

     

       29
       29
       +
       For a simple Subversion server with basic authentication, configure the

     

       30
       30
       +
       Subversion module for Apache as follows, setting `hostName` and

     

       31
       31
       +
       `documentRoot` appropriately, and `SVNParentPath` to the parent

     

       32
       32
       +
       directory of the repositories, `AuthzSVNAccessFile` to the location of

     

       33
       33
       +
       the `.authz` file describing access permission, and `AuthUserFile` to

     

       34
       34
       +
       the password file.

     

       35
       35
       +
       

     

       36
       36
       +
       ```nix

     

       37
       37
       +
       services.httpd.extraModules = [

     

       38
       38
       +
           # note that order is *super* important here

     

       39
       39
       +
           { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }

     

       40
       40
       +
           { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }

     

       41
       41
       +
         ];

     

       42
       42
       +
         services.httpd.virtualHosts = {

     

       43
       43
       +
           "svn" = {

     

       44
       44
       +
              hostName = HOSTNAME;

     

       45
       45
       +
              documentRoot = DOCUMENTROOT;

     

       46
       46
       +
              locations."/svn".extraConfig = ''

     

       47
       47
       +
                  DAV svn

     

       48
       48
       +
                  SVNParentPath REPO_PARENT

     

       49
       49
       +
                  AuthzSVNAccessFile ACCESS_FILE

     

       50
       50
       +
                  AuthName "SVN Repositories"

     

       51
       51
       +
                  AuthType Basic

     

       52
       52
       +
                  AuthUserFile PASSWORD_FILE

     

       53
       53
       +
                  Require valid-user

     

       54
       54
       +
             '';

     

       55
       55
       +
           }

     

       56
       56
       +
       ```

     

       57
       57
       +
       

     

       58
       58
       +
       The key `"svn"` is just a symbolic name identifying the virtual host.

     

       59
       59
       +
       The `"/svn"` in `locations."/svn".extraConfig` is the path underneath

     

       60
       60
       +
       which the repositories will be served.

     

       61
       61
       +
       

     

       62
       62
       +
       [This page](https://wiki.archlinux.org/index.php/Subversion) explains

     

       63
       63
       +
       how to set up the Subversion configuration itself. This boils down to

     

       64
       64
       +
       the following:

     

       65
       65
       +
       

     

       66
       66
       +
       Underneath `REPO_PARENT` repositories can be set up as follows:

     

       67
       67
       +
       

     

       68
       68
       +
       ```ShellSession

     

       69
       69
       +
       $ svn create REPO_NAME

     

       70
       70
       +
       ```

     

       71
       71
       +
       

     

       72
       72
       +
       Repository files need to be accessible by `wwwrun`:

     

       73
       73
       +
       

     

       74
       74
       +
       ```ShellSession

     

       75
       75
       +
       $ chown -R wwwrun:wwwrun REPO_PARENT

     

       76
       76
       +
       ```

     

       77
       77
       +
       

     

       78
       78
       +
       The password file `PASSWORD_FILE` can be created as follows:

     

       79
       79
       +
       

     

       80
       80
       +
       ```ShellSession

     

       81
       81
       +
       $ htpasswd -cs PASSWORD_FILE USER_NAME

     

       82
       82
       +
       ```

     

       83
       83
       +
       

     

       84
       84
       +
       Additional users can be set up similarly, omitting the `c` flag:

     

       85
       85
       +
       

     

       86
       86
       +
       ```ShellSession

     

       87
       87
       +
       $ htpasswd -s PASSWORD_FILE USER_NAME

     

       88
       88
       +
       ```

     

       89
       89
       +
       

     

       90
       90
       +
       The file describing access permissions `ACCESS_FILE` will look something

     

       91
       91
       +
       like the following:

     

       92
       92
       +
       

     

       93
       93
       +
       ```nix

     

       94
       94
       +
       [/]

     

       95
       95
       +
       * = r

     

       96
       96
       +
       

     

       97
       97
       +
       [REPO_NAME:/]

     

       98
       98
       +
       USER_NAME = rw

     

       99
       99
       +
       ```

     

       100
       100
       +
       

     

       101
       101
       +
       The Subversion repositories will be accessible as

     

       102
       102
       +
       `http://HOSTNAME/svn/REPO_NAME`.

-140

nixos/doc/manual/configuration/subversion.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="module-services-subversion">

     

       6
       6
       -
         <title>Subversion</title>

     

       7
       7
       -
       

     

       8
       8
       -
        <para>

     

       9
       9
       -
         <link xlink:href="https://subversion.apache.org/">Subversion</link>

     

       10
       10
       -
         is a centralized version-control system.  It can use a <link

     

       11
       11
       -
         xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety

     

       12
       12
       -
         of protocols</link> for communication between client and server.

     

       13
       13
       -
        </para>

     

       14
       14
       -
        <section xml:id="module-services-subversion-apache-httpd">

     

       15
       15
       -
         <title>Subversion inside Apache HTTP</title>

     

       16
       16
       -
       

     

       17
       17
       -
          <para>

     

       18
       18
       -
          This section focuses on configuring a web-based server on top of

     

       19
       19
       -
          the Apache HTTP server, which uses

     

       20
       20
       -
          <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link

     

       21
       21
       -
          xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link>

     

       22
       22
       -
          for communication.

     

       23
       23
       -
          </para>

     

       24
       24
       -
       

     

       25
       25
       -
          <para>For more information on the general setup, please refer to

     

       26
       26
       -
          the <link

     

       27
       27
       -
          xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the

     

       28
       28
       -
          appropriate section of the Subversion book</link>.

     

       29
       29
       -
          </para>

     

       30
       30
       -
       

     

       31
       31
       -
          <para>To configure, include in

     

       32
       32
       -
          <literal>/etc/nixos/configuration.nix</literal> code to activate

     

       33
       33
       -
          Apache HTTP, setting <xref linkend="opt-services.httpd.adminAddr" />

     

       34
       34
       -
          appropriately:

     

       35
       35
       -
          </para>

     

       36
       36
       -
       

     

       37
       37
       -
           <para>

     

       38
       38
       -
       <programlisting>

     

       39
       39
       -
         services.httpd.enable = true;

     

       40
       40
       -
         services.httpd.adminAddr = ...;

     

       41
       41
       -
         networking.firewall.allowedTCPPorts = [ 80 443 ];

     

       42
       42
       -
       </programlisting>

     

       43
       43
       -
           </para>

     

       44
       44
       -
       

     

       45
       45
       -
           <para>For a simple Subversion server with basic authentication,

     

       46
       46
       -
           configure the Subversion module for Apache as follows, setting

     

       47
       47
       -
           <literal>hostName</literal> and <literal>documentRoot</literal>

     

       48
       48
       -
           appropriately, and <literal>SVNParentPath</literal> to the parent

     

       49
       49
       -
           directory of the repositories,

     

       50
       50
       -
           <literal>AuthzSVNAccessFile</literal> to the location of the

     

       51
       51
       -
           <code>.authz</code> file describing access permission, and

     

       52
       52
       -
           <literal>AuthUserFile</literal> to the password file.

     

       53
       53
       -
           </para>

     

       54
       54
       -
           <para>

     

       55
       55
       -
       <programlisting>

     

       56
       56
       -
       services.httpd.extraModules = [

     

       57
       57
       -
           # note that order is *super* important here

     

       58
       58
       -
           { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }

     

       59
       59
       -
           { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }

     

       60
       60
       -
         ];

     

       61
       61
       -
         services.httpd.virtualHosts = {

     

       62
       62
       -
           "svn" = {

     

       63
       63
       -
              hostName = HOSTNAME;

     

       64
       64
       -
              documentRoot = DOCUMENTROOT;

     

       65
       65
       -
              locations."/svn".extraConfig = ''

     

       66
       66
       -
                  DAV svn

     

       67
       67
       -
                  SVNParentPath REPO_PARENT

     

       68
       68
       -
                  AuthzSVNAccessFile ACCESS_FILE

     

       69
       69
       -
                  AuthName "SVN Repositories"

     

       70
       70
       -
                  AuthType Basic

     

       71
       71
       -
                  AuthUserFile PASSWORD_FILE

     

       72
       72
       -
                  Require valid-user

     

       73
       73
       -
             '';

     

       74
       74
       -
           }

     

       75
       75
       -
       </programlisting>

     

       76
       76
       -
           </para>

     

       77
       77
       -
       

     

       78
       78
       -
           <para>

     

       79
       79
       -
           The key <code>"svn"</code> is just a symbolic name identifying the

     

       80
       80
       -
           virtual host.  The <code>"/svn"</code> in

     

       81
       81
       -
           <code>locations."/svn".extraConfig</code> is the path underneath

     

       82
       82
       -
           which the repositories will be served.

     

       83
       83
       -
           </para>

     

       84
       84
       -
       

     

       85
       85
       -
           <para><link

     

       86
       86
       -
                     xlink:href="https://wiki.archlinux.org/index.php/Subversion">This

     

       87
       87
       -
           page</link> explains how to set up the Subversion configuration

     

       88
       88
       -
           itself.  This boils down to the following:

     

       89
       89
       -
           </para>

     

       90
       90
       -
           <para>

     

       91
       91
       -
             Underneath <literal>REPO_PARENT</literal> repositories can be set up

     

       92
       92
       -
             as follows:

     

       93
       93
       -
           </para>

     

       94
       94
       -
           <para>

     

       95
       95
       -
       <screen>

     

       96
       96
       -
       <prompt>$ </prompt> svn create REPO_NAME

     

       97
       97
       -
       </screen>

     

       98
       98
       -
           </para>

     

       99
       99
       -
           <para>Repository files need to be accessible by

     

       100
       100
       -
           <literal>wwwrun</literal>:

     

       101
       101
       -
           </para>

     

       102
       102
       -
           <para>

     

       103
       103
       -
       <screen>

     

       104
       104
       -
       <prompt>$ </prompt> chown -R wwwrun:wwwrun REPO_PARENT

     

       105
       105
       -
       </screen>

     

       106
       106
       -
           </para>

     

       107
       107
       -
           <para>

     

       108
       108
       -
             The password file <literal>PASSWORD_FILE</literal> can be created as follows:

     

       109
       109
       -
           </para>

     

       110
       110
       -
           <para>

     

       111
       111
       -
       <screen>

     

       112
       112
       -
       <prompt>$ </prompt> htpasswd -cs PASSWORD_FILE USER_NAME

     

       113
       113
       -
       </screen>

     

       114
       114
       -
           </para>

     

       115
       115
       -
           <para>

     

       116
       116
       -
           Additional users can be set up similarly, omitting the

     

       117
       117
       -
           <code>c</code> flag:

     

       118
       118
       -
           </para>

     

       119
       119
       -
           <para>

     

       120
       120
       -
       <screen>

     

       121
       121
       -
       <prompt>$ </prompt> htpasswd -s PASSWORD_FILE USER_NAME

     

       122
       122
       -
       </screen>

     

       123
       123
       -
           </para>

     

       124
       124
       -
           <para>

     

       125
       125
       -
             The file describing access permissions

     

       126
       126
       -
             <literal>ACCESS_FILE</literal> will look something like

     

       127
       127
       -
             the following:

     

       128
       128
       -
           </para>

     

       129
       129
       -
           <para>

     

       130
       130
       -
       <programlisting>

     

       131
       131
       -
       [/]

     

       132
       132
       -
       * = r

     

       133
       133
       -
       

     

       134
       134
       -
       [REPO_NAME:/]

     

       135
       135
       -
       USER_NAME = rw

     

       136
       136
       -
       </programlisting>

     

       137
       137
       -
           </para>

     

       138
       138
       -
           <para>The Subversion repositories will be accessible as <code>http://HOSTNAME/svn/REPO_NAME</code>.</para>

     

       139
       139
       -
        </section>

     

       140
       140
       -
       </chapter>

+92

nixos/doc/manual/configuration/user-mgmt.chapter.md

···

       1
       1
       +
       # User Management {#sec-user-management}

     

       2
       2
       +
       

     

       3
       3
       +
       NixOS supports both declarative and imperative styles of user

     

       4
       4
       +
       management. In the declarative style, users are specified in

     

       5
       5
       +
       `configuration.nix`. For instance, the following states that a user

     

       6
       6
       +
       account named `alice` shall exist:

     

       7
       7
       +
       

     

       8
       8
       +
       ```nix

     

       9
       9
       +
       users.users.alice = {

     

       10
       10
       +
         isNormalUser = true;

     

       11
       11
       +
         home = "/home/alice";

     

       12
       12
       +
         description = "Alice Foobar";

     

       13
       13
       +
         extraGroups = [ "wheel" "networkmanager" ];

     

       14
       14
       +
         openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];

     

       15
       15
       +
       };

     

       16
       16
       +
       ```

     

       17
       17
       +
       

     

       18
       18
       +
       Note that `alice` is a member of the `wheel` and `networkmanager`

     

       19
       19
       +
       groups, which allows her to use `sudo` to execute commands as `root` and

     

       20
       20
       +
       to configure the network, respectively. Also note the SSH public key

     

       21
       21
       +
       that allows remote logins with the corresponding private key. Users

     

       22
       22
       +
       created in this way do not have a password by default, so they cannot

     

       23
       23
       +
       log in via mechanisms that require a password. However, you can use the

     

       24
       24
       +
       `passwd` program to set a password, which is retained across invocations

     

       25
       25
       +
       of `nixos-rebuild`.

     

       26
       26
       +
       

     

       27
       27
       +
       If you set [](#opt-users.mutableUsers) to

     

       28
       28
       +
       false, then the contents of `/etc/passwd` and `/etc/group` will be congruent

     

       29
       29
       +
       to your NixOS configuration. For instance, if you remove a user from

     

       30
       30
       +
       [](#opt-users.users) and run nixos-rebuild, the user

     

       31
       31
       +
       account will cease to exist. Also, imperative commands for managing users and

     

       32
       32
       +
       groups, such as useradd, are no longer available. Passwords may still be

     

       33
       33
       +
       assigned by setting the user\'s

     

       34
       34
       +
       [hashedPassword](#opt-users.users._name_.hashedPassword) option. A

     

       35
       35
       +
       hashed password can be generated using `mkpasswd -m

     

       36
       36
       +
         sha-512`.

     

       37
       37
       +
       

     

       38
       38
       +
       A user ID (uid) is assigned automatically. You can also specify a uid

     

       39
       39
       +
       manually by adding

     

       40
       40
       +
       

     

       41
       41
       +
       ```nix

     

       42
       42
       +
       uid = 1000;

     

       43
       43
       +
       ```

     

       44
       44
       +
       

     

       45
       45
       +
       to the user specification.

     

       46
       46
       +
       

     

       47
       47
       +
       Groups can be specified similarly. The following states that a group

     

       48
       48
       +
       named `students` shall exist:

     

       49
       49
       +
       

     

       50
       50
       +
       ```nix

     

       51
       51
       +
       users.groups.students.gid = 1000;

     

       52
       52
       +
       ```

     

       53
       53
       +
       

     

       54
       54
       +
       As with users, the group ID (gid) is optional and will be assigned

     

       55
       55
       +
       automatically if it's missing.

     

       56
       56
       +
       

     

       57
       57
       +
       In the imperative style, users and groups are managed by commands such

     

       58
       58
       +
       as `useradd`, `groupmod` and so on. For instance, to create a user

     

       59
       59
       +
       account named `alice`:

     

       60
       60
       +
       

     

       61
       61
       +
       ```ShellSession

     

       62
       62
       +
       # useradd -m alice

     

       63
       63
       +
       ```

     

       64
       64
       +
       

     

       65
       65
       +
       To make all nix tools available to this new user use \`su - USER\` which

     

       66
       66
       +
       opens a login shell (==shell that loads the profile) for given user.

     

       67
       67
       +
       This will create the \~/.nix-defexpr symlink. So run:

     

       68
       68
       +
       

     

       69
       69
       +
       ```ShellSession

     

       70
       70
       +
       # su - alice -c "true"

     

       71
       71
       +
       ```

     

       72
       72
       +
       

     

       73
       73
       +
       The flag `-m` causes the creation of a home directory for the new user,

     

       74
       74
       +
       which is generally what you want. The user does not have an initial

     

       75
       75
       +
       password and therefore cannot log in. A password can be set using the

     

       76
       76
       +
       `passwd` utility:

     

       77
       77
       +
       

     

       78
       78
       +
       ```ShellSession

     

       79
       79
       +
       # passwd alice

     

       80
       80
       +
       Enter new UNIX password: ***

     

       81
       81
       +
       Retype new UNIX password: ***

     

       82
       82
       +
       ```

     

       83
       83
       +
       

     

       84
       84
       +
       A user can be deleted using `userdel`:

     

       85
       85
       +
       

     

       86
       86
       +
       ```ShellSession

     

       87
       87
       +
       # userdel -r alice

     

       88
       88
       +
       ```

     

       89
       89
       +
       

     

       90
       90
       +
       The flag `-r` deletes the user's home directory. Accounts can be

     

       91
       91
       +
       modified using `usermod`. Unix groups can be managed using `groupadd`,

     

       92
       92
       +
       `groupmod` and `groupdel`.

-88

nixos/doc/manual/configuration/user-mgmt.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-user-management">

     

       6
       6
       -
        <title>User Management</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         NixOS supports both declarative and imperative styles of user management. In

     

       9
       9
       -
         the declarative style, users are specified in

     

       10
       10
       -
         <filename>configuration.nix</filename>. For instance, the following states

     

       11
       11
       -
         that a user account named <literal>alice</literal> shall exist:

     

       12
       12
       -
       <programlisting>

     

       13
       13
       -
       <xref linkend="opt-users.users"/>.alice = {

     

       14
       14
       -
         <link linkend="opt-users.users._name_.isNormalUser">isNormalUser</link> = true;

     

       15
       15
       -
         <link linkend="opt-users.users._name_.home">home</link> = "/home/alice";

     

       16
       16
       -
         <link linkend="opt-users.users._name_.description">description</link> = "Alice Foobar";

     

       17
       17
       -
         <link linkend="opt-users.users._name_.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ];

     

       18
       18
       -
         <link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ];

     

       19
       19
       -
       };

     

       20
       20
       -
       </programlisting>

     

       21
       21
       -
         Note that <literal>alice</literal> is a member of the

     

       22
       22
       -
         <literal>wheel</literal> and <literal>networkmanager</literal> groups, which

     

       23
       23
       -
         allows her to use <command>sudo</command> to execute commands as

     

       24
       24
       -
         <literal>root</literal> and to configure the network, respectively. Also note

     

       25
       25
       -
         the SSH public key that allows remote logins with the corresponding private

     

       26
       26
       -
         key. Users created in this way do not have a password by default, so they

     

       27
       27
       -
         cannot log in via mechanisms that require a password. However, you can use

     

       28
       28
       -
         the <command>passwd</command> program to set a password, which is retained

     

       29
       29
       -
         across invocations of <command>nixos-rebuild</command>.

     

       30
       30
       -
        </para>

     

       31
       31
       -
        <para>

     

       32
       32
       -
         If you set <xref linkend="opt-users.mutableUsers"/> to false, then the

     

       33
       33
       -
         contents of <literal>/etc/passwd</literal> and <literal>/etc/group</literal>

     

       34
       34
       -
         will be congruent to your NixOS configuration. For instance, if you remove a

     

       35
       35
       -
         user from <xref linkend="opt-users.users"/> and run nixos-rebuild, the user

     

       36
       36
       -
         account will cease to exist. Also, imperative commands for managing users and

     

       37
       37
       -
         groups, such as useradd, are no longer available. Passwords may still be

     

       38
       38
       -
         assigned by setting the user's

     

       39
       39
       -
         <link linkend="opt-users.users._name_.hashedPassword">hashedPassword</link>

     

       40
       40
       -
         option. A hashed password can be generated using <command>mkpasswd -m

     

       41
       41
       -
         sha-512</command>.

     

       42
       42
       -
        </para>

     

       43
       43
       -
        <para>

     

       44
       44
       -
         A user ID (uid) is assigned automatically. You can also specify a uid

     

       45
       45
       -
         manually by adding

     

       46
       46
       -
       <programlisting>

     

       47
       47
       -
       uid = 1000;

     

       48
       48
       -
       </programlisting>

     

       49
       49
       -
         to the user specification.

     

       50
       50
       -
        </para>

     

       51
       51
       -
        <para>

     

       52
       52
       -
         Groups can be specified similarly. The following states that a group named

     

       53
       53
       -
         <literal>students</literal> shall exist:

     

       54
       54
       -
       <programlisting>

     

       55
       55
       -
       <xref linkend="opt-users.groups"/>.students.gid = 1000;

     

       56
       56
       -
       </programlisting>

     

       57
       57
       -
         As with users, the group ID (gid) is optional and will be assigned

     

       58
       58
       -
         automatically if it’s missing.

     

       59
       59
       -
        </para>

     

       60
       60
       -
        <para>

     

       61
       61
       -
         In the imperative style, users and groups are managed by commands such as

     

       62
       62
       -
         <command>useradd</command>, <command>groupmod</command> and so on. For

     

       63
       63
       -
         instance, to create a user account named <literal>alice</literal>:

     

       64
       64
       -
       <screen>

     

       65
       65
       -
       <prompt># </prompt>useradd -m <replaceable>alice</replaceable></screen>

     

       66
       66
       -
         To make all nix tools available to this new user use `su - USER` which opens

     

       67
       67
       -
         a login shell (==shell that loads the profile) for given user. This will

     

       68
       68
       -
         create the ~/.nix-defexpr symlink. So run:

     

       69
       69
       -
       <screen>

     

       70
       70
       -
       <prompt># </prompt>su - <replaceable>alice</replaceable> -c "true"</screen>

     

       71
       71
       -
         The flag <option>-m</option> causes the creation of a home directory for the

     

       72
       72
       -
         new user, which is generally what you want. The user does not have an initial

     

       73
       73
       -
         password and therefore cannot log in. A password can be set using the

     

       74
       74
       -
         <command>passwd</command> utility:

     

       75
       75
       -
       <screen>

     

       76
       76
       -
       <prompt># </prompt>passwd <replaceable>alice</replaceable>

     

       77
       77
       -
       Enter new UNIX password: ***

     

       78
       78
       -
       Retype new UNIX password: ***

     

       79
       79
       -
       </screen>

     

       80
       80
       -
         A user can be deleted using <command>userdel</command>:

     

       81
       81
       -
       <screen>

     

       82
       82
       -
       <prompt># </prompt>userdel -r <replaceable>alice</replaceable></screen>

     

       83
       83
       -
         The flag <option>-r</option> deletes the user’s home directory. Accounts

     

       84
       84
       -
         can be modified using <command>usermod</command>. Unix groups can be managed

     

       85
       85
       -
         using <command>groupadd</command>, <command>groupmod</command> and

     

       86
       86
       -
         <command>groupdel</command>.

     

       87
       87
       -
        </para>

     

       88
       88
       -
       </chapter>

+27

nixos/doc/manual/configuration/wayland.chapter.md

···

       1
       1
       +
       # Wayland {#sec-wayland}

     

       2
       2
       +
       

     

       3
       3
       +
       While X11 (see [](#sec-x11)) is still the primary display technology

     

       4
       4
       +
       on NixOS, Wayland support is steadily improving. Where X11 separates the

     

       5
       5
       +
       X Server and the window manager, on Wayland those are combined: a

     

       6
       6
       +
       Wayland Compositor is like an X11 window manager, but also embeds the

     

       7
       7
       +
       Wayland \'Server\' functionality. This means it is sufficient to install

     

       8
       8
       +
       a Wayland Compositor such as sway without separately enabling a Wayland

     

       9
       9
       +
       server:

     

       10
       10
       +
       

     

       11
       11
       +
       ```nix

     

       12
       12
       +
       programs.sway.enable = true;

     

       13
       13
       +
       ```

     

       14
       14
       +
       

     

       15
       15
       +
       This installs the sway compositor along with some essential utilities.

     

       16
       16
       +
       Now you can start sway from the TTY console.

     

       17
       17
       +
       

     

       18
       18
       +
       If you are using a wlroots-based compositor, like sway, and want to be

     

       19
       19
       +
       able to share your screen, you might want to activate this option:

     

       20
       20
       +
       

     

       21
       21
       +
       ```nix

     

       22
       22
       +
       xdg.portal.wlr.enable = true;

     

       23
       23
       +
       ```

     

       24
       24
       +
       

     

       25
       25
       +
       and configure Pipewire using

     

       26
       26
       +
       [](#opt-services.pipewire.enable)

     

       27
       27
       +
       and related options.

-33

nixos/doc/manual/configuration/wayland.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-wayland">

     

       6
       6
       -
        <title>Wayland</title>

     

       7
       7
       -
       

     

       8
       8
       -
        <para>

     

       9
       9
       -
         While X11 (see <xref linkend="sec-x11"/>) is still the primary display

     

       10
       10
       -
         technology on NixOS, Wayland support is steadily improving.

     

       11
       11
       -
         Where X11 separates the X Server and the window manager, on Wayland those

     

       12
       12
       -
         are combined: a Wayland Compositor is like an X11 window manager, but also

     

       13
       13
       -
         embeds the Wayland 'Server' functionality. This means it is sufficient to

     

       14
       14
       -
         install a Wayland Compositor such as <package>sway</package> without

     

       15
       15
       -
         separately enabling a Wayland server:

     

       16
       16
       -
       <programlisting>

     

       17
       17
       -
       <xref linkend="opt-programs.sway.enable"/> = true;

     

       18
       18
       -
       </programlisting>

     

       19
       19
       -
         This installs the <package>sway</package> compositor along with some

     

       20
       20
       -
         essential utilities. Now you can start <package>sway</package> from the TTY

     

       21
       21
       -
         console.

     

       22
       22
       -
        </para>

     

       23
       23
       -
       

     

       24
       24
       -
        <para>

     

       25
       25
       -
         If you are using a wlroots-based compositor, like sway, and want to be able to

     

       26
       26
       -
         share your screen, you might want to activate this option:

     

       27
       27
       -
       <programlisting>

     

       28
       28
       -
       <xref linkend="opt-xdg.portal.wlr.enable"/> = true;

     

       29
       29
       -
       </programlisting>

     

       30
       30
       -
         and configure Pipewire using <xref linkend="opt-services.pipewire.enable"/>

     

       31
       31
       -
         and related options.

     

       32
       32
       -
        </para>

     

       33
       33
       -
       </chapter>

+337

nixos/doc/manual/configuration/x-windows.chapter.md

···

       1
       1
       +
       # X Window System {#sec-x11}

     

       2
       2
       +
       

     

       3
       3
       +
       The X Window System (X11) provides the basis of NixOS' graphical user

     

       4
       4
       +
       interface. It can be enabled as follows:

     

       5
       5
       +
       

     

       6
       6
       +
       ```nix

     

       7
       7
       +
       services.xserver.enable = true;

     

       8
       8
       +
       ```

     

       9
       9
       +
       

     

       10
       10
       +
       The X server will automatically detect and use the appropriate video

     

       11
       11
       +
       driver from a set of X.org drivers (such as `vesa` and `intel`). You can

     

       12
       12
       +
       also specify a driver manually, e.g.

     

       13
       13
       +
       

     

       14
       14
       +
       ```nix

     

       15
       15
       +
       services.xserver.videoDrivers = [ "r128" ];

     

       16
       16
       +
       ```

     

       17
       17
       +
       

     

       18
       18
       +
       to enable X.org's `xf86-video-r128` driver.

     

       19
       19
       +
       

     

       20
       20
       +
       You also need to enable at least one desktop or window manager.

     

       21
       21
       +
       Otherwise, you can only log into a plain undecorated `xterm` window.

     

       22
       22
       +
       Thus you should pick one or more of the following lines:

     

       23
       23
       +
       

     

       24
       24
       +
       ```nix

     

       25
       25
       +
       services.xserver.desktopManager.plasma5.enable = true;

     

       26
       26
       +
       services.xserver.desktopManager.xfce.enable = true;

     

       27
       27
       +
       services.xserver.desktopManager.gnome.enable = true;

     

       28
       28
       +
       services.xserver.desktopManager.mate.enable = true;

     

       29
       29
       +
       services.xserver.windowManager.xmonad.enable = true;

     

       30
       30
       +
       services.xserver.windowManager.twm.enable = true;

     

       31
       31
       +
       services.xserver.windowManager.icewm.enable = true;

     

       32
       32
       +
       services.xserver.windowManager.i3.enable = true;

     

       33
       33
       +
       services.xserver.windowManager.herbstluftwm.enable = true;

     

       34
       34
       +
       ```

     

       35
       35
       +
       

     

       36
       36
       +
       NixOS's default *display manager* (the program that provides a graphical

     

       37
       37
       +
       login prompt and manages the X server) is LightDM. You can select an

     

       38
       38
       +
       alternative one by picking one of the following lines:

     

       39
       39
       +
       

     

       40
       40
       +
       ```nix

     

       41
       41
       +
       services.xserver.displayManager.sddm.enable = true;

     

       42
       42
       +
       services.xserver.displayManager.gdm.enable = true;

     

       43
       43
       +
       ```

     

       44
       44
       +
       

     

       45
       45
       +
       You can set the keyboard layout (and optionally the layout variant):

     

       46
       46
       +
       

     

       47
       47
       +
       ```nix

     

       48
       48
       +
       services.xserver.layout = "de";

     

       49
       49
       +
       services.xserver.xkbVariant = "neo";

     

       50
       50
       +
       ```

     

       51
       51
       +
       

     

       52
       52
       +
       The X server is started automatically at boot time. If you don't want

     

       53
       53
       +
       this to happen, you can set:

     

       54
       54
       +
       

     

       55
       55
       +
       ```nix

     

       56
       56
       +
       services.xserver.autorun = false;

     

       57
       57
       +
       ```

     

       58
       58
       +
       

     

       59
       59
       +
       The X server can then be started manually:

     

       60
       60
       +
       

     

       61
       61
       +
       ```ShellSession

     

       62
       62
       +
       # systemctl start display-manager.service

     

       63
       63
       +
       ```

     

       64
       64
       +
       

     

       65
       65
       +
       On 64-bit systems, if you want OpenGL for 32-bit programs such as in

     

       66
       66
       +
       Wine, you should also set the following:

     

       67
       67
       +
       

     

       68
       68
       +
       ```nix

     

       69
       69
       +
       hardware.opengl.driSupport32Bit = true;

     

       70
       70
       +
       ```

     

       71
       71
       +
       

     

       72
       72
       +
       ## Auto-login {#sec-x11-auto-login .unnumbered}

     

       73
       73
       +
       

     

       74
       74
       +
       The x11 login screen can be skipped entirely, automatically logging you

     

       75
       75
       +
       into your window manager and desktop environment when you boot your

     

       76
       76
       +
       computer.

     

       77
       77
       +
       

     

       78
       78
       +
       This is especially helpful if you have disk encryption enabled. Since

     

       79
       79
       +
       you already have to provide a password to decrypt your disk, entering a

     

       80
       80
       +
       second password to login can be redundant.

     

       81
       81
       +
       

     

       82
       82
       +
       To enable auto-login, you need to define your default window manager and

     

       83
       83
       +
       desktop environment. If you wanted no desktop environment and i3 as your

     

       84
       84
       +
       your window manager, you\'d define:

     

       85
       85
       +
       

     

       86
       86
       +
       ```nix

     

       87
       87
       +
       services.xserver.displayManager.defaultSession = "none+i3";

     

       88
       88
       +
       ```

     

       89
       89
       +
       

     

       90
       90
       +
       Every display manager in NixOS supports auto-login, here is an example

     

       91
       91
       +
       using lightdm for a user `alice`:

     

       92
       92
       +
       

     

       93
       93
       +
       ```nix

     

       94
       94
       +
       services.xserver.displayManager.lightdm.enable = true;

     

       95
       95
       +
       services.xserver.displayManager.autoLogin.enable = true;

     

       96
       96
       +
       services.xserver.displayManager.autoLogin.user = "alice";

     

       97
       97
       +
       ```

     

       98
       98
       +
       

     

       99
       99
       +
       ## Intel Graphics drivers {#sec-x11--graphics-cards-intel .unnumbered}

     

       100
       100
       +
       

     

       101
       101
       +
       There are two choices for Intel Graphics drivers in X.org: `modesetting`

     

       102
       102
       +
       (included in the xorg-server itself) and `intel` (provided by the

     

       103
       103
       +
       package xf86-video-intel).

     

       104
       104
       +
       

     

       105
       105
       +
       The default and recommended is `modesetting`. It is a generic driver

     

       106
       106
       +
       which uses the kernel [mode

     

       107
       107
       +
       setting](https://en.wikipedia.org/wiki/Mode_setting) (KMS) mechanism. It

     

       108
       108
       +
       supports Glamor (2D graphics acceleration via OpenGL) and is actively

     

       109
       109
       +
       maintained but may perform worse in some cases (like in old chipsets).

     

       110
       110
       +
       

     

       111
       111
       +
       The second driver, `intel`, is specific to Intel GPUs, but not

     

       112
       112
       +
       recommended by most distributions: it lacks several modern features (for

     

       113
       113
       +
       example, it doesn\'t support Glamor) and the package hasn\'t been

     

       114
       114
       +
       officially updated since 2015.

     

       115
       115
       +
       

     

       116
       116
       +
       The results vary depending on the hardware, so you may have to try both

     

       117
       117
       +
       drivers. Use the option

     

       118
       118
       +
       [](#opt-services.xserver.videoDrivers)

     

       119
       119
       +
       to set one. The recommended configuration for modern systems is:

     

       120
       120
       +
       

     

       121
       121
       +
       ```nix

     

       122
       122
       +
       services.xserver.videoDrivers = [ "modesetting" ];

     

       123
       123
       +
       services.xserver.useGlamor = true;

     

       124
       124
       +
       ```

     

       125
       125
       +
       

     

       126
       126
       +
       If you experience screen tearing no matter what, this configuration was

     

       127
       127
       +
       reported to resolve the issue:

     

       128
       128
       +
       

     

       129
       129
       +
       ```nix

     

       130
       130
       +
       services.xserver.videoDrivers = [ "intel" ];

     

       131
       131
       +
       services.xserver.deviceSection = ''

     

       132
       132
       +
         Option "DRI" "2"

     

       133
       133
       +
         Option "TearFree" "true"

     

       134
       134
       +
       '';

     

       135
       135
       +
       ```

     

       136
       136
       +
       

     

       137
       137
       +
       Note that this will likely downgrade the performance compared to

     

       138
       138
       +
       `modesetting` or `intel` with DRI 3 (default).

     

       139
       139
       +
       

     

       140
       140
       +
       ## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia .unnumbered}

     

       141
       141
       +
       

     

       142
       142
       +
       NVIDIA provides a proprietary driver for its graphics cards that has

     

       143
       143
       +
       better 3D performance than the X.org drivers. It is not enabled by

     

       144
       144
       +
       default because it's not free software. You can enable it as follows:

     

       145
       145
       +
       

     

       146
       146
       +
       ```nix

     

       147
       147
       +
       services.xserver.videoDrivers = [ "nvidia" ];

     

       148
       148
       +
       ```

     

       149
       149
       +
       

     

       150
       150
       +
       Or if you have an older card, you may have to use one of the legacy

     

       151
       151
       +
       drivers:

     

       152
       152
       +
       

     

       153
       153
       +
       ```nix

     

       154
       154
       +
       services.xserver.videoDrivers = [ "nvidiaLegacy390" ];

     

       155
       155
       +
       services.xserver.videoDrivers = [ "nvidiaLegacy340" ];

     

       156
       156
       +
       services.xserver.videoDrivers = [ "nvidiaLegacy304" ];

     

       157
       157
       +
       ```

     

       158
       158
       +
       

     

       159
       159
       +
       You may need to reboot after enabling this driver to prevent a clash

     

       160
       160
       +
       with other kernel modules.

     

       161
       161
       +
       

     

       162
       162
       +
       ## Proprietary AMD drivers {#sec-x11--graphics-cards-amd .unnumbered}

     

       163
       163
       +
       

     

       164
       164
       +
       AMD provides a proprietary driver for its graphics cards that is not

     

       165
       165
       +
       enabled by default because it's not Free Software, is often broken in

     

       166
       166
       +
       nixpkgs and as of this writing doesn\'t offer more features or

     

       167
       167
       +
       performance. If you still want to use it anyway, you need to explicitly

     

       168
       168
       +
       set:

     

       169
       169
       +
       

     

       170
       170
       +
       ```nix

     

       171
       171
       +
       services.xserver.videoDrivers = [ "amdgpu-pro" ];

     

       172
       172
       +
       ```

     

       173
       173
       +
       

     

       174
       174
       +
       You will need to reboot after enabling this driver to prevent a clash

     

       175
       175
       +
       with other kernel modules.

     

       176
       176
       +
       

     

       177
       177
       +
       ## Touchpads {#sec-x11-touchpads .unnumbered}

     

       178
       178
       +
       

     

       179
       179
       +
       Support for Synaptics touchpads (found in many laptops such as the Dell

     

       180
       180
       +
       Latitude series) can be enabled as follows:

     

       181
       181
       +
       

     

       182
       182
       +
       ```nix

     

       183
       183
       +
       services.xserver.libinput.enable = true;

     

       184
       184
       +
       ```

     

       185
       185
       +
       

     

       186
       186
       +
       The driver has many options (see [](#ch-options)).

     

       187
       187
       +
       For instance, the following disables tap-to-click behavior:

     

       188
       188
       +
       

     

       189
       189
       +
       ```nix

     

       190
       190
       +
       services.xserver.libinput.touchpad.tapping = false;

     

       191
       191
       +
       ```

     

       192
       192
       +
       

     

       193
       193
       +
       Note: the use of `services.xserver.synaptics` is deprecated since NixOS

     

       194
       194
       +
       17.09.

     

       195
       195
       +
       

     

       196
       196
       +
       ## GTK/Qt themes {#sec-x11-gtk-and-qt-themes .unnumbered}

     

       197
       197
       +
       

     

       198
       198
       +
       GTK themes can be installed either to user profile or system-wide (via

     

       199
       199
       +
       `environment.systemPackages`). To make Qt 5 applications look similar to

     

       200
       200
       +
       GTK ones, you can use the following configuration:

     

       201
       201
       +
       

     

       202
       202
       +
       ```nix

     

       203
       203
       +
       qt5.enable = true;

     

       204
       204
       +
       qt5.platformTheme = "gtk2";

     

       205
       205
       +
       qt5.style = "gtk2";

     

       206
       206
       +
       ```

     

       207
       207
       +
       

     

       208
       208
       +
       ## Custom XKB layouts {#custom-xkb-layouts .unnumbered}

     

       209
       209
       +
       

     

       210
       210
       +
       It is possible to install custom [ XKB

     

       211
       211
       +
       ](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts

     

       212
       212
       +
       using the option `services.xserver.extraLayouts`.

     

       213
       213
       +
       

     

       214
       214
       +
       As a first example, we are going to create a layout based on the basic

     

       215
       215
       +
       US layout, with an additional layer to type some greek symbols by

     

       216
       216
       +
       pressing the right-alt key.

     

       217
       217
       +
       

     

       218
       218
       +
       Create a file called `us-greek` with the following content (under a

     

       219
       219
       +
       directory called `symbols`; it\'s an XKB peculiarity that will help with

     

       220
       220
       +
       testing):

     

       221
       221
       +
       

     

       222
       222
       +
       ```nix

     

       223
       223
       +
       xkb_symbols "us-greek"

     

       224
       224
       +
       {

     

       225
       225
       +
         include "us(basic)"            // includes the base US keys

     

       226
       226
       +
         include "level3(ralt_switch)"  // configures right alt as a third level switch

     

       227
       227
       +
       

     

       228
       228
       +
         key <LatA> { [ a, A, Greek_alpha ] };

     

       229
       229
       +
         key <LatB> { [ b, B, Greek_beta  ] };

     

       230
       230
       +
         key <LatG> { [ g, G, Greek_gamma ] };

     

       231
       231
       +
         key <LatD> { [ d, D, Greek_delta ] };

     

       232
       232
       +
         key <LatZ> { [ z, Z, Greek_zeta  ] };

     

       233
       233
       +
       };

     

       234
       234
       +
       ```

     

       235
       235
       +
       

     

       236
       236
       +
       A minimal layout specification must include the following:

     

       237
       237
       +
       

     

       238
       238
       +
       ```nix

     

       239
       239
       +
       services.xserver.extraLayouts.us-greek = {

     

       240
       240
       +
         description = "US layout with alt-gr greek";

     

       241
       241
       +
         languages   = [ "eng" ];

     

       242
       242
       +
         symbolsFile = /yourpath/symbols/us-greek;

     

       243
       243
       +
       };

     

       244
       244
       +
       ```

     

       245
       245
       +
       

     

       246
       246
       +
       ::: {.note}

     

       247
       247
       +
       The name (after `extraLayouts.`) should match the one given to the

     

       248
       248
       +
       `xkb_symbols` block.

     

       249
       249
       +
       :::

     

       250
       250
       +
       

     

       251
       251
       +
       Applying this customization requires rebuilding several packages, and a

     

       252
       252
       +
       broken XKB file can lead to the X session crashing at login. Therefore,

     

       253
       253
       +
       you\'re strongly advised to **test your layout before applying it**:

     

       254
       254
       +
       

     

       255
       255
       +
       ```ShellSession

     

       256
       256
       +
       $ nix-shell -p xorg.xkbcomp

     

       257
       257
       +
       $ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY

     

       258
       258
       +
       ```

     

       259
       259
       +
       

     

       260
       260
       +
       You can inspect the predefined XKB files for examples:

     

       261
       261
       +
       

     

       262
       262
       +
       ```ShellSession

     

       263
       263
       +
       $ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"

     

       264
       264
       +
       ```

     

       265
       265
       +
       

     

       266
       266
       +
       Once the configuration is applied, and you did a logout/login cycle, the

     

       267
       267
       +
       layout should be ready to use. You can try it by e.g. running

     

       268
       268
       +
       `setxkbmap us-greek` and then type `<alt>+a` (it may not get applied in

     

       269
       269
       +
       your terminal straight away). To change the default, the usual

     

       270
       270
       +
       `services.xserver.layout` option can still be used.

     

       271
       271
       +
       

     

       272
       272
       +
       A layout can have several other components besides `xkb_symbols`, for

     

       273
       273
       +
       example we will define new keycodes for some multimedia key and bind

     

       274
       274
       +
       these to some symbol.

     

       275
       275
       +
       

     

       276
       276
       +
       Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys

     

       277
       277
       +
       of interest, then create a `media-key` file to hold the keycodes

     

       278
       278
       +
       definitions

     

       279
       279
       +
       

     

       280
       280
       +
       ```nix

     

       281
       281
       +
       xkb_keycodes "media"

     

       282
       282
       +
       {

     

       283
       283
       +
        <volUp>   = 123;

     

       284
       284
       +
        <volDown> = 456;

     

       285
       285
       +
       }

     

       286
       286
       +
       ```

     

       287
       287
       +
       

     

       288
       288
       +
       Now use the newly define keycodes in `media-sym`:

     

       289
       289
       +
       

     

       290
       290
       +
       ```nix

     

       291
       291
       +
       xkb_symbols "media"

     

       292
       292
       +
       {

     

       293
       293
       +
        key.type = "ONE_LEVEL";

     

       294
       294
       +
        key <volUp>   { [ XF86AudioLowerVolume ] };

     

       295
       295
       +
        key <volDown> { [ XF86AudioRaiseVolume ] };

     

       296
       296
       +
       }

     

       297
       297
       +
       ```

     

       298
       298
       +
       

     

       299
       299
       +
       As before, to install the layout do

     

       300
       300
       +
       

     

       301
       301
       +
       ```nix

     

       302
       302
       +
       services.xserver.extraLayouts.media = {

     

       303
       303
       +
         description  = "Multimedia keys remapping";

     

       304
       304
       +
         languages    = [ "eng" ];

     

       305
       305
       +
         symbolsFile  = /path/to/media-key;

     

       306
       306
       +
         keycodesFile = /path/to/media-sym;

     

       307
       307
       +
       };

     

       308
       308
       +
       ```

     

       309
       309
       +
       

     

       310
       310
       +
       ::: {.note}

     

       311
       311
       +
       The function `pkgs.writeText <filename> <content>` can be useful if you

     

       312
       312
       +
       prefer to keep the layout definitions inside the NixOS configuration.

     

       313
       313
       +
       :::

     

       314
       314
       +
       

     

       315
       315
       +
       Unfortunately, the Xorg server does not (currently) support setting a

     

       316
       316
       +
       keymap directly but relies instead on XKB rules to select the matching

     

       317
       317
       +
       components (keycodes, types, \...) of a layout. This means that

     

       318
       318
       +
       components other than symbols won\'t be loaded by default. As a

     

       319
       319
       +
       workaround, you can set the keymap using `setxkbmap` at the start of the

     

       320
       320
       +
       session with:

     

       321
       321
       +
       

     

       322
       322
       +
       ```nix

     

       323
       323
       +
       services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";

     

       324
       324
       +
       ```

     

       325
       325
       +
       

     

       326
       326
       +
       If you are manually starting the X server, you should set the argument

     

       327
       327
       +
       `-xkbdir /etc/X11/xkb`, otherwise X won\'t find your layout files. For

     

       328
       328
       +
       example with `xinit` run

     

       329
       329
       +
       

     

       330
       330
       +
       ```ShellSession

     

       331
       331
       +
       $ xinit -- -xkbdir /etc/X11/xkb

     

       332
       332
       +
       ```

     

       333
       333
       +
       

     

       334
       334
       +
       To learn how to write layouts take a look at the XKB [documentation

     

       335
       335
       +
       ](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts).

     

       336
       336
       +
       More example layouts can also be found [here

     

       337
       337
       +
       ](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples).

-355

nixos/doc/manual/configuration/x-windows.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-x11">

     

       6
       6
       -
        <title>X Window System</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         The X Window System (X11) provides the basis of NixOS’ graphical user

     

       9
       9
       -
         interface. It can be enabled as follows:

     

       10
       10
       -
       <programlisting>

     

       11
       11
       -
       <xref linkend="opt-services.xserver.enable"/> = true;

     

       12
       12
       -
       </programlisting>

     

       13
       13
       -
         The X server will automatically detect and use the appropriate video driver

     

       14
       14
       -
         from a set of X.org drivers (such as <literal>vesa</literal> and

     

       15
       15
       -
         <literal>intel</literal>). You can also specify a driver manually, e.g.

     

       16
       16
       -
       <programlisting>

     

       17
       17
       -
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ];

     

       18
       18
       -
       </programlisting>

     

       19
       19
       -
         to enable X.org’s <literal>xf86-video-r128</literal> driver.

     

       20
       20
       -
        </para>

     

       21
       21
       -
        <para>

     

       22
       22
       -
         You also need to enable at least one desktop or window manager. Otherwise,

     

       23
       23
       -
         you can only log into a plain undecorated <command>xterm</command> window.

     

       24
       24
       -
         Thus you should pick one or more of the following lines:

     

       25
       25
       -
       <programlisting>

     

       26
       26
       -
       <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;

     

       27
       27
       -
       <xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true;

     

       28
       28
       -
       <xref linkend="opt-services.xserver.desktopManager.gnome.enable"/> = true;

     

       29
       29
       -
       <xref linkend="opt-services.xserver.desktopManager.mate.enable"/> = true;

     

       30
       30
       -
       <xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true;

     

       31
       31
       -
       <xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true;

     

       32
       32
       -
       <xref linkend="opt-services.xserver.windowManager.icewm.enable"/> = true;

     

       33
       33
       -
       <xref linkend="opt-services.xserver.windowManager.i3.enable"/> = true;

     

       34
       34
       -
       <xref linkend="opt-services.xserver.windowManager.herbstluftwm.enable"/> = true;

     

       35
       35
       -
       </programlisting>

     

       36
       36
       -
        </para>

     

       37
       37
       -
        <para>

     

       38
       38
       -
         NixOS’s default <emphasis>display manager</emphasis> (the program that

     

       39
       39
       -
         provides a graphical login prompt and manages the X server) is LightDM. You

     

       40
       40
       -
         can select an alternative one by picking one of the following lines:

     

       41
       41
       -
       <programlisting>

     

       42
       42
       -
       <xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;

     

       43
       43
       -
       <xref linkend="opt-services.xserver.displayManager.gdm.enable"/> = true;

     

       44
       44
       -
       </programlisting>

     

       45
       45
       -
        </para>

     

       46
       46
       -
        <para>

     

       47
       47
       -
         You can set the keyboard layout (and optionally the layout variant):

     

       48
       48
       -
       <programlisting>

     

       49
       49
       -
       <xref linkend="opt-services.xserver.layout"/> = "de";

     

       50
       50
       -
       <xref linkend="opt-services.xserver.xkbVariant"/> = "neo";

     

       51
       51
       -
       </programlisting>

     

       52
       52
       -
        </para>

     

       53
       53
       -
        <para>

     

       54
       54
       -
         The X server is started automatically at boot time. If you don’t want this

     

       55
       55
       -
         to happen, you can set:

     

       56
       56
       -
       <programlisting>

     

       57
       57
       -
       <xref linkend="opt-services.xserver.autorun"/> = false;

     

       58
       58
       -
       </programlisting>

     

       59
       59
       -
         The X server can then be started manually:

     

       60
       60
       -
       <screen>

     

       61
       61
       -
       <prompt># </prompt>systemctl start display-manager.service

     

       62
       62
       -
       </screen>

     

       63
       63
       -
        </para>

     

       64
       64
       -
        <para>

     

       65
       65
       -
         On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine,

     

       66
       66
       -
         you should also set the following:

     

       67
       67
       -
       <programlisting>

     

       68
       68
       -
       <xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true;

     

       69
       69
       -
       </programlisting>

     

       70
       70
       -
        </para>

     

       71
       71
       -
        <simplesect xml:id="sec-x11-auto-login">

     

       72
       72
       -
         <title>Auto-login</title>

     

       73
       73
       -
         <para>

     

       74
       74
       -
         The x11 login screen can be skipped entirely, automatically logging you into

     

       75
       75
       -
         your window manager and desktop environment when you boot your computer.

     

       76
       76
       -
         </para>

     

       77
       77
       -
         <para>

     

       78
       78
       -
         This is especially helpful if you have disk encryption enabled. Since you

     

       79
       79
       -
         already have to provide a password to decrypt your disk, entering a second

     

       80
       80
       -
         password to login can be redundant.

     

       81
       81
       -
         </para>

     

       82
       82
       -
         <para>

     

       83
       83
       -
         To enable auto-login, you need to define your default window manager and

     

       84
       84
       -
         desktop environment. If you wanted no desktop environment and i3 as your your

     

       85
       85
       -
         window manager, you'd define:

     

       86
       86
       -
       <programlisting>

     

       87
       87
       -
       <xref linkend="opt-services.xserver.displayManager.defaultSession"/> = "none+i3";

     

       88
       88
       -
       </programlisting>

     

       89
       89
       -
         Every display manager in NixOS supports auto-login, here is an example

     

       90
       90
       -
         using lightdm for a user <literal>alice</literal>:

     

       91
       91
       -
       <programlisting>

     

       92
       92
       -
       <xref linkend="opt-services.xserver.displayManager.lightdm.enable"/> = true;

     

       93
       93
       -
       <xref linkend="opt-services.xserver.displayManager.autoLogin.enable"/> = true;

     

       94
       94
       -
       <xref linkend="opt-services.xserver.displayManager.autoLogin.user"/> = "alice";

     

       95
       95
       -
       </programlisting>

     

       96
       96
       -
         </para>

     

       97
       97
       -
        </simplesect>

     

       98
       98
       -
        <simplesect xml:id="sec-x11--graphics-cards-intel">

     

       99
       99
       -
         <title>Intel Graphics drivers</title>

     

       100
       100
       -
         <para>

     

       101
       101
       -
          There are two choices for Intel Graphics drivers in X.org:

     

       102
       102
       -
          <literal>modesetting</literal> (included in the <package>xorg-server</package> itself)

     

       103
       103
       -
          and <literal>intel</literal> (provided by the package <package>xf86-video-intel</package>).

     

       104
       104
       -
         </para>

     

       105
       105
       -
         <para>

     

       106
       106
       -
          The default and recommended is <literal>modesetting</literal>.

     

       107
       107
       -
          It is a generic driver which uses the kernel

     

       108
       108
       -
          <link xlink:href="https://en.wikipedia.org/wiki/Mode_setting">mode setting</link>

     

       109
       109
       -
          (KMS) mechanism. It supports Glamor (2D graphics acceleration via OpenGL)

     

       110
       110
       -
          and is actively maintained but may perform worse in some cases (like in old chipsets).

     

       111
       111
       -
         </para>

     

       112
       112
       -
         <para>

     

       113
       113
       -
          The second driver, <literal>intel</literal>, is specific to Intel GPUs,

     

       114
       114
       -
          but not recommended by most distributions: it lacks several modern features

     

       115
       115
       -
          (for example, it doesn't support Glamor) and the package hasn't been officially

     

       116
       116
       -
          updated since 2015.

     

       117
       117
       -
         </para>

     

       118
       118
       -
         <para>

     

       119
       119
       -
          The results vary depending on the hardware, so you may have to try both drivers.

     

       120
       120
       -
          Use the option <xref linkend="opt-services.xserver.videoDrivers"/> to set one.

     

       121
       121
       -
          The recommended configuration for modern systems is:

     

       122
       122
       -
       <programlisting>

     

       123
       123
       -
         <xref linkend="opt-services.xserver.videoDrivers"/> = [ "modesetting" ];

     

       124
       124
       -
         <xref linkend="opt-services.xserver.useGlamor"/> = true;

     

       125
       125
       -
       </programlisting>

     

       126
       126
       -
          If you experience screen tearing no matter what, this configuration was

     

       127
       127
       -
          reported to resolve the issue:

     

       128
       128
       -
       <programlisting>

     

       129
       129
       -
         <xref linkend="opt-services.xserver.videoDrivers"/> = [ "intel" ];

     

       130
       130
       -
         <xref linkend="opt-services.xserver.deviceSection"/> = ''

     

       131
       131
       -
           Option "DRI" "2"

     

       132
       132
       -
           Option "TearFree" "true"

     

       133
       133
       -
         '';

     

       134
       134
       -
       </programlisting>

     

       135
       135
       -
          Note that this will likely downgrade the performance compared to

     

       136
       136
       -
         <literal>modesetting</literal> or <literal>intel</literal> with DRI 3 (default).

     

       137
       137
       -
         </para>

     

       138
       138
       -
        </simplesect>

     

       139
       139
       -
        <simplesect xml:id="sec-x11-graphics-cards-nvidia">

     

       140
       140
       -
         <title>Proprietary NVIDIA drivers</title>

     

       141
       141
       -
         <para>

     

       142
       142
       -
          NVIDIA provides a proprietary driver for its graphics cards that has better

     

       143
       143
       -
          3D performance than the X.org drivers. It is not enabled by default because

     

       144
       144
       -
          it’s not free software. You can enable it as follows:

     

       145
       145
       -
       <programlisting>

     

       146
       146
       -
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ];

     

       147
       147
       -
       </programlisting>

     

       148
       148
       -
          Or if you have an older card, you may have to use one of the legacy drivers:

     

       149
       149
       -
       <programlisting>

     

       150
       150
       -
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy390" ];

     

       151
       151
       -
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ];

     

       152
       152
       -
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ];

     

       153
       153
       -
       </programlisting>

     

       154
       154
       -
          You may need to reboot after enabling this driver to prevent a clash with

     

       155
       155
       -
          other kernel modules.

     

       156
       156
       -
         </para>

     

       157
       157
       -
        </simplesect>

     

       158
       158
       -
        <simplesect xml:id="sec-x11--graphics-cards-amd">

     

       159
       159
       -
         <title>Proprietary AMD drivers</title>

     

       160
       160
       -
         <para>

     

       161
       161
       -
          AMD provides a proprietary driver for its graphics cards that is not

     

       162
       162
       -
          enabled by default because it’s not Free Software, is often broken

     

       163
       163
       -
          in nixpkgs and as of this writing doesn't offer more features or

     

       164
       164
       -
          performance. If you still want to use it anyway, you need to explicitly set:

     

       165
       165
       -
       <programlisting>

     

       166
       166
       -
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "amdgpu-pro" ];

     

       167
       167
       -
       </programlisting>

     

       168
       168
       -
          You will need to reboot after enabling this driver to prevent a clash with

     

       169
       169
       -
          other kernel modules.

     

       170
       170
       -
         </para>

     

       171
       171
       -
        </simplesect>

     

       172
       172
       -
        <simplesect xml:id="sec-x11-touchpads">

     

       173
       173
       -
         <title>Touchpads</title>

     

       174
       174
       -
         <para>

     

       175
       175
       -
          Support for Synaptics touchpads (found in many laptops such as the Dell

     

       176
       176
       -
          Latitude series) can be enabled as follows:

     

       177
       177
       -
       <programlisting>

     

       178
       178
       -
       <xref linkend="opt-services.xserver.libinput.enable"/> = true;

     

       179
       179
       -
       </programlisting>

     

       180
       180
       -
          The driver has many options (see <xref linkend="ch-options"/>). For

     

       181
       181
       -
          instance, the following disables tap-to-click behavior:

     

       182
       182
       -
       <programlisting>

     

       183
       183
       -
       <xref linkend="opt-services.xserver.libinput.touchpad.tapping"/> = false;

     

       184
       184
       -
       </programlisting>

     

       185
       185
       -
          Note: the use of <literal>services.xserver.synaptics</literal> is deprecated

     

       186
       186
       -
          since NixOS 17.09.

     

       187
       187
       -
         </para>

     

       188
       188
       -
        </simplesect>

     

       189
       189
       -
        <simplesect xml:id="sec-x11-gtk-and-qt-themes">

     

       190
       190
       -
         <title>GTK/Qt themes</title>

     

       191
       191
       -
         <para>

     

       192
       192
       -
          GTK themes can be installed either to user profile or system-wide (via

     

       193
       193
       -
          <literal>environment.systemPackages</literal>). To make Qt 5 applications

     

       194
       194
       -
          look similar to GTK ones, you can use the following configuration:

     

       195
       195
       -
       <programlisting>

     

       196
       196
       -
       <xref linkend="opt-qt5.enable"/> = true;

     

       197
       197
       -
       <xref linkend="opt-qt5.platformTheme"/> = "gtk2";

     

       198
       198
       -
       <xref linkend="opt-qt5.style"/> = "gtk2";

     

       199
       199
       -
       </programlisting>

     

       200
       200
       -
         </para>

     

       201
       201
       -
        </simplesect>

     

       202
       202
       -
        <simplesect xml:id="custom-xkb-layouts">

     

       203
       203
       -
         <title>Custom XKB layouts</title>

     

       204
       204
       -
         <para>

     

       205
       205
       -
          It is possible to install custom

     

       206
       206
       -
          <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">

     

       207
       207
       -
           XKB

     

       208
       208
       -
          </link>

     

       209
       209
       -
          keyboard layouts using the option

     

       210
       210
       -
          <option><link linkend="opt-services.xserver.extraLayouts">

     

       211
       211
       -
            services.xserver.extraLayouts</link></option>.

     

       212
       212
       -
         </para>

     

       213
       213
       -
         <para>

     

       214
       214
       -
          As a first example, we are going to create a layout based on the basic US

     

       215
       215
       -
          layout, with an additional layer to type some greek symbols by pressing the

     

       216
       216
       -
          right-alt key.

     

       217
       217
       -
         </para>

     

       218
       218
       -
         <para>

     

       219
       219
       -
          Create a file called <literal>us-greek</literal> with the following

     

       220
       220
       -
          content (under a directory called <literal>symbols</literal>; it's

     

       221
       221
       -
          an XKB peculiarity that will help with testing):

     

       222
       222
       -
         </para>

     

       223
       223
       -
       <programlisting>

     

       224
       224
       -
       xkb_symbols &quot;us-greek&quot;

     

       225
       225
       -
       {

     

       226
       226
       -
         include &quot;us(basic)&quot;            // includes the base US keys

     

       227
       227
       -
         include &quot;level3(ralt_switch)&quot;  // configures right alt as a third level switch

     

       228
       228
       -
       

     

       229
       229
       -
         key &lt;LatA&gt; { [ a, A, Greek_alpha ] };

     

       230
       230
       -
         key &lt;LatB&gt; { [ b, B, Greek_beta  ] };

     

       231
       231
       -
         key &lt;LatG&gt; { [ g, G, Greek_gamma ] };

     

       232
       232
       -
         key &lt;LatD&gt; { [ d, D, Greek_delta ] };

     

       233
       233
       -
         key &lt;LatZ&gt; { [ z, Z, Greek_zeta  ] };

     

       234
       234
       -
       };

     

       235
       235
       -
       </programlisting>

     

       236
       236
       -
         <para>

     

       237
       237
       -
          A minimal layout specification must include the following:

     

       238
       238
       -
         </para>

     

       239
       239
       -
       <programlisting>

     

       240
       240
       -
       <xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = {

     

       241
       241
       -
         description = "US layout with alt-gr greek";

     

       242
       242
       -
         languages   = [ "eng" ];

     

       243
       243
       -
         symbolsFile = /yourpath/symbols/us-greek;

     

       244
       244
       -
       };

     

       245
       245
       -
       </programlisting>

     

       246
       246
       -
         <note>

     

       247
       247
       -
         <para>

     

       248
       248
       -
          The name (after <literal>extraLayouts.</literal>) should match the one given to the

     

       249
       249
       -
          <literal>xkb_symbols</literal> block.

     

       250
       250
       -
         </para>

     

       251
       251
       -
         </note>

     

       252
       252
       -
         <para>

     

       253
       253
       -
          Applying this customization requires rebuilding several packages,

     

       254
       254
       -
          and a broken XKB file can lead to the X session crashing at login.

     

       255
       255
       -
          Therefore, you're strongly advised to <emphasis role="strong">test

     

       256
       256
       -
          your layout before applying it</emphasis>:

     

       257
       257
       -
       <screen>

     

       258
       258
       -
       <prompt>$ </prompt>nix-shell -p xorg.xkbcomp

     

       259
       259
       -
       <prompt>$ </prompt>setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY

     

       260
       260
       -
       </screen>

     

       261
       261
       -
         </para>

     

       262
       262
       -
         <para>

     

       263
       263
       -
          You can inspect the predefined XKB files for examples:

     

       264
       264
       -
       <screen>

     

       265
       265
       -
       <prompt>$ </prompt>echo "$(nix-build --no-out-link '&lt;nixpkgs&gt;' -A xorg.xkeyboardconfig)/etc/X11/xkb/"

     

       266
       266
       -
       </screen>

     

       267
       267
       -
         </para>

     

       268
       268
       -
         <para>

     

       269
       269
       -
          Once the configuration is applied, and you did a logout/login

     

       270
       270
       -
          cycle, the layout should be ready to use. You can try it by e.g.

     

       271
       271
       -
          running <literal>setxkbmap us-greek</literal> and then type

     

       272
       272
       -
          <literal>&lt;alt&gt;+a</literal> (it may not get applied in your

     

       273
       273
       -
          terminal straight away). To change the default, the usual

     

       274
       274
       -
          <option>

     

       275
       275
       -
           <link linkend="opt-services.xserver.layout">

     

       276
       276
       -
            services.xserver.layout

     

       277
       277
       -
           </link>

     

       278
       278
       -
          </option>

     

       279
       279
       -
          option can still be used.

     

       280
       280
       -
         </para>

     

       281
       281
       -
         <para>

     

       282
       282
       -
          A layout can have several other components besides

     

       283
       283
       -
          <literal>xkb_symbols</literal>, for example we will define new

     

       284
       284
       -
          keycodes for some multimedia key and bind these to some symbol.

     

       285
       285
       -
         </para>

     

       286
       286
       -
         <para>

     

       287
       287
       -
          Use the <emphasis>xev</emphasis> utility from

     

       288
       288
       -
          <literal>pkgs.xorg.xev</literal> to find the codes of the keys of

     

       289
       289
       -
          interest, then create a <literal>media-key</literal> file to hold

     

       290
       290
       -
          the keycodes definitions

     

       291
       291
       -
         </para>

     

       292
       292
       -
       <programlisting>

     

       293
       293
       -
       xkb_keycodes &quot;media&quot;

     

       294
       294
       -
       {

     

       295
       295
       -
        &lt;volUp&gt;   = 123;

     

       296
       296
       -
        &lt;volDown&gt; = 456;

     

       297
       297
       -
       }

     

       298
       298
       -
       </programlisting>

     

       299
       299
       -
         <para>

     

       300
       300
       -
           Now use the newly define keycodes in <literal>media-sym</literal>:

     

       301
       301
       -
         </para>

     

       302
       302
       -
       <programlisting>

     

       303
       303
       -
       xkb_symbols &quot;media&quot;

     

       304
       304
       -
       {

     

       305
       305
       -
        key.type = &quot;ONE_LEVEL&quot;;

     

       306
       306
       -
        key &lt;volUp&gt;   { [ XF86AudioLowerVolume ] };

     

       307
       307
       -
        key &lt;volDown&gt; { [ XF86AudioRaiseVolume ] };

     

       308
       308
       -
       }

     

       309
       309
       -
       </programlisting>

     

       310
       310
       -
         <para>

     

       311
       311
       -
           As before, to install the layout do

     

       312
       312
       -
         </para>

     

       313
       313
       -
       <programlisting>

     

       314
       314
       -
       <xref linkend="opt-services.xserver.extraLayouts"/>.media = {

     

       315
       315
       -
         description  = "Multimedia keys remapping";

     

       316
       316
       -
         languages    = [ "eng" ];

     

       317
       317
       -
         symbolsFile  = /path/to/media-key;

     

       318
       318
       -
         keycodesFile = /path/to/media-sym;

     

       319
       319
       -
       };

     

       320
       320
       -
       </programlisting>

     

       321
       321
       -
         <note>

     

       322
       322
       -
         <para>

     

       323
       323
       -
          The function <literal>pkgs.writeText &lt;filename&gt; &lt;content&gt;

     

       324
       324
       -
          </literal> can be useful if you prefer to keep the layout definitions

     

       325
       325
       -
          inside the NixOS configuration.

     

       326
       326
       -
         </para>

     

       327
       327
       -
         </note>

     

       328
       328
       -
         <para>

     

       329
       329
       -
           Unfortunately, the Xorg server does not (currently) support setting a

     

       330
       330
       -
           keymap directly but relies instead on XKB rules to select the matching

     

       331
       331
       -
           components (keycodes, types, ...) of a layout. This means that components

     

       332
       332
       -
           other than symbols won't be loaded by default. As a workaround, you

     

       333
       333
       -
           can set the keymap using <literal>setxkbmap</literal> at the start of the

     

       334
       334
       -
           session with:

     

       335
       335
       -
         </para>

     

       336
       336
       -
       <programlisting>

     

       337
       337
       -
       <xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media";

     

       338
       338
       -
       </programlisting>

     

       339
       339
       -
         <para>

     

       340
       340
       -
           If you are manually starting the X server, you should set the argument

     

       341
       341
       -
           <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X won't find your layout files.

     

       342
       342
       -
           For example with <command>xinit</command> run

     

       343
       343
       -
           <screen><prompt>$ </prompt>xinit -- -xkbdir /etc/X11/xkb</screen>

     

       344
       344
       -
         </para>

     

       345
       345
       -
         <para>

     

       346
       346
       -
          To learn how to write layouts take a look at the XKB

     

       347
       347
       -
         <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">

     

       348
       348
       -
          documentation

     

       349
       349
       -
         </link>. More example layouts can also be found

     

       350
       350
       -
         <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">

     

       351
       351
       -
          here

     

       352
       352
       -
         </link>.

     

       353
       353
       -
         </para>

     

       354
       354
       -
       </simplesect>

     

       355
       355
       -
       </chapter>

+52

nixos/doc/manual/configuration/xfce.chapter.md

···

       1
       1
       +
       # Xfce Desktop Environment {#sec-xfce}

     

       2
       2
       +
       

     

       3
       3
       +
       To enable the Xfce Desktop Environment, set

     

       4
       4
       +
       

     

       5
       5
       +
       ```nix

     

       6
       6
       +
       services.xserver.desktopManager.xfce.enable = true;

     

       7
       7
       +
       services.xserver.displayManager.defaultSession = "xfce";

     

       8
       8
       +
       ```

     

       9
       9
       +
       

     

       10
       10
       +
       Optionally, *picom* can be enabled for nice graphical effects, some

     

       11
       11
       +
       example settings:

     

       12
       12
       +
       

     

       13
       13
       +
       ```nix

     

       14
       14
       +
       services.picom = {

     

       15
       15
       +
         enable = true;

     

       16
       16
       +
         fade = true;

     

       17
       17
       +
         inactiveOpacity = 0.9;

     

       18
       18
       +
         shadow = true;

     

       19
       19
       +
         fadeDelta = 4;

     

       20
       20
       +
       };

     

       21
       21
       +
       ```

     

       22
       22
       +
       

     

       23
       23
       +
       Some Xfce programs are not installed automatically. To install them

     

       24
       24
       +
       manually (system wide), put them into your

     

       25
       25
       +
       [](#opt-environment.systemPackages) from `pkgs.xfce`.

     

       26
       26
       +
       

     

       27
       27
       +
       ## Thunar Plugins {#sec-xfce-thunar-plugins .unnumbered}

     

       28
       28
       +
       

     

       29
       29
       +
       If you\'d like to add extra plugins to Thunar, add them to

     

       30
       30
       +
       [](#opt-services.xserver.desktopManager.xfce.thunarPlugins).

     

       31
       31
       +
       You shouldn\'t just add them to [](#opt-environment.systemPackages).

     

       32
       32
       +
       

     

       33
       33
       +
       ## Troubleshooting {#sec-xfce-troubleshooting .unnumbered}

     

       34
       34
       +
       

     

       35
       35
       +
       Even after enabling udisks2, volume management might not work. Thunar

     

       36
       36
       +
       and/or the desktop takes time to show up. Thunar will spit out this kind

     

       37
       37
       +
       of message on start (look at `journalctl --user -b`).

     

       38
       38
       +
       

     

       39
       39
       +
       ```plain

     

       40
       40
       +
       Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported

     

       41
       41
       +
       ```

     

       42
       42
       +
       

     

       43
       43
       +
       This is caused by some needed GNOME services not running. This is all

     

       44
       44
       +
       fixed by enabling \"Launch GNOME services on startup\" in the Advanced

     

       45
       45
       +
       tab of the Session and Startup settings panel. Alternatively, you can

     

       46
       46
       +
       run this command to do the same thing.

     

       47
       47
       +
       

     

       48
       48
       +
       ```ShellSession

     

       49
       49
       +
       $ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true

     

       50
       50
       +
       ```

     

       51
       51
       +
       

     

       52
       52
       +
       A log-out and re-log will be needed for this to take effect.

-59

nixos/doc/manual/configuration/xfce.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-xfce">

     

       6
       6
       -
        <title>Xfce Desktop Environment</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         To enable the Xfce Desktop Environment, set

     

       9
       9
       -
       <programlisting>

     

       10
       10
       -
       <xref linkend="opt-services.xserver.desktopManager.xfce.enable" /> = true;

     

       11
       11
       -
       <xref linkend="opt-services.xserver.displayManager.defaultSession" /> = "xfce";

     

       12
       12
       -
       </programlisting>

     

       13
       13
       -
        </para>

     

       14
       14
       -
        <para>

     

       15
       15
       -
         Optionally, <emphasis>picom</emphasis> can be enabled for nice graphical

     

       16
       16
       -
         effects, some example settings:

     

       17
       17
       -
       <programlisting>

     

       18
       18
       -
       <link linkend="opt-services.picom.enable">services.picom</link> = {

     

       19
       19
       -
         <link linkend="opt-services.picom.enable">enable</link> = true;

     

       20
       20
       -
         <link linkend="opt-services.picom.fade">fade</link> = true;

     

       21
       21
       -
         <link linkend="opt-services.picom.inactiveOpacity">inactiveOpacity</link> = 0.9;

     

       22
       22
       -
         <link linkend="opt-services.picom.shadow">shadow</link> = true;

     

       23
       23
       -
         <link linkend="opt-services.picom.fadeDelta">fadeDelta</link> = 4;

     

       24
       24
       -
       };

     

       25
       25
       -
       </programlisting>

     

       26
       26
       -
        </para>

     

       27
       27
       -
        <para>

     

       28
       28
       -
         Some Xfce programs are not installed automatically. To install them manually

     

       29
       29
       -
         (system wide), put them into your

     

       30
       30
       -
         <xref linkend="opt-environment.systemPackages"/> from <literal>pkgs.xfce</literal>.

     

       31
       31
       -
        </para>

     

       32
       32
       -
        <simplesect xml:id="sec-xfce-thunar-plugins">

     

       33
       33
       -
         <title>Thunar Plugins</title>

     

       34
       34
       -
         <para>

     

       35
       35
       -
           If you'd like to add extra plugins to Thunar, add them to

     

       36
       36
       -
           <xref linkend="opt-services.xserver.desktopManager.xfce.thunarPlugins"/>.

     

       37
       37
       -
           You shouldn't just add them to <xref linkend="opt-environment.systemPackages"/>.

     

       38
       38
       -
         </para>

     

       39
       39
       -
        </simplesect>

     

       40
       40
       -
        <simplesect xml:id="sec-xfce-troubleshooting">

     

       41
       41
       -
         <title>Troubleshooting</title>

     

       42
       42
       -
         <para>

     

       43
       43
       -
          Even after enabling udisks2, volume management might not work. Thunar and/or

     

       44
       44
       -
          the desktop takes time to show up. Thunar will spit out this kind of message

     

       45
       45
       -
          on start (look at <command>journalctl --user -b</command>).

     

       46
       46
       -
       <programlisting>

     

       47
       47
       -
       Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported

     

       48
       48
       -
       </programlisting>

     

       49
       49
       -
          This is caused by some needed GNOME services not running. This is all fixed

     

       50
       50
       -
          by enabling "Launch GNOME services on startup" in the Advanced tab of the

     

       51
       51
       -
          Session and Startup settings panel. Alternatively, you can run this command

     

       52
       52
       -
          to do the same thing.

     

       53
       53
       -
       <programlisting>

     

       54
       54
       -
       <prompt>$ </prompt>xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true

     

       55
       55
       -
       </programlisting>

     

       56
       56
       -
          A log-out and re-log will be needed for this to take effect.

     

       57
       57
       -
         </para>

     

       58
       58
       -
        </simplesect>

     

       59
       59
       -
       </chapter>

+239

nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-gpu-accel">

     

       2
       2
       +
         <title>GPU acceleration</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           NixOS provides various APIs that benefit from GPU hardware

     

       5
       5
       +
           acceleration, such as VA-API and VDPAU for video playback; OpenGL

     

       6
       6
       +
           and Vulkan for 3D graphics; and OpenCL for general-purpose

     

       7
       7
       +
           computing. This chapter describes how to set up GPU hardware

     

       8
       8
       +
           acceleration (as far as this is not done automatically) and how to

     

       9
       9
       +
           verify that hardware acceleration is indeed used.

     

       10
       10
       +
         </para>

     

       11
       11
       +
         <para>

     

       12
       12
       +
           Most of the aforementioned APIs are agnostic with regards to which

     

       13
       13
       +
           display server is used. Consequently, these instructions should

     

       14
       14
       +
           apply both to the X Window System and Wayland compositors.

     

       15
       15
       +
         </para>

     

       16
       16
       +
         <section xml:id="sec-gpu-accel-opencl">

     

       17
       17
       +
           <title>OpenCL</title>

     

       18
       18
       +
           <para>

     

       19
       19
       +
             <link xlink:href="https://en.wikipedia.org/wiki/OpenCL">OpenCL</link>

     

       20
       20
       +
             is a general compute API. It is used by various applications such

     

       21
       21
       +
             as Blender and Darktable to accelerate certain operations.

     

       22
       22
       +
           </para>

     

       23
       23
       +
           <para>

     

       24
       24
       +
             OpenCL applications load drivers through the <emphasis>Installable

     

       25
       25
       +
             Client Driver</emphasis> (ICD) mechanism. In this mechanism, an

     

       26
       26
       +
             ICD file specifies the path to the OpenCL driver for a particular

     

       27
       27
       +
             GPU family. In NixOS, there are two ways to make ICD files visible

     

       28
       28
       +
             to the ICD loader. The first is through the

     

       29
       29
       +
             <literal>OCL_ICD_VENDORS</literal> environment variable. This

     

       30
       30
       +
             variable can contain a directory which is scanned by the ICL

     

       31
       31
       +
             loader for ICD files. For example:

     

       32
       32
       +
           </para>

     

       33
       33
       +
           <programlisting>

     

       34
       34
       +
       $ export \

     

       35
       35
       +
         OCL_ICD_VENDORS=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/

     

       36
       36
       +
       </programlisting>

     

       37
       37
       +
           <para>

     

       38
       38
       +
             The second mechanism is to add the OpenCL driver package to

     

       39
       39
       +
             <xref linkend="opt-hardware.opengl.extraPackages" />. This links

     

       40
       40
       +
             the ICD file under <literal>/run/opengl-driver</literal>, where it

     

       41
       41
       +
             will be visible to the ICD loader.

     

       42
       42
       +
           </para>

     

       43
       43
       +
           <para>

     

       44
       44
       +
             The proper installation of OpenCL drivers can be verified through

     

       45
       45
       +
             the <literal>clinfo</literal> command of the clinfo package. This

     

       46
       46
       +
             command will report the number of hardware devices that is found

     

       47
       47
       +
             and give detailed information for each device:

     

       48
       48
       +
           </para>

     

       49
       49
       +
           <programlisting>

     

       50
       50
       +
       $ clinfo | head -n3

     

       51
       51
       +
       Number of platforms  1

     

       52
       52
       +
       Platform Name        AMD Accelerated Parallel Processing

     

       53
       53
       +
       Platform Vendor      Advanced Micro Devices, Inc.

     

       54
       54
       +
       </programlisting>

     

       55
       55
       +
           <section xml:id="sec-gpu-accel-opencl-amd">

     

       56
       56
       +
             <title>AMD</title>

     

       57
       57
       +
             <para>

     

       58
       58
       +
               Modern AMD

     

       59
       59
       +
               <link xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics

     

       60
       60
       +
               Core Next</link> (GCN) GPUs are supported through the

     

       61
       61
       +
               rocm-opencl-icd package. Adding this package to

     

       62
       62
       +
               <xref linkend="opt-hardware.opengl.extraPackages" /> enables

     

       63
       63
       +
               OpenCL support:

     

       64
       64
       +
             </para>

     

       65
       65
       +
             <programlisting language="bash">

     

       66
       66
       +
       hardware.opengl.extraPackages = [

     

       67
       67
       +
         rocm-opencl-icd

     

       68
       68
       +
       ];

     

       69
       69
       +
       </programlisting>

     

       70
       70
       +
           </section>

     

       71
       71
       +
           <section xml:id="sec-gpu-accel-opencl-intel">

     

       72
       72
       +
             <title>Intel</title>

     

       73
       73
       +
             <para>

     

       74
       74
       +
               <link xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8">Intel

     

       75
       75
       +
               Gen8 and later GPUs</link> are supported by the Intel NEO OpenCL

     

       76
       76
       +
               runtime that is provided by the intel-compute-runtime package.

     

       77
       77
       +
               For Gen7 GPUs, the deprecated Beignet runtime can be used, which

     

       78
       78
       +
               is provided by the beignet package. The proprietary Intel OpenCL

     

       79
       79
       +
               runtime, in the intel-ocl package, is an alternative for Gen7

     

       80
       80
       +
               GPUs.

     

       81
       81
       +
             </para>

     

       82
       82
       +
             <para>

     

       83
       83
       +
               The intel-compute-runtime, beignet, or intel-ocl package can be

     

       84
       84
       +
               added to <xref linkend="opt-hardware.opengl.extraPackages" /> to

     

       85
       85
       +
               enable OpenCL support. For example, for Gen8 and later GPUs, the

     

       86
       86
       +
               following configuration can be used:

     

       87
       87
       +
             </para>

     

       88
       88
       +
             <programlisting language="bash">

     

       89
       89
       +
       hardware.opengl.extraPackages = [

     

       90
       90
       +
         intel-compute-runtime

     

       91
       91
       +
       ];

     

       92
       92
       +
       </programlisting>

     

       93
       93
       +
           </section>

     

       94
       94
       +
         </section>

     

       95
       95
       +
         <section xml:id="sec-gpu-accel-vulkan">

     

       96
       96
       +
           <title>Vulkan</title>

     

       97
       97
       +
           <para>

     

       98
       98
       +
             <link xlink:href="https://en.wikipedia.org/wiki/Vulkan_(API)">Vulkan</link>

     

       99
       99
       +
             is a graphics and compute API for GPUs. It is used directly by

     

       100
       100
       +
             games or indirectly though compatibility layers like

     

       101
       101
       +
             <link xlink:href="https://github.com/doitsujin/dxvk/wiki">DXVK</link>.

     

       102
       102
       +
           </para>

     

       103
       103
       +
           <para>

     

       104
       104
       +
             By default, if <xref linkend="opt-hardware.opengl.driSupport" />

     

       105
       105
       +
             is enabled, mesa is installed and provides Vulkan for supported

     

       106
       106
       +
             hardware.

     

       107
       107
       +
           </para>

     

       108
       108
       +
           <para>

     

       109
       109
       +
             Similar to OpenCL, Vulkan drivers are loaded through the

     

       110
       110
       +
             <emphasis>Installable Client Driver</emphasis> (ICD) mechanism.

     

       111
       111
       +
             ICD files for Vulkan are JSON files that specify the path to the

     

       112
       112
       +
             driver library and the supported Vulkan version. All successfully

     

       113
       113
       +
             loaded drivers are exposed to the application as different GPUs.

     

       114
       114
       +
             In NixOS, there are two ways to make ICD files visible to Vulkan

     

       115
       115
       +
             applications: an environment variable and a module option.

     

       116
       116
       +
           </para>

     

       117
       117
       +
           <para>

     

       118
       118
       +
             The first option is through the

     

       119
       119
       +
             <literal>VK_ICD_FILENAMES</literal> environment variable. This

     

       120
       120
       +
             variable can contain multiple JSON files, separated by

     

       121
       121
       +
             <literal>:</literal>. For example:

     

       122
       122
       +
           </para>

     

       123
       123
       +
           <programlisting>

     

       124
       124
       +
       $ export \

     

       125
       125
       +
         VK_ICD_FILENAMES=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json

     

       126
       126
       +
       </programlisting>

     

       127
       127
       +
           <para>

     

       128
       128
       +
             The second mechanism is to add the Vulkan driver package to

     

       129
       129
       +
             <xref linkend="opt-hardware.opengl.extraPackages" />. This links

     

       130
       130
       +
             the ICD file under <literal>/run/opengl-driver</literal>, where it

     

       131
       131
       +
             will be visible to the ICD loader.

     

       132
       132
       +
           </para>

     

       133
       133
       +
           <para>

     

       134
       134
       +
             The proper installation of Vulkan drivers can be verified through

     

       135
       135
       +
             the <literal>vulkaninfo</literal> command of the vulkan-tools

     

       136
       136
       +
             package. This command will report the hardware devices and drivers

     

       137
       137
       +
             found, in this example output amdvlk and radv:

     

       138
       138
       +
           </para>

     

       139
       139
       +
           <programlisting>

     

       140
       140
       +
       $ vulkaninfo | grep GPU

     

       141
       141
       +
                       GPU id  : 0 (Unknown AMD GPU)

     

       142
       142
       +
                       GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))

     

       143
       143
       +
            ...

     

       144
       144
       +
       GPU0:

     

       145
       145
       +
               deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU

     

       146
       146
       +
               deviceName     = Unknown AMD GPU

     

       147
       147
       +
       GPU1:

     

       148
       148
       +
               deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU

     

       149
       149
       +
       </programlisting>

     

       150
       150
       +
           <para>

     

       151
       151
       +
             A simple graphical application that uses Vulkan is

     

       152
       152
       +
             <literal>vkcube</literal> from the vulkan-tools package.

     

       153
       153
       +
           </para>

     

       154
       154
       +
           <section xml:id="sec-gpu-accel-vulkan-amd">

     

       155
       155
       +
             <title>AMD</title>

     

       156
       156
       +
             <para>

     

       157
       157
       +
               Modern AMD

     

       158
       158
       +
               <link xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics

     

       159
       159
       +
               Core Next</link> (GCN) GPUs are supported through either radv,

     

       160
       160
       +
               which is part of mesa, or the amdvlk package. Adding the amdvlk

     

       161
       161
       +
               package to <xref linkend="opt-hardware.opengl.extraPackages" />

     

       162
       162
       +
               makes amdvlk the default driver and hides radv and lavapipe from

     

       163
       163
       +
               the device list. A specific driver can be forced as follows:

     

       164
       164
       +
             </para>

     

       165
       165
       +
             <programlisting language="bash">

     

       166
       166
       +
       hardware.opengl.extraPackages = [

     

       167
       167
       +
         pkgs.amdvlk

     

       168
       168
       +
       ];

     

       169
       169
       +
       

     

       170
       170
       +
       # To enable Vulkan support for 32-bit applications, also add:

     

       171
       171
       +
       hardware.opengl.extraPackages32 = [

     

       172
       172
       +
         pkgs.driversi686Linux.amdvlk

     

       173
       173
       +
       ];

     

       174
       174
       +
       

     

       175
       175
       +
       # Force radv

     

       176
       176
       +
       environment.variables.AMD_VULKAN_ICD = &quot;RADV&quot;;

     

       177
       177
       +
       # Or

     

       178
       178
       +
       environment.variables.VK_ICD_FILENAMES =

     

       179
       179
       +
         &quot;/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json&quot;;

     

       180
       180
       +
       </programlisting>

     

       181
       181
       +
           </section>

     

       182
       182
       +
         </section>

     

       183
       183
       +
         <section xml:id="sec-gpu-accel-common-issues">

     

       184
       184
       +
           <title>Common issues</title>

     

       185
       185
       +
           <section xml:id="sec-gpu-accel-common-issues-permissions">

     

       186
       186
       +
             <title>User permissions</title>

     

       187
       187
       +
             <para>

     

       188
       188
       +
               Except where noted explicitly, it should not be necessary to

     

       189
       189
       +
               adjust user permissions to use these acceleration APIs. In the

     

       190
       190
       +
               default configuration, GPU devices have world-read/write

     

       191
       191
       +
               permissions (<literal>/dev/dri/renderD*</literal>) or are tagged

     

       192
       192
       +
               as <literal>uaccess</literal>

     

       193
       193
       +
               (<literal>/dev/dri/card*</literal>). The access control lists of

     

       194
       194
       +
               devices with the <literal>uaccess</literal> tag will be updated

     

       195
       195
       +
               automatically when a user logs in through

     

       196
       196
       +
               <literal>systemd-logind</literal>. For example, if the user

     

       197
       197
       +
               <emphasis>jane</emphasis> is logged in, the access control list

     

       198
       198
       +
               should look as follows:

     

       199
       199
       +
             </para>

     

       200
       200
       +
             <programlisting>

     

       201
       201
       +
       $ getfacl /dev/dri/card0

     

       202
       202
       +
       # file: dev/dri/card0

     

       203
       203
       +
       # owner: root

     

       204
       204
       +
       # group: video

     

       205
       205
       +
       user::rw-

     

       206
       206
       +
       user:jane:rw-

     

       207
       207
       +
       group::rw-

     

       208
       208
       +
       mask::rw-

     

       209
       209
       +
       other::---

     

       210
       210
       +
       </programlisting>

     

       211
       211
       +
             <para>

     

       212
       212
       +
               If you disabled (this functionality of)

     

       213
       213
       +
               <literal>systemd-logind</literal>, you may need to add the user

     

       214
       214
       +
               to the <literal>video</literal> group and log in again.

     

       215
       215
       +
             </para>

     

       216
       216
       +
           </section>

     

       217
       217
       +
           <section xml:id="sec-gpu-accel-common-issues-mixing-nixpkgs">

     

       218
       218
       +
             <title>Mixing different versions of nixpkgs</title>

     

       219
       219
       +
             <para>

     

       220
       220
       +
               The <emphasis>Installable Client Driver</emphasis> (ICD)

     

       221
       221
       +
               mechanism used by OpenCL and Vulkan loads runtimes into its

     

       222
       222
       +
               address space using <literal>dlopen</literal>. Mixing an ICD

     

       223
       223
       +
               loader mechanism and runtimes from different version of nixpkgs

     

       224
       224
       +
               may not work. For example, if the ICD loader uses an older

     

       225
       225
       +
               version of glibc than the runtime, the runtime may not be

     

       226
       226
       +
               loadable due to missing symbols. Unfortunately, the loader will

     

       227
       227
       +
               generally be quiet about such issues.

     

       228
       228
       +
             </para>

     

       229
       229
       +
             <para>

     

       230
       230
       +
               If you suspect that you are running into library version

     

       231
       231
       +
               mismatches between an ICL loader and a runtime, you could run an

     

       232
       232
       +
               application with the <literal>LD_DEBUG</literal> variable set to

     

       233
       233
       +
               get more diagnostic information. For example, OpenCL can be

     

       234
       234
       +
               tested with <literal>LD_DEBUG=files clinfo</literal>, which

     

       235
       235
       +
               should report missing symbols.

     

       236
       236
       +
             </para>

     

       237
       237
       +
           </section>

     

       238
       238
       +
         </section>

     

       239
       239
       +
       </chapter>

+126

nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-kubernetes">

     

       2
       2
       +
         <title>Kubernetes</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           The NixOS Kubernetes module is a collective term for a handful of

     

       5
       5
       +
           individual submodules implementing the Kubernetes cluster

     

       6
       6
       +
           components.

     

       7
       7
       +
         </para>

     

       8
       8
       +
         <para>

     

       9
       9
       +
           There are generally two ways of enabling Kubernetes on NixOS. One

     

       10
       10
       +
           way is to enable and configure cluster components appropriately by

     

       11
       11
       +
           hand:

     

       12
       12
       +
         </para>

     

       13
       13
       +
         <programlisting language="bash">

     

       14
       14
       +
       services.kubernetes = {

     

       15
       15
       +
         apiserver.enable = true;

     

       16
       16
       +
         controllerManager.enable = true;

     

       17
       17
       +
         scheduler.enable = true;

     

       18
       18
       +
         addonManager.enable = true;

     

       19
       19
       +
         proxy.enable = true;

     

       20
       20
       +
         flannel.enable = true;

     

       21
       21
       +
       };

     

       22
       22
       +
       </programlisting>

     

       23
       23
       +
         <para>

     

       24
       24
       +
           Another way is to assign cluster roles (&quot;master&quot; and/or

     

       25
       25
       +
           &quot;node&quot;) to the host. This enables apiserver,

     

       26
       26
       +
           controllerManager, scheduler, addonManager, kube-proxy and etcd:

     

       27
       27
       +
         </para>

     

       28
       28
       +
         <programlisting language="bash">

     

       29
       29
       +
       services.kubernetes.roles = [ &quot;master&quot; ];

     

       30
       30
       +
       </programlisting>

     

       31
       31
       +
         <para>

     

       32
       32
       +
           While this will enable the kubelet and kube-proxy only:

     

       33
       33
       +
         </para>

     

       34
       34
       +
         <programlisting language="bash">

     

       35
       35
       +
       services.kubernetes.roles = [ &quot;node&quot; ];

     

       36
       36
       +
       </programlisting>

     

       37
       37
       +
         <para>

     

       38
       38
       +
           Assigning both the master and node roles is usable if you want a

     

       39
       39
       +
           single node Kubernetes cluster for dev or testing purposes:

     

       40
       40
       +
         </para>

     

       41
       41
       +
         <programlisting language="bash">

     

       42
       42
       +
       services.kubernetes.roles = [ &quot;master&quot; &quot;node&quot; ];

     

       43
       43
       +
       </programlisting>

     

       44
       44
       +
         <para>

     

       45
       45
       +
           Note: Assigning either role will also default both

     

       46
       46
       +
           <xref linkend="opt-services.kubernetes.flannel.enable" /> and

     

       47
       47
       +
           <xref linkend="opt-services.kubernetes.easyCerts" /> to true. This

     

       48
       48
       +
           sets up flannel as CNI and activates automatic PKI bootstrapping.

     

       49
       49
       +
         </para>

     

       50
       50
       +
         <para>

     

       51
       51
       +
           As of kubernetes 1.10.X it has been deprecated to open

     

       52
       52
       +
           non-tls-enabled ports on kubernetes components. Thus, from NixOS

     

       53
       53
       +
           19.03 all plain HTTP ports have been disabled by default. While

     

       54
       54
       +
           opening insecure ports is still possible, it is recommended not to

     

       55
       55
       +
           bind these to other interfaces than loopback. To re-enable the

     

       56
       56
       +
           insecure port on the apiserver, see options:

     

       57
       57
       +
           <xref linkend="opt-services.kubernetes.apiserver.insecurePort" />

     

       58
       58
       +
           and

     

       59
       59
       +
           <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress" />

     

       60
       60
       +
         </para>

     

       61
       61
       +
         <note>

     

       62
       62
       +
           <para>

     

       63
       63
       +
             As of NixOS 19.03, it is mandatory to configure:

     

       64
       64
       +
             <xref linkend="opt-services.kubernetes.masterAddress" />. The

     

       65
       65
       +
             masterAddress must be resolveable and routeable by all cluster

     

       66
       66
       +
             nodes. In single node clusters, this can be set to

     

       67
       67
       +
             <literal>localhost</literal>.

     

       68
       68
       +
           </para>

     

       69
       69
       +
         </note>

     

       70
       70
       +
         <para>

     

       71
       71
       +
           Role-based access control (RBAC) authorization mode is enabled by

     

       72
       72
       +
           default. This means that anonymous requests to the apiserver secure

     

       73
       73
       +
           port will expectedly cause a permission denied error. All cluster

     

       74
       74
       +
           components must therefore be configured with x509 certificates for

     

       75
       75
       +
           two-way tls communication. The x509 certificate subject section

     

       76
       76
       +
           determines the roles and permissions granted by the apiserver to

     

       77
       77
       +
           perform clusterwide or namespaced operations. See also:

     

       78
       78
       +
           <link xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">

     

       79
       79
       +
           Using RBAC Authorization</link>.

     

       80
       80
       +
         </para>

     

       81
       81
       +
         <para>

     

       82
       82
       +
           The NixOS kubernetes module provides an option for automatic

     

       83
       83
       +
           certificate bootstrapping and configuration,

     

       84
       84
       +
           <xref linkend="opt-services.kubernetes.easyCerts" />. The PKI

     

       85
       85
       +
           bootstrapping process involves setting up a certificate authority

     

       86
       86
       +
           (CA) daemon (cfssl) on the kubernetes master node. cfssl generates a

     

       87
       87
       +
           CA-cert for the cluster, and uses the CA-cert for signing

     

       88
       88
       +
           subordinate certs issued to each of the cluster components.

     

       89
       89
       +
           Subsequently, the certmgr daemon monitors active certificates and

     

       90
       90
       +
           renews them when needed. For single node Kubernetes clusters,

     

       91
       91
       +
           setting <xref linkend="opt-services.kubernetes.easyCerts" /> = true

     

       92
       92
       +
           is sufficient and no further action is required. For joining extra

     

       93
       93
       +
           node machines to an existing cluster on the other hand, establishing

     

       94
       94
       +
           initial trust is mandatory.

     

       95
       95
       +
         </para>

     

       96
       96
       +
         <para>

     

       97
       97
       +
           To add new nodes to the cluster: On any (non-master) cluster node

     

       98
       98
       +
           where <xref linkend="opt-services.kubernetes.easyCerts" /> is

     

       99
       99
       +
           enabled, the helper script

     

       100
       100
       +
           <literal>nixos-kubernetes-node-join</literal> is available on PATH.

     

       101
       101
       +
           Given a token on stdin, it will copy the token to the kubernetes

     

       102
       102
       +
           secrets directory and restart the certmgr service. As requested

     

       103
       103
       +
           certificates are issued, the script will restart kubernetes cluster

     

       104
       104
       +
           components as needed for them to pick up new keypairs.

     

       105
       105
       +
         </para>

     

       106
       106
       +
         <note>

     

       107
       107
       +
           <para>

     

       108
       108
       +
             Multi-master (HA) clusters are not supported by the easyCerts

     

       109
       109
       +
             module.

     

       110
       110
       +
           </para>

     

       111
       111
       +
         </note>

     

       112
       112
       +
         <para>

     

       113
       113
       +
           In order to interact with an RBAC-enabled cluster as an

     

       114
       114
       +
           administrator, one needs to have cluster-admin privileges. By

     

       115
       115
       +
           default, when easyCerts is enabled, a cluster-admin kubeconfig file

     

       116
       116
       +
           is generated and linked into

     

       117
       117
       +
           <literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as

     

       118
       118
       +
           determined by

     

       119
       119
       +
           <xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig" />.

     

       120
       120
       +
           <literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal>

     

       121
       121
       +
           will make kubectl use this kubeconfig to access and authenticate the

     

       122
       122
       +
           cluster. The cluster-admin kubeconfig references an auto-generated

     

       123
       123
       +
           keypair owned by root. Thus, only root on the kubernetes master may

     

       124
       124
       +
           obtain cluster-admin rights by means of this file.

     

       125
       125
       +
         </para>

     

       126
       126
       +
       </chapter>

+150

nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-kernel-config">

     

       2
       2
       +
         <title>Linux Kernel</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           You can override the Linux kernel and associated packages using the

     

       5
       5
       +
           option <literal>boot.kernelPackages</literal>. For instance, this

     

       6
       6
       +
           selects the Linux 3.10 kernel:

     

       7
       7
       +
         </para>

     

       8
       8
       +
         <programlisting language="bash">

     

       9
       9
       +
       boot.kernelPackages = pkgs.linuxPackages_3_10;

     

       10
       10
       +
       </programlisting>

     

       11
       11
       +
         <para>

     

       12
       12
       +
           Note that this not only replaces the kernel, but also packages that

     

       13
       13
       +
           are specific to the kernel version, such as the NVIDIA video

     

       14
       14
       +
           drivers. This ensures that driver packages are consistent with the

     

       15
       15
       +
           kernel.

     

       16
       16
       +
         </para>

     

       17
       17
       +
         <para>

     

       18
       18
       +
           The default Linux kernel configuration should be fine for most

     

       19
       19
       +
           users. You can see the configuration of your current kernel with the

     

       20
       20
       +
           following command:

     

       21
       21
       +
         </para>

     

       22
       22
       +
         <programlisting>

     

       23
       23
       +
       zcat /proc/config.gz

     

       24
       24
       +
       </programlisting>

     

       25
       25
       +
         <para>

     

       26
       26
       +
           If you want to change the kernel configuration, you can use the

     

       27
       27
       +
           <literal>packageOverrides</literal> feature (see

     

       28
       28
       +
           <xref linkend="sec-customising-packages" />). For instance, to

     

       29
       29
       +
           enable support for the kernel debugger KGDB:

     

       30
       30
       +
         </para>

     

       31
       31
       +
         <programlisting language="bash">

     

       32
       32
       +
       nixpkgs.config.packageOverrides = pkgs:

     

       33
       33
       +
         { linux_3_4 = pkgs.linux_3_4.override {

     

       34
       34
       +
             extraConfig =

     

       35
       35
       +
               ''

     

       36
       36
       +
                 KGDB y

     

       37
       37
       +
               '';

     

       38
       38
       +
           };

     

       39
       39
       +
         };

     

       40
       40
       +
       </programlisting>

     

       41
       41
       +
         <para>

     

       42
       42
       +
           <literal>extraConfig</literal> takes a list of Linux kernel

     

       43
       43
       +
           configuration options, one per line. The name of the option should

     

       44
       44
       +
           not include the prefix <literal>CONFIG_</literal>. The option value

     

       45
       45
       +
           is typically <literal>y</literal>, <literal>n</literal> or

     

       46
       46
       +
           <literal>m</literal> (to build something as a kernel module).

     

       47
       47
       +
         </para>

     

       48
       48
       +
         <para>

     

       49
       49
       +
           Kernel modules for hardware devices are generally loaded

     

       50
       50
       +
           automatically by <literal>udev</literal>. You can force a module to

     

       51
       51
       +
           be loaded via <xref linkend="opt-boot.kernelModules" />, e.g.

     

       52
       52
       +
         </para>

     

       53
       53
       +
         <programlisting language="bash">

     

       54
       54
       +
       boot.kernelModules = [ &quot;fuse&quot; &quot;kvm-intel&quot; &quot;coretemp&quot; ];

     

       55
       55
       +
       </programlisting>

     

       56
       56
       +
         <para>

     

       57
       57
       +
           If the module is required early during the boot (e.g. to mount the

     

       58
       58
       +
           root file system), you can use

     

       59
       59
       +
           <xref linkend="opt-boot.initrd.kernelModules" />:

     

       60
       60
       +
         </para>

     

       61
       61
       +
         <programlisting language="bash">

     

       62
       62
       +
       boot.initrd.kernelModules = [ &quot;cifs&quot; ];

     

       63
       63
       +
       </programlisting>

     

       64
       64
       +
         <para>

     

       65
       65
       +
           This causes the specified modules and their dependencies to be added

     

       66
       66
       +
           to the initial ramdisk.

     

       67
       67
       +
         </para>

     

       68
       68
       +
         <para>

     

       69
       69
       +
           Kernel runtime parameters can be set through

     

       70
       70
       +
           <xref linkend="opt-boot.kernel.sysctl" />, e.g.

     

       71
       71
       +
         </para>

     

       72
       72
       +
         <programlisting language="bash">

     

       73
       73
       +
       boot.kernel.sysctl.&quot;net.ipv4.tcp_keepalive_time&quot; = 120;

     

       74
       74
       +
       </programlisting>

     

       75
       75
       +
         <para>

     

       76
       76
       +
           sets the kernel’s TCP keepalive time to 120 seconds. To see the

     

       77
       77
       +
           available parameters, run <literal>sysctl -a</literal>.

     

       78
       78
       +
         </para>

     

       79
       79
       +
         <section xml:id="sec-linux-config-customizing">

     

       80
       80
       +
           <title>Customize your kernel</title>

     

       81
       81
       +
           <para>

     

       82
       82
       +
             The first step before compiling the kernel is to generate an

     

       83
       83
       +
             appropriate <literal>.config</literal> configuration. Either you

     

       84
       84
       +
             pass your own config via the <literal>configfile</literal> setting

     

       85
       85
       +
             of <literal>linuxManualConfig</literal>:

     

       86
       86
       +
           </para>

     

       87
       87
       +
           <programlisting language="bash">

     

       88
       88
       +
       custom-kernel = super.linuxManualConfig {

     

       89
       89
       +
         inherit (super) stdenv hostPlatform;

     

       90
       90
       +
         inherit (linux_4_9) src;

     

       91
       91
       +
         version = &quot;${linux_4_9.version}-custom&quot;;

     

       92
       92
       +
       

     

       93
       93
       +
         configfile = /home/me/my_kernel_config;

     

       94
       94
       +
         allowImportFromDerivation = true;

     

       95
       95
       +
       };

     

       96
       96
       +
       </programlisting>

     

       97
       97
       +
           <para>

     

       98
       98
       +
             You can edit the config with this snippet (by default

     

       99
       99
       +
             <literal>make menuconfig</literal> won't work out of the box on

     

       100
       100
       +
             nixos):

     

       101
       101
       +
           </para>

     

       102
       102
       +
           <programlisting>

     

       103
       103
       +
       nix-shell -E 'with import &lt;nixpkgs&gt; {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'

     

       104
       104
       +
       </programlisting>

     

       105
       105
       +
           <para>

     

       106
       106
       +
             or you can let nixpkgs generate the configuration. Nixpkgs

     

       107
       107
       +
             generates it via answering the interactive kernel utility

     

       108
       108
       +
             <literal>make config</literal>. The answers depend on parameters

     

       109
       109
       +
             passed to

     

       110
       110
       +
             <literal>pkgs/os-specific/linux/kernel/generic.nix</literal>

     

       111
       111
       +
             (which you can influence by overriding

     

       112
       112
       +
             <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>).

     

       113
       113
       +
           </para>

     

       114
       114
       +
           <programlisting language="bash">

     

       115
       115
       +
       mptcp93.override ({

     

       116
       116
       +
         name=&quot;mptcp-local&quot;;

     

       117
       117
       +
       

     

       118
       118
       +
         ignoreConfigErrors = true;

     

       119
       119
       +
         autoModules = false;

     

       120
       120
       +
         kernelPreferBuiltin = true;

     

       121
       121
       +
       

     

       122
       122
       +
         enableParallelBuilding = true;

     

       123
       123
       +
       

     

       124
       124
       +
         extraConfig = ''

     

       125
       125
       +
           DEBUG_KERNEL y

     

       126
       126
       +
           FRAME_POINTER y

     

       127
       127
       +
           KGDB y

     

       128
       128
       +
           KGDB_SERIAL_CONSOLE y

     

       129
       129
       +
           DEBUG_INFO y

     

       130
       130
       +
         '';

     

       131
       131
       +
       });

     

       132
       132
       +
       </programlisting>

     

       133
       133
       +
         </section>

     

       134
       134
       +
         <section xml:id="sec-linux-config-developing-modules">

     

       135
       135
       +
           <title>Developing kernel modules</title>

     

       136
       136
       +
           <para>

     

       137
       137
       +
             When developing kernel modules it's often convenient to run

     

       138
       138
       +
             edit-compile-run loop as quickly as possible. See below snippet as

     

       139
       139
       +
             an example of developing <literal>mellanox</literal> drivers.

     

       140
       140
       +
           </para>

     

       141
       141
       +
           <programlisting>

     

       142
       142
       +
       $ nix-build '&lt;nixpkgs&gt;' -A linuxPackages.kernel.dev

     

       143
       143
       +
       $ nix-shell '&lt;nixpkgs&gt;' -A linuxPackages.kernel

     

       144
       144
       +
       $ unpackPhase

     

       145
       145
       +
       $ cd linux-*

     

       146
       146
       +
       $ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules

     

       147
       147
       +
       # insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko

     

       148
       148
       +
       </programlisting>

     

       149
       149
       +
         </section>

     

       150
       150
       +
       </chapter>

+2 -2

nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml

···

       51
       51
        
           </para>

     

       52
       52
        
           <para>

     

       53
       53
        
             The file system can be configured in NixOS via the usual

     

       54
       54
       -
             <link xlink:href="options.html#opt-fileSystems">fileSystems</link>

     

       55
       55
       -
             option. Here’s a typical setup:

     

       54
       54
       +
             <link linkend="opt-fileSystems">fileSystems</link> option. Here’s

     

       55
       55
       +
             a typical setup:

     

       56
       56
        
           </para>

     

       57
       57
        
           <programlisting language="bash">

     

       58
       58
        
       {

+121

nixos/doc/manual/from_md/configuration/subversion.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-subversion">

     

       2
       2
       +
         <title>Subversion</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           <link xlink:href="https://subversion.apache.org/">Subversion</link>

     

       5
       5
       +
           is a centralized version-control system. It can use a

     

       6
       6
       +
           <link xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety

     

       7
       7
       +
           of protocols</link> for communication between client and server.

     

       8
       8
       +
         </para>

     

       9
       9
       +
         <section xml:id="module-services-subversion-apache-httpd">

     

       10
       10
       +
           <title>Subversion inside Apache HTTP</title>

     

       11
       11
       +
           <para>

     

       12
       12
       +
             This section focuses on configuring a web-based server on top of

     

       13
       13
       +
             the Apache HTTP server, which uses

     

       14
       14
       +
             <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link>

     

       15
       15
       +
             for communication.

     

       16
       16
       +
           </para>

     

       17
       17
       +
           <para>

     

       18
       18
       +
             For more information on the general setup, please refer to the

     

       19
       19
       +
             <link xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the

     

       20
       20
       +
             appropriate section of the Subversion book</link>.

     

       21
       21
       +
           </para>

     

       22
       22
       +
           <para>

     

       23
       23
       +
             To configure, include in

     

       24
       24
       +
             <literal>/etc/nixos/configuration.nix</literal> code to activate

     

       25
       25
       +
             Apache HTTP, setting

     

       26
       26
       +
             <xref linkend="opt-services.httpd.adminAddr" /> appropriately:

     

       27
       27
       +
           </para>

     

       28
       28
       +
           <programlisting language="bash">

     

       29
       29
       +
       services.httpd.enable = true;

     

       30
       30
       +
       services.httpd.adminAddr = ...;

     

       31
       31
       +
       networking.firewall.allowedTCPPorts = [ 80 443 ];

     

       32
       32
       +
       </programlisting>

     

       33
       33
       +
           <para>

     

       34
       34
       +
             For a simple Subversion server with basic authentication,

     

       35
       35
       +
             configure the Subversion module for Apache as follows, setting

     

       36
       36
       +
             <literal>hostName</literal> and <literal>documentRoot</literal>

     

       37
       37
       +
             appropriately, and <literal>SVNParentPath</literal> to the parent

     

       38
       38
       +
             directory of the repositories,

     

       39
       39
       +
             <literal>AuthzSVNAccessFile</literal> to the location of the

     

       40
       40
       +
             <literal>.authz</literal> file describing access permission, and

     

       41
       41
       +
             <literal>AuthUserFile</literal> to the password file.

     

       42
       42
       +
           </para>

     

       43
       43
       +
           <programlisting language="bash">

     

       44
       44
       +
       services.httpd.extraModules = [

     

       45
       45
       +
           # note that order is *super* important here

     

       46
       46
       +
           { name = &quot;dav_svn&quot;; path = &quot;${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so&quot;; }

     

       47
       47
       +
           { name = &quot;authz_svn&quot;; path = &quot;${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so&quot;; }

     

       48
       48
       +
         ];

     

       49
       49
       +
         services.httpd.virtualHosts = {

     

       50
       50
       +
           &quot;svn&quot; = {

     

       51
       51
       +
              hostName = HOSTNAME;

     

       52
       52
       +
              documentRoot = DOCUMENTROOT;

     

       53
       53
       +
              locations.&quot;/svn&quot;.extraConfig = ''

     

       54
       54
       +
                  DAV svn

     

       55
       55
       +
                  SVNParentPath REPO_PARENT

     

       56
       56
       +
                  AuthzSVNAccessFile ACCESS_FILE

     

       57
       57
       +
                  AuthName &quot;SVN Repositories&quot;

     

       58
       58
       +
                  AuthType Basic

     

       59
       59
       +
                  AuthUserFile PASSWORD_FILE

     

       60
       60
       +
                  Require valid-user

     

       61
       61
       +
             '';

     

       62
       62
       +
           }

     

       63
       63
       +
       </programlisting>

     

       64
       64
       +
           <para>

     

       65
       65
       +
             The key <literal>&quot;svn&quot;</literal> is just a symbolic name

     

       66
       66
       +
             identifying the virtual host. The

     

       67
       67
       +
             <literal>&quot;/svn&quot;</literal> in

     

       68
       68
       +
             <literal>locations.&quot;/svn&quot;.extraConfig</literal> is the

     

       69
       69
       +
             path underneath which the repositories will be served.

     

       70
       70
       +
           </para>

     

       71
       71
       +
           <para>

     

       72
       72
       +
             <link xlink:href="https://wiki.archlinux.org/index.php/Subversion">This

     

       73
       73
       +
             page</link> explains how to set up the Subversion configuration

     

       74
       74
       +
             itself. This boils down to the following:

     

       75
       75
       +
           </para>

     

       76
       76
       +
           <para>

     

       77
       77
       +
             Underneath <literal>REPO_PARENT</literal> repositories can be set

     

       78
       78
       +
             up as follows:

     

       79
       79
       +
           </para>

     

       80
       80
       +
           <programlisting>

     

       81
       81
       +
       $ svn create REPO_NAME

     

       82
       82
       +
       </programlisting>

     

       83
       83
       +
           <para>

     

       84
       84
       +
             Repository files need to be accessible by

     

       85
       85
       +
             <literal>wwwrun</literal>:

     

       86
       86
       +
           </para>

     

       87
       87
       +
           <programlisting>

     

       88
       88
       +
       $ chown -R wwwrun:wwwrun REPO_PARENT

     

       89
       89
       +
       </programlisting>

     

       90
       90
       +
           <para>

     

       91
       91
       +
             The password file <literal>PASSWORD_FILE</literal> can be created

     

       92
       92
       +
             as follows:

     

       93
       93
       +
           </para>

     

       94
       94
       +
           <programlisting>

     

       95
       95
       +
       $ htpasswd -cs PASSWORD_FILE USER_NAME

     

       96
       96
       +
       </programlisting>

     

       97
       97
       +
           <para>

     

       98
       98
       +
             Additional users can be set up similarly, omitting the

     

       99
       99
       +
             <literal>c</literal> flag:

     

       100
       100
       +
           </para>

     

       101
       101
       +
           <programlisting>

     

       102
       102
       +
       $ htpasswd -s PASSWORD_FILE USER_NAME

     

       103
       103
       +
       </programlisting>

     

       104
       104
       +
           <para>

     

       105
       105
       +
             The file describing access permissions

     

       106
       106
       +
             <literal>ACCESS_FILE</literal> will look something like the

     

       107
       107
       +
             following:

     

       108
       108
       +
           </para>

     

       109
       109
       +
           <programlisting language="bash">

     

       110
       110
       +
       [/]

     

       111
       111
       +
       * = r

     

       112
       112
       +
       

     

       113
       113
       +
       [REPO_NAME:/]

     

       114
       114
       +
       USER_NAME = rw

     

       115
       115
       +
       </programlisting>

     

       116
       116
       +
           <para>

     

       117
       117
       +
             The Subversion repositories will be accessible as

     

       118
       118
       +
             <literal>http://HOSTNAME/svn/REPO_NAME</literal>.

     

       119
       119
       +
           </para>

     

       120
       120
       +
         </section>

     

       121
       121
       +
       </chapter>

+105

nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-user-management">

     

       2
       2
       +
         <title>User Management</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           NixOS supports both declarative and imperative styles of user

     

       5
       5
       +
           management. In the declarative style, users are specified in

     

       6
       6
       +
           <literal>configuration.nix</literal>. For instance, the following

     

       7
       7
       +
           states that a user account named <literal>alice</literal> shall

     

       8
       8
       +
           exist:

     

       9
       9
       +
         </para>

     

       10
       10
       +
         <programlisting language="bash">

     

       11
       11
       +
       users.users.alice = {

     

       12
       12
       +
         isNormalUser = true;

     

       13
       13
       +
         home = &quot;/home/alice&quot;;

     

       14
       14
       +
         description = &quot;Alice Foobar&quot;;

     

       15
       15
       +
         extraGroups = [ &quot;wheel&quot; &quot;networkmanager&quot; ];

     

       16
       16
       +
         openssh.authorizedKeys.keys = [ &quot;ssh-dss AAAAB3Nza... alice@foobar&quot; ];

     

       17
       17
       +
       };

     

       18
       18
       +
       </programlisting>

     

       19
       19
       +
         <para>

     

       20
       20
       +
           Note that <literal>alice</literal> is a member of the

     

       21
       21
       +
           <literal>wheel</literal> and <literal>networkmanager</literal>

     

       22
       22
       +
           groups, which allows her to use <literal>sudo</literal> to execute

     

       23
       23
       +
           commands as <literal>root</literal> and to configure the network,

     

       24
       24
       +
           respectively. Also note the SSH public key that allows remote logins

     

       25
       25
       +
           with the corresponding private key. Users created in this way do not

     

       26
       26
       +
           have a password by default, so they cannot log in via mechanisms

     

       27
       27
       +
           that require a password. However, you can use the

     

       28
       28
       +
           <literal>passwd</literal> program to set a password, which is

     

       29
       29
       +
           retained across invocations of <literal>nixos-rebuild</literal>.

     

       30
       30
       +
         </para>

     

       31
       31
       +
         <para>

     

       32
       32
       +
           If you set <xref linkend="opt-users.mutableUsers" /> to false, then

     

       33
       33
       +
           the contents of <literal>/etc/passwd</literal> and

     

       34
       34
       +
           <literal>/etc/group</literal> will be congruent to your NixOS

     

       35
       35
       +
           configuration. For instance, if you remove a user from

     

       36
       36
       +
           <xref linkend="opt-users.users" /> and run nixos-rebuild, the user

     

       37
       37
       +
           account will cease to exist. Also, imperative commands for managing

     

       38
       38
       +
           users and groups, such as useradd, are no longer available.

     

       39
       39
       +
           Passwords may still be assigned by setting the user's

     

       40
       40
       +
           <link linkend="opt-users.users._name_.hashedPassword">hashedPassword</link>

     

       41
       41
       +
           option. A hashed password can be generated using

     

       42
       42
       +
           <literal>mkpasswd -m sha-512</literal>.

     

       43
       43
       +
         </para>

     

       44
       44
       +
         <para>

     

       45
       45
       +
           A user ID (uid) is assigned automatically. You can also specify a

     

       46
       46
       +
           uid manually by adding

     

       47
       47
       +
         </para>

     

       48
       48
       +
         <programlisting language="bash">

     

       49
       49
       +
       uid = 1000;

     

       50
       50
       +
       </programlisting>

     

       51
       51
       +
         <para>

     

       52
       52
       +
           to the user specification.

     

       53
       53
       +
         </para>

     

       54
       54
       +
         <para>

     

       55
       55
       +
           Groups can be specified similarly. The following states that a group

     

       56
       56
       +
           named <literal>students</literal> shall exist:

     

       57
       57
       +
         </para>

     

       58
       58
       +
         <programlisting language="bash">

     

       59
       59
       +
       users.groups.students.gid = 1000;

     

       60
       60
       +
       </programlisting>

     

       61
       61
       +
         <para>

     

       62
       62
       +
           As with users, the group ID (gid) is optional and will be assigned

     

       63
       63
       +
           automatically if it’s missing.

     

       64
       64
       +
         </para>

     

       65
       65
       +
         <para>

     

       66
       66
       +
           In the imperative style, users and groups are managed by commands

     

       67
       67
       +
           such as <literal>useradd</literal>, <literal>groupmod</literal> and

     

       68
       68
       +
           so on. For instance, to create a user account named

     

       69
       69
       +
           <literal>alice</literal>:

     

       70
       70
       +
         </para>

     

       71
       71
       +
         <programlisting>

     

       72
       72
       +
       # useradd -m alice

     

       73
       73
       +
       </programlisting>

     

       74
       74
       +
         <para>

     

       75
       75
       +
           To make all nix tools available to this new user use `su - USER`

     

       76
       76
       +
           which opens a login shell (==shell that loads the profile) for given

     

       77
       77
       +
           user. This will create the ~/.nix-defexpr symlink. So run:

     

       78
       78
       +
         </para>

     

       79
       79
       +
         <programlisting>

     

       80
       80
       +
       # su - alice -c &quot;true&quot;

     

       81
       81
       +
       </programlisting>

     

       82
       82
       +
         <para>

     

       83
       83
       +
           The flag <literal>-m</literal> causes the creation of a home

     

       84
       84
       +
           directory for the new user, which is generally what you want. The

     

       85
       85
       +
           user does not have an initial password and therefore cannot log in.

     

       86
       86
       +
           A password can be set using the <literal>passwd</literal> utility:

     

       87
       87
       +
         </para>

     

       88
       88
       +
         <programlisting>

     

       89
       89
       +
       # passwd alice

     

       90
       90
       +
       Enter new UNIX password: ***

     

       91
       91
       +
       Retype new UNIX password: ***

     

       92
       92
       +
       </programlisting>

     

       93
       93
       +
         <para>

     

       94
       94
       +
           A user can be deleted using <literal>userdel</literal>:

     

       95
       95
       +
         </para>

     

       96
       96
       +
         <programlisting>

     

       97
       97
       +
       # userdel -r alice

     

       98
       98
       +
       </programlisting>

     

       99
       99
       +
         <para>

     

       100
       100
       +
           The flag <literal>-r</literal> deletes the user’s home directory.

     

       101
       101
       +
           Accounts can be modified using <literal>usermod</literal>. Unix

     

       102
       102
       +
           groups can be managed using <literal>groupadd</literal>,

     

       103
       103
       +
           <literal>groupmod</literal> and <literal>groupdel</literal>.

     

       104
       104
       +
         </para>

     

       105
       105
       +
       </chapter>

+31

nixos/doc/manual/from_md/configuration/wayland.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-wayland">

     

       2
       2
       +
         <title>Wayland</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           While X11 (see <xref linkend="sec-x11" />) is still the primary

     

       5
       5
       +
           display technology on NixOS, Wayland support is steadily improving.

     

       6
       6
       +
           Where X11 separates the X Server and the window manager, on Wayland

     

       7
       7
       +
           those are combined: a Wayland Compositor is like an X11 window

     

       8
       8
       +
           manager, but also embeds the Wayland 'Server' functionality. This

     

       9
       9
       +
           means it is sufficient to install a Wayland Compositor such as sway

     

       10
       10
       +
           without separately enabling a Wayland server:

     

       11
       11
       +
         </para>

     

       12
       12
       +
         <programlisting language="bash">

     

       13
       13
       +
       programs.sway.enable = true;

     

       14
       14
       +
       </programlisting>

     

       15
       15
       +
         <para>

     

       16
       16
       +
           This installs the sway compositor along with some essential

     

       17
       17
       +
           utilities. Now you can start sway from the TTY console.

     

       18
       18
       +
         </para>

     

       19
       19
       +
         <para>

     

       20
       20
       +
           If you are using a wlroots-based compositor, like sway, and want to

     

       21
       21
       +
           be able to share your screen, you might want to activate this

     

       22
       22
       +
           option:

     

       23
       23
       +
         </para>

     

       24
       24
       +
         <programlisting language="bash">

     

       25
       25
       +
       xdg.portal.wlr.enable = true;

     

       26
       26
       +
       </programlisting>

     

       27
       27
       +
         <para>

     

       28
       28
       +
           and configure Pipewire using

     

       29
       29
       +
           <xref linkend="opt-services.pipewire.enable" /> and related options.

     

       30
       30
       +
         </para>

     

       31
       31
       +
       </chapter>

+381

nixos/doc/manual/from_md/configuration/x-windows.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-x11">

     

       2
       2
       +
         <title>X Window System</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           The X Window System (X11) provides the basis of NixOS’ graphical

     

       5
       5
       +
           user interface. It can be enabled as follows:

     

       6
       6
       +
         </para>

     

       7
       7
       +
         <programlisting language="bash">

     

       8
       8
       +
       services.xserver.enable = true;

     

       9
       9
       +
       </programlisting>

     

       10
       10
       +
         <para>

     

       11
       11
       +
           The X server will automatically detect and use the appropriate video

     

       12
       12
       +
           driver from a set of X.org drivers (such as <literal>vesa</literal>

     

       13
       13
       +
           and <literal>intel</literal>). You can also specify a driver

     

       14
       14
       +
           manually, e.g.

     

       15
       15
       +
         </para>

     

       16
       16
       +
         <programlisting language="bash">

     

       17
       17
       +
       services.xserver.videoDrivers = [ &quot;r128&quot; ];

     

       18
       18
       +
       </programlisting>

     

       19
       19
       +
         <para>

     

       20
       20
       +
           to enable X.org’s <literal>xf86-video-r128</literal> driver.

     

       21
       21
       +
         </para>

     

       22
       22
       +
         <para>

     

       23
       23
       +
           You also need to enable at least one desktop or window manager.

     

       24
       24
       +
           Otherwise, you can only log into a plain undecorated

     

       25
       25
       +
           <literal>xterm</literal> window. Thus you should pick one or more of

     

       26
       26
       +
           the following lines:

     

       27
       27
       +
         </para>

     

       28
       28
       +
         <programlisting language="bash">

     

       29
       29
       +
       services.xserver.desktopManager.plasma5.enable = true;

     

       30
       30
       +
       services.xserver.desktopManager.xfce.enable = true;

     

       31
       31
       +
       services.xserver.desktopManager.gnome.enable = true;

     

       32
       32
       +
       services.xserver.desktopManager.mate.enable = true;

     

       33
       33
       +
       services.xserver.windowManager.xmonad.enable = true;

     

       34
       34
       +
       services.xserver.windowManager.twm.enable = true;

     

       35
       35
       +
       services.xserver.windowManager.icewm.enable = true;

     

       36
       36
       +
       services.xserver.windowManager.i3.enable = true;

     

       37
       37
       +
       services.xserver.windowManager.herbstluftwm.enable = true;

     

       38
       38
       +
       </programlisting>

     

       39
       39
       +
         <para>

     

       40
       40
       +
           NixOS’s default <emphasis>display manager</emphasis> (the program

     

       41
       41
       +
           that provides a graphical login prompt and manages the X server) is

     

       42
       42
       +
           LightDM. You can select an alternative one by picking one of the

     

       43
       43
       +
           following lines:

     

       44
       44
       +
         </para>

     

       45
       45
       +
         <programlisting language="bash">

     

       46
       46
       +
       services.xserver.displayManager.sddm.enable = true;

     

       47
       47
       +
       services.xserver.displayManager.gdm.enable = true;

     

       48
       48
       +
       </programlisting>

     

       49
       49
       +
         <para>

     

       50
       50
       +
           You can set the keyboard layout (and optionally the layout variant):

     

       51
       51
       +
         </para>

     

       52
       52
       +
         <programlisting language="bash">

     

       53
       53
       +
       services.xserver.layout = &quot;de&quot;;

     

       54
       54
       +
       services.xserver.xkbVariant = &quot;neo&quot;;

     

       55
       55
       +
       </programlisting>

     

       56
       56
       +
         <para>

     

       57
       57
       +
           The X server is started automatically at boot time. If you don’t

     

       58
       58
       +
           want this to happen, you can set:

     

       59
       59
       +
         </para>

     

       60
       60
       +
         <programlisting language="bash">

     

       61
       61
       +
       services.xserver.autorun = false;

     

       62
       62
       +
       </programlisting>

     

       63
       63
       +
         <para>

     

       64
       64
       +
           The X server can then be started manually:

     

       65
       65
       +
         </para>

     

       66
       66
       +
         <programlisting>

     

       67
       67
       +
       # systemctl start display-manager.service

     

       68
       68
       +
       </programlisting>

     

       69
       69
       +
         <para>

     

       70
       70
       +
           On 64-bit systems, if you want OpenGL for 32-bit programs such as in

     

       71
       71
       +
           Wine, you should also set the following:

     

       72
       72
       +
         </para>

     

       73
       73
       +
         <programlisting language="bash">

     

       74
       74
       +
       hardware.opengl.driSupport32Bit = true;

     

       75
       75
       +
       </programlisting>

     

       76
       76
       +
         <section xml:id="sec-x11-auto-login">

     

       77
       77
       +
           <title>Auto-login</title>

     

       78
       78
       +
           <para>

     

       79
       79
       +
             The x11 login screen can be skipped entirely, automatically

     

       80
       80
       +
             logging you into your window manager and desktop environment when

     

       81
       81
       +
             you boot your computer.

     

       82
       82
       +
           </para>

     

       83
       83
       +
           <para>

     

       84
       84
       +
             This is especially helpful if you have disk encryption enabled.

     

       85
       85
       +
             Since you already have to provide a password to decrypt your disk,

     

       86
       86
       +
             entering a second password to login can be redundant.

     

       87
       87
       +
           </para>

     

       88
       88
       +
           <para>

     

       89
       89
       +
             To enable auto-login, you need to define your default window

     

       90
       90
       +
             manager and desktop environment. If you wanted no desktop

     

       91
       91
       +
             environment and i3 as your your window manager, you'd define:

     

       92
       92
       +
           </para>

     

       93
       93
       +
           <programlisting language="bash">

     

       94
       94
       +
       services.xserver.displayManager.defaultSession = &quot;none+i3&quot;;

     

       95
       95
       +
       </programlisting>

     

       96
       96
       +
           <para>

     

       97
       97
       +
             Every display manager in NixOS supports auto-login, here is an

     

       98
       98
       +
             example using lightdm for a user <literal>alice</literal>:

     

       99
       99
       +
           </para>

     

       100
       100
       +
           <programlisting language="bash">

     

       101
       101
       +
       services.xserver.displayManager.lightdm.enable = true;

     

       102
       102
       +
       services.xserver.displayManager.autoLogin.enable = true;

     

       103
       103
       +
       services.xserver.displayManager.autoLogin.user = &quot;alice&quot;;

     

       104
       104
       +
       </programlisting>

     

       105
       105
       +
         </section>

     

       106
       106
       +
         <section xml:id="sec-x11--graphics-cards-intel">

     

       107
       107
       +
           <title>Intel Graphics drivers</title>

     

       108
       108
       +
           <para>

     

       109
       109
       +
             There are two choices for Intel Graphics drivers in X.org:

     

       110
       110
       +
             <literal>modesetting</literal> (included in the xorg-server

     

       111
       111
       +
             itself) and <literal>intel</literal> (provided by the package

     

       112
       112
       +
             xf86-video-intel).

     

       113
       113
       +
           </para>

     

       114
       114
       +
           <para>

     

       115
       115
       +
             The default and recommended is <literal>modesetting</literal>. It

     

       116
       116
       +
             is a generic driver which uses the kernel

     

       117
       117
       +
             <link xlink:href="https://en.wikipedia.org/wiki/Mode_setting">mode

     

       118
       118
       +
             setting</link> (KMS) mechanism. It supports Glamor (2D graphics

     

       119
       119
       +
             acceleration via OpenGL) and is actively maintained but may

     

       120
       120
       +
             perform worse in some cases (like in old chipsets).

     

       121
       121
       +
           </para>

     

       122
       122
       +
           <para>

     

       123
       123
       +
             The second driver, <literal>intel</literal>, is specific to Intel

     

       124
       124
       +
             GPUs, but not recommended by most distributions: it lacks several

     

       125
       125
       +
             modern features (for example, it doesn't support Glamor) and the

     

       126
       126
       +
             package hasn't been officially updated since 2015.

     

       127
       127
       +
           </para>

     

       128
       128
       +
           <para>

     

       129
       129
       +
             The results vary depending on the hardware, so you may have to try

     

       130
       130
       +
             both drivers. Use the option

     

       131
       131
       +
             <xref linkend="opt-services.xserver.videoDrivers" /> to set one.

     

       132
       132
       +
             The recommended configuration for modern systems is:

     

       133
       133
       +
           </para>

     

       134
       134
       +
           <programlisting language="bash">

     

       135
       135
       +
       services.xserver.videoDrivers = [ &quot;modesetting&quot; ];

     

       136
       136
       +
       services.xserver.useGlamor = true;

     

       137
       137
       +
       </programlisting>

     

       138
       138
       +
           <para>

     

       139
       139
       +
             If you experience screen tearing no matter what, this

     

       140
       140
       +
             configuration was reported to resolve the issue:

     

       141
       141
       +
           </para>

     

       142
       142
       +
           <programlisting language="bash">

     

       143
       143
       +
       services.xserver.videoDrivers = [ &quot;intel&quot; ];

     

       144
       144
       +
       services.xserver.deviceSection = ''

     

       145
       145
       +
         Option &quot;DRI&quot; &quot;2&quot;

     

       146
       146
       +
         Option &quot;TearFree&quot; &quot;true&quot;

     

       147
       147
       +
       '';

     

       148
       148
       +
       </programlisting>

     

       149
       149
       +
           <para>

     

       150
       150
       +
             Note that this will likely downgrade the performance compared to

     

       151
       151
       +
             <literal>modesetting</literal> or <literal>intel</literal> with

     

       152
       152
       +
             DRI 3 (default).

     

       153
       153
       +
           </para>

     

       154
       154
       +
         </section>

     

       155
       155
       +
         <section xml:id="sec-x11-graphics-cards-nvidia">

     

       156
       156
       +
           <title>Proprietary NVIDIA drivers</title>

     

       157
       157
       +
           <para>

     

       158
       158
       +
             NVIDIA provides a proprietary driver for its graphics cards that

     

       159
       159
       +
             has better 3D performance than the X.org drivers. It is not

     

       160
       160
       +
             enabled by default because it’s not free software. You can enable

     

       161
       161
       +
             it as follows:

     

       162
       162
       +
           </para>

     

       163
       163
       +
           <programlisting language="bash">

     

       164
       164
       +
       services.xserver.videoDrivers = [ &quot;nvidia&quot; ];

     

       165
       165
       +
       </programlisting>

     

       166
       166
       +
           <para>

     

       167
       167
       +
             Or if you have an older card, you may have to use one of the

     

       168
       168
       +
             legacy drivers:

     

       169
       169
       +
           </para>

     

       170
       170
       +
           <programlisting language="bash">

     

       171
       171
       +
       services.xserver.videoDrivers = [ &quot;nvidiaLegacy390&quot; ];

     

       172
       172
       +
       services.xserver.videoDrivers = [ &quot;nvidiaLegacy340&quot; ];

     

       173
       173
       +
       services.xserver.videoDrivers = [ &quot;nvidiaLegacy304&quot; ];

     

       174
       174
       +
       </programlisting>

     

       175
       175
       +
           <para>

     

       176
       176
       +
             You may need to reboot after enabling this driver to prevent a

     

       177
       177
       +
             clash with other kernel modules.

     

       178
       178
       +
           </para>

     

       179
       179
       +
         </section>

     

       180
       180
       +
         <section xml:id="sec-x11--graphics-cards-amd">

     

       181
       181
       +
           <title>Proprietary AMD drivers</title>

     

       182
       182
       +
           <para>

     

       183
       183
       +
             AMD provides a proprietary driver for its graphics cards that is

     

       184
       184
       +
             not enabled by default because it’s not Free Software, is often

     

       185
       185
       +
             broken in nixpkgs and as of this writing doesn't offer more

     

       186
       186
       +
             features or performance. If you still want to use it anyway, you

     

       187
       187
       +
             need to explicitly set:

     

       188
       188
       +
           </para>

     

       189
       189
       +
           <programlisting language="bash">

     

       190
       190
       +
       services.xserver.videoDrivers = [ &quot;amdgpu-pro&quot; ];

     

       191
       191
       +
       </programlisting>

     

       192
       192
       +
           <para>

     

       193
       193
       +
             You will need to reboot after enabling this driver to prevent a

     

       194
       194
       +
             clash with other kernel modules.

     

       195
       195
       +
           </para>

     

       196
       196
       +
         </section>

     

       197
       197
       +
         <section xml:id="sec-x11-touchpads">

     

       198
       198
       +
           <title>Touchpads</title>

     

       199
       199
       +
           <para>

     

       200
       200
       +
             Support for Synaptics touchpads (found in many laptops such as the

     

       201
       201
       +
             Dell Latitude series) can be enabled as follows:

     

       202
       202
       +
           </para>

     

       203
       203
       +
           <programlisting language="bash">

     

       204
       204
       +
       services.xserver.libinput.enable = true;

     

       205
       205
       +
       </programlisting>

     

       206
       206
       +
           <para>

     

       207
       207
       +
             The driver has many options (see <xref linkend="ch-options" />).

     

       208
       208
       +
             For instance, the following disables tap-to-click behavior:

     

       209
       209
       +
           </para>

     

       210
       210
       +
           <programlisting language="bash">

     

       211
       211
       +
       services.xserver.libinput.touchpad.tapping = false;

     

       212
       212
       +
       </programlisting>

     

       213
       213
       +
           <para>

     

       214
       214
       +
             Note: the use of <literal>services.xserver.synaptics</literal> is

     

       215
       215
       +
             deprecated since NixOS 17.09.

     

       216
       216
       +
           </para>

     

       217
       217
       +
         </section>

     

       218
       218
       +
         <section xml:id="sec-x11-gtk-and-qt-themes">

     

       219
       219
       +
           <title>GTK/Qt themes</title>

     

       220
       220
       +
           <para>

     

       221
       221
       +
             GTK themes can be installed either to user profile or system-wide

     

       222
       222
       +
             (via <literal>environment.systemPackages</literal>). To make Qt 5

     

       223
       223
       +
             applications look similar to GTK ones, you can use the following

     

       224
       224
       +
             configuration:

     

       225
       225
       +
           </para>

     

       226
       226
       +
           <programlisting language="bash">

     

       227
       227
       +
       qt5.enable = true;

     

       228
       228
       +
       qt5.platformTheme = &quot;gtk2&quot;;

     

       229
       229
       +
       qt5.style = &quot;gtk2&quot;;

     

       230
       230
       +
       </programlisting>

     

       231
       231
       +
         </section>

     

       232
       232
       +
         <section xml:id="custom-xkb-layouts">

     

       233
       233
       +
           <title>Custom XKB layouts</title>

     

       234
       234
       +
           <para>

     

       235
       235
       +
             It is possible to install custom

     

       236
       236
       +
             <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">

     

       237
       237
       +
             XKB </link> keyboard layouts using the option

     

       238
       238
       +
             <literal>services.xserver.extraLayouts</literal>.

     

       239
       239
       +
           </para>

     

       240
       240
       +
           <para>

     

       241
       241
       +
             As a first example, we are going to create a layout based on the

     

       242
       242
       +
             basic US layout, with an additional layer to type some greek

     

       243
       243
       +
             symbols by pressing the right-alt key.

     

       244
       244
       +
           </para>

     

       245
       245
       +
           <para>

     

       246
       246
       +
             Create a file called <literal>us-greek</literal> with the

     

       247
       247
       +
             following content (under a directory called

     

       248
       248
       +
             <literal>symbols</literal>; it's an XKB peculiarity that will help

     

       249
       249
       +
             with testing):

     

       250
       250
       +
           </para>

     

       251
       251
       +
           <programlisting language="bash">

     

       252
       252
       +
       xkb_symbols &quot;us-greek&quot;

     

       253
       253
       +
       {

     

       254
       254
       +
         include &quot;us(basic)&quot;            // includes the base US keys

     

       255
       255
       +
         include &quot;level3(ralt_switch)&quot;  // configures right alt as a third level switch

     

       256
       256
       +
       

     

       257
       257
       +
         key &lt;LatA&gt; { [ a, A, Greek_alpha ] };

     

       258
       258
       +
         key &lt;LatB&gt; { [ b, B, Greek_beta  ] };

     

       259
       259
       +
         key &lt;LatG&gt; { [ g, G, Greek_gamma ] };

     

       260
       260
       +
         key &lt;LatD&gt; { [ d, D, Greek_delta ] };

     

       261
       261
       +
         key &lt;LatZ&gt; { [ z, Z, Greek_zeta  ] };

     

       262
       262
       +
       };

     

       263
       263
       +
       </programlisting>

     

       264
       264
       +
           <para>

     

       265
       265
       +
             A minimal layout specification must include the following:

     

       266
       266
       +
           </para>

     

       267
       267
       +
           <programlisting language="bash">

     

       268
       268
       +
       services.xserver.extraLayouts.us-greek = {

     

       269
       269
       +
         description = &quot;US layout with alt-gr greek&quot;;

     

       270
       270
       +
         languages   = [ &quot;eng&quot; ];

     

       271
       271
       +
         symbolsFile = /yourpath/symbols/us-greek;

     

       272
       272
       +
       };

     

       273
       273
       +
       </programlisting>

     

       274
       274
       +
           <note>

     

       275
       275
       +
             <para>

     

       276
       276
       +
               The name (after <literal>extraLayouts.</literal>) should match

     

       277
       277
       +
               the one given to the <literal>xkb_symbols</literal> block.

     

       278
       278
       +
             </para>

     

       279
       279
       +
           </note>

     

       280
       280
       +
           <para>

     

       281
       281
       +
             Applying this customization requires rebuilding several packages,

     

       282
       282
       +
             and a broken XKB file can lead to the X session crashing at login.

     

       283
       283
       +
             Therefore, you're strongly advised to <emphasis role="strong">test

     

       284
       284
       +
             your layout before applying it</emphasis>:

     

       285
       285
       +
           </para>

     

       286
       286
       +
           <programlisting>

     

       287
       287
       +
       $ nix-shell -p xorg.xkbcomp

     

       288
       288
       +
       $ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY

     

       289
       289
       +
       </programlisting>

     

       290
       290
       +
           <para>

     

       291
       291
       +
             You can inspect the predefined XKB files for examples:

     

       292
       292
       +
           </para>

     

       293
       293
       +
           <programlisting>

     

       294
       294
       +
       $ echo &quot;$(nix-build --no-out-link '&lt;nixpkgs&gt;' -A xorg.xkeyboardconfig)/etc/X11/xkb/&quot;

     

       295
       295
       +
       </programlisting>

     

       296
       296
       +
           <para>

     

       297
       297
       +
             Once the configuration is applied, and you did a logout/login

     

       298
       298
       +
             cycle, the layout should be ready to use. You can try it by e.g.

     

       299
       299
       +
             running <literal>setxkbmap us-greek</literal> and then type

     

       300
       300
       +
             <literal>&lt;alt&gt;+a</literal> (it may not get applied in your

     

       301
       301
       +
             terminal straight away). To change the default, the usual

     

       302
       302
       +
             <literal>services.xserver.layout</literal> option can still be

     

       303
       303
       +
             used.

     

       304
       304
       +
           </para>

     

       305
       305
       +
           <para>

     

       306
       306
       +
             A layout can have several other components besides

     

       307
       307
       +
             <literal>xkb_symbols</literal>, for example we will define new

     

       308
       308
       +
             keycodes for some multimedia key and bind these to some symbol.

     

       309
       309
       +
           </para>

     

       310
       310
       +
           <para>

     

       311
       311
       +
             Use the <emphasis>xev</emphasis> utility from

     

       312
       312
       +
             <literal>pkgs.xorg.xev</literal> to find the codes of the keys of

     

       313
       313
       +
             interest, then create a <literal>media-key</literal> file to hold

     

       314
       314
       +
             the keycodes definitions

     

       315
       315
       +
           </para>

     

       316
       316
       +
           <programlisting language="bash">

     

       317
       317
       +
       xkb_keycodes &quot;media&quot;

     

       318
       318
       +
       {

     

       319
       319
       +
        &lt;volUp&gt;   = 123;

     

       320
       320
       +
        &lt;volDown&gt; = 456;

     

       321
       321
       +
       }

     

       322
       322
       +
       </programlisting>

     

       323
       323
       +
           <para>

     

       324
       324
       +
             Now use the newly define keycodes in <literal>media-sym</literal>:

     

       325
       325
       +
           </para>

     

       326
       326
       +
           <programlisting language="bash">

     

       327
       327
       +
       xkb_symbols &quot;media&quot;

     

       328
       328
       +
       {

     

       329
       329
       +
        key.type = &quot;ONE_LEVEL&quot;;

     

       330
       330
       +
        key &lt;volUp&gt;   { [ XF86AudioLowerVolume ] };

     

       331
       331
       +
        key &lt;volDown&gt; { [ XF86AudioRaiseVolume ] };

     

       332
       332
       +
       }

     

       333
       333
       +
       </programlisting>

     

       334
       334
       +
           <para>

     

       335
       335
       +
             As before, to install the layout do

     

       336
       336
       +
           </para>

     

       337
       337
       +
           <programlisting language="bash">

     

       338
       338
       +
       services.xserver.extraLayouts.media = {

     

       339
       339
       +
         description  = &quot;Multimedia keys remapping&quot;;

     

       340
       340
       +
         languages    = [ &quot;eng&quot; ];

     

       341
       341
       +
         symbolsFile  = /path/to/media-key;

     

       342
       342
       +
         keycodesFile = /path/to/media-sym;

     

       343
       343
       +
       };

     

       344
       344
       +
       </programlisting>

     

       345
       345
       +
           <note>

     

       346
       346
       +
             <para>

     

       347
       347
       +
               The function

     

       348
       348
       +
               <literal>pkgs.writeText &lt;filename&gt; &lt;content&gt;</literal>

     

       349
       349
       +
               can be useful if you prefer to keep the layout definitions

     

       350
       350
       +
               inside the NixOS configuration.

     

       351
       351
       +
             </para>

     

       352
       352
       +
           </note>

     

       353
       353
       +
           <para>

     

       354
       354
       +
             Unfortunately, the Xorg server does not (currently) support

     

       355
       355
       +
             setting a keymap directly but relies instead on XKB rules to

     

       356
       356
       +
             select the matching components (keycodes, types, ...) of a layout.

     

       357
       357
       +
             This means that components other than symbols won't be loaded by

     

       358
       358
       +
             default. As a workaround, you can set the keymap using

     

       359
       359
       +
             <literal>setxkbmap</literal> at the start of the session with:

     

       360
       360
       +
           </para>

     

       361
       361
       +
           <programlisting language="bash">

     

       362
       362
       +
       services.xserver.displayManager.sessionCommands = &quot;setxkbmap -keycodes media&quot;;

     

       363
       363
       +
       </programlisting>

     

       364
       364
       +
           <para>

     

       365
       365
       +
             If you are manually starting the X server, you should set the

     

       366
       366
       +
             argument <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X

     

       367
       367
       +
             won't find your layout files. For example with

     

       368
       368
       +
             <literal>xinit</literal> run

     

       369
       369
       +
           </para>

     

       370
       370
       +
           <programlisting>

     

       371
       371
       +
       $ xinit -- -xkbdir /etc/X11/xkb

     

       372
       372
       +
       </programlisting>

     

       373
       373
       +
           <para>

     

       374
       374
       +
             To learn how to write layouts take a look at the XKB

     

       375
       375
       +
             <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">documentation

     

       376
       376
       +
             </link>. More example layouts can also be found

     

       377
       377
       +
             <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">here

     

       378
       378
       +
             </link>.

     

       379
       379
       +
           </para>

     

       380
       380
       +
         </section>

     

       381
       381
       +
       </chapter>

+62

nixos/doc/manual/from_md/configuration/xfce.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-xfce">

     

       2
       2
       +
         <title>Xfce Desktop Environment</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           To enable the Xfce Desktop Environment, set

     

       5
       5
       +
         </para>

     

       6
       6
       +
         <programlisting language="bash">

     

       7
       7
       +
       services.xserver.desktopManager.xfce.enable = true;

     

       8
       8
       +
       services.xserver.displayManager.defaultSession = &quot;xfce&quot;;

     

       9
       9
       +
       </programlisting>

     

       10
       10
       +
         <para>

     

       11
       11
       +
           Optionally, <emphasis>picom</emphasis> can be enabled for nice

     

       12
       12
       +
           graphical effects, some example settings:

     

       13
       13
       +
         </para>

     

       14
       14
       +
         <programlisting language="bash">

     

       15
       15
       +
       services.picom = {

     

       16
       16
       +
         enable = true;

     

       17
       17
       +
         fade = true;

     

       18
       18
       +
         inactiveOpacity = 0.9;

     

       19
       19
       +
         shadow = true;

     

       20
       20
       +
         fadeDelta = 4;

     

       21
       21
       +
       };

     

       22
       22
       +
       </programlisting>

     

       23
       23
       +
         <para>

     

       24
       24
       +
           Some Xfce programs are not installed automatically. To install them

     

       25
       25
       +
           manually (system wide), put them into your

     

       26
       26
       +
           <xref linkend="opt-environment.systemPackages" /> from

     

       27
       27
       +
           <literal>pkgs.xfce</literal>.

     

       28
       28
       +
         </para>

     

       29
       29
       +
         <section xml:id="sec-xfce-thunar-plugins">

     

       30
       30
       +
           <title>Thunar Plugins</title>

     

       31
       31
       +
           <para>

     

       32
       32
       +
             If you'd like to add extra plugins to Thunar, add them to

     

       33
       33
       +
             <xref linkend="opt-services.xserver.desktopManager.xfce.thunarPlugins" />.

     

       34
       34
       +
             You shouldn't just add them to

     

       35
       35
       +
             <xref linkend="opt-environment.systemPackages" />.

     

       36
       36
       +
           </para>

     

       37
       37
       +
         </section>

     

       38
       38
       +
         <section xml:id="sec-xfce-troubleshooting">

     

       39
       39
       +
           <title>Troubleshooting</title>

     

       40
       40
       +
           <para>

     

       41
       41
       +
             Even after enabling udisks2, volume management might not work.

     

       42
       42
       +
             Thunar and/or the desktop takes time to show up. Thunar will spit

     

       43
       43
       +
             out this kind of message on start (look at

     

       44
       44
       +
             <literal>journalctl --user -b</literal>).

     

       45
       45
       +
           </para>

     

       46
       46
       +
           <programlisting>

     

       47
       47
       +
       Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported

     

       48
       48
       +
       </programlisting>

     

       49
       49
       +
           <para>

     

       50
       50
       +
             This is caused by some needed GNOME services not running. This is

     

       51
       51
       +
             all fixed by enabling &quot;Launch GNOME services on startup&quot;

     

       52
       52
       +
             in the Advanced tab of the Session and Startup settings panel.

     

       53
       53
       +
             Alternatively, you can run this command to do the same thing.

     

       54
       54
       +
           </para>

     

       55
       55
       +
           <programlisting>

     

       56
       56
       +
       $ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true

     

       57
       57
       +
       </programlisting>

     

       58
       58
       +
           <para>

     

       59
       59
       +
             A log-out and re-log will be needed for this to take effect.

     

       60
       60
       +
           </para>

     

       61
       61
       +
         </section>

     

       62
       62
       +
       </chapter>