diff options
Diffstat (limited to 'nixos/doc/manual/configuration')
43 files changed, 2498 insertions, 0 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/ad-hoc-network-config.section.md b/nixos/doc/manual/configuration/ad-hoc-network-config.section.md new file mode 100644 index 00000000000..4478d77f361 --- /dev/null +++ b/nixos/doc/manual/configuration/ad-hoc-network-config.section.md @@ -0,0 +1,13 @@ +# Ad-Hoc Configuration {#ad-hoc-network-config} + +You can use [](#opt-networking.localCommands) to +specify shell commands to be run at the end of `network-setup.service`. This +is useful for doing network configuration not covered by the existing NixOS +modules. For instance, to statically configure an IPv6 address: + +```nix +networking.localCommands = + '' + ip -6 addr add 2001:610:685:1::1/64 dev eth0 + ''; +``` diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.section.md b/nixos/doc/manual/configuration/ad-hoc-packages.section.md new file mode 100644 index 00000000000..e9d574903a1 --- /dev/null +++ b/nixos/doc/manual/configuration/ad-hoc-packages.section.md @@ -0,0 +1,51 @@ +# Ad-Hoc Package Management {#sec-ad-hoc-packages} + +With the command `nix-env`, you can install and uninstall packages from +the command line. For instance, to install Mozilla Thunderbird: + +```ShellSession +$ nix-env -iA nixos.thunderbird +``` + +If you invoke this as root, the package is installed in the Nix profile +`/nix/var/nix/profiles/default` and visible to all users of the system; +otherwise, the package ends up in +`/nix/var/nix/profiles/per-user/username/profile` and is not visible to +other users. The `-A` flag specifies the package by its attribute name; +without it, the package is installed by matching against its package +name (e.g. `thunderbird`). The latter is slower because it requires +matching against all available Nix packages, and is ambiguous if there +are multiple matching packages. + +Packages come from the NixOS channel. You typically upgrade a package by +updating to the latest version of the NixOS channel: + +```ShellSession +$ nix-channel --update nixos +``` + +and then running `nix-env -i` again. Other packages in the profile are +*not* affected; this is the crucial difference with the declarative +style of package management, where running `nixos-rebuild switch` causes +all packages to be updated to their current versions in the NixOS +channel. You can however upgrade all packages for which there is a newer +version by doing: + +```ShellSession +$ nix-env -u '*' +``` + +A package can be uninstalled using the `-e` flag: + +```ShellSession +$ nix-env -e thunderbird +``` + +Finally, you can roll back an undesirable `nix-env` action: + +```ShellSession +$ nix-env --rollback +``` + +`nix-env` has many more flags. For details, see the nix-env(1) manpage or +the Nix manual. diff --git a/nixos/doc/manual/configuration/adding-custom-packages.section.md b/nixos/doc/manual/configuration/adding-custom-packages.section.md new file mode 100644 index 00000000000..5d1198fb0f4 --- /dev/null +++ b/nixos/doc/manual/configuration/adding-custom-packages.section.md @@ -0,0 +1,74 @@ +# Adding Custom Packages {#sec-custom-packages} + +It's possible that a package you need is not available in NixOS. In that +case, you can do two things. First, you can clone the Nixpkgs +repository, add the package to your clone, and (optionally) submit a +patch or pull request to have it accepted into the main Nixpkgs repository. +This is described in detail in the [Nixpkgs manual](https://nixos.org/nixpkgs/manual). +In short, you clone Nixpkgs: + +```ShellSession +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs +``` + +Then you write and test the package as described in the Nixpkgs manual. +Finally, you add it to [](#opt-environment.systemPackages), e.g. + +```nix +environment.systemPackages = [ pkgs.my-package ]; +``` + +and you run `nixos-rebuild`, specifying your own Nixpkgs tree: + +```ShellSession +# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs +``` + +The second possibility is to add the package outside of the Nixpkgs +tree. For instance, here is how you specify a build of the +[GNU Hello](https://www.gnu.org/software/hello/) package directly in +`configuration.nix`: + +```nix +environment.systemPackages = + let + my-hello = with pkgs; stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; + }; + in + [ my-hello ]; +``` + +Of course, you can also move the definition of `my-hello` into a +separate Nix expression, e.g. + +```nix +environment.systemPackages = [ (import ./my-hello.nix) ]; +``` + +where `my-hello.nix` contains: + +```nix +with import <nixpkgs> {}; # bring all of Nixpkgs into scope + +stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; +} +``` + +This allows testing the package easily: + +```ShellSession +$ nix-build my-hello.nix +$ ./result/bin/hello +Hello, world! +``` diff --git a/nixos/doc/manual/configuration/config-file.section.md b/nixos/doc/manual/configuration/config-file.section.md new file mode 100644 index 00000000000..f21ba113bf8 --- /dev/null +++ b/nixos/doc/manual/configuration/config-file.section.md @@ -0,0 +1,175 @@ +# NixOS Configuration File {#sec-configuration-file} + +The NixOS configuration file generally looks like this: + +```nix +{ config, pkgs, ... }: + +{ option definitions +} +``` + +The first line (`{ config, pkgs, ... }:`) denotes that this is actually +a function that takes at least the two arguments `config` and `pkgs`. +(These are explained later, in chapter [](#sec-writing-modules)) The +function returns a *set* of option definitions (`{ ... }`). +These definitions have the form `name = value`, where `name` is the +name of an option and `value` is its value. For example, + +```nix +{ config, pkgs, ... }: + +{ services.httpd.enable = true; + services.httpd.adminAddr = "alice@example.org"; + services.httpd.virtualHosts.localhost.documentRoot = "/webroot"; +} +``` + +defines a configuration with three option definitions that together +enable the Apache HTTP Server with `/webroot` as the document root. + +Sets can be nested, and in fact dots in option names are shorthand for +defining a set containing another set. For instance, +[](#opt-services.httpd.enable) defines a set named +`services` that contains a set named `httpd`, which in turn contains an +option definition named `enable` with value `true`. This means that the +example above can also be written as: + +```nix +{ config, pkgs, ... }: + +{ services = { + httpd = { + enable = true; + adminAddr = "alice@example.org"; + virtualHosts = { + localhost = { + documentRoot = "/webroot"; + }; + }; + }; + }; +} +``` + +which may be more convenient if you have lots of option definitions that +share the same prefix (such as `services.httpd`). + +NixOS checks your option definitions for correctness. For instance, if +you try to define an option that doesn't exist (that is, doesn't have a +corresponding *option declaration*), `nixos-rebuild` will give an error +like: + +```plain +The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist. +``` + +Likewise, values in option definitions must have a correct type. For +instance, `services.httpd.enable` must be a Boolean (`true` or `false`). +Trying to give it a value of another type, such as a string, will cause +an error: + +```plain +The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean. +``` + +Options have various types of values. The most important are: + +Strings + +: Strings are enclosed in double quotes, e.g. + + ```nix + networking.hostName = "dexter"; + ``` + + Special characters can be escaped by prefixing them with a backslash + (e.g. `\"`). + + Multi-line strings can be enclosed in *double single quotes*, e.g. + + ```nix + networking.extraHosts = + '' + 127.0.0.2 other-localhost + 10.0.0.1 server + ''; + ``` + + The main difference is that it strips from each line a number of + spaces equal to the minimal indentation of the string as a whole + (disregarding the indentation of empty lines), and that characters + like `"` and `\` are not special (making it more convenient for + including things like shell code). See more info about this in the + Nix manual [here](https://nixos.org/nix/manual/#ssec-values). + +Booleans + +: These can be `true` or `false`, e.g. + + ```nix + networking.firewall.enable = true; + networking.firewall.allowPing = false; + ``` + +Integers + +: For example, + + ```nix + boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60; + ``` + + (Note that here the attribute name `net.ipv4.tcp_keepalive_time` is + enclosed in quotes to prevent it from being interpreted as a set + named `net` containing a set named `ipv4`, and so on. This is + because it's not a NixOS option but the literal name of a Linux + kernel setting.) + +Sets + +: Sets were introduced above. They are name/value pairs enclosed in + braces, as in the option definition + + ```nix + fileSystems."/boot" = + { device = "/dev/sda1"; + fsType = "ext4"; + options = [ "rw" "data=ordered" "relatime" ]; + }; + ``` + +Lists + +: The important thing to note about lists is that list elements are + separated by whitespace, like this: + + ```nix + boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; + ``` + + List elements can be any other type, e.g. sets: + + ```nix + swapDevices = [ { device = "/dev/disk/by-label/swap"; } ]; + ``` + +Packages + +: Usually, the packages you need are already part of the Nix Packages + collection, which is a set that can be accessed through the function + argument `pkgs`. Typical uses: + + ```nix + environment.systemPackages = + [ pkgs.thunderbird + pkgs.emacs + ]; + + services.postgresql.package = pkgs.postgresql_10; + ``` + + The latter option definition changes the default PostgreSQL package + used by NixOS's PostgreSQL service to 10.x. For more information on + packages, including how to add new ones, see + [](#sec-custom-packages). diff --git a/nixos/doc/manual/configuration/config-syntax.chapter.md b/nixos/doc/manual/configuration/config-syntax.chapter.md new file mode 100644 index 00000000000..56d093c0f6e --- /dev/null +++ b/nixos/doc/manual/configuration/config-syntax.chapter.md @@ -0,0 +1,19 @@ +# Configuration Syntax {#sec-configuration-syntax} + +The NixOS configuration file `/etc/nixos/configuration.nix` is actually +a *Nix expression*, which is the Nix package manager's purely functional +language for describing how to build packages and configurations. This +means you have all the expressive power of that language at your +disposal, including the ability to abstract over common patterns, which +is very useful when managing complex systems. The syntax and semantics +of the Nix language are fully described in the [Nix +manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions), but +here we give a short overview of the most important constructs useful in +NixOS configuration files. + +```{=docbook} +<xi:include href="config-file.section.xml" /> +<xi:include href="abstractions.section.xml" /> +<xi:include href="modularity.section.xml" /> +<xi:include href="summary.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml new file mode 100644 index 00000000000..b04316cfa48 --- /dev/null +++ b/nixos/doc/manual/configuration/configuration.xml @@ -0,0 +1,31 @@ +<part 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="ch-configuration"> + <title>Configuration</title> + <partintro xml:id="ch-configuration-intro"> + <para> + This chapter describes how to configure various aspects of a NixOS machine + through the configuration file + <filename>/etc/nixos/configuration.nix</filename>. As described in + <xref linkend="sec-changing-config" />, changes to this file only take + effect after you run <command>nixos-rebuild</command>. + </para> + </partintro> + <xi:include href="../from_md/configuration/config-syntax.chapter.xml" /> + <xi:include href="../from_md/configuration/package-mgmt.chapter.xml" /> + <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" /> + <xi:include href="../from_md/configuration/file-systems.chapter.xml" /> + <xi:include href="../from_md/configuration/x-windows.chapter.xml" /> + <xi:include href="../from_md/configuration/wayland.chapter.xml" /> + <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" /> + <xi:include href="../from_md/configuration/xfce.chapter.xml" /> + <xi:include href="../from_md/configuration/networking.chapter.xml" /> + <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" /> + <xi:include href="../from_md/configuration/subversion.chapter.xml" /> + <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> + <xi:include href="../from_md/configuration/profiles.chapter.xml" /> + <xi:include href="../from_md/configuration/kubernetes.chapter.xml" /> +<!-- Apache; libvirtd virtualisation --> +</part> diff --git a/nixos/doc/manual/configuration/customizing-packages.section.md b/nixos/doc/manual/configuration/customizing-packages.section.md new file mode 100644 index 00000000000..bceeeb2d7a1 --- /dev/null +++ b/nixos/doc/manual/configuration/customizing-packages.section.md @@ -0,0 +1,74 @@ +# Customising Packages {#sec-customising-packages} + +Some packages in Nixpkgs have options to enable or disable optional +functionality or change other aspects of the package. For instance, the +Firefox wrapper package (which provides Firefox with a set of plugins +such as the Adobe Flash player) has an option to enable the Google Talk +plugin. It can be set in `configuration.nix` as follows: +`nixpkgs.config.firefox.enableGoogleTalkPlugin = true;` + +::: {.warning} +Unfortunately, Nixpkgs currently lacks a way to query available +configuration options. +::: + +Apart from high-level options, it's possible to tweak a package in +almost arbitrary ways, such as changing or disabling dependencies of a +package. For instance, the Emacs package in Nixpkgs by default has a +dependency on GTK 2. If you want to build it against GTK 3, you can +specify that as follows: + +```nix +environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; +``` + +The function `override` performs the call to the Nix function that +produces Emacs, with the original arguments amended by the set of +arguments specified by you. So here the function argument `gtk` gets the +value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses +are necessary because in Nix, function application binds more weakly +than list construction, so without them, +[](#opt-environment.systemPackages) +would be a list with two elements.) + +Even greater customisation is possible using the function +`overrideAttrs`. While the `override` mechanism above overrides the +arguments of a package function, `overrideAttrs` allows changing the +*attributes* passed to `mkDerivation`. This permits changing any aspect +of the package, such as the source code. For instance, if you want to +override the source code of Emacs, you can say: + +```nix +environment.systemPackages = [ + (pkgs.emacs.overrideAttrs (oldAttrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) +]; +``` + +Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs` +and produces a new derivation in which the original's `name` and `src` +attribute have been replaced by the given values by re-calling +`stdenv.mkDerivation`. The original attributes are accessible via the +function argument, which is conventionally named `oldAttrs`. + +The overrides shown above are not global. They do not affect the +original package; other packages in Nixpkgs continue to depend on the +original rather than the customised package. This means that if another +package in your system depends on the original package, you end up with +two instances of the package. If you want to have everything depend on +your customised instance, you can apply a *global* override as follows: + +```nix +nixpkgs.config.packageOverrides = pkgs: + { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; + }; +``` + +The effect of this definition is essentially equivalent to modifying the +`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs +that depends on `emacs` will be passed your customised instance. +(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides` +refers to the original rather than overridden instance, to prevent an +infinite recursion.) diff --git a/nixos/doc/manual/configuration/declarative-packages.section.md b/nixos/doc/manual/configuration/declarative-packages.section.md new file mode 100644 index 00000000000..337cdf8472e --- /dev/null +++ b/nixos/doc/manual/configuration/declarative-packages.section.md @@ -0,0 +1,46 @@ +# Declarative Package Management {#sec-declarative-package-mgmt} + +With declarative package management, you specify which packages you want +on your system by setting the option +[](#opt-environment.systemPackages). For instance, adding the +following line to `configuration.nix` enables the Mozilla Thunderbird +email application: + +```nix +environment.systemPackages = [ pkgs.thunderbird ]; +``` + +The effect of this specification is that the Thunderbird package from +Nixpkgs will be built or downloaded as part of the system when you run +`nixos-rebuild switch`. + +::: {.note} +Some packages require additional global configuration such as D-Bus or +systemd service registration so adding them to +[](#opt-environment.systemPackages) might not be sufficient. You are +advised to check the [list of options](#ch-options) whether a NixOS +module for the package does not exist. +::: + +You can get a list of the available packages as follows: + +```ShellSession +$ nix-env -qaP '*' --description +nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded +... +``` + +The first column in the output is the *attribute name*, such as +`nixos.thunderbird`. + +Note: the `nixos` prefix tells us that we want to get the package from +the `nixos` channel and works only in CLI tools. In declarative +configuration use `pkgs` prefix (variable). + +To "uninstall" a package, simply remove it from +[](#opt-environment.systemPackages) and run `nixos-rebuild switch`. + +```{=docbook} +<xi:include href="customizing-packages.section.xml" /> +<xi:include href="adding-custom-packages.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/file-systems.chapter.md b/nixos/doc/manual/configuration/file-systems.chapter.md new file mode 100644 index 00000000000..901e2e4f181 --- /dev/null +++ b/nixos/doc/manual/configuration/file-systems.chapter.md @@ -0,0 +1,42 @@ +# File Systems {#ch-file-systems} + +You can define file systems using the `fileSystems` configuration +option. For instance, the following definition causes NixOS to mount the +Ext4 file system on device `/dev/disk/by-label/data` onto the mount +point `/data`: + +```nix +fileSystems."/data" = + { device = "/dev/disk/by-label/data"; + fsType = "ext4"; + }; +``` + +This will create an entry in `/etc/fstab`, which will generate a +corresponding [systemd.mount](https://www.freedesktop.org/software/systemd/man/systemd.mount.html) +unit via [systemd-fstab-generator](https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html). +The filesystem will be mounted automatically unless `"noauto"` is +present in [options](#opt-fileSystems._name_.options). `"noauto"` +filesystems can be mounted explicitly using `systemctl` e.g. +`systemctl start data.mount`. Mount points are created automatically if they don't +already exist. For `device`, it's best to use the topology-independent +device aliases in `/dev/disk/by-label` and `/dev/disk/by-uuid`, as these +don't change if the topology changes (e.g. if a disk is moved to another +IDE controller). + +You can usually omit the file system type (`fsType`), since `mount` 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 `ext2`, `ext3` or `ext4`, then it's best +to specify `fsType` to ensure that the kernel module is available. + +::: {.note} +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 `options = [ "nofail" ];`. +::: + +```{=docbook} +<xi:include href="luks-file-systems.section.xml" /> +<xi:include href="sshfs-file-systems.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/firewall.section.md b/nixos/doc/manual/configuration/firewall.section.md new file mode 100644 index 00000000000..dbf0ffb9273 --- /dev/null +++ b/nixos/doc/manual/configuration/firewall.section.md @@ -0,0 +1,32 @@ +# Firewall {#sec-firewall} + +NixOS has a simple stateful firewall that blocks incoming connections +and other unexpected packets. The firewall applies to both IPv4 and IPv6 +traffic. It is enabled by default. It can be disabled as follows: + +```nix +networking.firewall.enable = false; +``` + +If the firewall is enabled, you can open specific TCP ports to the +outside world: + +```nix +networking.firewall.allowedTCPPorts = [ 80 443 ]; +``` + +Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is +enabled (`services.openssh.enable = true`). UDP ports can be opened through +[](#opt-networking.firewall.allowedUDPPorts). + +To open ranges of TCP ports: + +```nix +networking.firewall.allowedTCPPortRanges = [ + { from = 4000; to = 4007; } + { from = 8000; to = 8010; } +]; +``` + +Similarly, UDP port ranges can be opened through +[](#opt-networking.firewall.allowedUDPPortRanges). diff --git a/nixos/doc/manual/configuration/gpu-accel.chapter.md b/nixos/doc/manual/configuration/gpu-accel.chapter.md new file mode 100644 index 00000000000..08b6af5d98a --- /dev/null +++ b/nixos/doc/manual/configuration/gpu-accel.chapter.md @@ -0,0 +1,204 @@ +# GPU acceleration {#sec-gpu-accel} + +NixOS provides various APIs that benefit from GPU hardware acceleration, +such as VA-API and VDPAU for video playback; OpenGL and Vulkan for 3D +graphics; and OpenCL for general-purpose computing. This chapter +describes how to set up GPU hardware acceleration (as far as this is not +done automatically) and how to verify that hardware acceleration is +indeed used. + +Most of the aforementioned APIs are agnostic with regards to which +display server is used. Consequently, these instructions should apply +both to the X Window System and Wayland compositors. + +## OpenCL {#sec-gpu-accel-opencl} + +[OpenCL](https://en.wikipedia.org/wiki/OpenCL) is a general compute API. +It is used by various applications such as Blender and Darktable to +accelerate certain operations. + +OpenCL applications load drivers through the *Installable Client Driver* +(ICD) mechanism. In this mechanism, an ICD file specifies the path to +the OpenCL driver for a particular GPU family. In NixOS, there are two +ways to make ICD files visible to the ICD loader. The first is through +the `OCL_ICD_VENDORS` environment variable. This variable can contain a +directory which is scanned by the ICL loader for ICD files. For example: + +```ShellSession +$ export \ + OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/ +``` + +The second mechanism is to add the OpenCL driver package to +[](#opt-hardware.opengl.extraPackages). +This links the ICD file under `/run/opengl-driver`, where it will be visible +to the ICD loader. + +The proper installation of OpenCL drivers can be verified through the +`clinfo` command of the clinfo package. This command will report the +number of hardware devices that is found and give detailed information +for each device: + +```ShellSession +$ clinfo | head -n3 +Number of platforms 1 +Platform Name AMD Accelerated Parallel Processing +Platform Vendor Advanced Micro Devices, Inc. +``` + +### AMD {#sec-gpu-accel-opencl-amd} + +Modern AMD [Graphics Core +Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are +supported through the rocm-opencl-icd package. Adding this package to +[](#opt-hardware.opengl.extraPackages) +enables OpenCL support: + +```nix +hardware.opengl.extraPackages = [ + rocm-opencl-icd +]; +``` + +### Intel {#sec-gpu-accel-opencl-intel} + +[Intel Gen8 and later +GPUs](https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8) +are supported by the Intel NEO OpenCL runtime that is provided by the +intel-compute-runtime package. For Gen7 GPUs, the deprecated Beignet +runtime can be used, which is provided by the beignet package. The +proprietary Intel OpenCL runtime, in the intel-ocl package, is an +alternative for Gen7 GPUs. + +The intel-compute-runtime, beignet, or intel-ocl package can be added to +[](#opt-hardware.opengl.extraPackages) +to enable OpenCL support. For example, for Gen8 and later GPUs, the following +configuration can be used: + +```nix +hardware.opengl.extraPackages = [ + intel-compute-runtime +]; +``` + +## Vulkan {#sec-gpu-accel-vulkan} + +[Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API)) is a graphics and +compute API for GPUs. It is used directly by games or indirectly though +compatibility layers like +[DXVK](https://github.com/doitsujin/dxvk/wiki). + +By default, if [](#opt-hardware.opengl.driSupport) +is enabled, mesa is installed and provides Vulkan for supported hardware. + +Similar to OpenCL, Vulkan drivers are loaded through the *Installable +Client Driver* (ICD) mechanism. ICD files for Vulkan are JSON files that +specify the path to the driver library and the supported Vulkan version. +All successfully loaded drivers are exposed to the application as +different GPUs. In NixOS, there are two ways to make ICD files visible +to Vulkan applications: an environment variable and a module option. + +The first option is through the `VK_ICD_FILENAMES` environment variable. +This variable can contain multiple JSON files, separated by `:`. For +example: + +```ShellSession +$ export \ + VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json +``` + +The second mechanism is to add the Vulkan driver package to +[](#opt-hardware.opengl.extraPackages). +This links the ICD file under `/run/opengl-driver`, where it will be +visible to the ICD loader. + +The proper installation of Vulkan drivers can be verified through the +`vulkaninfo` command of the vulkan-tools package. This command will +report the hardware devices and drivers found, in this example output +amdvlk and radv: + +```ShellSession +$ vulkaninfo | grep GPU + GPU id : 0 (Unknown AMD GPU) + GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1)) + ... +GPU0: + deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU + deviceName = Unknown AMD GPU +GPU1: + deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU +``` + +A simple graphical application that uses Vulkan is `vkcube` from the +vulkan-tools package. + +### AMD {#sec-gpu-accel-vulkan-amd} + +Modern AMD [Graphics Core +Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are +supported through either radv, which is part of mesa, or the amdvlk +package. Adding the amdvlk package to +[](#opt-hardware.opengl.extraPackages) +makes amdvlk the default driver and hides radv and lavapipe from the device list. +A specific driver can be forced as follows: + +```nix +hardware.opengl.extraPackages = [ + pkgs.amdvlk +]; + +# To enable Vulkan support for 32-bit applications, also add: +hardware.opengl.extraPackages32 = [ + pkgs.driversi686Linux.amdvlk +]; + +# Force radv +environment.variables.AMD_VULKAN_ICD = "RADV"; +# Or +environment.variables.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; +``` + +## Common issues {#sec-gpu-accel-common-issues} + +### User permissions {#sec-gpu-accel-common-issues-permissions} + +Except where noted explicitly, it should not be necessary to adjust user +permissions to use these acceleration APIs. In the default +configuration, GPU devices have world-read/write permissions +(`/dev/dri/renderD*`) or are tagged as `uaccess` (`/dev/dri/card*`). The +access control lists of devices with the `uaccess` tag will be updated +automatically when a user logs in through `systemd-logind`. For example, +if the user *jane* is logged in, the access control list should look as +follows: + +```ShellSession +$ getfacl /dev/dri/card0 +# file: dev/dri/card0 +# owner: root +# group: video +user::rw- +user:jane:rw- +group::rw- +mask::rw- +other::--- +``` + +If you disabled (this functionality of) `systemd-logind`, you may need +to add the user to the `video` group and log in again. + +### Mixing different versions of nixpkgs {#sec-gpu-accel-common-issues-mixing-nixpkgs} + +The *Installable Client Driver* (ICD) mechanism used by OpenCL and +Vulkan loads runtimes into its address space using `dlopen`. Mixing an +ICD loader mechanism and runtimes from different version of nixpkgs may +not work. For example, if the ICD loader uses an older version of glibc +than the runtime, the runtime may not be loadable due to missing +symbols. Unfortunately, the loader will generally be quiet about such +issues. + +If you suspect that you are running into library version mismatches +between an ICL loader and a runtime, you could run an application with +the `LD_DEBUG` variable set to get more diagnostic information. For +example, OpenCL can be tested with `LD_DEBUG=files clinfo`, which should +report missing symbols. diff --git a/nixos/doc/manual/configuration/ipv4-config.section.md b/nixos/doc/manual/configuration/ipv4-config.section.md new file mode 100644 index 00000000000..c73024b856d --- /dev/null +++ b/nixos/doc/manual/configuration/ipv4-config.section.md @@ -0,0 +1,35 @@ +# IPv4 Configuration {#sec-ipv4} + +By default, NixOS uses DHCP (specifically, `dhcpcd`) to automatically +configure network interfaces. However, you can configure an interface +manually as follows: + +```nix +networking.interfaces.eth0.ipv4.addresses = [ { + address = "192.168.1.2"; + prefixLength = 24; +} ]; +``` + +Typically you'll also want to set a default gateway and set of name +servers: + +```nix +networking.defaultGateway = "192.168.1.1"; +networking.nameservers = [ "8.8.8.8" ]; +``` + +::: {.note} +Statically configured interfaces are set up by the systemd service +`interface-name-cfg.service`. The default gateway and name server +configuration is performed by `network-setup.service`. +::: + +The host name is set using [](#opt-networking.hostName): + +```nix +networking.hostName = "cartman"; +``` + +The default host name is `nixos`. Set it to the empty string (`""`) to +allow the DHCP server to provide the host name. diff --git a/nixos/doc/manual/configuration/ipv6-config.section.md b/nixos/doc/manual/configuration/ipv6-config.section.md new file mode 100644 index 00000000000..ce66f53ed47 --- /dev/null +++ b/nixos/doc/manual/configuration/ipv6-config.section.md @@ -0,0 +1,42 @@ +# IPv6 Configuration {#sec-ipv6} + +IPv6 is enabled by default. Stateless address autoconfiguration is used +to automatically assign IPv6 addresses to all interfaces, and Privacy +Extensions (RFC 4946) are enabled by default. You can adjust the default +for this by setting [](#opt-networking.tempAddresses). This option +may be overridden on a per-interface basis by +[](#opt-networking.interfaces._name_.tempAddress). You can disable +IPv6 support globally by setting: + +```nix +networking.enableIPv6 = false; +``` + +You can disable IPv6 on a single interface using a normal sysctl (in +this example, we use interface `eth0`): + +```nix +boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true; +``` + +As with IPv4 networking interfaces are automatically configured via +DHCPv6. You can configure an interface manually: + +```nix +networking.interfaces.eth0.ipv6.addresses = [ { + address = "fe00:aa:bb:cc::2"; + prefixLength = 64; +} ]; +``` + +For configuring a gateway, optionally with explicitly specified +interface: + +```nix +networking.defaultGateway6 = { + address = "fe00::1"; + interface = "enp0s3"; +}; +``` + +See [](#sec-ipv4) for similar examples and additional information. diff --git a/nixos/doc/manual/configuration/kubernetes.chapter.md b/nixos/doc/manual/configuration/kubernetes.chapter.md new file mode 100644 index 00000000000..93787577be9 --- /dev/null +++ b/nixos/doc/manual/configuration/kubernetes.chapter.md @@ -0,0 +1,104 @@ +# Kubernetes {#sec-kubernetes} + +The NixOS Kubernetes module is a collective term for a handful of +individual submodules implementing the Kubernetes cluster components. + +There are generally two ways of enabling Kubernetes on NixOS. One way is +to enable and configure cluster components appropriately by hand: + +```nix +services.kubernetes = { + apiserver.enable = true; + controllerManager.enable = true; + scheduler.enable = true; + addonManager.enable = true; + proxy.enable = true; + flannel.enable = true; +}; +``` + +Another way is to assign cluster roles (\"master\" and/or \"node\") to +the host. This enables apiserver, controllerManager, scheduler, +addonManager, kube-proxy and etcd: + +```nix +services.kubernetes.roles = [ "master" ]; +``` + +While this will enable the kubelet and kube-proxy only: + +```nix +services.kubernetes.roles = [ "node" ]; +``` + +Assigning both the master and node roles is usable if you want a single +node Kubernetes cluster for dev or testing purposes: + +```nix +services.kubernetes.roles = [ "master" "node" ]; +``` + +Note: Assigning either role will also default both +[](#opt-services.kubernetes.flannel.enable) +and [](#opt-services.kubernetes.easyCerts) +to true. This sets up flannel as CNI and activates automatic PKI bootstrapping. + +As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled +ports on kubernetes components. Thus, from NixOS 19.03 all plain HTTP +ports have been disabled by default. While opening insecure ports is +still possible, it is recommended not to bind these to other interfaces +than loopback. To re-enable the insecure port on the apiserver, see options: +[](#opt-services.kubernetes.apiserver.insecurePort) and +[](#opt-services.kubernetes.apiserver.insecureBindAddress) + +::: {.note} +As of NixOS 19.03, it is mandatory to configure: +[](#opt-services.kubernetes.masterAddress). +The masterAddress must be resolveable and routeable by all cluster nodes. +In single node clusters, this can be set to `localhost`. +::: + +Role-based access control (RBAC) authorization mode is enabled by +default. This means that anonymous requests to the apiserver secure port +will expectedly cause a permission denied error. All cluster components +must therefore be configured with x509 certificates for two-way tls +communication. The x509 certificate subject section determines the roles +and permissions granted by the apiserver to perform clusterwide or +namespaced operations. See also: [ Using RBAC +Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). + +The NixOS kubernetes module provides an option for automatic certificate +bootstrapping and configuration, +[](#opt-services.kubernetes.easyCerts). +The PKI bootstrapping process involves setting up a certificate authority (CA) +daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert +for the cluster, and uses the CA-cert for signing subordinate certs issued +to each of the cluster components. Subsequently, the certmgr daemon monitors +active certificates and renews them when needed. For single node Kubernetes +clusters, setting [](#opt-services.kubernetes.easyCerts) += true is sufficient and no further action is required. For joining extra node +machines to an existing cluster on the other hand, establishing initial +trust is mandatory. + +To add new nodes to the cluster: On any (non-master) cluster node where +[](#opt-services.kubernetes.easyCerts) +is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH. +Given a token on stdin, it will copy the token to the kubernetes secrets directory +and restart the certmgr service. As requested certificates are issued, the +script will restart kubernetes cluster components as needed for them to +pick up new keypairs. + +::: {.note} +Multi-master (HA) clusters are not supported by the easyCerts module. +::: + +In order to interact with an RBAC-enabled cluster as an administrator, +one needs to have cluster-admin privileges. By default, when easyCerts +is enabled, a cluster-admin kubeconfig file is generated and linked into +`/etc/kubernetes/cluster-admin.kubeconfig` as determined by +[](#opt-services.kubernetes.pki.etcClusterAdminKubeconfig). +`export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make +kubectl use this kubeconfig to access and authenticate the cluster. The +cluster-admin kubeconfig references an auto-generated keypair owned by +root. Thus, only root on the kubernetes master may obtain cluster-admin +rights by means of this file. diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md new file mode 100644 index 00000000000..1d06543d4f1 --- /dev/null +++ b/nixos/doc/manual/configuration/linux-kernel.chapter.md @@ -0,0 +1,140 @@ +# Linux Kernel {#sec-kernel-config} + +You can override the Linux kernel and associated packages using the +option `boot.kernelPackages`. For instance, this selects the Linux 3.10 +kernel: + +```nix +boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10; +``` + +Note that this not only replaces the kernel, but also packages that are +specific to the kernel version, such as the NVIDIA video drivers. This +ensures that driver packages are consistent with the kernel. + +While `pkgs.linuxKernel.packages` contains all available kernel packages, +you may want to use one of the unversioned `pkgs.linuxPackages_*` aliases +such as `pkgs.linuxPackages_latest`, that are kept up to date with new +versions. + +The default Linux kernel configuration should be fine for most users. +You can see the configuration of your current kernel with the following +command: + +```ShellSession +zcat /proc/config.gz +``` + +If you want to change the kernel configuration, you can use the +`packageOverrides` feature (see [](#sec-customising-packages)). For +instance, to enable support for the kernel debugger KGDB: + +```nix +nixpkgs.config.packageOverrides = pkgs: pkgs.lib.recursiveUpdate pkgs { + linuxKernel.kernels.linux_5_10 = pkgs.linuxKernel.kernels.linux_5_10.override { + extraConfig = '' + KGDB y + ''; + }; +}; +``` + +`extraConfig` takes a list of Linux kernel configuration options, one +per line. The name of the option should not include the prefix +`CONFIG_`. The option value is typically `y`, `n` or `m` (to build +something as a kernel module). + +Kernel modules for hardware devices are generally loaded automatically +by `udev`. You can force a module to be loaded via +[](#opt-boot.kernelModules), e.g. + +```nix +boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; +``` + +If the module is required early during the boot (e.g. to mount the root +file system), you can use [](#opt-boot.initrd.kernelModules): + +```nix +boot.initrd.kernelModules = [ "cifs" ]; +``` + +This causes the specified modules and their dependencies to be added to +the initial ramdisk. + +Kernel runtime parameters can be set through +[](#opt-boot.kernel.sysctl), e.g. + +```nix +boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; +``` + +sets the kernel's TCP keepalive time to 120 seconds. To see the +available parameters, run `sysctl -a`. + +## Customize your kernel {#sec-linux-config-customizing} + +The first step before compiling the kernel is to generate an appropriate +`.config` configuration. Either you pass your own config via the +`configfile` setting of `linuxKernel.manualConfig`: + +```nix +custom-kernel = let base_kernel = linuxKernel.kernels.linux_4_9; + in super.linuxKernel.manualConfig { + inherit (super) stdenv hostPlatform; + inherit (base_kernel) src; + version = "${base_kernel.version}-custom"; + + configfile = /home/me/my_kernel_config; + allowImportFromDerivation = true; +}; +``` + +You can edit the config with this snippet (by default `make + menuconfig` won\'t work out of the box on nixos): + +```ShellSession +nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})' +``` + +or you can let nixpkgs generate the configuration. Nixpkgs generates it +via answering the interactive kernel utility `make config`. The answers +depend on parameters passed to +`pkgs/os-specific/linux/kernel/generic.nix` (which you can influence by +overriding `extraConfig, autoModules, + modDirVersion, preferBuiltin, extraConfig`). + +```nix +mptcp93.override ({ + name="mptcp-local"; + + ignoreConfigErrors = true; + autoModules = false; + kernelPreferBuiltin = true; + + enableParallelBuilding = true; + + extraConfig = '' + DEBUG_KERNEL y + FRAME_POINTER y + KGDB y + KGDB_SERIAL_CONSOLE y + DEBUG_INFO y + ''; +}); +``` + +## Developing kernel modules {#sec-linux-config-developing-modules} + +When developing kernel modules it\'s often convenient to run +edit-compile-run loop as quickly as possible. See below snippet as an +example of developing `mellanox` drivers. + +```ShellSession +$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev +$ nix-shell '<nixpkgs>' -A linuxPackages.kernel +$ unpackPhase +$ cd linux-* +$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules +# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko +``` diff --git a/nixos/doc/manual/configuration/luks-file-systems.section.md b/nixos/doc/manual/configuration/luks-file-systems.section.md new file mode 100644 index 00000000000..b5d0407d165 --- /dev/null +++ b/nixos/doc/manual/configuration/luks-file-systems.section.md @@ -0,0 +1,77 @@ +# LUKS-Encrypted File Systems {#sec-luks-file-systems} + +NixOS supports file systems that are encrypted using *LUKS* (Linux +Unified Key Setup). For example, here is how you create an encrypted +Ext4 file system on the device +`/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d`: + +```ShellSession +# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d + +WARNING! +======== +This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably. + +Are you sure? (Type uppercase yes): YES +Enter LUKS passphrase: *** +Verify passphrase: *** + +# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted +Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: *** + +# mkfs.ext4 /dev/mapper/crypted +``` + +The LUKS volume should be automatically picked up by +`nixos-generate-config`, but you might want to verify that your +`hardware-configuration.nix` looks correct. To manually ensure that the +system is automatically mounted at boot time as `/`, add the following +to `configuration.nix`: + +```nix +boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d"; +fileSystems."/".device = "/dev/mapper/crypted"; +``` + +Should grub be used as bootloader, and `/boot` is located on an +encrypted partition, it is necessary to add the following grub option: + +```nix +boot.loader.grub.enableCryptodisk = true; +``` + +## FIDO2 {#sec-luks-file-systems-fido2} + +NixOS also supports unlocking your LUKS-Encrypted file system using a +FIDO2 compatible token. In the following example, we will create a new +FIDO2 credential and add it as a new key to our existing device +`/dev/sda2`: + +```ShellSession +# export FIDO2_LABEL="/dev/sda2 @ $HOSTNAME" +# fido2luks credential "$FIDO2_LABEL" +f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7 + +# fido2luks -i add-key /dev/sda2 f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7 +Password: +Password (again): +Old password: +Old password (again): +Added to key to device /dev/sda2, slot: 2 +``` + +To ensure that this file system is decrypted using the FIDO2 compatible +key, add the following to `configuration.nix`: + +```nix +boot.initrd.luks.fido2Support = true; +boot.initrd.luks.devices."/dev/sda2".fido2.credential = "f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7"; +``` + +You can also use the FIDO2 passwordless setup, but for security reasons, +you might want to enable it only when your device is PIN protected, such +as [Trezor](https://trezor.io/). + +```nix +boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = true; +``` diff --git a/nixos/doc/manual/configuration/modularity.section.md b/nixos/doc/manual/configuration/modularity.section.md new file mode 100644 index 00000000000..3395ace20c4 --- /dev/null +++ b/nixos/doc/manual/configuration/modularity.section.md @@ -0,0 +1,133 @@ +# Modularity {#sec-modularity} + +The NixOS configuration mechanism is modular. If your +`configuration.nix` becomes too big, you can split it into multiple +files. Likewise, if you have multiple NixOS configurations (e.g. for +different computers) with some commonality, you can move the common +configuration into a shared file. + +Modules have exactly the same syntax as `configuration.nix`. In fact, +`configuration.nix` is itself a module. You can use other modules by +including them from `configuration.nix`, e.g.: + +```nix +{ config, pkgs, ... }: + +{ imports = [ ./vpn.nix ./kde.nix ]; + services.httpd.enable = true; + environment.systemPackages = [ pkgs.emacs ]; + ... +} +``` + +Here, we include two modules from the same directory, `vpn.nix` and +`kde.nix`. The latter might look like this: + +```nix +{ config, pkgs, ... }: + +{ services.xserver.enable = true; + services.xserver.displayManager.sddm.enable = true; + services.xserver.desktopManager.plasma5.enable = true; + environment.systemPackages = [ pkgs.vim ]; +} +``` + +Note that both `configuration.nix` and `kde.nix` define the option +[](#opt-environment.systemPackages). When multiple modules define an +option, NixOS will try to *merge* the definitions. In the case of +[](#opt-environment.systemPackages), that's easy: the lists of +packages can simply be concatenated. The value in `configuration.nix` is +merged last, so for list-type options, it will appear at the end of the +merged list. If you want it to appear first, you can use `mkBefore`: + +```nix +boot.kernelModules = mkBefore [ "kvm-intel" ]; +``` + +This causes the `kvm-intel` kernel module to be loaded before any other +kernel modules. + +For other types of options, a merge may not be possible. For instance, +if two modules define [](#opt-services.httpd.adminAddr), +`nixos-rebuild` will give an error: + +```plain +The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'. +``` + +When that happens, it's possible to force one definition take precedence +over the others: + +```nix +services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org"; +``` + +When using multiple modules, you may need to access configuration values +defined in other modules. This is what the `config` function argument is +for: it contains the complete, merged system configuration. That is, +`config` is the result of combining the configurations returned by every +module [^1] . For example, here is a module that adds some packages to +[](#opt-environment.systemPackages) only if +[](#opt-services.xserver.enable) is set to `true` somewhere else: + +```nix +{ config, pkgs, ... }: + +{ environment.systemPackages = + if config.services.xserver.enable then + [ pkgs.firefox + pkgs.thunderbird + ] + else + [ ]; +} +``` + +With multiple modules, it may not be obvious what the final value of a +configuration option is. The command `nixos-option` allows you to find +out: + +```ShellSession +$ nixos-option services.xserver.enable +true + +$ nixos-option boot.kernelModules +[ "tun" "ipv6" "loop" ... ] +``` + +Interactive exploration of the configuration is possible using `nix + repl`, a read-eval-print loop for Nix expressions. A typical use: + +```ShellSession +$ nix repl '<nixpkgs/nixos>' + +nix-repl> config.networking.hostName +"mandark" + +nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts +[ "example.org" "example.gov" ] +``` + +While abstracting your configuration, you may find it useful to generate +modules using code, instead of writing files. The example below would +have the same effect as importing a file which sets those options. + +```nix +{ config, pkgs, ... }: + +let netConfig = hostName: { + networking.hostName = hostName; + networking.useDHCP = false; +}; + +in + +{ imports = [ (netConfig "nixos.localdomain") ]; } +``` + +[^1]: If you're wondering how it's possible that the (indirect) *result* + of a function is passed as an *input* to that same function: that's + because Nix is a "lazy" language --- it only computes values when + they are needed. This works as long as no individual configuration + value depends on itself. diff --git a/nixos/doc/manual/configuration/network-manager.section.md b/nixos/doc/manual/configuration/network-manager.section.md new file mode 100644 index 00000000000..4bda21d34a1 --- /dev/null +++ b/nixos/doc/manual/configuration/network-manager.section.md @@ -0,0 +1,42 @@ +# NetworkManager {#sec-networkmanager} + +To facilitate network configuration, some desktop environments use +NetworkManager. You can enable NetworkManager by setting: + +```nix +networking.networkmanager.enable = true; +``` + +some desktop managers (e.g., GNOME) enable NetworkManager automatically +for you. + +All users that should have permission to change network settings must +belong to the `networkmanager` group: + +```nix +users.users.alice.extraGroups = [ "networkmanager" ]; +``` + +NetworkManager is controlled using either `nmcli` or `nmtui` +(curses-based terminal user interface). See their manual pages for +details on their usage. Some desktop environments (GNOME, KDE) have +their own configuration tools for NetworkManager. On XFCE, there is no +configuration tool for NetworkManager by default: by enabling +[](#opt-programs.nm-applet.enable), the graphical applet will be +installed and will launch automatically when the graphical session is +started. + +::: {.note} +`networking.networkmanager` and `networking.wireless` (WPA Supplicant) +can be used together if desired. To do this you need to instruct +NetworkManager to ignore those interfaces like: + +```nix +networking.networkmanager.unmanaged = [ + "*" "except:type:wwan" "except:type:gsm" +]; +``` + +Refer to the option description for the exact syntax and references to +external documentation. +::: diff --git a/nixos/doc/manual/configuration/networking.chapter.md b/nixos/doc/manual/configuration/networking.chapter.md new file mode 100644 index 00000000000..529dc0610bd --- /dev/null +++ b/nixos/doc/manual/configuration/networking.chapter.md @@ -0,0 +1,16 @@ +# Networking {#sec-networking} + +This section describes how to configure networking components +on your NixOS machine. + +```{=docbook} +<xi:include href="network-manager.section.xml" /> +<xi:include href="ssh.section.xml" /> +<xi:include href="ipv4-config.section.xml" /> +<xi:include href="ipv6-config.section.xml" /> +<xi:include href="firewall.section.xml" /> +<xi:include href="wireless.section.xml" /> +<xi:include href="ad-hoc-network-config.section.xml" /> +<xi:include href="renaming-interfaces.section.xml" /> +``` +<!-- TODO: OpenVPN, NAT --> diff --git a/nixos/doc/manual/configuration/package-mgmt.chapter.md b/nixos/doc/manual/configuration/package-mgmt.chapter.md new file mode 100644 index 00000000000..a6c414be59a --- /dev/null +++ b/nixos/doc/manual/configuration/package-mgmt.chapter.md @@ -0,0 +1,18 @@ +# Package Management {#sec-package-management} + +This section describes how to add additional packages to your system. +NixOS has two distinct styles of package management: + +- *Declarative*, where you declare what packages you want in your + `configuration.nix`. Every time you run `nixos-rebuild`, NixOS will + ensure that you get a consistent set of binaries corresponding to + your specification. + +- *Ad hoc*, where you install, upgrade and uninstall packages via the + `nix-env` command. This style allows mixing packages from different + Nixpkgs versions. It's the only choice for non-root users. + +```{=docbook} +<xi:include href="declarative-packages.section.xml" /> +<xi:include href="ad-hoc-packages.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/profiles.chapter.md b/nixos/doc/manual/configuration/profiles.chapter.md new file mode 100644 index 00000000000..b4ae1b7d3fa --- /dev/null +++ b/nixos/doc/manual/configuration/profiles.chapter.md @@ -0,0 +1,34 @@ +# Profiles {#ch-profiles} + +In some cases, it may be desirable to take advantage of commonly-used, +predefined configurations provided by nixpkgs, but different from those +that come as default. This is a role fulfilled by NixOS\'s Profiles, +which come as files living in `<nixpkgs/nixos/modules/profiles>`. That +is to say, expected usage is to add them to the imports list of your +`/etc/configuration.nix` as such: + +```nix +imports = [ + <nixpkgs/nixos/modules/profiles/profile-name.nix> +]; +``` + +Even if some of these profiles seem only useful in the context of +install media, many are actually intended to be used in real installs. + +What follows is a brief explanation on the purpose and use-case for each +profile. Detailing each option configured by each one is out of scope. + +```{=docbook} +<xi:include href="profiles/all-hardware.section.xml" /> +<xi:include href="profiles/base.section.xml" /> +<xi:include href="profiles/clone-config.section.xml" /> +<xi:include href="profiles/demo.section.xml" /> +<xi:include href="profiles/docker-container.section.xml" /> +<xi:include href="profiles/graphical.section.xml" /> +<xi:include href="profiles/hardened.section.xml" /> +<xi:include href="profiles/headless.section.xml" /> +<xi:include href="profiles/installation-device.section.xml" /> +<xi:include href="profiles/minimal.section.xml" /> +<xi:include href="profiles/qemu-guest.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/profiles/all-hardware.section.md b/nixos/doc/manual/configuration/profiles/all-hardware.section.md new file mode 100644 index 00000000000..e2dd7c76089 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/all-hardware.section.md @@ -0,0 +1,11 @@ +# All Hardware {#sec-profile-all-hardware} + +Enables all hardware supported by NixOS: i.e., all firmware is included, and +all devices from which one may boot are enabled in the initrd. Its primary +use is in the NixOS installation CDs. + +The enabled kernel modules include support for SATA and PATA, SCSI +(partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and +Hyper-V. Additionally, [](#opt-hardware.enableAllFirmware) is +enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically +installed. diff --git a/nixos/doc/manual/configuration/profiles/base.section.md b/nixos/doc/manual/configuration/profiles/base.section.md new file mode 100644 index 00000000000..59b3068fda3 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/base.section.md @@ -0,0 +1,7 @@ +# Base {#sec-profile-base} + +Defines the software packages included in the "minimal" installation CD. It +installs several utilities useful in a simple recovery or install media, such +as a text-mode web browser, and tools for manipulating block devices, +networking, hardware diagnostics, and filesystems (with their respective +kernel modules). diff --git a/nixos/doc/manual/configuration/profiles/clone-config.section.md b/nixos/doc/manual/configuration/profiles/clone-config.section.md new file mode 100644 index 00000000000..e2583715e51 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/clone-config.section.md @@ -0,0 +1,11 @@ +# Clone Config {#sec-profile-clone-config} + +This profile is used in installer images. It provides an editable +configuration.nix that imports all the modules that were also used when +creating the image in the first place. As a result it allows users to edit +and rebuild the live-system. + +On images where the installation media also becomes an installation target, +copying over `configuration.nix` should be disabled by +setting `installer.cloneConfig` to `false`. +For example, this is done in `sd-image-aarch64-installer.nix`. diff --git a/nixos/doc/manual/configuration/profiles/demo.section.md b/nixos/doc/manual/configuration/profiles/demo.section.md new file mode 100644 index 00000000000..0a0df483c12 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/demo.section.md @@ -0,0 +1,4 @@ +# Demo {#sec-profile-demo} + +This profile just enables a `demo` user, with password `demo`, uid `1000`, `wheel` group and +[autologin in the SDDM display manager](#opt-services.xserver.displayManager.autoLogin). diff --git a/nixos/doc/manual/configuration/profiles/docker-container.section.md b/nixos/doc/manual/configuration/profiles/docker-container.section.md new file mode 100644 index 00000000000..f3e29b92f5e --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/docker-container.section.md @@ -0,0 +1,7 @@ +# Docker Container {#sec-profile-docker-container} + +This is the profile from which the Docker images are generated. It prepares a +working system by importing the [Minimal](#sec-profile-minimal) and +[Clone Config](#sec-profile-clone-config) profiles, and +setting appropriate configuration options that are useful inside a container +context, like [](#opt-boot.isContainer). diff --git a/nixos/doc/manual/configuration/profiles/graphical.section.md b/nixos/doc/manual/configuration/profiles/graphical.section.md new file mode 100644 index 00000000000..aaea5c8c028 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/graphical.section.md @@ -0,0 +1,10 @@ +# Graphical {#sec-profile-graphical} + +Defines a NixOS configuration with the Plasma 5 desktop. It's used by the +graphical installation CD. + +It sets [](#opt-services.xserver.enable), +[](#opt-services.xserver.displayManager.sddm.enable), +[](#opt-services.xserver.desktopManager.plasma5.enable), +and [](#opt-services.xserver.libinput.enable) to true. It also +includes glxinfo and firefox in the system packages list. diff --git a/nixos/doc/manual/configuration/profiles/hardened.section.md b/nixos/doc/manual/configuration/profiles/hardened.section.md new file mode 100644 index 00000000000..9fb5e18c384 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/hardened.section.md @@ -0,0 +1,20 @@ +# Hardened {#sec-profile-hardened} + +A profile with most (vanilla) hardening options enabled by default, +potentially at the cost of stability, features and performance. + +This includes a hardened kernel, and limiting the system information +available to processes through the `/sys` and +`/proc` filesystems. It also disables the User Namespaces +feature of the kernel, which stops Nix from being able to build anything +(this particular setting can be overriden via +[](#opt-security.allowUserNamespaces)). See the +[profile source](https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix) +for further detail on which settings are altered. + +::: {.warning} +This profile enables options that are known to affect system +stability. If you experience any stability issues when using the +profile, try disabling it. If you report an issue and use this +profile, always mention that you do. +::: diff --git a/nixos/doc/manual/configuration/profiles/headless.section.md b/nixos/doc/manual/configuration/profiles/headless.section.md new file mode 100644 index 00000000000..d185a9a774b --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/headless.section.md @@ -0,0 +1,9 @@ +# Headless {#sec-profile-headless} + +Common configuration for headless machines (e.g., Amazon EC2 instances). + +Disables [sound](#opt-sound.enable), +[vesa](#opt-boot.vesa), serial consoles, +[emergency mode](#opt-systemd.enableEmergencyMode), +[grub splash images](#opt-boot.loader.grub.splashImage) +and configures the kernel to reboot automatically on panic. diff --git a/nixos/doc/manual/configuration/profiles/installation-device.section.md b/nixos/doc/manual/configuration/profiles/installation-device.section.md new file mode 100644 index 00000000000..ae9f8fa7757 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/installation-device.section.md @@ -0,0 +1,24 @@ +# Installation Device {#sec-profile-installation-device} + +Provides a basic configuration for installation devices like CDs. +This enables redistributable firmware, includes the +[Clone Config profile](#sec-profile-clone-config) +and a copy of the Nixpkgs channel, so `nixos-install` +works out of the box. + +Documentation for [Nixpkgs](#opt-documentation.enable) +and [NixOS](#opt-documentation.nixos.enable) are +forcefully enabled (to override the +[Minimal profile](#sec-profile-minimal) preference); the +NixOS manual is shown automatically on TTY 8, udisks is disabled. +Autologin is enabled as `nixos` user, while passwordless +login as both `root` and `nixos` is possible. +Passwordless `sudo` is enabled too. +[wpa_supplicant](#opt-networking.wireless.enable) is +enabled, but configured to not autostart. + +It is explained how to login, start the ssh server, and if available, +how to start the display manager. + +Several settings are tweaked so that the installer has a better chance of +succeeding under low-memory environments. diff --git a/nixos/doc/manual/configuration/profiles/minimal.section.md b/nixos/doc/manual/configuration/profiles/minimal.section.md new file mode 100644 index 00000000000..02a3b65ae42 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/minimal.section.md @@ -0,0 +1,9 @@ +# Minimal {#sec-profile-minimal} + +This profile defines a small NixOS configuration. It does not contain any +graphical stuff. It's a very short file that enables +[noXlibs](#opt-environment.noXlibs), sets +[](#opt-i18n.supportedLocales) to +only support the user-selected locale, +[disables packages' documentation](#opt-documentation.enable), +and [disables sound](#opt-sound.enable). diff --git a/nixos/doc/manual/configuration/profiles/qemu-guest.section.md b/nixos/doc/manual/configuration/profiles/qemu-guest.section.md new file mode 100644 index 00000000000..d7e3cae9cb0 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/qemu-guest.section.md @@ -0,0 +1,7 @@ +# QEMU Guest {#sec-profile-qemu-guest} + +This profile contains common configuration for virtual machines running under +QEMU (using virtio). + +It makes virtio modules available on the initrd and sets the system time from +the hardware clock to work around a bug in qemu-kvm. diff --git a/nixos/doc/manual/configuration/renaming-interfaces.section.md b/nixos/doc/manual/configuration/renaming-interfaces.section.md new file mode 100644 index 00000000000..18390c959b2 --- /dev/null +++ b/nixos/doc/manual/configuration/renaming-interfaces.section.md @@ -0,0 +1,51 @@ +# Renaming network interfaces {#sec-rename-ifs} + +NixOS uses the udev [predictable naming +scheme](https://systemd.io/PREDICTABLE_INTERFACE_NAMES/) to assign names +to network interfaces. This means that by default cards are not given +the traditional names like `eth0` or `eth1`, whose order can change +unpredictably across reboots. Instead, relying on physical locations and +firmware information, the scheme produces names like `ens1`, `enp2s0`, +etc. + +These names are predictable but less memorable and not necessarily +stable: for example installing new hardware or changing firmware +settings can result in a [name +change](https://github.com/systemd/systemd/issues/3715#issue-165347602). +If this is undesirable, for example if you have a single ethernet card, +you can revert to the traditional scheme by setting +[](#opt-networking.usePredictableInterfaceNames) +to `false`. + +## Assigning custom names {#sec-custom-ifnames} + +In case there are multiple interfaces of the same type, it's better to +assign custom names based on the device hardware address. For example, +we assign the name `wan` to the interface with MAC address +`52:54:00:12:01:01` using a netword link unit: + +```nix +systemd.network.links."10-wan" = { + matchConfig.PermanentMACAddress = "52:54:00:12:01:01"; + linkConfig.Name = "wan"; +}; +``` + +Note that links are directly read by udev, *not networkd*, and will work +even if networkd is disabled. + +Alternatively, we can use a plain old udev rule: + +```nix +services.udev.initrdRules = '' + SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \ + ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan" +''; +``` + +::: {.warning} +The rule must be installed in the initrd using +`services.udev.initrdRules`, not the usual `services.udev.extraRules` +option. This is to avoid race conditions with other programs controlling +the interface. +::: diff --git a/nixos/doc/manual/configuration/ssh.section.md b/nixos/doc/manual/configuration/ssh.section.md new file mode 100644 index 00000000000..cba81eb43f4 --- /dev/null +++ b/nixos/doc/manual/configuration/ssh.section.md @@ -0,0 +1,19 @@ +# Secure Shell Access {#sec-ssh} + +Secure shell (SSH) access to your machine can be enabled by setting: + +```nix +services.openssh.enable = true; +``` + +By default, root logins using a password are disallowed. They can be +disabled entirely by setting +[](#opt-services.openssh.permitRootLogin) to `"no"`. + +You can declaratively specify authorised RSA/DSA public keys for a user +as follows: + +```nix +users.users.alice.openssh.authorizedKeys.keys = + [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ]; +``` 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..4dd1b203a24 --- /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](#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.chapter.md b/nixos/doc/manual/configuration/subversion.chapter.md new file mode 100644 index 00000000000..84f9c270337 --- /dev/null +++ b/nixos/doc/manual/configuration/subversion.chapter.md @@ -0,0 +1,102 @@ +# Subversion {#module-services-subversion} + +[Subversion](https://subversion.apache.org/) is a centralized +version-control system. It can use a [variety of +protocols](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing) +for communication between client and server. + +## Subversion inside Apache HTTP {#module-services-subversion-apache-httpd} + +This section focuses on configuring a web-based server on top of the +Apache HTTP server, which uses +[WebDAV](http://www.webdav.org/)/[DeltaV](http://www.webdav.org/deltav/WWW10/deltav-intro.htm) +for communication. + +For more information on the general setup, please refer to the [the +appropriate section of the Subversion +book](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd). + +To configure, include in `/etc/nixos/configuration.nix` code to activate +Apache HTTP, setting [](#opt-services.httpd.adminAddr) +appropriately: + +```nix +services.httpd.enable = true; +services.httpd.adminAddr = ...; +networking.firewall.allowedTCPPorts = [ 80 443 ]; +``` + +For a simple Subversion server with basic authentication, configure the +Subversion module for Apache as follows, setting `hostName` and +`documentRoot` appropriately, and `SVNParentPath` to the parent +directory of the repositories, `AuthzSVNAccessFile` to the location of +the `.authz` file describing access permission, and `AuthUserFile` to +the password file. + +```nix +services.httpd.extraModules = [ + # note that order is *super* important here + { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; } + { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; } + ]; + services.httpd.virtualHosts = { + "svn" = { + hostName = HOSTNAME; + documentRoot = DOCUMENTROOT; + locations."/svn".extraConfig = '' + DAV svn + SVNParentPath REPO_PARENT + AuthzSVNAccessFile ACCESS_FILE + AuthName "SVN Repositories" + AuthType Basic + AuthUserFile PASSWORD_FILE + Require valid-user + ''; + } +``` + +The key `"svn"` is just a symbolic name identifying the virtual host. +The `"/svn"` in `locations."/svn".extraConfig` is the path underneath +which the repositories will be served. + +[This page](https://wiki.archlinux.org/index.php/Subversion) explains +how to set up the Subversion configuration itself. This boils down to +the following: + +Underneath `REPO_PARENT` repositories can be set up as follows: + +```ShellSession +$ svn create REPO_NAME +``` + +Repository files need to be accessible by `wwwrun`: + +```ShellSession +$ chown -R wwwrun:wwwrun REPO_PARENT +``` + +The password file `PASSWORD_FILE` can be created as follows: + +```ShellSession +$ htpasswd -cs PASSWORD_FILE USER_NAME +``` + +Additional users can be set up similarly, omitting the `c` flag: + +```ShellSession +$ htpasswd -s PASSWORD_FILE USER_NAME +``` + +The file describing access permissions `ACCESS_FILE` will look something +like the following: + +```nix +[/] +* = r + +[REPO_NAME:/] +USER_NAME = rw +``` + +The Subversion repositories will be accessible as +`http://HOSTNAME/svn/REPO_NAME`. diff --git a/nixos/doc/manual/configuration/summary.section.md b/nixos/doc/manual/configuration/summary.section.md new file mode 100644 index 00000000000..8abbbe257fd --- /dev/null +++ b/nixos/doc/manual/configuration/summary.section.md @@ -0,0 +1,46 @@ +# Syntax Summary {#sec-nix-syntax-summary} + +Below is a summary of the most important syntactic constructs in the Nix +expression language. It's not complete. In particular, there are many +other built-in functions. See the [Nix +manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions) for +the rest. + +| Example | Description | +|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------| +| *Basic values* | | +| `"Hello world"` | A string | +| `"${pkgs.bash}/bin/sh"` | A string containing an expression (expands to `"/nix/store/hash-bash-version/bin/sh"`) | +| `true`, `false` | Booleans | +| `123` | An integer | +| `./foo.png` | A path (relative to the containing Nix expression) | +| *Compound values* | | +| `{ x = 1; y = 2; }` | A set with attributes named `x` and `y` | +| `{ foo.bar = 1; }` | A nested set, equivalent to `{ foo = { bar = 1; }; }` | +| `rec { x = "foo"; y = x + "bar"; }` | A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }` | +| `[ "foo" "bar" ]` | A list with two elements | +| *Operators* | | +| `"foo" + "bar"` | String concatenation | +| `1 + 2` | Integer addition | +| `"foo" == "f" + "oo"` | Equality test (evaluates to `true`) | +| `"foo" != "bar"` | Inequality test (evaluates to `true`) | +| `!true` | Boolean negation | +| `{ x = 1; y = 2; }.x` | Attribute selection (evaluates to `1`) | +| `{ x = 1; y = 2; }.z or 3` | Attribute selection with default (evaluates to `3`) | +| `{ x = 1; y = 2; } // { z = 3; }` | Merge two sets (attributes in the right-hand set taking precedence) | +| *Control structures* | | +| `if 1 + 1 == 2 then "yes!" else "no!"` | Conditional expression | +| `assert 1 + 1 == 2; "yes!"` | Assertion check (evaluates to `"yes!"`). See [](#sec-assertions) for using assertions in modules | +| `let x = "foo"; y = "bar"; in x + y` | Variable definition | +| `with pkgs.lib; head [ 1 2 3 ]` | Add all attributes from the given set to the scope (evaluates to `1`) | +| *Functions (lambdas)* | | +| `x: x + 1` | A function that expects an integer and returns it increased by 1 | +| `(x: x + 1) 100` | A function call (evaluates to 101) | +| `let inc = x: x + 1; in inc (inc (inc 100))` | A function bound to a variable and subsequently called by name (evaluates to 103) | +| `{ x, y }: x + y` | A function that expects a set with required attributes `x` and `y` and concatenates them | +| `{ x, y ? "bar" }: x + y` | A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y` | +| `{ x, y, ... }: x + y` | A function that expects a set with required attributes `x` and `y` and ignores any other attributes | +| `{ x, y } @ args: x + y` | A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args` | +| *Built-in functions* | | +| `import ./foo.nix` | Load and return Nix expression in given file | +| `map (x: x + x) [ 1 2 3 ]` | Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`) | diff --git a/nixos/doc/manual/configuration/user-mgmt.chapter.md b/nixos/doc/manual/configuration/user-mgmt.chapter.md new file mode 100644 index 00000000000..37990664a8f --- /dev/null +++ b/nixos/doc/manual/configuration/user-mgmt.chapter.md @@ -0,0 +1,92 @@ +# User Management {#sec-user-management} + +NixOS supports both declarative and imperative styles of user +management. In the declarative style, users are specified in +`configuration.nix`. For instance, the following states that a user +account named `alice` shall exist: + +```nix +users.users.alice = { + isNormalUser = true; + home = "/home/alice"; + description = "Alice Foobar"; + extraGroups = [ "wheel" "networkmanager" ]; + openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; +}; +``` + +Note that `alice` is a member of the `wheel` and `networkmanager` +groups, which allows her to use `sudo` to execute commands as `root` and +to configure the network, respectively. Also note the SSH public key +that allows remote logins with the corresponding private key. Users +created in this way do not have a password by default, so they cannot +log in via mechanisms that require a password. However, you can use the +`passwd` program to set a password, which is retained across invocations +of `nixos-rebuild`. + +If you set [](#opt-users.mutableUsers) to +false, then the contents of `/etc/passwd` and `/etc/group` will be congruent +to your NixOS configuration. For instance, if you remove a user from +[](#opt-users.users) and run nixos-rebuild, the user +account will cease to exist. Also, imperative commands for managing users and +groups, such as useradd, are no longer available. Passwords may still be +assigned by setting the user\'s +[hashedPassword](#opt-users.users._name_.hashedPassword) option. A +hashed password can be generated using `mkpasswd -m + sha-512`. + +A user ID (uid) is assigned automatically. You can also specify a uid +manually by adding + +```nix +uid = 1000; +``` + +to the user specification. + +Groups can be specified similarly. The following states that a group +named `students` shall exist: + +```nix +users.groups.students.gid = 1000; +``` + +As with users, the group ID (gid) is optional and will be assigned +automatically if it's missing. + +In the imperative style, users and groups are managed by commands such +as `useradd`, `groupmod` and so on. For instance, to create a user +account named `alice`: + +```ShellSession +# useradd -m alice +``` + +To make all nix tools available to this new user use \`su - USER\` which +opens a login shell (==shell that loads the profile) for given user. +This will create the \~/.nix-defexpr symlink. So run: + +```ShellSession +# su - alice -c "true" +``` + +The flag `-m` causes the creation of a home directory for the new user, +which is generally what you want. The user does not have an initial +password and therefore cannot log in. A password can be set using the +`passwd` utility: + +```ShellSession +# passwd alice +Enter new UNIX password: *** +Retype new UNIX password: *** +``` + +A user can be deleted using `userdel`: + +```ShellSession +# userdel -r alice +``` + +The flag `-r` deletes the user's home directory. Accounts can be +modified using `usermod`. Unix groups can be managed using `groupadd`, +`groupmod` and `groupdel`. diff --git a/nixos/doc/manual/configuration/wayland.chapter.md b/nixos/doc/manual/configuration/wayland.chapter.md new file mode 100644 index 00000000000..a3a46aa3da6 --- /dev/null +++ b/nixos/doc/manual/configuration/wayland.chapter.md @@ -0,0 +1,27 @@ +# Wayland {#sec-wayland} + +While X11 (see [](#sec-x11)) is still the primary display technology +on NixOS, Wayland support is steadily improving. Where X11 separates the +X Server and the window manager, on Wayland those are combined: a +Wayland Compositor is like an X11 window manager, but also embeds the +Wayland \'Server\' functionality. This means it is sufficient to install +a Wayland Compositor such as sway without separately enabling a Wayland +server: + +```nix +programs.sway.enable = true; +``` + +This installs the sway compositor along with some essential utilities. +Now you can start sway from the TTY console. + +If you are using a wlroots-based compositor, like sway, and want to be +able to share your screen, you might want to activate this option: + +```nix +xdg.portal.wlr.enable = true; +``` + +and configure Pipewire using +[](#opt-services.pipewire.enable) +and related options. diff --git a/nixos/doc/manual/configuration/wireless.section.md b/nixos/doc/manual/configuration/wireless.section.md new file mode 100644 index 00000000000..6b223d843ac --- /dev/null +++ b/nixos/doc/manual/configuration/wireless.section.md @@ -0,0 +1,67 @@ +# Wireless Networks {#sec-wireless} + +For a desktop installation using NetworkManager (e.g., GNOME), you just +have to make sure the user is in the `networkmanager` group and you can +skip the rest of this section on wireless networks. + +NixOS will start wpa_supplicant for you if you enable this setting: + +```nix +networking.wireless.enable = true; +``` + +NixOS lets you specify networks for wpa_supplicant declaratively: + +```nix +networking.wireless.networks = { + echelon = { # SSID with no spaces or special characters + psk = "abcdefgh"; + }; + "echelon's AP" = { # SSID with spaces and/or special characters + psk = "ijklmnop"; + }; + echelon = { # Hidden SSID + hidden = true; + psk = "qrstuvwx"; + }; + free.wifi = {}; # Public wireless network +}; +``` + +Be aware that keys will be written to the nix store in plaintext! When +no networks are set, it will default to using a configuration file at +`/etc/wpa_supplicant.conf`. You should edit this file yourself to define +wireless networks, WPA keys and so on (see wpa_supplicant.conf(5)). + +If you are using WPA2 you can generate pskRaw key using +`wpa_passphrase`: + +```ShellSession +$ wpa_passphrase ESSID PSK +network={ + ssid="echelon" + #psk="abcdefgh" + psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435 +} +``` + +```nix +networking.wireless.networks = { + echelon = { + pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435"; + }; +} +``` + +or you can use it to directly generate the `wpa_supplicant.conf`: + +```ShellSession +# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf +``` + +After you have edited the `wpa_supplicant.conf`, you need to restart the +wpa_supplicant service. + +```ShellSession +# systemctl restart wpa_supplicant.service +``` diff --git a/nixos/doc/manual/configuration/x-windows.chapter.md b/nixos/doc/manual/configuration/x-windows.chapter.md new file mode 100644 index 00000000000..2c80b786b26 --- /dev/null +++ b/nixos/doc/manual/configuration/x-windows.chapter.md @@ -0,0 +1,337 @@ +# X Window System {#sec-x11} + +The X Window System (X11) provides the basis of NixOS' graphical user +interface. It can be enabled as follows: + +```nix +services.xserver.enable = true; +``` + +The X server will automatically detect and use the appropriate video +driver from a set of X.org drivers (such as `vesa` and `intel`). You can +also specify a driver manually, e.g. + +```nix +services.xserver.videoDrivers = [ "r128" ]; +``` + +to enable X.org's `xf86-video-r128` driver. + +You also need to enable at least one desktop or window manager. +Otherwise, you can only log into a plain undecorated `xterm` window. +Thus you should pick one or more of the following lines: + +```nix +services.xserver.desktopManager.plasma5.enable = true; +services.xserver.desktopManager.xfce.enable = true; +services.xserver.desktopManager.gnome.enable = true; +services.xserver.desktopManager.mate.enable = true; +services.xserver.windowManager.xmonad.enable = true; +services.xserver.windowManager.twm.enable = true; +services.xserver.windowManager.icewm.enable = true; +services.xserver.windowManager.i3.enable = true; +services.xserver.windowManager.herbstluftwm.enable = true; +``` + +NixOS's default *display manager* (the program that provides a graphical +login prompt and manages the X server) is LightDM. You can select an +alternative one by picking one of the following lines: + +```nix +services.xserver.displayManager.sddm.enable = true; +services.xserver.displayManager.gdm.enable = true; +``` + +You can set the keyboard layout (and optionally the layout variant): + +```nix +services.xserver.layout = "de"; +services.xserver.xkbVariant = "neo"; +``` + +The X server is started automatically at boot time. If you don't want +this to happen, you can set: + +```nix +services.xserver.autorun = false; +``` + +The X server can then be started manually: + +```ShellSession +# systemctl start display-manager.service +``` + +On 64-bit systems, if you want OpenGL for 32-bit programs such as in +Wine, you should also set the following: + +```nix +hardware.opengl.driSupport32Bit = true; +``` + +## Auto-login {#sec-x11-auto-login .unnumbered} + +The x11 login screen can be skipped entirely, automatically logging you +into your window manager and desktop environment when you boot your +computer. + +This is especially helpful if you have disk encryption enabled. Since +you already have to provide a password to decrypt your disk, entering a +second password to login can be redundant. + +To enable auto-login, you need to define your default window manager and +desktop environment. If you wanted no desktop environment and i3 as your +your window manager, you\'d define: + +```nix +services.xserver.displayManager.defaultSession = "none+i3"; +``` + +Every display manager in NixOS supports auto-login, here is an example +using lightdm for a user `alice`: + +```nix +services.xserver.displayManager.lightdm.enable = true; +services.xserver.displayManager.autoLogin.enable = true; +services.xserver.displayManager.autoLogin.user = "alice"; +``` + +## Intel Graphics drivers {#sec-x11--graphics-cards-intel .unnumbered} + +There are two choices for Intel Graphics drivers in X.org: `modesetting` +(included in the xorg-server itself) and `intel` (provided by the +package xf86-video-intel). + +The default and recommended is `modesetting`. It is a generic driver +which uses the kernel [mode +setting](https://en.wikipedia.org/wiki/Mode_setting) (KMS) mechanism. It +supports Glamor (2D graphics acceleration via OpenGL) and is actively +maintained but may perform worse in some cases (like in old chipsets). + +The second driver, `intel`, is specific to Intel GPUs, but not +recommended by most distributions: it lacks several modern features (for +example, it doesn\'t support Glamor) and the package hasn\'t been +officially updated since 2015. + +The results vary depending on the hardware, so you may have to try both +drivers. Use the option +[](#opt-services.xserver.videoDrivers) +to set one. The recommended configuration for modern systems is: + +```nix +services.xserver.videoDrivers = [ "modesetting" ]; +services.xserver.useGlamor = true; +``` + +If you experience screen tearing no matter what, this configuration was +reported to resolve the issue: + +```nix +services.xserver.videoDrivers = [ "intel" ]; +services.xserver.deviceSection = '' + Option "DRI" "2" + Option "TearFree" "true" +''; +``` + +Note that this will likely downgrade the performance compared to +`modesetting` or `intel` with DRI 3 (default). + +## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia .unnumbered} + +NVIDIA provides a proprietary driver for its graphics cards that has +better 3D performance than the X.org drivers. It is not enabled by +default because it's not free software. You can enable it as follows: + +```nix +services.xserver.videoDrivers = [ "nvidia" ]; +``` + +Or if you have an older card, you may have to use one of the legacy +drivers: + +```nix +services.xserver.videoDrivers = [ "nvidiaLegacy390" ]; +services.xserver.videoDrivers = [ "nvidiaLegacy340" ]; +services.xserver.videoDrivers = [ "nvidiaLegacy304" ]; +``` + +You may need to reboot after enabling this driver to prevent a clash +with other kernel modules. + +## Proprietary AMD drivers {#sec-x11--graphics-cards-amd .unnumbered} + +AMD provides a proprietary driver for its graphics cards that is not +enabled by default because it's not Free Software, is often broken in +nixpkgs and as of this writing doesn\'t offer more features or +performance. If you still want to use it anyway, you need to explicitly +set: + +```nix +services.xserver.videoDrivers = [ "amdgpu-pro" ]; +``` + +You will need to reboot after enabling this driver to prevent a clash +with other kernel modules. + +## Touchpads {#sec-x11-touchpads .unnumbered} + +Support for Synaptics touchpads (found in many laptops such as the Dell +Latitude series) can be enabled as follows: + +```nix +services.xserver.libinput.enable = true; +``` + +The driver has many options (see [](#ch-options)). +For instance, the following disables tap-to-click behavior: + +```nix +services.xserver.libinput.touchpad.tapping = false; +``` + +Note: the use of `services.xserver.synaptics` is deprecated since NixOS +17.09. + +## GTK/Qt themes {#sec-x11-gtk-and-qt-themes .unnumbered} + +GTK themes can be installed either to user profile or system-wide (via +`environment.systemPackages`). To make Qt 5 applications look similar to +GTK ones, you can use the following configuration: + +```nix +qt5.enable = true; +qt5.platformTheme = "gtk2"; +qt5.style = "gtk2"; +``` + +## Custom XKB layouts {#custom-xkb-layouts .unnumbered} + +It is possible to install custom [ XKB +](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts +using the option `services.xserver.extraLayouts`. + +As a first example, we are going to create a layout based on the basic +US layout, with an additional layer to type some greek symbols by +pressing the right-alt key. + +Create a file called `us-greek` with the following content (under a +directory called `symbols`; it\'s an XKB peculiarity that will help with +testing): + +```nix +xkb_symbols "us-greek" +{ + include "us(basic)" // includes the base US keys + include "level3(ralt_switch)" // configures right alt as a third level switch + + key <LatA> { [ a, A, Greek_alpha ] }; + key <LatB> { [ b, B, Greek_beta ] }; + key <LatG> { [ g, G, Greek_gamma ] }; + key <LatD> { [ d, D, Greek_delta ] }; + key <LatZ> { [ z, Z, Greek_zeta ] }; +}; +``` + +A minimal layout specification must include the following: + +```nix +services.xserver.extraLayouts.us-greek = { + description = "US layout with alt-gr greek"; + languages = [ "eng" ]; + symbolsFile = /yourpath/symbols/us-greek; +}; +``` + +::: {.note} +The name (after `extraLayouts.`) should match the one given to the +`xkb_symbols` block. +::: + +Applying this customization requires rebuilding several packages, and a +broken XKB file can lead to the X session crashing at login. Therefore, +you\'re strongly advised to **test your layout before applying it**: + +```ShellSession +$ nix-shell -p xorg.xkbcomp +$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY +``` + +You can inspect the predefined XKB files for examples: + +```ShellSession +$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/" +``` + +Once the configuration is applied, and you did a logout/login cycle, the +layout should be ready to use. You can try it by e.g. running +`setxkbmap us-greek` and then type `<alt>+a` (it may not get applied in +your terminal straight away). To change the default, the usual +`services.xserver.layout` option can still be used. + +A layout can have several other components besides `xkb_symbols`, for +example we will define new keycodes for some multimedia key and bind +these to some symbol. + +Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys +of interest, then create a `media-key` file to hold the keycodes +definitions + +```nix +xkb_keycodes "media" +{ + <volUp> = 123; + <volDown> = 456; +} +``` + +Now use the newly define keycodes in `media-sym`: + +```nix +xkb_symbols "media" +{ + key.type = "ONE_LEVEL"; + key <volUp> { [ XF86AudioLowerVolume ] }; + key <volDown> { [ XF86AudioRaiseVolume ] }; +} +``` + +As before, to install the layout do + +```nix +services.xserver.extraLayouts.media = { + description = "Multimedia keys remapping"; + languages = [ "eng" ]; + symbolsFile = /path/to/media-key; + keycodesFile = /path/to/media-sym; +}; +``` + +::: {.note} +The function `pkgs.writeText <filename> <content>` can be useful if you +prefer to keep the layout definitions inside the NixOS configuration. +::: + +Unfortunately, the Xorg server does not (currently) support setting a +keymap directly but relies instead on XKB rules to select the matching +components (keycodes, types, \...) of a layout. This means that +components other than symbols won\'t be loaded by default. As a +workaround, you can set the keymap using `setxkbmap` at the start of the +session with: + +```nix +services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media"; +``` + +If you are manually starting the X server, you should set the argument +`-xkbdir /etc/X11/xkb`, otherwise X won\'t find your layout files. For +example with `xinit` run + +```ShellSession +$ xinit -- -xkbdir /etc/X11/xkb +``` + +To learn how to write layouts take a look at the XKB [documentation +](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts). +More example layouts can also be found [here +](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples). diff --git a/nixos/doc/manual/configuration/xfce.chapter.md b/nixos/doc/manual/configuration/xfce.chapter.md new file mode 100644 index 00000000000..b0ef6682aae --- /dev/null +++ b/nixos/doc/manual/configuration/xfce.chapter.md @@ -0,0 +1,52 @@ +# Xfce Desktop Environment {#sec-xfce} + +To enable the Xfce Desktop Environment, set + +```nix +services.xserver.desktopManager.xfce.enable = true; +services.xserver.displayManager.defaultSession = "xfce"; +``` + +Optionally, *picom* can be enabled for nice graphical effects, some +example settings: + +```nix +services.picom = { + enable = true; + fade = true; + inactiveOpacity = 0.9; + shadow = true; + fadeDelta = 4; +}; +``` + +Some Xfce programs are not installed automatically. To install them +manually (system wide), put them into your +[](#opt-environment.systemPackages) from `pkgs.xfce`. + +## Thunar Plugins {#sec-xfce-thunar-plugins .unnumbered} + +If you\'d like to add extra plugins to Thunar, add them to +[](#opt-services.xserver.desktopManager.xfce.thunarPlugins). +You shouldn\'t just add them to [](#opt-environment.systemPackages). + +## Troubleshooting {#sec-xfce-troubleshooting .unnumbered} + +Even after enabling udisks2, volume management might not work. Thunar +and/or the desktop takes time to show up. Thunar will spit out this kind +of message on start (look at `journalctl --user -b`). + +```plain +Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported +``` + +This is caused by some needed GNOME services not running. This is all +fixed by enabling \"Launch GNOME services on startup\" in the Advanced +tab of the Session and Startup settings panel. Alternatively, you can +run this command to do the same thing. + +```ShellSession +$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true +``` + +A log-out and re-log will be needed for this to take effect. |