diff options
Diffstat (limited to 'infra/libkookie/nixpkgs/nixos/doc/manual/configuration')
41 files changed, 2919 insertions, 0 deletions
diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/abstractions.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/abstractions.xml new file mode 100644 index 000000000000..df9ff2615e1a --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/abstractions.xml @@ -0,0 +1,101 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-module-abstractions"> + <title>Abstractions</title> + + <para> + If you find yourself repeating yourself over and over, it’s time to + abstract. Take, for instance, this Apache HTTP Server configuration: +<programlisting> +{ + <xref linkend="opt-services.httpd.virtualHosts"/> = + { "blog.example.org" = { + documentRoot = "/webroot/blog.example.org"; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + enablePHP = true; + }; + "wiki.example.org" = { + documentRoot = "/webroot/wiki.example.org"; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + enablePHP = true; + }; + }; +} +</programlisting> + It defines two virtual hosts with nearly identical configuration; the only + difference is the document root directories. To prevent this + duplication, we can use a <literal>let</literal>: +<programlisting> +let + commonConfig = + { adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + }; +in +{ + <xref linkend="opt-services.httpd.virtualHosts"/> = + { "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; }); + "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.com"; }); + }; +} +</programlisting> + The <literal>let commonConfig = <replaceable>...</replaceable></literal> + defines a variable named <literal>commonConfig</literal>. The + <literal>//</literal> operator merges two attribute sets, so the + configuration of the second virtual host is the set + <literal>commonConfig</literal> extended with the document root option. + </para> + + <para> + You can write a <literal>let</literal> wherever an expression is allowed. + Thus, you also could have written: +<programlisting> +{ + <xref linkend="opt-services.httpd.virtualHosts"/> = + let commonConfig = <replaceable>...</replaceable>; in + { "blog.example.org" = (commonConfig // { <replaceable>...</replaceable> }) + "wiki.example.org" = (commonConfig // { <replaceable>...</replaceable> }) + }; +} +</programlisting> + but not <literal>{ let commonConfig = <replaceable>...</replaceable>; in + <replaceable>...</replaceable>; }</literal> since attributes (as opposed to + attribute values) are not expressions. + </para> + + <para> + <emphasis>Functions</emphasis> provide another method of abstraction. For + instance, suppose that we want to generate lots of different virtual hosts, + all with identical configuration except for the document root. This can be done + as follows: +<programlisting> +{ + <xref linkend="opt-services.httpd.virtualHosts"/> = + let + makeVirtualHost = webroot: + { documentRoot = webroot; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + }; + in + { "example.org" = (makeVirtualHost "/webroot/example.org"); + "example.com" = (makeVirtualHost "/webroot/example.com"); + "example.gov" = (makeVirtualHost "/webroot/example.gov"); + "example.nl" = (makeVirtualHost "/webroot/example.nl"); + }; +} +</programlisting> + Here, <varname>makeVirtualHost</varname> is a function that takes a single + argument <literal>webroot</literal> and returns the configuration for a virtual + host. That function is then called for several names to produce the list of + virtual host configurations. + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ad-hoc-network-config.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ad-hoc-network-config.xml new file mode 100644 index 000000000000..00e595c7cb7f --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ad-hoc-network-config.xml @@ -0,0 +1,20 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="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: +<programlisting> +<xref linkend="opt-networking.localCommands"/> = + '' + ip -6 addr add 2001:610:685:1::1/64 dev eth0 + ''; +</programlisting> + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml new file mode 100644 index 000000000000..c7e882d846fa --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml @@ -0,0 +1,61 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-ad-hoc-packages"> + <title>Ad-Hoc Package Management</title> + + <para> + With the command <command>nix-env</command>, you can install and uninstall + packages from the command line. For instance, to install Mozilla Thunderbird: +<screen> +<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen> + If you invoke this as root, the package is installed in the Nix profile + <filename>/nix/var/nix/profiles/default</filename> and visible to all users + of the system; otherwise, the package ends up in + <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename> + and is not visible to other users. The <option>-A</option> 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: +<screen> +<prompt>$ </prompt>nix-channel --update nixos +</screen> + 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 + <command>nixos-rebuild switch</command> 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: +<screen> +<prompt>$ </prompt>nix-env -u '*' +</screen> + </para> + + <para> + A package can be uninstalled using the <option>-e</option> flag: +<screen> +<prompt>$ </prompt>nix-env -e thunderbird +</screen> + </para> + + <para> + Finally, you can roll back an undesirable <command>nix-env</command> action: +<screen> +<prompt>$ </prompt>nix-env --rollback +</screen> + </para> + + <para> + <command>nix-env</command> has many more flags. For details, see the + <citerefentry> + <refentrytitle>nix-env</refentrytitle> + <manvolnum>1</manvolnum></citerefentry> manpage or the Nix manual. + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/adding-custom-packages.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/adding-custom-packages.xml new file mode 100644 index 000000000000..19eb2429d0a0 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/adding-custom-packages.xml @@ -0,0 +1,73 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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: +<screen> +<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs +<prompt>$ </prompt>cd nixpkgs +</screen> + Then you write and test the package as described in the Nixpkgs manual. + Finally, you add it to <literal>environment.systemPackages</literal>, e.g. +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ]; +</programlisting> + and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs + tree: +<screen> +<prompt># </prompt>nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen> + </para> + + <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 <filename>configuration.nix</filename>: +<programlisting> +<xref linkend="opt-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> + Of course, you can also move the definition of <literal>my-hello</literal> + into a separate Nix expression, e.g. +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ]; +</programlisting> + where <filename>my-hello.nix</filename> contains: +<programlisting> +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> + This allows testing the package easily: +<screen> +<prompt>$ </prompt>nix-build my-hello.nix +<prompt>$ </prompt>./result/bin/hello +Hello, world! +</screen> + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/config-file.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/config-file.xml new file mode 100644 index 000000000000..7ccb5b3664ea --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/config-file.xml @@ -0,0 +1,215 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-configuration-file"> + <title>NixOS Configuration File</title> + + <para> + The NixOS configuration file generally looks like this: +<programlisting> +{ config, pkgs, ... }: + +{ <replaceable>option definitions</replaceable> +} +</programlisting> + The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this + is actually a function that takes at least the two arguments + <varname>config</varname> and <varname>pkgs</varname>. (These are explained + later.) The function returns a <emphasis>set</emphasis> of option definitions + (<literal>{ <replaceable>...</replaceable> }</literal>). These definitions + have the form <literal><replaceable>name</replaceable> = + <replaceable>value</replaceable></literal>, where + <replaceable>name</replaceable> is the name of an option and + <replaceable>value</replaceable> is its value. For example, +<programlisting> +{ config, pkgs, ... }: + +{ <xref linkend="opt-services.httpd.enable"/> = true; + <xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org"; + <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.localhost.documentRoot</link> = "/webroot"; +} +</programlisting> + defines a configuration with three option definitions that together enable + the Apache HTTP Server with <filename>/webroot</filename> 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 + <varname>services</varname> that contains a set named + <varname>httpd</varname>, which in turn contains an option definition named + <varname>enable</varname> with value <literal>true</literal>. This means that + the example above can also be written as: +<programlisting> +{ config, pkgs, ... }: + +{ services = { + httpd = { + enable = true; + adminAddr = "alice@example.org"; + virtualHosts = { + localhost = { + documentRoot = "/webroot"; + }; + }; + }; + }; +} +</programlisting> + 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>), + <command>nixos-rebuild</command> will give an error like: +<screen> +The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist. +</screen> + Likewise, values in option definitions must have a correct type. For + instance, <option>services.httpd.enable</option> 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: +<screen> +The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean. +</screen> + </para> + + <para> + Options have various types of values. The most important are: + <variablelist> + <varlistentry> + <term> + Strings + </term> + <listitem> + <para> + Strings are enclosed in double quotes, e.g. +<programlisting> +<xref linkend="opt-networking.hostName"/> = "dexter"; +</programlisting> + 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. +<programlisting> +<xref linkend="opt-networking.extraHosts"/> = + '' + 127.0.0.2 other-localhost + 10.0.0.1 server + ''; +</programlisting> + 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. +<programlisting> +<xref linkend="opt-networking.firewall.enable"/> = true; +<xref linkend="opt-networking.firewall.allowPing"/> = false; +</programlisting> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Integers + </term> + <listitem> + <para> + For example, +<programlisting> +<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60; +</programlisting> + (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 +<programlisting> +<xref linkend="opt-fileSystems"/>."/boot" = + { device = "/dev/sda1"; + fsType = "ext4"; + options = [ "rw" "data=ordered" "relatime" ]; + }; +</programlisting> + </para> + </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: +<programlisting> +<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ]; +</programlisting> + List elements can be any other type, e.g. sets: +<programlisting> +swapDevices = [ { device = "/dev/disk/by-label/swap"; } ]; +</programlisting> + </para> + </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 <varname>pkgs</varname>. Typical uses: +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = + [ pkgs.thunderbird + pkgs.emacs + ]; + +<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10; +</programlisting> + 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> + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/config-syntax.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/config-syntax.xml new file mode 100644 index 000000000000..5526dea247c0 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/config-syntax.xml @@ -0,0 +1,25 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-configuration-syntax"> + <title>Configuration Syntax</title> + <para> + The NixOS configuration file + <filename>/etc/nixos/configuration.nix</filename> 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.xml" /> + <xi:include href="abstractions.xml" /> + <xi:include href="modularity.xml" /> + <xi:include href="summary.xml" /> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/configuration.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/configuration.xml new file mode 100644 index 000000000000..6949189b8883 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/configuration.xml @@ -0,0 +1,31 @@ +<part xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-configuration"> + <title>Configuration</title> + <partintro xml:id="ch-configuration-intro"> + <para> + This chapter describes how to configure various aspects of a NixOS machine + through the configuration file + <filename>/etc/nixos/configuration.nix</filename>. As described in + <xref linkend="sec-changing-config" />, changes to this file only take + effect after you run <command>nixos-rebuild</command>. + </para> + </partintro> + <xi:include href="config-syntax.xml" /> + <xi:include href="package-mgmt.xml" /> + <xi:include href="user-mgmt.xml" /> + <xi:include href="file-systems.xml" /> + <xi:include href="x-windows.xml" /> + <xi:include href="wayland.xml" /> + <xi:include href="gpu-accel.xml" /> + <xi:include href="xfce.xml" /> + <xi:include href="networking.xml" /> + <xi:include href="linux-kernel.xml" /> + <xi:include href="subversion.xml" /> + <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> + <xi:include href="profiles.xml" /> + <xi:include href="kubernetes.xml" /> +<!-- Apache; libvirtd virtualisation --> +</part> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml new file mode 100644 index 000000000000..34e6ab4b24d6 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml @@ -0,0 +1,86 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 <filename>configuration.nix</filename> as follows: <filename> + nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename> + </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: +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; +</programlisting> + The function <varname>override</varname> 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 + <varname>gtk</varname> 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 + <varname>overrideAttrs</varname>. While the <varname>override</varname> + mechanism above overrides the arguments of a package function, + <varname>overrideAttrs</varname> 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: +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = [ + (pkgs.emacs.overrideAttrs (oldAttrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) +]; +</programlisting> + Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by + <varname>pkgs.emacs</varname> 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 + <varname>oldAttrs</varname>. + </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: +<screen> +nixpkgs.config.packageOverrides = pkgs: + { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; + }; +</screen> + 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 + <varname>nixpkgs.config.packageOverrides</varname> refers to the original + rather than overridden instance, to prevent an infinite recursion.) + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/declarative-packages.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/declarative-packages.xml new file mode 100644 index 000000000000..cd84d1951d24 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/declarative-packages.xml @@ -0,0 +1,54 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 <filename>configuration.nix</filename> enables the Mozilla + Thunderbird email application: +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ]; +</programlisting> + 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 + <command>nixos-rebuild switch</command>. + </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 xlink:href="#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: +<screen> +<prompt>$ </prompt>nix-env -qaP '*' --description +nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded +<replaceable>...</replaceable> +</screen> + 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 “uninstall” a package, simply remove it from + <xref linkend="opt-environment.systemPackages"/> and run + <command>nixos-rebuild switch</command>. + </para> + + <xi:include href="customizing-packages.xml" /> + + <xi:include href="adding-custom-packages.xml" /> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/file-systems.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/file-systems.xml new file mode 100644 index 000000000000..9747433375fc --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/file-systems.xml @@ -0,0 +1,57 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-file-systems"> + <title>File Systems</title> + <para> + You can define file systems using the <option>fileSystems</option> + configuration option. For instance, the following definition causes NixOS to + mount the Ext4 file system on device + <filename>/dev/disk/by-label/data</filename> onto the mount point + <filename>/data</filename>: +<programlisting> +<xref linkend="opt-fileSystems"/>."/data" = + { device = "/dev/disk/by-label/data"; + fsType = "ext4"; + }; +</programlisting> + This will create an entry in <filename>/etc/fstab</filename>, 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 + <command>systemctl</command> e.g. <command>systemctl start + data.mount</command>. + Mount points are created automatically if they don’t already exist. For + <option><link linkend="opt-fileSystems._name_.device">device</link></option>, + it’s best to use the topology-independent device aliases in + <filename>/dev/disk/by-label</filename> and + <filename>/dev/disk/by-uuid</filename>, as these don’t change if the + topology changes (e.g. if a disk is moved to another IDE controller). + </para> + <para> + You can usually omit the file system type + (<option><link linkend="opt-fileSystems._name_.fsType">fsType</link></option>), + since <command>mount</command> can usually detect the type and load the + necessary kernel module automatically. However, if the file system is needed + at early boot (in the initial ramdisk) and is not <literal>ext2</literal>, + <literal>ext3</literal> or <literal>ext4</literal>, then it’s best to + specify <option>fsType</option> 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><link linkend="opt-fileSystems._name_.options">options</link> = [ + "nofail" ];</literal>. + </para> + </note> + <xi:include href="luks-file-systems.xml" /> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/firewall.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/firewall.xml new file mode 100644 index 000000000000..47a19ac82c0f --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/firewall.xml @@ -0,0 +1,37 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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: +<programlisting> +<xref linkend="opt-networking.firewall.enable"/> = false; +</programlisting> + If the firewall is enabled, you can open specific TCP ports to the outside + world: +<programlisting> +<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 443 ]; +</programlisting> + Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is + enabled (<option><xref linkend="opt-services.openssh.enable"/> = + true</option>). UDP ports can be opened through + <xref linkend="opt-networking.firewall.allowedUDPPorts"/>. + </para> + + <para> + To open ranges of TCP ports: +<programlisting> +<xref linkend="opt-networking.firewall.allowedTCPPortRanges"/> = [ + { from = 4000; to = 4007; } + { from = 8000; to = 8010; } +]; +</programlisting> + Similarly, UDP port ranges can be opened through + <xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>. + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/gpu-accel.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/gpu-accel.xml new file mode 100644 index 000000000000..3695a5ff445a --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/gpu-accel.xml @@ -0,0 +1,263 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 <varname>OCL_ICD_VENDORS</varname> + environment variable. This variable can contain a directory which + is scanned by the ICL loader for ICD files. For example: + + <screen><prompt>$</prompt> export \ + OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/</screen> + </para> + + <para> + The second mechanism is to add the OpenCL driver package to + <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the + ICD file under <filename>/run/opengl-driver</filename>, where it will + be visible to the ICD loader. + </para> + + <para> + The proper installation of OpenCL drivers can be verified through + the <command>clinfo</command> command of the <package>clinfo</package> + package. This command will report the number of hardware devices + that is found and give detailed information for each device: + </para> + + <screen><prompt>$</prompt> clinfo | head -n3 +Number of platforms 1 +Platform Name AMD Accelerated Parallel Processing +Platform Vendor Advanced Micro Devices, Inc.</screen> + + <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 + <package>rocm-opencl-icd</package> package. Adding this package to + <xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL + support: + + <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ + rocm-opencl-icd + ];</programlisting> + </para> + </section> + + <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 + <package>intel-compute-runtime</package> package. For Gen7 GPUs, + the deprecated Beignet runtime can be used, which is provided + by the <package>beignet</package> package. The proprietary Intel + OpenCL runtime, in the <package>intel-ocl</package> package, is + an alternative for Gen7 GPUs. + </para> + + <para> + The <package>intel-compute-runtime</package>, <package>beignet</package>, + or <package>intel-ocl</package> 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: + + <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ + intel-compute-runtime + ];</programlisting> + + </para> + </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, + <package>mesa</package> 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 <varname>VK_ICD_FILENAMES</varname> + environment variable. This variable can contain multiple JSON files, separated by + <literal>:</literal>. For example: + + <screen><prompt>$</prompt> export \ + VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json</screen> + </para> + + <para> + The second mechanism is to add the Vulkan driver package to + <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the + ICD file under <filename>/run/opengl-driver</filename>, where it will + be visible to the ICD loader. + </para> + + <para> + The proper installation of Vulkan drivers can be verified through + the <command>vulkaninfo</command> command of the <package>vulkan-tools</package> + package. This command will report the hardware devices and drivers found, + in this example output amdvlk and radv: + </para> + + <screen><prompt>$</prompt> 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</screen> + + <para> + A simple graphical application that uses Vulkan is <command>vkcube</command> + from the <package>vulkan-tools</package> 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 <package>mesa</package>, or the <package>amdvlk</package> package. + Adding the <package>amdvlk</package> package to + <xref linkend="opt-hardware.opengl.extraPackages"/> makes both drivers + available for applications and lets them choose. A specific driver can + be forced as follows: + + <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ + pkgs.<package>amdvlk</package> + ]; + + # To enable Vulkan support for 32-bit applications, also add: + <xref linkend="opt-hardware.opengl.extraPackages32"/> = [ + pkgs.driversi686Linux.<package>amdvlk</package> + ]; + + # For amdvlk + <xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/amd_icd64.json"; + # For radv + <xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; + </programlisting> + </para> + </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 + (<filename>/dev/dri/renderD*</filename>) or are tagged as + <code>uaccess</code> (<filename>/dev/dri/card*</filename>). The + access control lists of devices with the <varname>uaccess</varname> + tag will be updated automatically when a user logs in through + <command>systemd-logind</command>. For example, if the user + <emphasis>jane</emphasis> is logged in, the access control list + should look as follows: + + <screen><prompt>$</prompt> getfacl /dev/dri/card0 +# file: dev/dri/card0 +# owner: root +# group: video +user::rw- +user:jane:rw- +group::rw- +mask::rw- +other::---</screen> + + If you disabled (this functionality of) <command>systemd-logind</command>, + you may need to add the user to the <code>video</code> 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 <code>dlopen</code>. 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 <package>glibc</package> + 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 <code>LD_DEBUG</code> variable set to get more diagnostic + information. For example, OpenCL can be tested with + <code>LD_DEBUG=files clinfo</code>, which should report missing + symbols. + </para> + </section> + </section> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ipv4-config.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ipv4-config.xml new file mode 100644 index 000000000000..884becf0979a --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ipv4-config.xml @@ -0,0 +1,43 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-ipv4"> + <title>IPv4 Configuration</title> + + <para> + By default, NixOS uses DHCP (specifically, <command>dhcpcd</command>) to + automatically configure network interfaces. However, you can configure an + interface manually as follows: +<programlisting> +<link linkend="opt-networking.interfaces._name_.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ { + address = "192.168.1.2"; + prefixLength = 24; +} ]; +</programlisting> + Typically you’ll also want to set a default gateway and set of name + servers: +<programlisting> +<xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1"; +<xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ]; +</programlisting> + </para> + + <note> + <para> + Statically configured interfaces are set up by the systemd service + <replaceable>interface-name</replaceable><literal>-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"/>: +<programlisting> +<xref linkend="opt-networking.hostName"/> = "cartman"; +</programlisting> + 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/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ipv6-config.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ipv6-config.xml new file mode 100644 index 000000000000..7b89b4092be7 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ipv6-config.xml @@ -0,0 +1,50 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-ipv6"> + <title>IPv6 Configuration</title> + + <para> + IPv6 is enabled by default. Stateless address autoconfiguration is used to + automatically assign IPv6 addresses to all interfaces. You can disable IPv6 + support globally by setting: +<programlisting> +<xref linkend="opt-networking.enableIPv6"/> = false; +</programlisting> + </para> + + <para> + You can disable IPv6 on a single interface using a normal sysctl (in this + example, we use interface <varname>eth0</varname>): +<programlisting> +<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv6.conf.eth0.disable_ipv6" = true; +</programlisting> + </para> + + <para> + As with IPv4 networking interfaces are automatically configured via DHCPv6. + You can configure an interface manually: +<programlisting> +<link linkend="opt-networking.interfaces._name_.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ { + address = "fe00:aa:bb:cc::2"; + prefixLength = 64; +} ]; +</programlisting> + </para> + + <para> + For configuring a gateway, optionally with explicitly specified interface: +<programlisting> +<xref linkend="opt-networking.defaultGateway6"/> = { + address = "fe00::1"; + interface = "enp0s3"; +}; +</programlisting> + </para> + + <para> + See <xref linkend='sec-ipv4' /> for similar examples and additional + information. + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/kubernetes.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/kubernetes.xml new file mode 100644 index 000000000000..54a100e44795 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/kubernetes.xml @@ -0,0 +1,112 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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: +<programlisting> +services.kubernetes = { + apiserver.enable = true; + controllerManager.enable = true; + scheduler.enable = true; + addonManager.enable = true; + proxy.enable = true; + flannel.enable = true; +}; +</programlisting> + Another way is to assign cluster roles ("master" and/or "node") to the host. + This enables apiserver, controllerManager, scheduler, addonManager, + kube-proxy and etcd: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "master" ]; +</programlisting> + While this will enable the kubelet and kube-proxy only: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "node" ]; +</programlisting> + Assigning both the master and node roles is usable if you want a single node + Kubernetes cluster for dev or testing purposes: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ]; +</programlisting> + 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/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/linux-kernel.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/linux-kernel.xml new file mode 100644 index 000000000000..dbdcc9414954 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/linux-kernel.xml @@ -0,0 +1,138 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-kernel-config"> + <title>Linux Kernel</title> + <para> + You can override the Linux kernel and associated packages using the option + <option>boot.kernelPackages</option>. For instance, this selects the Linux + 3.10 kernel: +<programlisting> +<xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10; +</programlisting> + 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> + The default Linux kernel configuration should be fine for most users. You can + see the configuration of your current kernel with the following command: +<programlisting> +zcat /proc/config.gz +</programlisting> + If you want to change the kernel configuration, you can use the + <option>packageOverrides</option> feature (see + <xref +linkend="sec-customising-packages" />). For instance, to enable support + for the kernel debugger KGDB: +<programlisting> +nixpkgs.config.packageOverrides = pkgs: + { linux_3_4 = pkgs.linux_3_4.override { + extraConfig = + '' + KGDB y + ''; + }; + }; +</programlisting> + <varname>extraConfig</varname> 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 + <command>udev</command>. You can force a module to be loaded via + <xref linkend="opt-boot.kernelModules"/>, e.g. +<programlisting> +<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ]; +</programlisting> + 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"/>: +<programlisting> +<xref linkend="opt-boot.initrd.kernelModules"/> = [ "cifs" ]; +</programlisting> + 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. +<programlisting> +<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120; +</programlisting> + sets the kernel’s TCP keepalive time to 120 seconds. To see the available + parameters, run <command>sysctl -a</command>. + </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>linuxManualConfig</literal>: +<screen><![CDATA[ + custom-kernel = super.linuxManualConfig { + inherit (super) stdenv hostPlatform; + inherit (linux_4_9) src; + version = "${linux_4_9.version}-custom"; + + configfile = /home/me/my_kernel_config; + allowImportFromDerivation = true; + }; + ]]></screen> + You can edit the config with this snippet (by default <command>make + menuconfig</command> won't work out of the box on nixos): +<screen><![CDATA[ + nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})' + ]]></screen> + or you can let nixpkgs generate the configuration. Nixpkgs generates it via + answering the interactive kernel utility <command>make config</command>. The + answers depend on parameters passed to + <filename>pkgs/os-specific/linux/kernel/generic.nix</filename> (which you + can influence by overriding <literal>extraConfig, autoModules, + modDirVersion, preferBuiltin, extraConfig</literal>). +<screen><![CDATA[ + + 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 + ''; + }); + ]]></screen> + </para> + </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> + +<screen> +<prompt>$ </prompt>nix-build '<nixpkgs>' -A linuxPackages.kernel.dev +<prompt>$ </prompt>nix-shell '<nixpkgs>' -A linuxPackages.kernel +<prompt>$ </prompt>unpackPhase +<prompt>$ </prompt>cd linux-* +<prompt>$ </prompt>make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules +<prompt># </prompt>insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko +</screen> + </section> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/luks-file-systems.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/luks-file-systems.xml new file mode 100644 index 000000000000..405a50a9e430 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/luks-file-systems.xml @@ -0,0 +1,74 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 + <filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>: +<screen> +<prompt># </prompt>cryptsetup luksFormat <replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable> + +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: *** + +<prompt># </prompt>cryptsetup luksOpen <replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable> <replaceable>crypted</replaceable> +Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: *** + +<prompt># </prompt>mkfs.ext4 /dev/mapper/<replaceable>crypted</replaceable> +</screen> + To ensure that this file system is automatically mounted at boot time as + <filename>/</filename>, add the following to + <filename>configuration.nix</filename>: +<programlisting> +<link linkend="opt-boot.initrd.luks.devices._name_.device">boot.initrd.luks.devices.crypted.device</link> = "<replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable>"; +<xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/<replaceable>crypted</replaceable>"; +</programlisting> + Should grub be used as bootloader, and <filename>/boot</filename> is located + on an encrypted partition, it is necessary to add the following grub option: +<programlisting><xref linkend="opt-boot.loader.grub.enableCryptodisk"/> = true;</programlisting> + </para> + <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 <filename>/dev/sda2</filename>: + + <screen> +<prompt># </prompt>export FIDO2_LABEL="<replaceable>/dev/sda2</replaceable> @ $HOSTNAME" +<prompt># </prompt>fido2luks credential "$FIDO2_LABEL" +f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7 + +<prompt># </prompt>fido2luks -i add-key <replaceable>/dev/sda2</replaceable> <replaceable>f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7</replaceable> +Password: +Password (again): +Old password: +Old password (again): +Added to key to device /dev/sda2, slot: 2 +</screen> + + To ensure that this file system is decrypted using the FIDO2 compatible key, add the following to <filename>configuration.nix</filename>: +<programlisting> +<link linkend="opt-boot.initrd.luks.fido2Support">boot.initrd.luks.fido2Support</link> = true; +<link linkend="opt-boot.initrd.luks.devices._name_.fido2.credential">boot.initrd.luks.devices."<replaceable>/dev/sda2</replaceable>".fido2.credential</link> = "<replaceable>f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7</replaceable>"; +</programlisting> + + You can also use the FIDO2 passwordless setup, but for security reasons, you might want to enable it only when your device is PIN protected, such as <link xlink:href="https://trezor.io/">Trezor</link>. + +<programlisting> +<link linkend="opt-boot.initrd.luks.devices._name_.fido2.passwordLess">boot.initrd.luks.devices."<replaceable>/dev/sda2</replaceable>".fido2.passwordLess</link> = true; +</programlisting> + </para> + </section> + +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/modularity.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/modularity.xml new file mode 100644 index 000000000000..532a2c615e4d --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/modularity.xml @@ -0,0 +1,146 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-modularity"> + <title>Modularity</title> + + <para> + The NixOS configuration mechanism is modular. If your + <filename>configuration.nix</filename> 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 + <filename>configuration.nix</filename>. In fact, + <filename>configuration.nix</filename> is itself a module. You can use other + modules by including them from <filename>configuration.nix</filename>, e.g.: +<programlisting> +{ config, pkgs, ... }: + +{ imports = [ ./vpn.nix ./kde.nix ]; + <xref linkend="opt-services.httpd.enable"/> = true; + <xref linkend="opt-environment.systemPackages"/> = [ pkgs.emacs ]; + <replaceable>...</replaceable> +} +</programlisting> + Here, we include two modules from the same directory, + <filename>vpn.nix</filename> and <filename>kde.nix</filename>. The latter + might look like this: +<programlisting> +{ config, pkgs, ... }: + +{ <xref linkend="opt-services.xserver.enable"/> = true; + <xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true; + <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true; + <xref linkend="opt-environment.systemPackages"/> = [ pkgs.vim ]; +} +</programlisting> + Note that both <filename>configuration.nix</filename> and + <filename>kde.nix</filename> 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 + <filename>configuration.nix</filename> 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 <varname>mkBefore</varname>: +<programlisting> +<xref linkend="opt-boot.kernelModules"/> = mkBefore [ "kvm-intel" ]; +</programlisting> + 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"/>, + <command>nixos-rebuild</command> will give an error: +<screen> +The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'. +</screen> + When that happens, it’s possible to force one definition take precedence + over the others: +<programlisting> +<xref linkend="opt-services.httpd.adminAddr"/> = pkgs.lib.mkForce "bob@example.org"; +</programlisting> + </para> + + <para> + When using multiple modules, you may need to access configuration values + defined in other modules. This is what the <varname>config</varname> function + argument is for: it contains the complete, merged system configuration. That + is, <varname>config</varname> is the result of combining the configurations + returned by every module + <footnote xml:id="footnote-nix-is-lazy"> + <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 + “lazy” 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: +<programlisting> +{ config, pkgs, ... }: + +{ <xref linkend="opt-environment.systemPackages"/> = + if config.<xref linkend="opt-services.xserver.enable"/> then + [ pkgs.firefox + pkgs.thunderbird + ] + else + [ ]; +} +</programlisting> + </para> + + <para> + With multiple modules, it may not be obvious what the final value of a + configuration option is. The command <option>nixos-option</option> allows you + to find out: +<screen> +<prompt>$ </prompt>nixos-option <xref linkend="opt-services.xserver.enable"/> +true + +<prompt>$ </prompt>nixos-option <xref linkend="opt-boot.kernelModules"/> +[ "tun" "ipv6" "loop" <replaceable>...</replaceable> ] +</screen> + Interactive exploration of the configuration is possible using <command>nix + repl</command>, a read-eval-print loop for Nix expressions. A typical use: +<screen> +<prompt>$ </prompt>nix repl '<nixpkgs/nixos>' + +<prompt>nix-repl> </prompt>config.<xref linkend="opt-networking.hostName"/> +"mandark" + +<prompt>nix-repl> </prompt>map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/> +[ "example.org" "example.gov" ] +</screen> + </para> + + <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. +<programlisting> +{ config, pkgs, ... }: + +let netConfig = { hostName }: { + networking.hostName = hostName; + networking.useDHCP = false; +}; + +in + +{ imports = [ (netConfig "nixos.localdomain") ]; } +</programlisting> + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/network-manager.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/network-manager.xml new file mode 100644 index 000000000000..94d229fd803f --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/network-manager.xml @@ -0,0 +1,48 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-networkmanager"> + <title>NetworkManager</title> + + <para> + To facilitate network configuration, some desktop environments use + NetworkManager. You can enable NetworkManager by setting: +<programlisting> +<xref linkend="opt-networking.networkmanager.enable"/> = true; +</programlisting> + 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 <code>networkmanager</code> group: +<programlisting> +<link linkend="opt-users.users._name_.extraGroups">users.users.alice.extraGroups</link> = [ "networkmanager" ]; +</programlisting> + </para> + + <para> + NetworkManager is controlled using either <command>nmcli</command> or + <command>nmtui</command> (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> + <code>networking.networkmanager</code> and <code>networking.wireless</code> + (WPA Supplicant) can be used together if desired. To do this you need to instruct + NetworkManager to ignore those interfaces like: +<programlisting> +<xref linkend="opt-networking.networkmanager.unmanaged"/> = [ + "*" "except:type:wwan" "except:type:gsm" +]; +</programlisting> + Refer to the option description for the exact syntax and references to external documentation. + </para> + </note> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/networking.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/networking.xml new file mode 100644 index 000000000000..02cf811e0bd3 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/networking.xml @@ -0,0 +1,19 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-networking"> + <title>Networking</title> + <para> + This section describes how to configure networking components on your NixOS + machine. + </para> + <xi:include href="network-manager.xml" /> + <xi:include href="ssh.xml" /> + <xi:include href="ipv4-config.xml" /> + <xi:include href="ipv6-config.xml" /> + <xi:include href="firewall.xml" /> + <xi:include href="wireless.xml" /> + <xi:include href="ad-hoc-network-config.xml" /> +<!-- TODO: OpenVPN, NAT --> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/package-mgmt.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/package-mgmt.xml new file mode 100644 index 000000000000..e8ac5d0681a9 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/package-mgmt.xml @@ -0,0 +1,31 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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: + <itemizedlist> + <listitem> + <para> + <emphasis>Declarative</emphasis>, where you declare what packages you want + in your <filename>configuration.nix</filename>. Every time you run + <command>nixos-rebuild</command>, 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 <command>nix-env</command> command. This style allows + mixing packages from different Nixpkgs versions. It’s the only choice + for non-root users. + </para> + </listitem> + </itemizedlist> + </para> + <xi:include href="declarative-packages.xml" /> + <xi:include href="ad-hoc-packages.xml" /> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles.xml new file mode 100644 index 000000000000..9d08f7f7bed2 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles.xml @@ -0,0 +1,39 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="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 <filename><nixpkgs/nixos/modules/profiles></filename>. + That is to say, expected usage is to add them to the imports list of your + <filename>/etc/configuration.nix</filename> as such: + </para> +<programlisting> + 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.xml" /> + <xi:include href="profiles/base.xml" /> + <xi:include href="profiles/clone-config.xml" /> + <xi:include href="profiles/demo.xml" /> + <xi:include href="profiles/docker-container.xml" /> + <xi:include href="profiles/graphical.xml" /> + <xi:include href="profiles/hardened.xml" /> + <xi:include href="profiles/headless.xml" /> + <xi:include href="profiles/installation-device.xml" /> + <xi:include href="profiles/minimal.xml" /> + <xi:include href="profiles/qemu-guest.xml" /> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/all-hardware.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/all-hardware.xml new file mode 100644 index 000000000000..2936f71069d5 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/all-hardware.xml @@ -0,0 +1,21 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/base.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/base.xml new file mode 100644 index 000000000000..b75f6ba25b4f --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/base.xml @@ -0,0 +1,15 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-profile-base"> + <title>Base</title> + + <para> + Defines the software packages included in the "minimal" installation CD. It + installs several utilities useful in a simple recovery or install media, such + as a text-mode web browser, and tools for manipulating block devices, + networking, hardware diagnostics, and filesystems (with their respective + kernel modules). + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/clone-config.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/clone-config.xml new file mode 100644 index 000000000000..04fa1643d0fd --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/clone-config.xml @@ -0,0 +1,21 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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.nix</literal>. + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/demo.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/demo.xml new file mode 100644 index 000000000000..bc801bb3dc5b --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/demo.xml @@ -0,0 +1,14 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-profile-demo"> + <title>Demo</title> + + <para> + This profile just enables a <systemitem class="username">demo</systemitem> + user, with password <literal>demo</literal>, uid <literal>1000</literal>, + <systemitem class="groupname">wheel</systemitem> group and + <link linkend="opt-services.xserver.displayManager.autoLogin">autologin in the SDDM display manager</link>. + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/docker-container.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/docker-container.xml new file mode 100644 index 000000000000..efa7b8f24c43 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/docker-container.xml @@ -0,0 +1,16 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/graphical.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/graphical.xml new file mode 100644 index 000000000000..cc6d0825d241 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/graphical.xml @@ -0,0 +1,20 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/hardened.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/hardened.xml new file mode 100644 index 000000000000..dc83fc837e2a --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/hardened.xml @@ -0,0 +1,24 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-profile-hardened"> + <title>Hardened</title> + + <para> + A profile with most (vanilla) hardening options enabled by default, + potentially at the cost of features and performance. + </para> + + <para> + This includes a hardened kernel, and limiting the system information + available to processes through the <filename>/sys</filename> and + <filename>/proc</filename> 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 + <literal + xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix"> + profile source</literal> for further detail on which settings are altered. + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/headless.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/headless.xml new file mode 100644 index 000000000000..1b64497ebf7f --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/headless.xml @@ -0,0 +1,19 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/installation-device.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/installation-device.xml new file mode 100644 index 000000000000..192ae955b689 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/installation-device.xml @@ -0,0 +1,36 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 <command>nixos-install</command> + 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 <command>sudo</command> 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/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/minimal.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/minimal.xml new file mode 100644 index 000000000000..179f2d0be64b --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/minimal.xml @@ -0,0 +1,17 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 + <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> 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/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/qemu-guest.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/qemu-guest.xml new file mode 100644 index 000000000000..5d055c45d2d8 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/profiles/qemu-guest.xml @@ -0,0 +1,18 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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, sets the system time from + the hardware clock to work around a bug in qemu-kvm, and + <link linkend="opt-security.rngd.enable">enables rngd</link>. + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ssh.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ssh.xml new file mode 100644 index 000000000000..95ad3edff935 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/ssh.xml @@ -0,0 +1,27 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-ssh"> + <title>Secure Shell Access</title> + + <para> + Secure shell (SSH) access to your machine can be enabled by setting: +<programlisting> +<xref linkend="opt-services.openssh.enable"/> = true; +</programlisting> + 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: +<!-- FIXME: this might not work if the user is unmanaged. --> +<programlisting> +<link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.alice.openssh.authorizedKeys.keys</link> = + [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ]; +</programlisting> + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/subversion.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/subversion.xml new file mode 100644 index 000000000000..940d63cc4e6d --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/subversion.xml @@ -0,0 +1,140 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="module-services-subversion"> + <title>Subversion</title> + + <para> + <link xlink:href="https://subversion.apache.org/">Subversion</link> + is a centralized version-control system. It can use a <link + xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety + of protocols</link> for communication between client and server. + </para> + <section xml:id="module-services-subversion-apache-httpd"> + <title>Subversion inside Apache HTTP</title> + + <para> + This section focuses on configuring a web-based server on top of + the Apache HTTP server, which uses + <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link + xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link> + for communication. + </para> + + <para>For more information on the general setup, please refer to + the <link + xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the + appropriate section of the Subversion book</link>. + </para> + + <para>To configure, include in + <literal>/etc/nixos/configuration.nix</literal> code to activate + Apache HTTP, setting <xref linkend="opt-services.httpd.adminAddr" /> + appropriately: + </para> + + <para> +<programlisting> + services.httpd.enable = true; + services.httpd.adminAddr = ...; + networking.firewall.allowedTCPPorts = [ 80 443 ]; +</programlisting> + </para> + + <para>For a simple Subversion server with basic authentication, + configure the Subversion module for Apache as follows, setting + <literal>hostName</literal> and <literal>documentRoot</literal> + appropriately, and <literal>SVNParentPath</literal> to the parent + directory of the repositories, + <literal>AuthzSVNAccessFile</literal> to the location of the + <code>.authz</code> file describing access permission, and + <literal>AuthUserFile</literal> to the password file. + </para> + <para> +<programlisting> +services.httpd.extraModules = [ + # note that order is *super* important here + { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; } + { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; } + ]; + services.httpd.virtualHosts = { + "svn" = { + hostName = HOSTNAME; + documentRoot = DOCUMENTROOT; + locations."/svn".extraConfig = '' + DAV svn + SVNParentPath REPO_PARENT + AuthzSVNAccessFile ACCESS_FILE + AuthName "SVN Repositories" + AuthType Basic + AuthUserFile PASSWORD_FILE + Require valid-user + ''; + } +</programlisting> + </para> + + <para> + The key <code>"svn"</code> is just a symbolic name identifying the + virtual host. The <code>"/svn"</code> in + <code>locations."/svn".extraConfig</code> is the path underneath + which the repositories will be served. + </para> + + <para><link + xlink:href="https://wiki.archlinux.org/index.php/Subversion">This + page</link> explains how to set up the Subversion configuration + itself. This boils down to the following: + </para> + <para> + Underneath <literal>REPO_PARENT</literal> repositories can be set up + as follows: + </para> + <para> +<screen> +<prompt>$ </prompt> svn create REPO_NAME +</screen> + </para> + <para>Repository files need to be accessible by + <literal>wwwrun</literal>: + </para> + <para> +<screen> +<prompt>$ </prompt> chown -R wwwrun:wwwrun REPO_PARENT +</screen> + </para> + <para> + The password file <literal>PASSWORD_FILE</literal> can be created as follows: + </para> + <para> +<screen> +<prompt>$ </prompt> htpasswd -cs PASSWORD_FILE USER_NAME +</screen> + </para> + <para> + Additional users can be set up similarly, omitting the + <code>c</code> flag: + </para> + <para> +<screen> +<prompt>$ </prompt> htpasswd -s PASSWORD_FILE USER_NAME +</screen> + </para> + <para> + The file describing access permissions + <literal>ACCESS_FILE</literal> will look something like + the following: + </para> + <para> +<programlisting> +[/] +* = r + +[REPO_NAME:/] +USER_NAME = rw +</programlisting> + </para> + <para>The Subversion repositories will be accessible as <code>http://HOSTNAME/svn/REPO_NAME</code>.</para> + </section> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/summary.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/summary.xml new file mode 100644 index 000000000000..289face16de9 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/summary.xml @@ -0,0 +1,227 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 frame='none'> + <tgroup cols='2'> + <colspec colname='c1' rowsep='1' colsep='1' /> + <colspec colname='c2' rowsep='1' /> + <thead> + <row> + <entry>Example</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry namest="c1" nameend="c2"><emphasis>Basic values</emphasis> + </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/<replaceable>hash</replaceable>-bash-<replaceable>version</replaceable>/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 namest="c1" nameend="c2"><emphasis>Compound values</emphasis> + </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 namest="c1" nameend="c2"><emphasis>Operators</emphasis> + </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 namest="c1" nameend="c2"><emphasis>Control structures</emphasis> + </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 namest="c1" nameend="c2"><emphasis>Functions (lambdas)</emphasis> + </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 namest="c1" nameend="c2"><emphasis>Built-in functions</emphasis> + </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> +<!-- + <row> + <entry><literal>throw "Urgh"</literal></entry> + <entry>Raise an error condition</entry> + </row> + --> + </tbody> + </tgroup> + </informaltable> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/user-mgmt.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/user-mgmt.xml new file mode 100644 index 000000000000..e83e7b75ef54 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/user-mgmt.xml @@ -0,0 +1,88 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 + <filename>configuration.nix</filename>. For instance, the following states + that a user account named <literal>alice</literal> shall exist: +<programlisting> +<xref linkend="opt-users.users"/>.alice = { + <link linkend="opt-users.users._name_.isNormalUser">isNormalUser</link> = true; + <link linkend="opt-users.users._name_.home">home</link> = "/home/alice"; + <link linkend="opt-users.users._name_.description">description</link> = "Alice Foobar"; + <link linkend="opt-users.users._name_.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ]; + <link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; +}; +</programlisting> + Note that <literal>alice</literal> is a member of the + <literal>wheel</literal> and <literal>networkmanager</literal> groups, which + allows her to use <command>sudo</command> 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 <command>passwd</command> program to set a password, which is retained + across invocations of <command>nixos-rebuild</command>. + </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 <command>mkpasswd -m + sha-512</command>. + </para> + <para> + A user ID (uid) is assigned automatically. You can also specify a uid + manually by adding +<programlisting> +uid = 1000; +</programlisting> + to the user specification. + </para> + <para> + Groups can be specified similarly. The following states that a group named + <literal>students</literal> shall exist: +<programlisting> +<xref linkend="opt-users.groups"/>.students.gid = 1000; +</programlisting> + 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 + <command>useradd</command>, <command>groupmod</command> and so on. For + instance, to create a user account named <literal>alice</literal>: +<screen> +<prompt># </prompt>useradd -m <replaceable>alice</replaceable></screen> + To make all nix tools available to this new user use `su - USER` which opens + a login shell (==shell that loads the profile) for given user. This will + create the ~/.nix-defexpr symlink. So run: +<screen> +<prompt># </prompt>su - <replaceable>alice</replaceable> -c "true"</screen> + The flag <option>-m</option> causes the creation of a home directory for the + new user, which is generally what you want. The user does not have an initial + password and therefore cannot log in. A password can be set using the + <command>passwd</command> utility: +<screen> +<prompt># </prompt>passwd <replaceable>alice</replaceable> +Enter new UNIX password: *** +Retype new UNIX password: *** +</screen> + A user can be deleted using <command>userdel</command>: +<screen> +<prompt># </prompt>userdel -r <replaceable>alice</replaceable></screen> + The flag <option>-r</option> deletes the user’s home directory. Accounts + can be modified using <command>usermod</command>. Unix groups can be managed + using <command>groupadd</command>, <command>groupmod</command> and + <command>groupdel</command>. + </para> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/wayland.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/wayland.xml new file mode 100644 index 000000000000..231c219cf081 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/wayland.xml @@ -0,0 +1,23 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-wayland"> + <title>Wayland</title> + + <para> + While X11 (see <xref linkend="sec-x11"/>) is still the primary display + technology on NixOS, Wayland support is steadily improving. + Where X11 separates the X Server and the window manager, on Wayland those + are combined: a Wayland Compositor is like an X11 window manager, but also + embeds the Wayland 'Server' functionality. This means it is sufficient to + install a Wayland Compositor such as <package>sway</package> without + separately enabling a Wayland server: +<programlisting> +<xref linkend="opt-programs.sway.enable"/> = true; +</programlisting> + This installs the <package>sway</package> compositor along with some + essential utilities. Now you can start <package>sway</package> from the TTY + console. + </para> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/wireless.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/wireless.xml new file mode 100644 index 000000000000..247d29d58314 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/wireless.xml @@ -0,0 +1,70 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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 <code>networkmanager</code> 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: +<programlisting> +<xref linkend="opt-networking.wireless.enable"/> = true; +</programlisting> + NixOS lets you specify networks for wpa_supplicant declaratively: +<programlisting> +<xref linkend="opt-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> + 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 <citerefentry> + <refentrytitle>wpa_supplicant.conf</refentrytitle> + <manvolnum>5</manvolnum> </citerefentry>). + </para> + + <para> + If you are using WPA2 you can generate pskRaw key using + <command>wpa_passphrase</command>: +<screen> +<prompt>$ </prompt>wpa_passphrase ESSID PSK +network={ + ssid="echelon" + #psk="abcdefgh" + psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435 +} +</screen> +<programlisting> +<xref linkend="opt-networking.wireless.networks"/> = { + echelon = { + pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435"; + }; +} +</programlisting> + or you can use it to directly generate the + <literal>wpa_supplicant.conf</literal>: +<screen> +<prompt># </prompt>wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen> + After you have edited the <literal>wpa_supplicant.conf</literal>, you need to + restart the wpa_supplicant service. +<screen> +<prompt># </prompt>systemctl restart wpa_supplicant.service</screen> + </para> +</section> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/x-windows.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/x-windows.xml new file mode 100644 index 000000000000..b33f6cf82b52 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/x-windows.xml @@ -0,0 +1,341 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-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: +<programlisting> +<xref linkend="opt-services.xserver.enable"/> = true; +</programlisting> + 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. +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ]; +</programlisting> + 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 <command>xterm</command> window. + Thus you should pick one or more of the following lines: +<programlisting> +<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.gnome3.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.mate.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.icewm.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.i3.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.herbstluftwm.enable"/> = true; +</programlisting> + </para> + <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: +<programlisting> +<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.gdm.enable"/> = true; +</programlisting> + </para> + <para> + You can set the keyboard layout (and optionally the layout variant): +<programlisting> +<xref linkend="opt-services.xserver.layout"/> = "de"; +<xref linkend="opt-services.xserver.xkbVariant"/> = "neo"; +</programlisting> + </para> + <para> + The X server is started automatically at boot time. If you don’t want this + to happen, you can set: +<programlisting> +<xref linkend="opt-services.xserver.autorun"/> = false; +</programlisting> + The X server can then be started manually: +<screen> +<prompt># </prompt>systemctl start display-manager.service +</screen> + </para> + <para> + On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine, + you should also set the following: +<programlisting> +<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true; +</programlisting> + </para> + <simplesect 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: +<programlisting> +<xref linkend="opt-services.xserver.displayManager.defaultSession"/> = "none+i3"; +</programlisting> + Every display manager in NixOS supports auto-login, here is an example + using lightdm for a user <literal>alice</literal>: +<programlisting> +<xref linkend="opt-services.xserver.displayManager.lightdm.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.autoLogin.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.autoLogin.user"/> = "alice"; +</programlisting> + </para> + </simplesect> + <simplesect 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 <package>xorg-server</package> itself) + and <literal>intel</literal> (provided by the package <package>xf86-video-intel</package>). + </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: +<programlisting> + <xref linkend="opt-services.xserver.videoDrivers"/> = [ "modesetting" ]; + <xref linkend="opt-services.xserver.useGlamor"/> = true; +</programlisting> + If you experience screen tearing no matter what, this configuration was + reported to resolve the issue: +<programlisting> + <xref linkend="opt-services.xserver.videoDrivers"/> = [ "intel" ]; + <xref linkend="opt-services.xserver.deviceSection"/> = '' + Option "DRI" "2" + Option "TearFree" "true" + ''; +</programlisting> + Note that this will likely downgrade the performance compared to + <literal>modesetting</literal> or <literal>intel</literal> with DRI 3 (default). + </para> + </simplesect> + <simplesect 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: +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ]; +</programlisting> + Or if you have an older card, you may have to use one of the legacy drivers: +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy390" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy173" ]; +</programlisting> + You may need to reboot after enabling this driver to prevent a clash with + other kernel modules. + </para> + </simplesect> + <simplesect xml:id="sec-x11--graphics-cards-amd"> + <title>Proprietary AMD drivers</title> + <para> + AMD provides a proprietary driver for its graphics cards that has better 3D + performance than the X.org drivers. It is not enabled by default because + it’s not free software. You can enable it as follows: +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "ati_unfree" ]; +</programlisting> + You will need to reboot after enabling this driver to prevent a clash with + other kernel modules. + </para> + <note> + <para> + For recent AMD GPUs you most likely want to keep either the defaults + or <literal>"amdgpu"</literal> (both free). + </para> + </note> + </simplesect> + <simplesect xml:id="sec-x11-touchpads"> + <title>Touchpads</title> + <para> + Support for Synaptics touchpads (found in many laptops such as the Dell + Latitude series) can be enabled as follows: +<programlisting> +<xref linkend="opt-services.xserver.libinput.enable"/> = true; +</programlisting> + The driver has many options (see <xref linkend="ch-options"/>). For + instance, the following disables tap-to-click behavior: +<programlisting> +<xref linkend="opt-services.xserver.libinput.tapping"/> = false; +</programlisting> + Note: the use of <literal>services.xserver.synaptics</literal> is deprecated + since NixOS 17.09. + </para> + </simplesect> + <simplesect 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 GTK2 ones, you can install <literal>qt5.qtbase.gtk</literal> + package into your system environment. It should work for all Qt 5 library + versions. + </para> + </simplesect> + <simplesect 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 + <option> + <link linkend="opt-services.xserver.extraLayouts"> + services.xserver.extraLayouts + </link> + </option>. + As a first example, we are going to create a layout based on the basic US + layout, with an additional layer to type some greek symbols by pressing the + right-alt key. + </para> + <para> + To do this we are going to create a <literal>us-greek</literal> file + with a <literal>xkb_symbols</literal> section. + </para> +<programlisting> +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> + To install the layout, the filepath, a description and the list of + languages must be given: + </para> +<programlisting> +<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = { + description = "US layout with alt-gr greek"; + languages = [ "eng" ]; + symbolsFile = /path/to/us-greek; +} +</programlisting> + <note> + <para> + The name should match the one given to the + <literal>xkb_symbols</literal> block. + </para> + </note> + <para> + The layout should now be installed and ready to use: try it by + running <literal>setxkbmap us-greek</literal> and type + <literal><alt>+a</literal>. To change the default the usual + <option> + <link linkend="opt-services.xserver.layout"> + services.xserver.layout + </link> + </option> + 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> +xkb_keycodes "media" +{ + <volUp> = 123; + <volDown> = 456; +} +</programlisting> + <para> + Now use the newly define keycodes in <literal>media-sym</literal>: + </para> +<programlisting> +xkb_symbols "media" +{ + key.type = "ONE_LEVEL"; + key <volUp> { [ XF86AudioLowerVolume ] }; + key <volDown> { [ XF86AudioRaiseVolume ] }; +} +</programlisting> + <para> + As before, to install the layout do + </para> +<programlisting> +<xref linkend="opt-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> +<xref linkend="opt-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 <command>xinit</command> run + <screen><prompt>$ </prompt>xinit -- -xkbdir /etc/X11/xkb</screen> + </para> + <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> +</simplesect> +</chapter> diff --git a/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/xfce.xml b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/xfce.xml new file mode 100644 index 000000000000..abcf5f648a48 --- /dev/null +++ b/infra/libkookie/nixpkgs/nixos/doc/manual/configuration/xfce.xml @@ -0,0 +1,59 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-xfce"> + <title>Xfce Desktop Environment</title> + <para> + To enable the Xfce Desktop Environment, set +<programlisting> +<xref linkend="opt-services.xserver.desktopManager.xfce.enable" /> = true; +<xref linkend="opt-services.xserver.displayManager.defaultSession" /> = "xfce"; +</programlisting> + </para> + <para> + Optionally, <emphasis>picom</emphasis> can be enabled for nice graphical + effects, some example settings: +<programlisting> +<link linkend="opt-services.picom.enable">services.picom</link> = { + <link linkend="opt-services.picom.enable">enable</link> = true; + <link linkend="opt-services.picom.fade">fade</link> = true; + <link linkend="opt-services.picom.inactiveOpacity">inactiveOpacity</link> = 0.9; + <link linkend="opt-services.picom.shadow">shadow</link> = true; + <link linkend="opt-services.picom.fadeDelta">fadeDelta</link> = 4; +}; +</programlisting> + </para> + <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> + <simplesect 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> + </simplesect> + <simplesect 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 <command>journalctl --user -b</command>). +<programlisting> +Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported +</programlisting> + 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. +<programlisting> +<prompt>$ </prompt>xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true +</programlisting> + A log-out and re-log will be needed for this to take effect. + </para> + </simplesect> +</chapter> |