diff options
Diffstat (limited to 'nixos/doc/manual/configuration')
25 files changed, 579 insertions, 218 deletions
diff --git a/nixos/doc/manual/configuration/abstractions.section.md b/nixos/doc/manual/configuration/abstractions.section.md new file mode 100644 index 00000000000..bf26e4c51ed --- /dev/null +++ b/nixos/doc/manual/configuration/abstractions.section.md @@ -0,0 +1,80 @@ +# Abstractions {#sec-module-abstractions} + +If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration: + +```nix +{ + services.httpd.virtualHosts = + { "blog.example.org" = { + documentRoot = "/webroot/blog.example.org"; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + enablePHP = true; + }; + "wiki.example.org" = { + documentRoot = "/webroot/wiki.example.org"; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + enablePHP = true; + }; + }; +} +``` + +It defines two virtual hosts with nearly identical configuration; the only difference is the document root directories. To prevent this duplication, we can use a `let`: +```nix +let + commonConfig = + { adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + }; +in +{ + services.httpd.virtualHosts = + { "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; }); + "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.com"; }); + }; +} +``` + +The `let commonConfig = ...` defines a variable named `commonConfig`. The `//` operator merges two attribute sets, so the configuration of the second virtual host is the set `commonConfig` extended with the document root option. + +You can write a `let` wherever an expression is allowed. Thus, you also could have written: + +```nix +{ + services.httpd.virtualHosts = + let commonConfig = ...; in + { "blog.example.org" = (commonConfig // { ... }) + "wiki.example.org" = (commonConfig // { ... }) + }; +} +``` + +but not `{ let commonConfig = ...; in ...; }` since attributes (as opposed to attribute values) are not expressions. + +**Functions** provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the document root. This can be done as follows: + +```nix +{ + services.httpd.virtualHosts = + let + makeVirtualHost = webroot: + { documentRoot = webroot; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + }; + in + { "example.org" = (makeVirtualHost "/webroot/example.org"); + "example.com" = (makeVirtualHost "/webroot/example.com"); + "example.gov" = (makeVirtualHost "/webroot/example.gov"); + "example.nl" = (makeVirtualHost "/webroot/example.nl"); + }; +} +``` + +Here, `makeVirtualHost` is a function that takes a single argument `webroot` and returns the configuration for a virtual host. That function is then called for several names to produce the list of virtual host configurations. diff --git a/nixos/doc/manual/configuration/abstractions.xml b/nixos/doc/manual/configuration/abstractions.xml deleted file mode 100644 index df9ff2615e1..00000000000 --- a/nixos/doc/manual/configuration/abstractions.xml +++ /dev/null @@ -1,101 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-module-abstractions"> - <title>Abstractions</title> - - <para> - If you find yourself repeating yourself over and over, it’s time to - abstract. Take, for instance, this Apache HTTP Server configuration: -<programlisting> -{ - <xref linkend="opt-services.httpd.virtualHosts"/> = - { "blog.example.org" = { - documentRoot = "/webroot/blog.example.org"; - adminAddr = "alice@example.org"; - forceSSL = true; - enableACME = true; - enablePHP = true; - }; - "wiki.example.org" = { - documentRoot = "/webroot/wiki.example.org"; - adminAddr = "alice@example.org"; - forceSSL = true; - enableACME = true; - enablePHP = true; - }; - }; -} -</programlisting> - It defines two virtual hosts with nearly identical configuration; the only - difference is the document root directories. To prevent this - duplication, we can use a <literal>let</literal>: -<programlisting> -let - commonConfig = - { adminAddr = "alice@example.org"; - forceSSL = true; - enableACME = true; - }; -in -{ - <xref linkend="opt-services.httpd.virtualHosts"/> = - { "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; }); - "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.com"; }); - }; -} -</programlisting> - The <literal>let commonConfig = <replaceable>...</replaceable></literal> - defines a variable named <literal>commonConfig</literal>. The - <literal>//</literal> operator merges two attribute sets, so the - configuration of the second virtual host is the set - <literal>commonConfig</literal> extended with the document root option. - </para> - - <para> - You can write a <literal>let</literal> wherever an expression is allowed. - Thus, you also could have written: -<programlisting> -{ - <xref linkend="opt-services.httpd.virtualHosts"/> = - let commonConfig = <replaceable>...</replaceable>; in - { "blog.example.org" = (commonConfig // { <replaceable>...</replaceable> }) - "wiki.example.org" = (commonConfig // { <replaceable>...</replaceable> }) - }; -} -</programlisting> - but not <literal>{ let commonConfig = <replaceable>...</replaceable>; in - <replaceable>...</replaceable>; }</literal> since attributes (as opposed to - attribute values) are not expressions. - </para> - - <para> - <emphasis>Functions</emphasis> provide another method of abstraction. For - instance, suppose that we want to generate lots of different virtual hosts, - all with identical configuration except for the document root. This can be done - as follows: -<programlisting> -{ - <xref linkend="opt-services.httpd.virtualHosts"/> = - let - makeVirtualHost = webroot: - { documentRoot = webroot; - adminAddr = "alice@example.org"; - forceSSL = true; - enableACME = true; - }; - in - { "example.org" = (makeVirtualHost "/webroot/example.org"); - "example.com" = (makeVirtualHost "/webroot/example.com"); - "example.gov" = (makeVirtualHost "/webroot/example.gov"); - "example.nl" = (makeVirtualHost "/webroot/example.nl"); - }; -} -</programlisting> - Here, <varname>makeVirtualHost</varname> is a function that takes a single - argument <literal>webroot</literal> and returns the configuration for a virtual - host. That function is then called for several names to produce the list of - virtual host configurations. - </para> -</section> diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml index 02cb78f47e8..19eb2429d0a 100644 --- a/nixos/doc/manual/configuration/adding-custom-packages.xml +++ b/nixos/doc/manual/configuration/adding-custom-packages.xml @@ -25,7 +25,7 @@ xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs tree: <screen> -# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen> +<prompt># </prompt>nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen> </para> <para> diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml index 7ccb5b3664e..19cfb57920d 100644 --- a/nixos/doc/manual/configuration/config-file.xml +++ b/nixos/doc/manual/configuration/config-file.xml @@ -16,9 +16,10 @@ The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this is actually a function that takes at least the two arguments <varname>config</varname> and <varname>pkgs</varname>. (These are explained - later.) The function returns a <emphasis>set</emphasis> of option definitions - (<literal>{ <replaceable>...</replaceable> }</literal>). These definitions - have the form <literal><replaceable>name</replaceable> = + later, in chapter <xref linkend="sec-writing-modules" />) The function returns + a <emphasis>set</emphasis> of option definitions (<literal>{ + <replaceable>...</replaceable> }</literal>). These definitions have the form + <literal><replaceable>name</replaceable> = <replaceable>value</replaceable></literal>, where <replaceable>name</replaceable> is the name of an option and <replaceable>value</replaceable> is its value. For example, diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml index 5526dea247c..a374c6a8707 100644 --- a/nixos/doc/manual/configuration/config-syntax.xml +++ b/nixos/doc/manual/configuration/config-syntax.xml @@ -19,7 +19,7 @@ xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix constructs useful in NixOS configuration files. </para> <xi:include href="config-file.xml" /> - <xi:include href="abstractions.xml" /> + <xi:include href="../from_md/configuration/abstractions.section.xml" /> <xi:include href="modularity.xml" /> <xi:include href="summary.xml" /> </chapter> diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 6eb8f50baca..6949189b888 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -18,10 +18,12 @@ <xi:include href="user-mgmt.xml" /> <xi:include href="file-systems.xml" /> <xi:include href="x-windows.xml" /> + <xi:include href="wayland.xml" /> <xi:include href="gpu-accel.xml" /> <xi:include href="xfce.xml" /> <xi:include href="networking.xml" /> <xi:include href="linux-kernel.xml" /> + <xi:include href="subversion.xml" /> <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> <xi:include href="profiles.xml" /> <xi:include href="kubernetes.xml" /> diff --git a/nixos/doc/manual/configuration/file-systems.xml b/nixos/doc/manual/configuration/file-systems.xml index 3ac02a975eb..42c59844ff4 100644 --- a/nixos/doc/manual/configuration/file-systems.xml +++ b/nixos/doc/manual/configuration/file-systems.xml @@ -23,12 +23,12 @@ <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html">systemd-fstab-generator</link>. The filesystem will be mounted automatically unless <literal>"noauto"</literal> is present in <link - linkend="opt-fileSystems._name__.options">options</link>. + linkend="opt-fileSystems._name_.options">options</link>. <literal>"noauto"</literal> filesystems can be mounted explicitly using <command>systemctl</command> e.g. <command>systemctl start data.mount</command>. Mount points are created automatically if they don’t already exist. For - <option><link linkend="opt-fileSystems._name__.device">device</link></option>, + <option><link linkend="opt-fileSystems._name_.device">device</link></option>, it’s best to use the topology-independent device aliases in <filename>/dev/disk/by-label</filename> and <filename>/dev/disk/by-uuid</filename>, as these don’t change if the @@ -36,7 +36,7 @@ </para> <para> You can usually omit the file system type - (<option><link linkend="opt-fileSystems._name__.fsType">fsType</link></option>), + (<option><link linkend="opt-fileSystems._name_.fsType">fsType</link></option>), since <command>mount</command> can usually detect the type and load the necessary kernel module automatically. However, if the file system is needed at early boot (in the initial ramdisk) and is not <literal>ext2</literal>, @@ -49,9 +49,10 @@ System startup will fail if any of the filesystems fails to mount, dropping you to the emergency shell. You can make a mount asynchronous and non-critical by adding - <literal><link linkend="opt-fileSystems._name__.options">options</link> = [ + <literal><link linkend="opt-fileSystems._name_.options">options</link> = [ "nofail" ];</literal>. </para> </note> <xi:include href="luks-file-systems.xml" /> + <xi:include href="../from_md/configuration/sshfs-file-systems.section.xml" /> </chapter> diff --git a/nixos/doc/manual/configuration/gpu-accel.xml b/nixos/doc/manual/configuration/gpu-accel.xml index 251e5c26ba4..9aa9be86a06 100644 --- a/nixos/doc/manual/configuration/gpu-accel.xml +++ b/nixos/doc/manual/configuration/gpu-accel.xml @@ -65,16 +65,16 @@ Platform Vendor Advanced Micro Devices, Inc.</screen> <title>AMD</title> <para> - Modern AMD <link - xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics - Core Next</link> (GCN) GPUs are supported through the - <package>rocm-opencl-icd</package> package. Adding this package to - <xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL - support: - - <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ - rocm-opencl-icd -];</programlisting> + Modern AMD <link + xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics + Core Next</link> (GCN) GPUs are supported through the + <package>rocm-opencl-icd</package> package. Adding this package to + <xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL + support: + + <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ + rocm-opencl-icd + ];</programlisting> </para> </section> @@ -100,9 +100,9 @@ Platform Vendor Advanced Micro Devices, Inc.</screen> support. For example, for Gen8 and later GPUs, the following configuration can be used: - <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ - intel-compute-runtime -];</programlisting> + <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ + intel-compute-runtime + ];</programlisting> </para> </section> @@ -173,26 +173,30 @@ GPU1: <title>AMD</title> <para> - Modern AMD <link - xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics - Core Next</link> (GCN) GPUs are supported through either radv, which is - part of <package>mesa</package>, or the <package>amdvlk</package> package. - Adding the <package>amdvlk</package> package to - <xref linkend="opt-hardware.opengl.extraPackages"/> makes both drivers - available for applications and lets them choose. A specific driver can - be forced as follows: - - <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ - <package>amdvlk</package> -]; - -# For amdvlk -<xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES = - "/run/opengl-driver/share/vulkan/icd.d/amd_icd64.json"; -# For radv -<xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES = - "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; -</programlisting> + Modern AMD <link + xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics + Core Next</link> (GCN) GPUs are supported through either radv, which is + part of <package>mesa</package>, or the <package>amdvlk</package> package. + Adding the <package>amdvlk</package> package to + <xref linkend="opt-hardware.opengl.extraPackages"/> makes amdvlk the + default driver and hides radv and lavapipe from the device list. A + specific driver can be forced as follows: + + <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ + pkgs.<package>amdvlk</package> + ]; + + # To enable Vulkan support for 32-bit applications, also add: + <xref linkend="opt-hardware.opengl.extraPackages32"/> = [ + pkgs.driversi686Linux.<package>amdvlk</package> + ]; + + # Force radv + <xref linkend="opt-environment.variables"/>.AMD_VULKAN_ICD = "RADV"; + # Or + <xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; + </programlisting> </para> </section> </section> diff --git a/nixos/doc/manual/configuration/ipv4-config.xml b/nixos/doc/manual/configuration/ipv4-config.xml index 71ddf41491b..884becf0979 100644 --- a/nixos/doc/manual/configuration/ipv4-config.xml +++ b/nixos/doc/manual/configuration/ipv4-config.xml @@ -10,7 +10,7 @@ automatically configure network interfaces. However, you can configure an interface manually as follows: <programlisting> -<link linkend="opt-networking.interfaces._name__.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ { +<link linkend="opt-networking.interfaces._name_.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ { address = "192.168.1.2"; prefixLength = 24; } ]; diff --git a/nixos/doc/manual/configuration/ipv6-config.xml b/nixos/doc/manual/configuration/ipv6-config.xml index 675a5d9a260..45e85dbf3df 100644 --- a/nixos/doc/manual/configuration/ipv6-config.xml +++ b/nixos/doc/manual/configuration/ipv6-config.xml @@ -7,8 +7,12 @@ <para> IPv6 is enabled by default. Stateless address autoconfiguration is used to - automatically assign IPv6 addresses to all interfaces. You can disable IPv6 - support globally by setting: + automatically assign IPv6 addresses to all interfaces, and Privacy + Extensions (RFC 4946) are enabled by default. You can adjust the default + for this by setting <xref linkend="opt-networking.tempAddresses"/>. + This option may be overridden on a per-interface basis by + <xref linkend="opt-networking.interfaces._name_.tempAddress"/>. + You can disable IPv6 support globally by setting: <programlisting> <xref linkend="opt-networking.enableIPv6"/> = false; </programlisting> @@ -26,7 +30,7 @@ As with IPv4 networking interfaces are automatically configured via DHCPv6. You can configure an interface manually: <programlisting> -<link linkend="opt-networking.interfaces._name__.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ { +<link linkend="opt-networking.interfaces._name_.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ { address = "fe00:aa:bb:cc::2"; prefixLength = 64; } ]; diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml index 644d3a33ffd..529ac1b1cd4 100644 --- a/nixos/doc/manual/configuration/linux-kernel.xml +++ b/nixos/doc/manual/configuration/linux-kernel.xml @@ -87,7 +87,7 @@ nixpkgs.config.packageOverrides = pkgs: You can edit the config with this snippet (by default <command>make menuconfig</command> won't work out of the box on nixos): <screen><![CDATA[ - nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})' + nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})' ]]></screen> or you can let nixpkgs generate the configuration. Nixpkgs generates it via answering the interactive kernel utility <command>make config</command>. The @@ -126,13 +126,13 @@ nixpkgs.config.packageOverrides = pkgs: <literal>mellanox</literal> drivers. </para> -<screen><![CDATA[ -$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev -$ nix-shell '<nixpkgs>' -A linuxPackages.kernel -$ unpackPhase -$ cd linux-* -$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules -# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko -]]></screen> +<screen> +<prompt>$ </prompt>nix-build '<nixpkgs>' -A linuxPackages.kernel.dev +<prompt>$ </prompt>nix-shell '<nixpkgs>' -A linuxPackages.kernel +<prompt>$ </prompt>unpackPhase +<prompt>$ </prompt>cd linux-* +<prompt>$ </prompt>make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules +<prompt># </prompt>insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko +</screen> </section> </chapter> diff --git a/nixos/doc/manual/configuration/luks-file-systems.xml b/nixos/doc/manual/configuration/luks-file-systems.xml index d3007843d68..d8654d71ac0 100644 --- a/nixos/doc/manual/configuration/luks-file-systems.xml +++ b/nixos/doc/manual/configuration/luks-file-systems.xml @@ -11,7 +11,7 @@ you create an encrypted Ext4 file system on the device <filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>: <screen> -# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d +<prompt># </prompt>cryptsetup luksFormat <replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable> WARNING! ======== @@ -21,17 +21,21 @@ Are you sure? (Type uppercase yes): YES Enter LUKS passphrase: *** Verify passphrase: *** -# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted +<prompt># </prompt>cryptsetup luksOpen <replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable> <replaceable>crypted</replaceable> Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: *** -# mkfs.ext4 /dev/mapper/crypted +<prompt># </prompt>mkfs.ext4 /dev/mapper/<replaceable>crypted</replaceable> </screen> - To ensure that this file system is automatically mounted at boot time as + The LUKS volume should be automatically picked up by + <command>nixos-generate-config</command>, but you might want to verify that your + <filename>hardware-configuration.nix</filename> looks correct. + + To manually ensure that the system is automatically mounted at boot time as <filename>/</filename>, add the following to <filename>configuration.nix</filename>: <programlisting> -<link linkend="opt-boot.initrd.luks.devices._name__.device">boot.initrd.luks.devices.crypted.device</link> = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d"; -<xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/crypted"; +<link linkend="opt-boot.initrd.luks.devices._name_.device">boot.initrd.luks.devices.crypted.device</link> = "<replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable>"; +<xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/<replaceable>crypted</replaceable>"; </programlisting> Should grub be used as bootloader, and <filename>/boot</filename> is located on an encrypted partition, it is necessary to add the following grub option: @@ -45,11 +49,11 @@ Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: *** and add it as a new key to our existing device <filename>/dev/sda2</filename>: <screen> -# export FIDO2_LABEL="/dev/sda2 @ $HOSTNAME" -# fido2luks credential "$FIDO2_LABEL" +<prompt># </prompt>export FIDO2_LABEL="<replaceable>/dev/sda2</replaceable> @ $HOSTNAME" +<prompt># </prompt>fido2luks credential "$FIDO2_LABEL" f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7 -# fido2luks -i add-key /dev/sda2 f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7 +<prompt># </prompt>fido2luks -i add-key <replaceable>/dev/sda2</replaceable> <replaceable>f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7</replaceable> Password: Password (again): Old password: @@ -60,13 +64,13 @@ Added to key to device /dev/sda2, slot: 2 To ensure that this file system is decrypted using the FIDO2 compatible key, add the following to <filename>configuration.nix</filename>: <programlisting> <link linkend="opt-boot.initrd.luks.fido2Support">boot.initrd.luks.fido2Support</link> = true; -<link linkend="opt-boot.initrd.luks.devices._name__.fido2.credential">boot.initrd.luks.devices."/dev/sda2".fido2.credential</link> = "f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7"; +<link linkend="opt-boot.initrd.luks.devices._name_.fido2.credential">boot.initrd.luks.devices."<replaceable>/dev/sda2</replaceable>".fido2.credential</link> = "<replaceable>f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7</replaceable>"; </programlisting> You can also use the FIDO2 passwordless setup, but for security reasons, you might want to enable it only when your device is PIN protected, such as <link xlink:href="https://trezor.io/">Trezor</link>. <programlisting> -<link linkend="opt-boot.initrd.luks.devices._name__.fido2.passwordLess">boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess</link> = true; +<link linkend="opt-boot.initrd.luks.devices._name_.fido2.passwordLess">boot.initrd.luks.devices."<replaceable>/dev/sda2</replaceable>".fido2.passwordLess</link> = true; </programlisting> </para> </section> diff --git a/nixos/doc/manual/configuration/modularity.xml b/nixos/doc/manual/configuration/modularity.xml index 532a2c615e4..d6eee4e9d76 100644 --- a/nixos/doc/manual/configuration/modularity.xml +++ b/nixos/doc/manual/configuration/modularity.xml @@ -133,7 +133,7 @@ true <programlisting> { config, pkgs, ... }: -let netConfig = { hostName }: { +let netConfig = hostName: { networking.hostName = hostName; networking.useDHCP = false; }; diff --git a/nixos/doc/manual/configuration/network-manager.xml b/nixos/doc/manual/configuration/network-manager.xml index 3953e0ffe85..94d229fd803 100644 --- a/nixos/doc/manual/configuration/network-manager.xml +++ b/nixos/doc/manual/configuration/network-manager.xml @@ -19,7 +19,7 @@ All users that should have permission to change network settings must belong to the <code>networkmanager</code> group: <programlisting> -<link linkend="opt-users.users._name__.extraGroups">users.users.alice.extraGroups</link> = [ "networkmanager" ]; +<link linkend="opt-users.users._name_.extraGroups">users.users.alice.extraGroups</link> = [ "networkmanager" ]; </programlisting> </para> diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml index 02cf811e0bd..8369e9c9c85 100644 --- a/nixos/doc/manual/configuration/networking.xml +++ b/nixos/doc/manual/configuration/networking.xml @@ -15,5 +15,6 @@ <xi:include href="firewall.xml" /> <xi:include href="wireless.xml" /> <xi:include href="ad-hoc-network-config.xml" /> + <xi:include href="renaming-interfaces.xml" /> <!-- TODO: OpenVPN, NAT --> </chapter> diff --git a/nixos/doc/manual/configuration/profiles/clone-config.xml b/nixos/doc/manual/configuration/profiles/clone-config.xml index 04fa1643d0f..9c70cf35204 100644 --- a/nixos/doc/manual/configuration/profiles/clone-config.xml +++ b/nixos/doc/manual/configuration/profiles/clone-config.xml @@ -16,6 +16,6 @@ On images where the installation media also becomes an installation target, copying over <literal>configuration.nix</literal> should be disabled by setting <literal>installer.cloneConfig</literal> to <literal>false</literal>. - For example, this is done in <literal>sd-image-aarch64.nix</literal>. + For example, this is done in <literal>sd-image-aarch64-installer.nix</literal>. </para> </section> diff --git a/nixos/doc/manual/configuration/profiles/hardened.xml b/nixos/doc/manual/configuration/profiles/hardened.xml index dc83fc837e2..4a51754cc7a 100644 --- a/nixos/doc/manual/configuration/profiles/hardened.xml +++ b/nixos/doc/manual/configuration/profiles/hardened.xml @@ -7,7 +7,7 @@ <para> A profile with most (vanilla) hardening options enabled by default, - potentially at the cost of features and performance. + potentially at the cost of stability, features and performance. </para> <para> @@ -21,4 +21,12 @@ xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix"> profile source</literal> for further detail on which settings are altered. </para> + <warning> + <para> + This profile enables options that are known to affect system + stability. If you experience any stability issues when using the + profile, try disabling it. If you report an issue and use this + profile, always mention that you do. + </para> + </warning> </section> diff --git a/nixos/doc/manual/configuration/profiles/qemu-guest.xml b/nixos/doc/manual/configuration/profiles/qemu-guest.xml index 5d055c45d2d..3ed97b94b51 100644 --- a/nixos/doc/manual/configuration/profiles/qemu-guest.xml +++ b/nixos/doc/manual/configuration/profiles/qemu-guest.xml @@ -11,8 +11,7 @@ </para> <para> - It makes virtio modules available on the initrd, sets the system time from - the hardware clock to work around a bug in qemu-kvm, and - <link linkend="opt-security.rngd.enable">enables rngd</link>. + It makes virtio modules available on the initrd and sets the system time from + the hardware clock to work around a bug in qemu-kvm. </para> </section> diff --git a/nixos/doc/manual/configuration/renaming-interfaces.xml b/nixos/doc/manual/configuration/renaming-interfaces.xml new file mode 100644 index 00000000000..d760bb3a4da --- /dev/null +++ b/nixos/doc/manual/configuration/renaming-interfaces.xml @@ -0,0 +1,67 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-rename-ifs"> + <title>Renaming network interfaces</title> + + <para> + NixOS uses the udev + <link xlink:href="https://systemd.io/PREDICTABLE_INTERFACE_NAMES/">predictable naming scheme</link> + to assign names to network interfaces. This means that by default + cards are not given the traditional names like + <literal>eth0</literal> or <literal>eth1</literal>, whose order can + change unpredictably across reboots. Instead, relying on physical + locations and firmware information, the scheme produces names like + <literal>ens1</literal>, <literal>enp2s0</literal>, etc. + </para> + + <para> + These names are predictable but less memorable and not necessarily + stable: for example installing new hardware or changing firmware + settings can result in a + <link xlink:href="https://github.com/systemd/systemd/issues/3715#issue-165347602">name change</link>. + If this is undesirable, for example if you have a single ethernet + card, you can revert to the traditional scheme by setting + <xref linkend="opt-networking.usePredictableInterfaceNames"/> to + <literal>false</literal>. + </para> + + <section xml:id="sec-custom-ifnames"> + <title>Assigning custom names</title> + <para> + In case there are multiple interfaces of the same type, it’s better to + assign custom names based on the device hardware address. For + example, we assign the name <literal>wan</literal> to the interface + with MAC address <literal>52:54:00:12:01:01</literal> using a + netword link unit: + </para> + <programlisting> + <link linkend="opt-systemd.network.links">systemd.network.links."10-wan"</link> = { + matchConfig.MACAddress = "52:54:00:12:01:01"; + linkConfig.Name = "wan"; + }; + </programlisting> + <para> + Note that links are directly read by udev, <emphasis>not networkd</emphasis>, + and will work even if networkd is disabled. + </para> + <para> + Alternatively, we can use a plain old udev rule: + </para> + <programlisting> + <link linkend="opt-services.udev.initrdRules">services.udev.initrdRules</link> = '' + SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \ + ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan" + ''; + </programlisting> + + <warning><para> + The rule must be installed in the initrd using + <literal>services.udev.initrdRules</literal>, not the usual + <literal>services.udev.extraRules</literal> option. This is to avoid race + conditions with other programs controlling the interface. + </para></warning> + </section> + +</section> diff --git a/nixos/doc/manual/configuration/ssh.xml b/nixos/doc/manual/configuration/ssh.xml index a4af1b96583..95ad3edff93 100644 --- a/nixos/doc/manual/configuration/ssh.xml +++ b/nixos/doc/manual/configuration/ssh.xml @@ -20,7 +20,7 @@ follows: <!-- FIXME: this might not work if the user is unmanaged. --> <programlisting> -<link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.alice.openssh.authorizedKeys.keys</link> = +<link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.alice.openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ]; </programlisting> </para> diff --git a/nixos/doc/manual/configuration/sshfs-file-systems.section.md b/nixos/doc/manual/configuration/sshfs-file-systems.section.md new file mode 100644 index 00000000000..4625fce03d5 --- /dev/null +++ b/nixos/doc/manual/configuration/sshfs-file-systems.section.md @@ -0,0 +1,104 @@ +# SSHFS File Systems {#sec-sshfs-file-systems} + +[SSHFS][sshfs] is a [FUSE][fuse] filesystem that allows easy access to directories on a remote machine using the SSH File Transfer Protocol (SFTP). +It means that if you have SSH access to a machine, no additional setup is needed to mount a directory. + +[sshfs]: https://github.com/libfuse/sshfs +[fuse]: https://en.wikipedia.org/wiki/Filesystem_in_Userspace + +## Interactive mounting {#sec-sshfs-interactive} + +In NixOS, SSHFS is packaged as <package>sshfs</package>. +Once installed, mounting a directory interactively is simple as running: +```ShellSession +$ sshfs my-user@example.com:/my-dir /mnt/my-dir +``` +Like any other FUSE file system, the directory is unmounted using: +```ShellSession +$ fusermount -u /mnt/my-dir +``` + +## Non-interactive mounting {#sec-sshfs-non-interactive} + +Mounting non-interactively requires some precautions because `sshfs` will run at boot and under a different user (root). +For obvious reason, you can't input a password, so public key authentication using an unencrypted key is needed. +To create a new key without a passphrase you can do: +```ShellSession +$ ssh-keygen -t ed25519 -P '' -f example-key +Generating public/private ed25519 key pair. +Your identification has been saved in test-key +Your public key has been saved in test-key.pub +The key fingerprint is: +SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation +``` +To keep the key safe, change the ownership to `root:root` and make sure the permissions are `600`: +OpenSSH normally refuses to use the key if it's not well-protected. + +The file system can be configured in NixOS via the usual [fileSystems](options.html#opt-fileSystems) option. +Here's a typical setup: +```nix +{ + system.fsPackages = [ pkgs.sshfs ]; + + fileSystems."/mnt/my-dir" = { + device = "my-user@example.com:/my-dir/"; + fsType = "sshfs"; + options = + [ # Filesystem options + "allow_other" # for non-root access + "_netdev" # this is a network fs + "x-systemd.automount" # mount on demand + + # SSH options + "reconnect" # handle connection drops + "ServerAliveInterval=15" # keep connections alive + "IdentityFile=/var/secrets/example-key" + ]; + }; +} +``` +More options from `ssh_config(5)` can be given as well, for example you can change the default SSH port or specify a jump proxy: +```nix +{ + options = + [ "ProxyJump=bastion@example.com" + "Port=22" + ]; +} +``` +It's also possible to change the `ssh` command used by SSHFS to connect to the server. +For example: +```nix +{ + options = + [ (builtins.replaceStrings [" "] ["\\040"] + "ssh_command=${pkgs.openssh}/bin/ssh -v -L 8080:localhost:80") + ]; + +} +``` + +::: {.note} +The escaping of spaces is needed because every option is written to the `/etc/fstab` file, which is a space-separated table. +::: + +### Troubleshooting {#sec-sshfs-troubleshooting} + +If you're having a hard time figuring out why mounting is failing, you can add the option `"debug"`. +This enables a verbose log in SSHFS that you can access via: +```ShellSession +$ journalctl -u $(systemd-escape -p /mnt/my-dir/).mount +Jun 22 11:41:18 workstation mount[87790]: SSHFS version 3.7.1 +Jun 22 11:41:18 workstation mount[87793]: executing <ssh> <-x> <-a> <-oClearAllForwardings=yes> <-oServerAliveInterval=15> <-oIdentityFile=/var/secrets/wrong-key> <-2> <my-user@example.com> <-s> <sftp> +Jun 22 11:41:19 workstation mount[87793]: my-user@example.com: Permission denied (publickey). +Jun 22 11:41:19 workstation mount[87790]: read: Connection reset by peer +Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Mount process exited, code=exited, status=1/FAILURE +Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Failed with result 'exit-code'. +Jun 22 11:41:19 workstation systemd[1]: Failed to mount /mnt/my-dir. +Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Consumed 54ms CPU time, received 2.3K IP traffic, sent 2.7K IP traffic. +``` + +::: {.note} +If the mount point contains special characters it needs to be escaped using `systemd-escape`. +This is due to the way systemd converts paths into unit names. +::: diff --git a/nixos/doc/manual/configuration/subversion.xml b/nixos/doc/manual/configuration/subversion.xml new file mode 100644 index 00000000000..940d63cc4e6 --- /dev/null +++ b/nixos/doc/manual/configuration/subversion.xml @@ -0,0 +1,140 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="module-services-subversion"> + <title>Subversion</title> + + <para> + <link xlink:href="https://subversion.apache.org/">Subversion</link> + is a centralized version-control system. It can use a <link + xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety + of protocols</link> for communication between client and server. + </para> + <section xml:id="module-services-subversion-apache-httpd"> + <title>Subversion inside Apache HTTP</title> + + <para> + This section focuses on configuring a web-based server on top of + the Apache HTTP server, which uses + <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link + xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link> + for communication. + </para> + + <para>For more information on the general setup, please refer to + the <link + xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the + appropriate section of the Subversion book</link>. + </para> + + <para>To configure, include in + <literal>/etc/nixos/configuration.nix</literal> code to activate + Apache HTTP, setting <xref linkend="opt-services.httpd.adminAddr" /> + appropriately: + </para> + + <para> +<programlisting> + services.httpd.enable = true; + services.httpd.adminAddr = ...; + networking.firewall.allowedTCPPorts = [ 80 443 ]; +</programlisting> + </para> + + <para>For a simple Subversion server with basic authentication, + configure the Subversion module for Apache as follows, setting + <literal>hostName</literal> and <literal>documentRoot</literal> + appropriately, and <literal>SVNParentPath</literal> to the parent + directory of the repositories, + <literal>AuthzSVNAccessFile</literal> to the location of the + <code>.authz</code> file describing access permission, and + <literal>AuthUserFile</literal> to the password file. + </para> + <para> +<programlisting> +services.httpd.extraModules = [ + # note that order is *super* important here + { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; } + { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; } + ]; + services.httpd.virtualHosts = { + "svn" = { + hostName = HOSTNAME; + documentRoot = DOCUMENTROOT; + locations."/svn".extraConfig = '' + DAV svn + SVNParentPath REPO_PARENT + AuthzSVNAccessFile ACCESS_FILE + AuthName "SVN Repositories" + AuthType Basic + AuthUserFile PASSWORD_FILE + Require valid-user + ''; + } +</programlisting> + </para> + + <para> + The key <code>"svn"</code> is just a symbolic name identifying the + virtual host. The <code>"/svn"</code> in + <code>locations."/svn".extraConfig</code> is the path underneath + which the repositories will be served. + </para> + + <para><link + xlink:href="https://wiki.archlinux.org/index.php/Subversion">This + page</link> explains how to set up the Subversion configuration + itself. This boils down to the following: + </para> + <para> + Underneath <literal>REPO_PARENT</literal> repositories can be set up + as follows: + </para> + <para> +<screen> +<prompt>$ </prompt> svn create REPO_NAME +</screen> + </para> + <para>Repository files need to be accessible by + <literal>wwwrun</literal>: + </para> + <para> +<screen> +<prompt>$ </prompt> chown -R wwwrun:wwwrun REPO_PARENT +</screen> + </para> + <para> + The password file <literal>PASSWORD_FILE</literal> can be created as follows: + </para> + <para> +<screen> +<prompt>$ </prompt> htpasswd -cs PASSWORD_FILE USER_NAME +</screen> + </para> + <para> + Additional users can be set up similarly, omitting the + <code>c</code> flag: + </para> + <para> +<screen> +<prompt>$ </prompt> htpasswd -s PASSWORD_FILE USER_NAME +</screen> + </para> + <para> + The file describing access permissions + <literal>ACCESS_FILE</literal> will look something like + the following: + </para> + <para> +<programlisting> +[/] +* = r + +[REPO_NAME:/] +USER_NAME = rw +</programlisting> + </para> + <para>The Subversion repositories will be accessible as <code>http://HOSTNAME/svn/REPO_NAME</code>.</para> + </section> +</chapter> diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml index 4b1710f3a2b..e83e7b75ef5 100644 --- a/nixos/doc/manual/configuration/user-mgmt.xml +++ b/nixos/doc/manual/configuration/user-mgmt.xml @@ -11,11 +11,11 @@ that a user account named <literal>alice</literal> shall exist: <programlisting> <xref linkend="opt-users.users"/>.alice = { - <link linkend="opt-users.users._name__.isNormalUser">isNormalUser</link> = true; - <link linkend="opt-users.users._name__.home">home</link> = "/home/alice"; - <link linkend="opt-users.users._name__.description">description</link> = "Alice Foobar"; - <link linkend="opt-users.users._name__.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ]; - <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; + <link linkend="opt-users.users._name_.isNormalUser">isNormalUser</link> = true; + <link linkend="opt-users.users._name_.home">home</link> = "/home/alice"; + <link linkend="opt-users.users._name_.description">description</link> = "Alice Foobar"; + <link linkend="opt-users.users._name_.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ]; + <link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; }; </programlisting> Note that <literal>alice</literal> is a member of the @@ -36,9 +36,9 @@ account will cease to exist. Also, imperative commands for managing users and groups, such as useradd, are no longer available. Passwords may still be assigned by setting the user's - <link linkend="opt-users.users._name__.hashedPassword">hashedPassword</link> + <link linkend="opt-users.users._name_.hashedPassword">hashedPassword</link> option. A hashed password can be generated using <command>mkpasswd -m - sha-512</command> after installing the <literal>mkpasswd</literal> package. + sha-512</command>. </para> <para> A user ID (uid) is assigned automatically. You can also specify a uid @@ -62,24 +62,24 @@ uid = 1000; <command>useradd</command>, <command>groupmod</command> and so on. For instance, to create a user account named <literal>alice</literal>: <screen> -# useradd -m alice</screen> +<prompt># </prompt>useradd -m <replaceable>alice</replaceable></screen> To make all nix tools available to this new user use `su - USER` which opens a login shell (==shell that loads the profile) for given user. This will create the ~/.nix-defexpr symlink. So run: <screen> -# su - alice -c "true"</screen> +<prompt># </prompt>su - <replaceable>alice</replaceable> -c "true"</screen> The flag <option>-m</option> causes the creation of a home directory for the new user, which is generally what you want. The user does not have an initial password and therefore cannot log in. A password can be set using the <command>passwd</command> utility: <screen> -# passwd alice +<prompt># </prompt>passwd <replaceable>alice</replaceable> Enter new UNIX password: *** Retype new UNIX password: *** </screen> A user can be deleted using <command>userdel</command>: <screen> -# userdel -r alice</screen> +<prompt># </prompt>userdel -r <replaceable>alice</replaceable></screen> The flag <option>-r</option> deletes the user’s home directory. Accounts can be modified using <command>usermod</command>. Unix groups can be managed using <command>groupadd</command>, <command>groupmod</command> and diff --git a/nixos/doc/manual/configuration/wayland.xml b/nixos/doc/manual/configuration/wayland.xml new file mode 100644 index 00000000000..2aefda3e22c --- /dev/null +++ b/nixos/doc/manual/configuration/wayland.xml @@ -0,0 +1,33 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-wayland"> + <title>Wayland</title> + + <para> + While X11 (see <xref linkend="sec-x11"/>) is still the primary display + technology on NixOS, Wayland support is steadily improving. + Where X11 separates the X Server and the window manager, on Wayland those + are combined: a Wayland Compositor is like an X11 window manager, but also + embeds the Wayland 'Server' functionality. This means it is sufficient to + install a Wayland Compositor such as <package>sway</package> without + separately enabling a Wayland server: +<programlisting> +<xref linkend="opt-programs.sway.enable"/> = true; +</programlisting> + This installs the <package>sway</package> compositor along with some + essential utilities. Now you can start <package>sway</package> from the TTY + console. + </para> + + <para> + If you are using a wlroots-based compositor, like sway, and want to be able to + share your screen, you might want to activate this option: +<programlisting> +<xref linkend="opt-xdg.portal.wlr.enable"/> = true; +</programlisting> + and configure Pipewire using <xref linkend="opt-services.pipewire.enable"/> + and related options. + </para> +</chapter> diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml index 18f0be5e7f3..f9121508d7d 100644 --- a/nixos/doc/manual/configuration/x-windows.xml +++ b/nixos/doc/manual/configuration/x-windows.xml @@ -25,7 +25,7 @@ <programlisting> <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true; <xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true; -<xref linkend="opt-services.xserver.desktopManager.gnome3.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.gnome.enable"/> = true; <xref linkend="opt-services.xserver.desktopManager.mate.enable"/> = true; <xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true; <xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true; @@ -58,7 +58,7 @@ </programlisting> The X server can then be started manually: <screen> -# systemctl start display-manager.service +<prompt># </prompt>systemctl start display-manager.service </screen> </para> <para> @@ -150,7 +150,6 @@ <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy390" ]; <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ]; <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ]; -<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy173" ]; </programlisting> You may need to reboot after enabling this driver to prevent a clash with other kernel modules. @@ -159,21 +158,16 @@ <simplesect xml:id="sec-x11--graphics-cards-amd"> <title>Proprietary AMD drivers</title> <para> - AMD provides a proprietary driver for its graphics cards that has better 3D - performance than the X.org drivers. It is not enabled by default because - it’s not free software. You can enable it as follows: + AMD provides a proprietary driver for its graphics cards that is not + enabled by default because it’s not Free Software, is often broken + in nixpkgs and as of this writing doesn't offer more features or + performance. If you still want to use it anyway, you need to explicitly set: <programlisting> -<xref linkend="opt-services.xserver.videoDrivers"/> = [ "ati_unfree" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "amdgpu-pro" ]; </programlisting> You will need to reboot after enabling this driver to prevent a clash with other kernel modules. </para> - <note> - <para> - For recent AMD GPUs you most likely want to keep either the defaults - or <literal>"amdgpu"</literal> (both free). - </para> - </note> </simplesect> <simplesect xml:id="sec-x11-touchpads"> <title>Touchpads</title> @@ -186,7 +180,7 @@ The driver has many options (see <xref linkend="ch-options"/>). For instance, the following disables tap-to-click behavior: <programlisting> -<xref linkend="opt-services.xserver.libinput.tapping"/> = false; +<xref linkend="opt-services.xserver.libinput.touchpad.tapping"/> = false; </programlisting> Note: the use of <literal>services.xserver.synaptics</literal> is deprecated since NixOS 17.09. @@ -197,9 +191,12 @@ <para> GTK themes can be installed either to user profile or system-wide (via <literal>environment.systemPackages</literal>). To make Qt 5 applications - look similar to GTK2 ones, you can install <literal>qt5.qtbase.gtk</literal> - package into your system environment. It should work for all Qt 5 library - versions. + look similar to GTK ones, you can use the following configuration: +<programlisting> +<xref linkend="opt-qt5.enable"/> = true; +<xref linkend="opt-qt5.platformTheme"/> = "gtk2"; +<xref linkend="opt-qt5.style"/> = "gtk2"; +</programlisting> </para> </simplesect> <simplesect xml:id="custom-xkb-layouts"> @@ -210,18 +207,18 @@ XKB </link> keyboard layouts using the option - <option> - <link linkend="opt-services.xserver.extraLayouts"> - services.xserver.extraLayouts - </link> - </option>. + <option><link linkend="opt-services.xserver.extraLayouts"> + services.xserver.extraLayouts</link></option>. + </para> + <para> As a first example, we are going to create a layout based on the basic US layout, with an additional layer to type some greek symbols by pressing the right-alt key. </para> <para> - To do this we are going to create a <literal>us-greek</literal> file - with a <literal>xkb_symbols</literal> section. + Create a file called <literal>us-greek</literal> with the following + content (under a directory called <literal>symbols</literal>; it's + an XKB peculiarity that will help with testing): </para> <programlisting> xkb_symbols "us-greek" @@ -237,26 +234,43 @@ xkb_symbols "us-greek" }; </programlisting> <para> - To install the layout, the filepath, a description and the list of - languages must be given: + A minimal layout specification must include the following: </para> <programlisting> <xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = { description = "US layout with alt-gr greek"; languages = [ "eng" ]; - symbolsFile = /path/to/us-greek; -} + symbolsFile = /yourpath/symbols/us-greek; +}; </programlisting> <note> <para> - The name should match the one given to the + The name (after <literal>extraLayouts.</literal>) should match the one given to the <literal>xkb_symbols</literal> block. </para> </note> <para> - The layout should now be installed and ready to use: try it by - running <literal>setxkbmap us-greek</literal> and type - <literal><alt>+a</literal>. To change the default the usual + Applying this customization requires rebuilding several packages, + and a broken XKB file can lead to the X session crashing at login. + Therefore, you're strongly advised to <emphasis role="strong">test + your layout before applying it</emphasis>: +<screen> +<prompt>$ </prompt>nix-shell -p xorg.xkbcomp +<prompt>$ </prompt>setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY +</screen> + </para> + <para> + You can inspect the predefined XKB files for examples: +<screen> +<prompt>$ </prompt>echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/" +</screen> + </para> + <para> + Once the configuration is applied, and you did a logout/login + cycle, the layout should be ready to use. You can try it by e.g. + running <literal>setxkbmap us-greek</literal> and then type + <literal><alt>+a</literal> (it may not get applied in your + terminal straight away). To change the default, the usual <option> <link linkend="opt-services.xserver.layout"> services.xserver.layout |