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