kaffa/obsidian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

dev: NixOS 25.11 매뉴얼 로컬 사본 추가

Browse Source 
nixpkgs nixos-25.11 브랜치의 nixos/doc/manual/ 디렉토리를 sparse clone으로
가져와 ~/obsidian/dev/nixos-manual/에 복사. _index.md에 구조/갱신 방법 정리.

오프라인 참조 + AI 에이전트 컨텍스트용. sandbox-tokyo 같은 NixOS 노드 운영 시
빠른 참조로 사용.
This commit is contained in:
kappa
2026-04-08 16:15:46 +09:00
parent 862ca9bae8
commit 370c7da4a9
145 changed files with 24441 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
dev/nixos-manual/configuration/abstractions.section.md Normal file
View File

@@ -0,0 +1,94 @@
# Abstractions {#sec-module-abstractions}
If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration:
```nix
{
services.httpd.virtualHosts = {
"blog.example.org" = {
documentRoot = "/webroot/blog.example.org";
adminAddr = "alice@example.org";
forceSSL = true;
enableACME = true;
};
"wiki.example.org" = {
documentRoot = "/webroot/wiki.example.org";
adminAddr = "alice@example.org";
forceSSL = true;
enableACME = true;
};
};
}
```
It defines two virtual hosts with nearly identical configuration; the only difference is the document root directories. To prevent this duplication, we can use a `let`:
```nix
let
commonConfig = {
adminAddr = "alice@example.org";
forceSSL = true;
enableACME = true;
};
in
{
services.httpd.virtualHosts = {
"blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; });
"wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.org"; });
};
}
```
The `let commonConfig = ...` defines a variable named `commonConfig`. The `//` operator merges two attribute sets, so the configuration of the second virtual host is the set `commonConfig` extended with the document root option.
You can write a `let` wherever an expression is allowed. Thus, you also could have written:
```nix
{
services.httpd.virtualHosts =
let
commonConfig = {
# ...
};
in
{
"blog.example.org" = (
commonConfig
// {
# ...
}
);
"wiki.example.org" = (
commonConfig
// {
# ...
}
);
};
}
```
but not `{ let commonConfig = ...; in ...; }` since attributes (as opposed to attribute values) are not expressions.
**Functions** provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the document root. This can be done as follows:
```nix
{
services.httpd.virtualHosts =
let
makeVirtualHost = webroot: {
documentRoot = webroot;
adminAddr = "alice@example.org";
forceSSL = true;
enableACME = true;
};
in
{
"example.org" = (makeVirtualHost "/webroot/example.org");
"example.com" = (makeVirtualHost "/webroot/example.com");
"example.gov" = (makeVirtualHost "/webroot/example.gov");
"example.nl" = (makeVirtualHost "/webroot/example.nl");
};
}
```
Here, `makeVirtualHost` is a function that takes a single argument `webroot` and returns the configuration for a virtual host. That function is then called for several names to produce the list of virtual host configurations.

14
dev/nixos-manual/configuration/ad-hoc-network-config.section.md Normal file
View File

@@ -0,0 +1,14 @@
# Ad-Hoc Configuration {#ad-hoc-network-config}
You can use [](#opt-networking.localCommands) to
specify shell commands to be run at the end of `network-setup.service`. This
is useful for doing network configuration not covered by the existing NixOS
modules. For instance, to statically configure an IPv6 address:
```nix
{
networking.localCommands = ''
ip -6 addr add 2001:610:685:1::1/64 dev eth0
'';
}
```

51
dev/nixos-manual/configuration/ad-hoc-packages.section.md Normal file
View File

@@ -0,0 +1,51 @@
# Ad-Hoc Package Management {#sec-ad-hoc-packages}
With the command `nix-env`, you can install and uninstall packages from
the command line. For instance, to install Mozilla Thunderbird:
```ShellSession
$ nix-env -iA nixos.thunderbird
```
If you invoke this as root, the package is installed in the Nix profile
`/nix/var/nix/profiles/default` and visible to all users of the system;
otherwise, the package ends up in
`/nix/var/nix/profiles/per-user/username/profile` and is not visible to
other users. The `-A` flag specifies the package by its attribute name;
without it, the package is installed by matching against its package
name (e.g. `thunderbird`). The latter is slower because it requires
matching against all available Nix packages, and is ambiguous if there
are multiple matching packages.
Packages come from the NixOS channel. You typically upgrade a package by
updating to the latest version of the NixOS channel:
```ShellSession
$ nix-channel --update nixos
```
and then running `nix-env -i` again. Other packages in the profile are
*not* affected; this is the crucial difference with the declarative
style of package management, where running `nixos-rebuild switch` causes
all packages to be updated to their current versions in the NixOS
channel. You can however upgrade all packages for which there is a newer
version by doing:
```ShellSession
$ nix-env -u '*'
```
A package can be uninstalled using the `-e` flag:
```ShellSession
$ nix-env -e thunderbird
```
Finally, you can roll back an undesirable `nix-env` action:
```ShellSession
$ nix-env --rollback
```
`nix-env` has many more flags. For details, see the nix-env(1) manpage or
the Nix manual.

119
dev/nixos-manual/configuration/adding-custom-packages.section.md Normal file
View File

@@ -0,0 +1,119 @@
# Adding Custom Packages {#sec-custom-packages}
It's possible that a package you need is not available in NixOS. In that
case, you can do two things. Either you can package it with Nix, or you can try
to use prebuilt packages from upstream. Due to the peculiarities of NixOS, it
is important to note that building software from source is often easier than
using pre-built executables.
## Building with Nix {#sec-custom-packages-nix}
This can be done either in-tree or out-of-tree. For an in-tree build, you can
clone the Nixpkgs repository, add the package to your clone, and (optionally)
submit a patch or pull request to have it accepted into the main Nixpkgs
repository. This is described in detail in the [Nixpkgs
manual](https://nixos.org/nixpkgs/manual). In short, you clone Nixpkgs:
```ShellSession
$ git clone https://github.com/NixOS/nixpkgs
$ cd nixpkgs
```
Then you write and test the package as described in the Nixpkgs manual.
Finally, you add it to [](#opt-environment.systemPackages), e.g.
```nix
{ environment.systemPackages = [ pkgs.my-package ]; }
```
and you run `nixos-rebuild`, specifying your own Nixpkgs tree:
```ShellSession
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
```
The second possibility is to add the package outside of the Nixpkgs
tree. For instance, here is how you specify a build of the
[GNU Hello](https://www.gnu.org/software/hello/) package directly in
`configuration.nix`:
```nix
{
environment.systemPackages =
let
my-hello =
with pkgs;
stdenv.mkDerivation rec {
name = "hello-2.8";
src = fetchurl {
url = "mirror://gnu/hello/${name}.tar.gz";
hash = "sha256-5rd/gffPfa761Kn1tl3myunD8TuM+66oy1O7XqVGDXM=";
};
};
in
[ my-hello ];
}
```
Of course, you can also move the definition of `my-hello` into a
separate Nix expression, e.g.
```nix
{ environment.systemPackages = [ (import ./my-hello.nix) ]; }
```
where `my-hello.nix` contains:
```nix
with import <nixpkgs> { }; # bring all of Nixpkgs into scope
stdenv.mkDerivation rec {
name = "hello-2.8";
src = fetchurl {
url = "mirror://gnu/hello/${name}.tar.gz";
hash = "sha256-5rd/gffPfa761Kn1tl3myunD8TuM+66oy1O7XqVGDXM=";
};
}
```
This allows testing the package easily:
```ShellSession
$ nix-build my-hello.nix
$ ./result/bin/hello
Hello, world!
```
## Using pre-built executables {#sec-custom-packages-prebuilt}
Most pre-built executables will not work on NixOS. There are two notable
exceptions: flatpaks and AppImages. For flatpaks see the [dedicated
section](#module-services-flatpak). AppImages can run "as-is" on NixOS.
First you need to enable AppImage support: add to `/etc/nixos/configuration.nix`
```nix
{
programs.appimage.enable = true;
programs.appimage.binfmt = true;
}
```
Then you can run the AppImage "as-is" or with `appimage-run foo.appimage`.
If there are shared libraries missing add them with
```nix
{
programs.appimage.package = pkgs.appimage-run.override {
extraPkgs = pkgs: [
# missing libraries here, e.g.: `pkgs.libepoxy`
];
};
}
```
To make other pre-built executables work on NixOS, you need to package them
with Nix and special helpers like `autoPatchelfHook` or `buildFHSEnv`. See
the [Nixpkgs manual](https://nixos.org/nixpkgs/manual) for details. This
is complex and often doing a source build is easier.

194
dev/nixos-manual/configuration/config-file.section.md Normal file
View File

@@ -0,0 +1,194 @@
# NixOS Configuration File {#sec-configuration-file}
The NixOS configuration file generally looks like this:
```nix
{ config, pkgs, ... }:
{
# option definitions
}
```
The first line (`{ config, pkgs, ... }:`) denotes that this is actually
a function that takes at least the two arguments `config` and `pkgs`.
(These are explained later, in chapter [](#sec-writing-modules)) The
function returns a *set* of option definitions (`{ ... }`).
These definitions have the form `name = value`, where `name` is the
name of an option and `value` is its value. For example,
```nix
{ config, pkgs, ... }:
{
services.httpd.enable = true;
services.httpd.adminAddr = "alice@example.org";
services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
}
```
defines a configuration with three option definitions that together
enable the Apache HTTP Server with `/webroot` as the document root.
Sets can be nested, and in fact dots in option names are shorthand for
defining a set containing another set. For instance,
[](#opt-services.httpd.enable) defines a set named
`services` that contains a set named `httpd`, which in turn contains an
option definition named `enable` with value `true`. This means that the
example above can also be written as:
```nix
{ config, pkgs, ... }:
{
services = {
httpd = {
enable = true;
adminAddr = "alice@example.org";
virtualHosts = {
localhost = {
documentRoot = "/webroot";
};
};
};
};
}
```
which may be more convenient if you have lots of option definitions that
share the same prefix (such as `services.httpd`).
NixOS checks your option definitions for correctness. For instance, if
you try to define an option that doesn't exist (that is, doesn't have a
corresponding *option declaration*), `nixos-rebuild` will give an error
like:
```plain
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
```
Likewise, values in option definitions must have a correct type. For
instance, `services.httpd.enable` must be a Boolean (`true` or `false`).
Trying to give it a value of another type, such as a string, will cause
an error:
```plain
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
```
Options have various types of values. The most important are:
Strings
: Strings are enclosed in double quotes, e.g.
```nix
{
networking.hostName = "dexter";
}
```
Special characters can be escaped by prefixing them with a backslash
(e.g. `\"`).
Multi-line strings can be enclosed in *double single quotes*, e.g.
```nix
{
networking.extraHosts =
''
127.0.0.2 other-localhost
10.0.0.1 server
'';
}
```
The main difference is that it strips from each line a number of
spaces equal to the minimal indentation of the string as a whole
(disregarding the indentation of empty lines), and that characters
like `"` and `\` are not special (making it more convenient for
including things like shell code). See more info about this in the
Nix manual [here](https://nixos.org/nix/manual/#ssec-values).
Booleans
: These can be `true` or `false`, e.g.
```nix
{
networking.firewall.enable = true;
networking.firewall.allowPing = false;
}
```
Integers
: For example,
```nix
{
boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
}
```
(Note that here the attribute name `net.ipv4.tcp_keepalive_time` is
enclosed in quotes to prevent it from being interpreted as a set
named `net` containing a set named `ipv4`, and so on. This is
because it's not a NixOS option but the literal name of a Linux
kernel setting.)
Sets
: Sets were introduced above. They are name/value pairs enclosed in
braces, as in the option definition
```nix
{
fileSystems."/boot" =
{ device = "/dev/sda1";
fsType = "ext4";
options = [ "rw" "data=ordered" "relatime" ];
};
}
```
Lists
: The important thing to note about lists is that list elements are
separated by whitespace, like this:
```nix
{
boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
}
```
List elements can be any other type, e.g. sets:
```nix
{
swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
}
```
Packages
: Usually, the packages you need are already part of the Nix Packages
collection, which is a set that can be accessed through the function
argument `pkgs`. Typical uses:
```nix
{
environment.systemPackages =
[ pkgs.thunderbird
pkgs.emacs
];
services.postgresql.package = pkgs.postgresql_14;
}
```
The latter option definition changes the default PostgreSQL package
used by NixOS's PostgreSQL service to 14.x. For more information on
packages, including how to add new ones, see
[](#sec-custom-packages).

18
dev/nixos-manual/configuration/config-syntax.chapter.md Normal file
View File

@@ -0,0 +1,18 @@
# Configuration Syntax {#sec-configuration-syntax}
The NixOS configuration file `/etc/nixos/configuration.nix` is actually
a *Nix expression*, which is the Nix package manager's purely functional
language for describing how to build packages and configurations. This
means you have all the expressive power of that language at your
disposal, including the ability to abstract over common patterns, which
is very useful when managing complex systems. The syntax and semantics
of the Nix language are fully described in the [Nix
manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions), but
here we give a short overview of the most important constructs useful in
NixOS configuration files.
```{=include=} sections
config-file.section.md
abstractions.section.md
modularity.section.md
```

28
dev/nixos-manual/configuration/configuration.md Normal file
View File

@@ -0,0 +1,28 @@
# Configuration {#ch-configuration}
This chapter describes how to configure various aspects of a NixOS machine through the configuration file {file}`/etc/nixos/configuration.nix`. As described in [](#sec-changing-config), changes to this file only take effect after you run {command}`nixos-rebuild`.
```{=include=} chapters
config-syntax.chapter.md
package-mgmt.chapter.md
user-mgmt.chapter.md
file-systems.chapter.md
x-windows.chapter.md
wayland.chapter.md
gpu-accel.chapter.md
xfce.chapter.md
networking.chapter.md
linux-kernel.chapter.md
subversion.chapter.md
```
```{=include=} chapters
@MODULE_CHAPTERS@
```
```{=include=} chapters
profiles.chapter.md
mattermost.chapter.md
kubernetes.chapter.md
```
<!-- Apache; libvirtd virtualisation -->

121
dev/nixos-manual/configuration/customizing-packages.section.md Normal file
View File

@@ -0,0 +1,121 @@
# Customising Packages {#sec-customising-packages}
The Nixpkgs configuration for a NixOS system is set by the {option}`nixpkgs.config` option.
::::{.example}
# Globally allow unfree packages
```nix
{
nixpkgs.config = {
allowUnfree = true;
};
}
```
:::{.note}
This only allows unfree software in the given NixOS configuration.
For users invoking Nix commands such as [`nix-build`](https://nixos.org/manual/nix/stable/command-ref/nix-build), Nixpkgs is configured independently.
See the [Nixpkgs manual section on global configuration](https://nixos.org/manual/nixpkgs/unstable/#chap-packageconfig) for details.
:::
::::
<!-- TODO(@fricklerhandwerk)
all of the following should go to the Nixpkgs manual, it has nothing to do with NixOS
-->
Some packages in Nixpkgs have options to enable or disable optional functionality, or change other aspects of the package.
::: {.warning}
Unfortunately, Nixpkgs currently lacks a way to query available package configuration options.
:::
::: {.note}
For example, many packages come with extensions one might add.
Examples include:
- [`passExtensions.pass-otp`](https://search.nixos.org/packages?query=passExtensions.pass-otp)
- [`python312Packages.requests`](https://search.nixos.org/packages?query=python312Packages.requests)
You can use them like this:
```nix
{
environment.systemPackages = with pkgs; [
sl
(pass.withExtensions (
subpkgs: with subpkgs; [
pass-audit
pass-otp
pass-genphrase
]
))
(python3.withPackages (subpkgs: with subpkgs; [ requests ]))
cowsay
];
}
```
:::
Apart from high-level options, it's possible to tweak a package in
almost arbitrary ways, such as changing or disabling dependencies of a
package. For instance, the Emacs package in Nixpkgs by default has a
dependency on GTK 2. If you want to build it against GTK 3, you can
specify that as follows:
```nix
{ environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; }
```
The function `override` performs the call to the Nix function that
produces Emacs, with the original arguments amended by the set of
arguments specified by you. So here the function argument `gtk` gets the
value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses
are necessary because in Nix, function application binds more weakly
than list construction, so without them,
[](#opt-environment.systemPackages)
would be a list with two elements.)
Even greater customisation is possible using the function
`overrideAttrs`. While the `override` mechanism above overrides the
arguments of a package function, `overrideAttrs` allows changing the
*attributes* passed to `mkDerivation`. This permits changing any aspect
of the package, such as the source code. For instance, if you want to
override the source code of Emacs, you can say:
```nix
{
environment.systemPackages = [
(pkgs.emacs.overrideAttrs (oldAttrs: {
name = "emacs-25.0-pre";
src = /path/to/my/emacs/tree;
}))
];
}
```
Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs`
and produces a new derivation in which the original's `name` and `src`
attribute have been replaced by the given values by re-calling
`stdenv.mkDerivation`. The original attributes are accessible via the
function argument, which is conventionally named `oldAttrs`.
The overrides shown above are not global. They do not affect the
original package; other packages in Nixpkgs continue to depend on the
original rather than the customised package. This means that if another
package in your system depends on the original package, you end up with
two instances of the package. If you want to have everything depend on
your customised instance, you can apply a *global* override as follows:
```nix
{
nixpkgs.config.packageOverrides = pkgs: {
emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
};
}
```
The effect of this definition is essentially equivalent to modifying the
`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs
that depends on `emacs` will be passed your customised instance.
(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides`
refers to the original rather than overridden instance, to prevent an
infinite recursion.)

46
dev/nixos-manual/configuration/declarative-packages.section.md Normal file
View File

@@ -0,0 +1,46 @@
# Declarative Package Management {#sec-declarative-package-mgmt}
With declarative package management, you specify which packages you want
on your system by setting the option
[](#opt-environment.systemPackages). For instance, adding the
following line to `configuration.nix` enables the Mozilla Thunderbird
email application:
```nix
{ environment.systemPackages = [ pkgs.thunderbird ]; }
```
The effect of this specification is that the Thunderbird package from
Nixpkgs will be built or downloaded as part of the system when you run
`nixos-rebuild switch`.
::: {.note}
Some packages require additional global configuration such as D-Bus or
systemd service registration so adding them to
[](#opt-environment.systemPackages) might not be sufficient. You are
advised to check the [list of options](#ch-options) whether a NixOS
module for the package does not exist.
:::
You can get a list of the available packages as follows:
```ShellSession
$ nix-env -qaP '*' --description
nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
...
```
The first column in the output is the *attribute name*, such as
`nixos.thunderbird`.
Note: the `nixos` prefix tells us that we want to get the package from
the `nixos` channel and works only in CLI tools. In declarative
configuration, use `pkgs` prefix (variable).
To "uninstall" a package, remove it from
[](#opt-environment.systemPackages) and run `nixos-rebuild switch`.
```{=include=} sections
customizing-packages.section.md
adding-custom-packages.section.md
```

45
dev/nixos-manual/configuration/file-systems.chapter.md Normal file
View File

@@ -0,0 +1,45 @@
# File Systems {#ch-file-systems}
You can define file systems using the `fileSystems` configuration
option. For instance, the following definition causes NixOS to mount the
Ext4 file system on device `/dev/disk/by-label/data` onto the mount
point `/data`:
```nix
{
fileSystems."/data" = {
device = "/dev/disk/by-label/data";
fsType = "ext4";
};
}
```
This will create an entry in `/etc/fstab`, which will generate a
corresponding [systemd.mount](https://www.freedesktop.org/software/systemd/man/systemd.mount.html)
unit via [systemd-fstab-generator](https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html).
The filesystem will be mounted automatically unless `"noauto"` is
present in [options](#opt-fileSystems._name_.options). `"noauto"`
filesystems can be mounted explicitly using `systemctl` e.g.
`systemctl start data.mount`. Mount points are created automatically if they don't
already exist. For `device`, it's best to use the topology-independent
device aliases in `/dev/disk/by-label` and `/dev/disk/by-uuid`, as these
don't change if the topology changes (e.g. if a disk is moved to another
IDE controller).
You can usually omit the file system type (`fsType`), since `mount` can
usually detect the type and load the necessary kernel module
automatically. However, if the file system is needed at early boot (in
the initial ramdisk) and is not `ext2`, `ext3` or `ext4`, then it's best
to specify `fsType` to ensure that the kernel module is available.
::: {.note}
System startup will fail if any of the filesystems fails to mount,
dropping you to the emergency shell. You can make a mount asynchronous
and non-critical by adding `options = [ "nofail" ];`.
:::
```{=include=} sections
luks-file-systems.section.md
sshfs-file-systems.section.md
overlayfs.section.md
```

45
dev/nixos-manual/configuration/firewall.section.md Normal file
View File

@@ -0,0 +1,45 @@
# Firewall {#sec-firewall}
NixOS has a simple stateful firewall that blocks incoming connections
and other unexpected packets. The firewall applies to both IPv4 and IPv6
traffic. It is enabled by default. It can be disabled as follows:
```nix
{ networking.firewall.enable = false; }
```
If the firewall is enabled, you can open specific TCP ports to the
outside world:
```nix
{
networking.firewall.allowedTCPPorts = [
80
443
];
}
```
Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is
enabled (`services.openssh.enable = true`). UDP ports can be opened through
[](#opt-networking.firewall.allowedUDPPorts).
To open ranges of TCP ports:
```nix
{
networking.firewall.allowedTCPPortRanges = [
{
from = 4000;
to = 4007;
}
{
from = 8000;
to = 8010;
}
];
}
```
Similarly, UDP port ranges can be opened through
[](#opt-networking.firewall.allowedUDPPortRanges).

197
dev/nixos-manual/configuration/gpu-accel.chapter.md Normal file
View File

@@ -0,0 +1,197 @@
# GPU acceleration {#sec-gpu-accel}
NixOS provides various APIs that benefit from GPU hardware acceleration,
such as VA-API and VDPAU for video playback; OpenGL and Vulkan for 3D
graphics; and OpenCL for general-purpose computing. This chapter
describes how to set up GPU hardware acceleration (as far as this is not
done automatically) and how to verify that hardware acceleration is
indeed used.
Most of the aforementioned APIs are agnostic with regards to which
display server is used. Consequently, these instructions should apply
both to the X Window System and Wayland compositors.
## OpenCL {#sec-gpu-accel-opencl}
[OpenCL](https://en.wikipedia.org/wiki/OpenCL) is a general compute API.
It is used by various applications such as Blender and Darktable to
accelerate certain operations.
OpenCL applications load drivers through the *Installable Client Driver*
(ICD) mechanism. In this mechanism, an ICD file specifies the path to
the OpenCL driver for a particular GPU family. In NixOS, there are two
ways to make ICD files visible to the ICD loader. The first is through
the `OCL_ICD_VENDORS` environment variable. This variable can contain a
directory which is scanned by the ICL loader for ICD files. For example:
```ShellSession
$ export \
OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocmPackages.clr.icd`/etc/OpenCL/vendors/
```
The second mechanism is to add the OpenCL driver package to
[](#opt-hardware.graphics.extraPackages).
This links the ICD file under `/run/opengl-driver`, where it will be visible
to the ICD loader.
The proper installation of OpenCL drivers can be verified through the
`clinfo` command of the clinfo package. This command will report the
number of hardware devices that is found and give detailed information
for each device:
```ShellSession
$ clinfo | head -n3
Number of platforms 1
Platform Name AMD Accelerated Parallel Processing
Platform Vendor Advanced Micro Devices, Inc.
```
### AMD {#sec-gpu-accel-opencl-amd}
Modern AMD [Graphics Core
Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are
supported through the rocmPackages.clr.icd package. Adding this package to
[](#opt-hardware.graphics.extraPackages)
enables OpenCL support:
```nix
{ hardware.graphics.extraPackages = [ rocmPackages.clr.icd ]; }
```
### Intel {#sec-gpu-accel-opencl-intel}
[Intel Gen12 and later GPUs](https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen12)
are supported by the Intel NEO OpenCL runtime that is provided by the `intel-compute-runtime` package.
The previous generations (8,9 and 11), have been moved to the `intel-compute-runtime-legacy1` package.
The proprietary Intel OpenCL runtime, in the `intel-ocl` package, is an alternative for Gen7 GPUs.
Both `intel-compute-runtime` packages, as well as the `intel-ocl` package can be added to
[](#opt-hardware.graphics.extraPackages)
to enable OpenCL support. For example, for Gen12 and later GPUs, the following
configuration can be used:
```nix
{ hardware.graphics.extraPackages = [ intel-compute-runtime ]; }
```
## Vulkan {#sec-gpu-accel-vulkan}
[Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API)) is a graphics and
compute API for GPUs. It is used directly by games or indirectly though
compatibility layers like
[DXVK](https://github.com/doitsujin/dxvk/wiki).
By default, if [](#opt-hardware.graphics.enable)
is enabled, Mesa is installed and provides Vulkan for supported hardware.
Similar to OpenCL, Vulkan drivers are loaded through the *Installable
Client Driver* (ICD) mechanism. ICD files for Vulkan are JSON files that
specify the path to the driver library and the supported Vulkan version.
All successfully loaded drivers are exposed to the application as
different GPUs. In NixOS, there are two ways to make ICD files visible
to Vulkan applications: an environment variable and a module option.
The way to do this is to add the Vulkan driver package to
[](#opt-hardware.graphics.extraPackages).
This links the ICD file under `/run/opengl-driver`, where it will be
visible to the ICD loader.
The proper installation of Vulkan drivers can be verified through the
`vulkaninfo` command of the vulkan-tools package. This command will
report the hardware devices and drivers found, in this example output
amdvlk and radv:
```ShellSession
$ vulkaninfo | grep GPU
GPU id : 0 (Unknown AMD GPU)
GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
...
GPU0:
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
deviceName = Unknown AMD GPU
GPU1:
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
```
A simple graphical application that uses Vulkan is `vkcube` from the
vulkan-tools package.
### AMD {#sec-gpu-accel-vulkan-amd}
Modern AMD [Graphics Core
Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are
supported through the RADV driver, which is part of mesa.
## VA-API {#sec-gpu-accel-va-api}
[VA-API (Video Acceleration API)](https://www.intel.com/content/www/us/en/developer/articles/technical/linuxmedia-vaapi.html)
is an open-source library and API specification, which provides access to
graphics hardware acceleration capabilities for video processing.
VA-API drivers are loaded by `libva`. The version in nixpkgs is built to search
the opengl driver path, so drivers can be installed in
[](#opt-hardware.graphics.extraPackages).
VA-API can be tested using:
```ShellSession
$ nix-shell -p libva-utils --run vainfo
```
### Intel {#sec-gpu-accel-va-api-intel}
Modern Intel GPUs use the iHD driver, which can be installed with:
```nix
{ hardware.graphics.extraPackages = [ intel-media-driver ]; }
```
Older Intel GPUs use the i965 driver, which can be installed with:
```nix
{ hardware.graphics.extraPackages = [ intel-vaapi-driver ]; }
```
## Common issues {#sec-gpu-accel-common-issues}
### User permissions {#sec-gpu-accel-common-issues-permissions}
Except where noted explicitly, it should not be necessary to adjust user
permissions to use these acceleration APIs. In the default
configuration, GPU devices have world-read/write permissions
(`/dev/dri/renderD*`) or are tagged as `uaccess` (`/dev/dri/card*`). The
access control lists of devices with the `uaccess` tag will be updated
automatically when a user logs in through `systemd-logind`. For example,
if the user *alice* is logged in, the access control list should look as
follows:
```ShellSession
$ getfacl /dev/dri/card0
# file: dev/dri/card0
# owner: root
# group: video
user::rw-
user:alice:rw-
group::rw-
mask::rw-
other::---
```
If you disabled (this functionality of) `systemd-logind`, you may need
to add the user to the `video` group and log in again.
### Mixing different versions of nixpkgs {#sec-gpu-accel-common-issues-mixing-nixpkgs}
The *Installable Client Driver* (ICD) mechanism used by OpenCL and
Vulkan loads runtimes into its address space using `dlopen`. Mixing an
ICD loader mechanism and runtimes from different version of nixpkgs may
not work. For example, if the ICD loader uses an older version of glibc
than the runtime, the runtime may not be loadable due to missing
symbols. Unfortunately, the loader will generally be quiet about such
issues.
If you suspect that you are running into library version mismatches
between an ICL loader and a runtime, you could run an application with
the `LD_DEBUG` variable set to get more diagnostic information. For
example, OpenCL can be tested with `LD_DEBUG=files clinfo`, which should
report missing symbols.

41
dev/nixos-manual/configuration/ipv4-config.section.md Normal file
View File

@@ -0,0 +1,41 @@
# IPv4 Configuration {#sec-ipv4}
By default, NixOS uses DHCP (specifically, `dhcpcd`) to automatically
configure network interfaces. However, you can configure an interface
manually as follows:
```nix
{
networking.interfaces.eth0.ipv4.addresses = [
{
address = "192.168.1.2";
prefixLength = 24;
}
];
}
```
Typically you'll also want to set a default gateway and set of name
servers:
```nix
{
networking.defaultGateway = "192.168.1.1";
networking.nameservers = [ "8.8.8.8" ];
}
```
::: {.note}
Statically configured interfaces are set up by the systemd service
`interface-name-cfg.service`. The default gateway and name server
configuration is performed by `network-setup.service`.
:::
The host name is set using [](#opt-networking.hostName):
```nix
{ networking.hostName = "cartman"; }
```
The default host name is `nixos`. Set it to the empty string (`""`) to
allow the DHCP server to provide the host name.

48
dev/nixos-manual/configuration/ipv6-config.section.md Normal file
View File

@@ -0,0 +1,48 @@
# IPv6 Configuration {#sec-ipv6}
IPv6 is enabled by default. Stateless address autoconfiguration is used
to automatically assign IPv6 addresses to all interfaces, and Privacy
Extensions (RFC 4941) are enabled by default. You can adjust the default
for this by setting [](#opt-networking.tempAddresses). This option
may be overridden on a per-interface basis by
[](#opt-networking.interfaces._name_.tempAddress). You can disable
IPv6 support globally by setting:
```nix
{ networking.enableIPv6 = false; }
```
You can disable IPv6 on a single interface using a normal sysctl (in
this example, we use interface `eth0`):
```nix
{ boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true; }
```
As with IPv4 networking interfaces are automatically configured via
DHCPv6. You can configure an interface manually:
```nix
{
networking.interfaces.eth0.ipv6.addresses = [
{
address = "fe00:aa:bb:cc::2";
prefixLength = 64;
}
];
}
```
For configuring a gateway, optionally with explicitly specified
interface:
```nix
{
networking.defaultGateway6 = {
address = "fe00::1";
interface = "enp0s3";
};
}
```
See [](#sec-ipv4) for similar examples and additional information.

103
dev/nixos-manual/configuration/kubernetes.chapter.md Normal file
View File

@@ -0,0 +1,103 @@
# Kubernetes {#sec-kubernetes}
The NixOS Kubernetes module is a collective term for a handful of
individual submodules implementing the Kubernetes cluster components.
There are generally two ways of enabling Kubernetes on NixOS. One way is
to enable and configure cluster components appropriately by hand:
```nix
{
services.kubernetes = {
apiserver.enable = true;
controllerManager.enable = true;
scheduler.enable = true;
addonManager.enable = true;
proxy.enable = true;
flannel.enable = true;
};
}
```
Another way is to assign cluster roles ("master" and/or "node") to
the host. This enables apiserver, controllerManager, scheduler,
addonManager, kube-proxy and etcd:
```nix
{ services.kubernetes.roles = [ "master" ]; }
```
While this will enable the kubelet and kube-proxy only:
```nix
{ services.kubernetes.roles = [ "node" ]; }
```
Assigning both the master and node roles is usable if you want a single
node Kubernetes cluster for dev or testing purposes:
```nix
{
services.kubernetes.roles = [
"master"
"node"
];
}
```
Note: Assigning either role will also default both
[](#opt-services.kubernetes.flannel.enable)
and [](#opt-services.kubernetes.easyCerts)
to true. This sets up flannel as CNI and activates automatic PKI bootstrapping.
::: {.note}
It is mandatory to configure:
[](#opt-services.kubernetes.masterAddress).
The masterAddress must be resolvable and routable by all cluster nodes.
In single node clusters, this can be set to `localhost`.
:::
Role-based access control (RBAC) authorization mode is enabled by
default. This means that anonymous requests to the apiserver secure port
will expectedly cause a permission denied error. All cluster components
must therefore be configured with x509 certificates for two-way tls
communication. The x509 certificate subject section determines the roles
and permissions granted by the apiserver to perform clusterwide or
namespaced operations. See also: [ Using RBAC
Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
The NixOS kubernetes module provides an option for automatic certificate
bootstrapping and configuration,
[](#opt-services.kubernetes.easyCerts).
The PKI bootstrapping process involves setting up a certificate authority (CA)
daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert
for the cluster, and uses the CA-cert for signing subordinate certs issued
to each of the cluster components. Subsequently, the certmgr daemon monitors
active certificates and renews them when needed. For single node Kubernetes
clusters, setting [](#opt-services.kubernetes.easyCerts)
= true is sufficient and no further action is required. For joining extra node
machines to an existing cluster on the other hand, establishing initial
trust is mandatory.
To add new nodes to the cluster: On any (non-master) cluster node where
[](#opt-services.kubernetes.easyCerts)
is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH.
Given a token on stdin, it will copy the token to the kubernetes secrets directory
and restart the certmgr service. As requested certificates are issued, the
script will restart kubernetes cluster components as needed for them to
pick up new keypairs.
::: {.note}
Multi-master (HA) clusters are not supported by the easyCerts module.
:::
In order to interact with an RBAC-enabled cluster as an administrator,
one needs to have cluster-admin privileges. By default, when easyCerts
is enabled, a cluster-admin kubeconfig file is generated and linked into
`/etc/kubernetes/cluster-admin.kubeconfig` as determined by
[](#opt-services.kubernetes.pki.etcClusterAdminKubeconfig).
`export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make
kubectl use this kubeconfig to access and authenticate the cluster. The
cluster-admin kubeconfig references an auto-generated keypair owned by
root. Thus, only root on the kubernetes master may obtain cluster-admin
rights by means of this file.

139
dev/nixos-manual/configuration/linux-kernel.chapter.md Normal file
View File

@@ -0,0 +1,139 @@
# Linux Kernel {#sec-kernel-config}
You can override the Linux kernel and associated packages using the
option `boot.kernelPackages`. For instance, this selects the Linux 3.10
kernel:
```nix
{ boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10; }
```
Note that this not only replaces the kernel, but also packages that are
specific to the kernel version, such as the NVIDIA video drivers. This
ensures that driver packages are consistent with the kernel.
While `pkgs.linuxKernel.packages` contains all available kernel packages,
you may want to use one of the unversioned `pkgs.linuxPackages_*` aliases
such as `pkgs.linuxPackages_latest`, that are kept up to date with new
versions.
Please note that the current convention in NixOS is to only keep actively
maintained kernel versions on both unstable and the currently supported stable
release(s) of NixOS. This means that a non-longterm kernel will be removed after it's
abandoned by the kernel developers, even on stable NixOS versions. If you
pin your kernel onto a non-longterm version, expect your evaluation to fail as
soon as the version is out of maintenance.
A kernel will be removed from nixpkgs when the first batch of stable kernels
_after_ the final release is published. E.g. when 6.15.11 is the final release
of the 6.15 series and is released together with 6.16.3 and 6.12.43, it will be
removed on the release of 6.16.4 and 6.12.44. Custom kernel variants such
as linux-hardened are also affected by this.
Longterm versions of kernels will be removed before the next stable NixOS that will
exceed the maintenance period of the kernel version.
The default Linux kernel configuration should be fine for most users.
You can see the configuration of your current kernel with the following
command:
```ShellSession
zcat /proc/config.gz
```
If you want to change the kernel configuration, you can use the
`packageOverrides` feature (see [](#sec-customising-packages)). For
instance, to enable support for the kernel debugger KGDB:
```nix
{
nixpkgs.config.packageOverrides =
pkgs:
pkgs.lib.recursiveUpdate pkgs {
linuxKernel.kernels.linux_5_10 = pkgs.linuxKernel.kernels.linux_5_10.override {
extraConfig = ''
KGDB y
'';
};
};
}
```
`extraConfig` takes a list of Linux kernel configuration options, one
per line. The name of the option should not include the prefix
`CONFIG_`. The option value is typically `y`, `n` or `m` (to build
something as a kernel module).
Kernel modules for hardware devices are generally loaded automatically
by `udev`. You can force a module to be loaded via
[](#opt-boot.kernelModules), e.g.
```nix
{
boot.kernelModules = [
"fuse"
"kvm-intel"
"coretemp"
];
}
```
If the module is required early during the boot (e.g. to mount the root
file system), you can use [](#opt-boot.initrd.kernelModules):
```nix
{ boot.initrd.kernelModules = [ "cifs" ]; }
```
This causes the specified modules and their dependencies to be added to
the initial ramdisk.
Kernel runtime parameters can be set through
[](#opt-boot.kernel.sysctl), e.g.
```nix
{ boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; }
```
sets the kernel's TCP keepalive time to 120 seconds. To see the
available parameters, run `sysctl -a`.
## Building a custom kernel {#sec-linux-config-customizing}
Please refer to the Nixpkgs manual for the various ways of [building a custom kernel](https://nixos.org/nixpkgs/manual#sec-linux-kernel).
To use your custom kernel package in your NixOS configuration, set
```nix
{ boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel; }
```
## Rust {#sec-linux-rust}
The Linux kernel does not have Rust language support enabled by
default. For kernel versions 6.7 or newer, experimental Rust support
can be enabled. In a NixOS configuration, set:
```nix
{
boot.kernelPatches = [
{
name = "Rust Support";
patch = null;
features = {
rust = true;
};
}
];
}
```
## Developing kernel modules {#sec-linux-config-developing-modules}
This section was moved to the [Nixpkgs manual](https://nixos.org/nixpkgs/manual#sec-linux-kernel-developing-modules).
## ZFS {#sec-linux-zfs}
It's a common issue that the latest stable version of ZFS doesn't support the latest
available Linux kernel. It is recommended to use the latest available LTS that's compatible
with ZFS. Usually this is the default kernel provided by nixpkgs (i.e. `pkgs.linuxPackages`).

122
dev/nixos-manual/configuration/luks-file-systems.section.md Normal file
View File

@@ -0,0 +1,122 @@
# LUKS-Encrypted File Systems {#sec-luks-file-systems}
NixOS supports file systems that are encrypted using *LUKS* (Linux
Unified Key Setup). For example, here is how you create an encrypted
Ext4 file system on the device
`/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d`:
```ShellSession
# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d
WARNING!
========
This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably.
Are you sure? (Type uppercase yes): YES
Enter LUKS passphrase: ***
Verify passphrase: ***
# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***
# mkfs.ext4 /dev/mapper/crypted
```
The LUKS volume should be automatically picked up by
`nixos-generate-config`, but you might want to verify that your
`hardware-configuration.nix` looks correct. To manually ensure that the
system is automatically mounted at boot time as `/`, add the following
to `configuration.nix`:
```nix
{
boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
fileSystems."/".device = "/dev/mapper/crypted";
}
```
Should grub be used as bootloader, and `/boot` is located on an
encrypted partition, it is necessary to add the following grub option:
```nix
{ boot.loader.grub.enableCryptodisk = true; }
```
## FIDO2 {#sec-luks-file-systems-fido2}
NixOS also supports unlocking your LUKS-Encrypted file system using a FIDO2
compatible token.
### Without systemd in initrd {#sec-luks-file-systems-fido2-legacy}
In the following example, we will create a new
FIDO2 credential and add it as a new key to our existing device
`/dev/sda2`:
```ShellSession
# export FIDO2_LABEL="/dev/sda2 @ $HOSTNAME"
# fido2luks credential "$FIDO2_LABEL"
f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
# fido2luks -i add-key /dev/sda2 f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
Password:
Password (again):
Old password:
Old password (again):
Added to key to device /dev/sda2, slot: 2
```
To ensure that this file system is decrypted using the FIDO2 compatible
key, add the following to `configuration.nix`:
```nix
{
boot.initrd.luks.fido2Support = true;
boot.initrd.luks.devices."/dev/sda2".fido2.credential =
"f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7";
}
```
You can also use the FIDO2 passwordless setup, but for security reasons,
you might want to enable it only when your device is PIN protected, such
as [Trezor](https://trezor.io/).
```nix
{ boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = true; }
```
### systemd Stage 1 {#sec-luks-file-systems-fido2-systemd}
If systemd stage 1 is enabled, it handles unlocking of LUKS-encrypted volumes
during boot. The following example enables systemd stage1 and adds support for
unlocking the existing LUKS2 volume `root` using any enrolled FIDO2 compatible
tokens.
```nix
{
boot.initrd = {
luks.devices.root = {
crypttabExtraOpts = [ "fido2-device=auto" ];
device = "/dev/sda2";
};
systemd.enable = true;
};
}
```
All tokens that should be used for unlocking the LUKS2-encrypted volume must
first be enrolled using [systemd-cryptenroll](https://www.freedesktop.org/software/systemd/man/systemd-cryptenroll.html).
In the following example, a new key slot for the first discovered token is
added to the LUKS volume.
```ShellSession
# systemd-cryptenroll --fido2-device=auto /dev/sda2
```
Existing key slots are left intact, unless `--wipe-slot=` is specified. It is
recommended to add a recovery key that should be stored in a secure physical
location and can be entered wherever a password would be entered.
```ShellSession
# systemd-cryptenroll --recovery-key /dev/sda2
```

132
dev/nixos-manual/configuration/mattermost.chapter.md Normal file
View File

@@ -0,0 +1,132 @@
# Mattermost {#sec-mattermost}
The NixOS Mattermost module lets you build [Mattermost](https://mattermost.com)
instances for collaboration over chat, optionally with custom builds of plugins
specific to your instance.
To enable Mattermost using Postgres, use a config like this:
```nix
{
services.mattermost = {
enable = true;
# You can change this if you are reverse proxying.
host = "0.0.0.0";
port = 8065;
# Allow modifications to the config from Mattermost.
mutableConfig = true;
# Override modifications to the config with your NixOS config.
preferNixConfig = true;
socket = {
# Enable control with the `mmctl` socket.
enable = true;
# Exporting the control socket will add `mmctl` to your PATH, and export
# MMCTL_LOCAL_SOCKET_PATH systemwide. Otherwise, you can get the socket
# path out of `config.mattermost.socket.path` and set it manually.
export = true;
};
# For example, to disable auto-installation of prepackaged plugins.
settings.PluginSettings.AutomaticPrepackagedPlugins = false;
};
}
```
As of NixOS 25.05, Mattermost uses peer authentication with Postgres or
MySQL by default. If you previously used password auth on localhost,
this will automatically be configured if your `stateVersion` is set to at least
`25.05`.
## Using the Mattermost derivation {#sec-mattermost-derivation}
The nixpkgs `mattermost` derivation runs the entire test suite during the
`checkPhase`. This test suite is run with a live MySQL and Postgres database
instance in the sandbox. If you are building Mattermost, this can take a while,
especially if it is building on a resource-constrained system.
The following passthrus are designed to assist with enabling or disabling
the `checkPhase`:
- `mattermost.withTests`
- `mattermost.withoutTests`
The default (`mattermost`) is an alias for `mattermost.withTests`.
## Using Mattermost plugins {#sec-mattermost-plugins}
You can configure Mattermost plugins by either using prebuilt binaries or by
building your own. We test building and using plugins in the NixOS test suite.
Mattermost plugins are tarballs containing a system-specific statically linked
Go binary and webapp resources.
Here is an example with a prebuilt plugin tarball:
```nix
{
services.mattermost = {
plugins = with pkgs; [
# todo
# 0.7.1
# https://github.com/mattermost/mattermost-plugin-todo/releases/tag/v0.7.1
(fetchurl {
# Note: Don't unpack the tarball; the NixOS module will repack it for you.
url = "https://github.com/mattermost-community/mattermost-plugin-todo/releases/download/v0.7.1/com.mattermost.plugin-todo-0.7.1.tar.gz";
hash = "sha256-P+Z66vqE7FRmc2kTZw9FyU5YdLLbVlcJf11QCbfeJ84=";
})
];
};
}
```
Once the plugin is installed and the config rebuilt, you can enable this plugin
in the System Console.
## Building Mattermost plugins {#sec-mattermost-plugins-build}
The `mattermost` derivation includes the `buildPlugin` passthru for building
plugins that use the "standard" Mattermost plugin build template at
[mattermost-plugin-demo](https://github.com/mattermost/mattermost-plugin-demo).
Since this is a "de facto" standard for building Mattermost plugins that makes
assumptions about the build environment, the `buildPlugin` helper tries to fit
these assumptions the best it can.
Here is how to build the above Todo plugin. Note that we rely on
package-lock.json being assembled correctly, so must use a version where it is!
If there is no lockfile or the lockfile is incorrect, Nix cannot fetch NPM build
and runtime dependencies for a sandbox build.
```nix
{
services.mattermost = {
plugins = with pkgs; [
(mattermost.buildPlugin {
pname = "mattermost-plugin-todo";
version = "0.8-pre";
src = fetchFromGitHub {
owner = "mattermost-community";
repo = "mattermost-plugin-todo";
# 0.7.1 didn't work, seems to use an older set of node dependencies.
rev = "f25dc91ea401c9f0dcd4abcebaff10eb8b9836e5";
hash = "sha256-OM+m4rTqVtolvL5tUE8RKfclqzoe0Y38jLU60Pz7+HI=";
};
vendorHash = "sha256-5KpechSp3z/Nq713PXYruyNxveo6CwrCSKf2JaErbgg=";
npmDepsHash = "sha256-o2UOEkwb8Vx2lDWayNYgng0GXvmS6lp/ExfOq3peyMY=";
extraGoModuleAttrs = {
npmFlags = [ "--legacy-peer-deps" ];
};
})
];
};
}
```
See `pkgs/by-name/ma/mattermost/build-plugin.nix` for all the options.
As in the previous example, once the plugin is installed and the config rebuilt,
you can enable this plugin in the System Console.

142
dev/nixos-manual/configuration/modularity.section.md Normal file
View File

@@ -0,0 +1,142 @@
# Modularity {#sec-modularity}
The NixOS configuration mechanism is modular. If your
`configuration.nix` becomes too big, you can split it into multiple
files. Likewise, if you have multiple NixOS configurations (e.g. for
different computers) with some commonality, you can move the common
configuration into a shared file.
Modules have exactly the same syntax as `configuration.nix`. In fact,
`configuration.nix` is itself a module. You can use other modules by
including them from `configuration.nix`, e.g.:
```nix
{ config, pkgs, ... }:
{
imports = [
./vpn.nix
./kde.nix
];
services.httpd.enable = true;
environment.systemPackages = [ pkgs.emacs ];
# ...
}
```
Here, we include two modules from the same directory, `vpn.nix` and
`kde.nix`. The latter might look like this:
```nix
{ config, pkgs, ... }:
{
services.xserver.enable = true;
services.displayManager.sddm.enable = true;
services.desktopManager.plasma6.enable = true;
environment.systemPackages = [ pkgs.vim ];
}
```
Note that both `configuration.nix` and `kde.nix` define the option
[](#opt-environment.systemPackages). When multiple modules define an
option, NixOS will try to *merge* the definitions. In the case of
[](#opt-environment.systemPackages) the lists of packages will be
concatenated. The value in `configuration.nix` is
merged last, so for list-type options, it will appear at the end of the
merged list. If you want it to appear first, you can use `mkBefore`:
```nix
{ boot.kernelModules = mkBefore [ "kvm-intel" ]; }
```
This causes the `kvm-intel` kernel module to be loaded before any other
kernel modules.
For other types of options, a merge may not be possible. For instance,
if two modules define [](#opt-services.httpd.adminAddr),
`nixos-rebuild` will give an error:
```plain
The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.
```
When that happens, it's possible to force one definition take precedence
over the others:
```nix
{ services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org"; }
```
When using multiple modules, you may need to access configuration values
defined in other modules. This is what the `config` function argument is
for: it contains the complete, merged system configuration. That is,
`config` is the result of combining the configurations returned by every
module. (If you're wondering how it's possible that the (indirect) *result*
of a function is passed as an *input* to that same function: that's
because Nix is a "lazy" language --- it only computes values when
they are needed. This works as long as no individual configuration
value depends on itself.)
For example, here is a module that adds some packages to
[](#opt-environment.systemPackages) only if
[](#opt-services.xserver.enable) is set to `true` somewhere else:
```nix
{ config, pkgs, ... }:
{
environment.systemPackages =
if config.services.xserver.enable then
[
pkgs.firefox
pkgs.thunderbird
]
else
[ ];
}
```
With multiple modules, it may not be obvious what the final value of a
configuration option is. The command `nixos-option` allows you to find
out:
```ShellSession
$ nixos-option services.xserver.enable
true
$ nixos-option boot.kernelModules
[ "tun" "ipv6" "loop" ... ]
```
Interactive exploration of the configuration is possible using `nix
repl`, a read-eval-print loop for Nix expressions. A typical use:
```ShellSession
$ nix repl '<nixpkgs/nixos>'
nix-repl> config.networking.hostName
"mandark"
nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts
[ "example.org" "example.gov" ]
```
While abstracting your configuration, you may find it useful to generate
modules using code, instead of writing files. The example below would
have the same effect as importing a file which sets those options.
```nix
{ config, pkgs, ... }:
let
netConfig = hostName: {
networking.hostName = hostName;
networking.useDHCP = false;
};
in
{
imports = [ (netConfig "nixos.localdomain") ];
}
```

46
dev/nixos-manual/configuration/network-manager.section.md Normal file
View File

@@ -0,0 +1,46 @@
# NetworkManager {#sec-networkmanager}
To facilitate network configuration, some desktop environments use
NetworkManager. You can enable NetworkManager by setting:
```nix
{ networking.networkmanager.enable = true; }
```
some desktop managers (e.g., GNOME) enable NetworkManager automatically
for you.
All users that should have permission to change network settings must
belong to the `networkmanager` group:
```nix
{ users.users.alice.extraGroups = [ "networkmanager" ]; }
```
NetworkManager is controlled using either `nmcli` or `nmtui`
(curses-based terminal user interface). See their manual pages for
details on their usage. Some desktop environments (GNOME, KDE) have
their own configuration tools for NetworkManager. On XFCE, there is no
configuration tool for NetworkManager by default: by enabling
[](#opt-programs.nm-applet.enable), the graphical applet will be
installed and will launch automatically when the graphical session is
started.
::: {.note}
`networking.networkmanager` and `networking.wireless` (WPA Supplicant)
can be used together if desired. To do this you need to instruct
NetworkManager to ignore those interfaces like:
```nix
{
networking.networkmanager.unmanaged = [
"*"
"except:type:wwan"
"except:type:gsm"
];
}
```
Refer to the option description for the exact syntax and references to
external documentation.
:::

16
dev/nixos-manual/configuration/networking.chapter.md Normal file
View File

@@ -0,0 +1,16 @@
# Networking {#sec-networking}
This section describes how to configure networking components
on your NixOS machine.
```{=include=} sections
network-manager.section.md
ssh.section.md
ipv4-config.section.md
ipv6-config.section.md
firewall.section.md
wireless.section.md
ad-hoc-network-config.section.md
renaming-interfaces.section.md
```
<!-- TODO: OpenVPN, NAT -->

29
dev/nixos-manual/configuration/overlayfs.section.md Normal file
View File

@@ -0,0 +1,29 @@
# Overlayfs {#sec-overlayfs}
NixOS offers a convenient abstraction to create both read-only as well writable
overlays.
```nix
{
fileSystems = {
"/writable-overlay" = {
overlay = {
lowerdir = [ writableOverlayLowerdir ];
upperdir = "/.rw-writable-overlay/upper";
workdir = "/.rw-writable-overlay/work";
};
# Mount the writable overlay in the initrd.
neededForBoot = true;
};
"/readonly-overlay".overlay.lowerdir = [
writableOverlayLowerdir
writableOverlayLowerdir2
];
};
}
```
If `upperdir` and `workdir` are not null, they will be created before the
overlay is mounted.
To mount an overlay as read-only, you need to provide at least two `lowerdir`s.

18
dev/nixos-manual/configuration/package-mgmt.chapter.md Normal file
View File

@@ -0,0 +1,18 @@
# Package Management {#sec-package-management}
This section describes how to add additional packages to your system.
NixOS has two distinct styles of package management:
- *Declarative*, where you declare what packages you want in your
`configuration.nix`. Every time you run `nixos-rebuild`, NixOS will
ensure that you get a consistent set of binaries corresponding to
your specification.
- *Ad hoc*, where you install, upgrade and uninstall packages via the
`nix-env` command. This style allows mixing packages from different
Nixpkgs versions. It's the only choice for non-root users.
```{=include=} sections
declarative-packages.section.md
ad-hoc-packages.section.md
```

33
dev/nixos-manual/configuration/profiles.chapter.md Normal file
View File

@@ -0,0 +1,33 @@
# Profiles {#ch-profiles}
In some cases, it may be desirable to take advantage of commonly-used,
predefined configurations provided by nixpkgs, but different from those
that come as default. This is a role fulfilled by NixOS's Profiles,
which come as files living in `<nixpkgs/nixos/modules/profiles>`. That
is to say, expected usage is to add them to the imports list of your
`/etc/configuration.nix` as such:
```nix
{ imports = [ <nixpkgs/nixos/modules/profiles/profile-name.nix> ]; }
```
Even if some of these profiles seem only useful in the context of
install media, many are actually intended to be used in real installs.
What follows is a brief explanation of the purpose and use-case for each
profile. Detailing each option configured by each one is out of scope.
```{=include=} sections
profiles/all-hardware.section.md
profiles/base.section.md
profiles/clone-config.section.md
profiles/demo.section.md
profiles/docker-container.section.md
profiles/graphical.section.md
profiles/hardened.section.md
profiles/headless.section.md
profiles/installation-device.section.md
profiles/perlless.section.md
profiles/minimal.section.md
profiles/qemu-guest.section.md
```

11
dev/nixos-manual/configuration/profiles/all-hardware.section.md Normal file
View File

@@ -0,0 +1,11 @@
# All Hardware {#sec-profile-all-hardware}
Enables all hardware supported by NixOS: i.e., all firmware is included, and
all devices from which one may boot are enabled in the initrd. Its primary
use is in the NixOS installation CDs.
The enabled kernel modules include support for SATA and PATA, SCSI
(partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and
Hyper-V. Additionally, [](#opt-hardware.enableAllFirmware) is
enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically
installed.

7
dev/nixos-manual/configuration/profiles/base.section.md Normal file
View File

@@ -0,0 +1,7 @@
# Base {#sec-profile-base}
Defines the software packages included in the "minimal" installation CD. It
installs several utilities useful in a simple recovery or install media, such
as a text-mode web browser, and tools for manipulating block devices,
networking, hardware diagnostics, and filesystems (with their respective
kernel modules).

11
dev/nixos-manual/configuration/profiles/clone-config.section.md Normal file
View File

@@ -0,0 +1,11 @@
# Clone Config {#sec-profile-clone-config}
This profile is used in installer images. It provides an editable
configuration.nix that imports all the modules that were also used when
creating the image in the first place. As a result it allows users to edit
and rebuild the live-system.
On images where the installation media also becomes an installation target,
copying over `configuration.nix` should be disabled by
setting `installer.cloneConfig` to `false`.
For example, this is done in `sd-image-aarch64-installer.nix`.

4
dev/nixos-manual/configuration/profiles/demo.section.md Normal file
View File

@@ -0,0 +1,4 @@
# Demo {#sec-profile-demo}
This profile just enables a `demo` user, with password `demo`, uid `1000`, `wheel` group and
[autologin in the SDDM display manager](#opt-services.displayManager.autoLogin).

7
dev/nixos-manual/configuration/profiles/docker-container.section.md Normal file
View File

@@ -0,0 +1,7 @@
# Docker Container {#sec-profile-docker-container}
This is the profile from which the Docker images are generated. It prepares a
working system by importing the [Minimal](#sec-profile-minimal) and
[Clone Config](#sec-profile-clone-config) profiles, and
setting appropriate configuration options that are useful inside a container
context, like [](#opt-boot.isContainer).

10
dev/nixos-manual/configuration/profiles/graphical.section.md Normal file
View File

@@ -0,0 +1,10 @@
# Graphical {#sec-profile-graphical}
Defines a NixOS configuration with the Plasma 6 desktop. It's used by the
graphical installation CD.
It sets [](#opt-services.xserver.enable),
[](#opt-services.displayManager.sddm.enable),
[](#opt-services.desktopManager.plasma6.enable),
and [](#opt-services.libinput.enable) to true. It also
includes glxinfo and firefox in the system packages list.

20
dev/nixos-manual/configuration/profiles/hardened.section.md Normal file
View File

@@ -0,0 +1,20 @@
# Hardened {#sec-profile-hardened}
A profile with most (vanilla) hardening options enabled by default,
potentially at the cost of stability, features and performance.
This includes a hardened kernel, and limiting the system information
available to processes through the `/sys` and
`/proc` filesystems. It also disables the User Namespaces
feature of the kernel, which stops Nix from being able to build anything
(this particular setting can be overridden via
[](#opt-security.allowUserNamespaces)). See the
[profile source](https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix)
for further detail on which settings are altered.
::: {.warning}
This profile enables options that are known to affect system
stability. If you experience any stability issues when using the
profile, try disabling it. If you report an issue and use this
profile, always mention that you do.
:::

8
dev/nixos-manual/configuration/profiles/headless.section.md Normal file
View File

@@ -0,0 +1,8 @@
# Headless {#sec-profile-headless}
Common configuration for headless machines (e.g., Amazon EC2 instances).
Disables [vesa](#opt-boot.vesa), serial consoles,
[emergency mode](#opt-systemd.enableEmergencyMode),
[grub splash images](#opt-boot.loader.grub.splashImage)
and configures the kernel to reboot automatically on panic.

24
dev/nixos-manual/configuration/profiles/installation-device.section.md Normal file
View File

@@ -0,0 +1,24 @@
# Installation Device {#sec-profile-installation-device}
Provides a basic configuration for installation devices like CDs.
This enables redistributable firmware, includes the
[Clone Config profile](#sec-profile-clone-config)
and a copy of the Nixpkgs channel, so `nixos-install`
works out of the box.
Documentation for [Nixpkgs](#opt-documentation.enable)
and [NixOS](#opt-documentation.nixos.enable) are
forcefully enabled (to override the
[Minimal profile](#sec-profile-minimal) preference); the
NixOS manual is shown automatically on TTY 8, udisks is disabled.
Autologin is enabled as `nixos` user, while passwordless
login as both `root` and `nixos` is possible.
Passwordless `sudo` is enabled too.
[NetworkManager](#opt-networking.networkmanager.enable) is
enabled and can be configured interactively with `nmtui`.
It is explained how to login, start the ssh server, and if available,
how to start the display manager.
Several settings are tweaked so that the installer has a better chance of
succeeding under low-memory environments.

6
dev/nixos-manual/configuration/profiles/minimal.section.md Normal file
View File

@@ -0,0 +1,6 @@
# Minimal {#sec-profile-minimal}
This profile defines a small NixOS configuration. It does not contain any
graphical stuff. It's a very short file that sets the supported locales
to only support the user-selected locale, and
[disables packages' documentation](#opt-documentation.enable).

5
dev/nixos-manual/configuration/profiles/perlless.section.md Normal file
View File

@@ -0,0 +1,5 @@
# Perlless {#sec-perlless}
Render your system completely perlless (i.e. without the perl interpreter). This
includes a mechanism so that your build fails if it contains a Nix store path
that references the string "perl".

7
dev/nixos-manual/configuration/profiles/qemu-guest.section.md Normal file
View File

@@ -0,0 +1,7 @@
# QEMU Guest {#sec-profile-qemu-guest}
This profile contains common configuration for virtual machines running under
QEMU (using virtio).
It makes virtio modules available on the initrd and sets the system time from
the hardware clock to work around a bug in qemu-kvm.

55
dev/nixos-manual/configuration/renaming-interfaces.section.md Normal file
View File

@@ -0,0 +1,55 @@
# Renaming network interfaces {#sec-rename-ifs}
NixOS uses the udev [predictable naming
scheme](https://systemd.io/PREDICTABLE_INTERFACE_NAMES/) to assign names
to network interfaces. This means that by default cards are not given
the traditional names like `eth0` or `eth1`, whose order can change
unpredictably across reboots. Instead, relying on physical locations and
firmware information, the scheme produces names like `ens1`, `enp2s0`,
etc.
These names are predictable but less memorable and not necessarily
stable: for example installing new hardware or changing firmware
settings can result in a [name
change](https://github.com/systemd/systemd/issues/3715#issue-165347602).
If this is undesirable, for example if you have a single ethernet card,
you can revert to the traditional scheme by setting
[](#opt-networking.usePredictableInterfaceNames)
to `false`.
## Assigning custom names {#sec-custom-ifnames}
In case there are multiple interfaces of the same type, it's better to
assign custom names based on the device hardware address. For example,
we assign the name `wan` to the interface with MAC address
`52:54:00:12:01:01` using a netword link unit:
```nix
{
systemd.network.links."10-wan" = {
matchConfig.PermanentMACAddress = "52:54:00:12:01:01";
linkConfig.Name = "wan";
};
}
```
Note that links are directly read by udev, *not networkd*, and will work
even if networkd is disabled.
Alternatively, we can use a plain old udev rule:
```nix
{
boot.initrd.services.udev.rules = ''
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
'';
}
```
::: {.warning}
The rule must be installed in the initrd using
`boot.initrd.services.udev.rules`, not the usual `services.udev.extraRules`
option. This is to avoid race conditions with other programs controlling
the interface.
:::

20
dev/nixos-manual/configuration/ssh.section.md Normal file
View File

@@ -0,0 +1,20 @@
# Secure Shell Access {#sec-ssh}
Secure shell (SSH) access to your machine can be enabled by setting:
```nix
{ services.openssh.enable = true; }
```
By default, root logins using a password are disallowed. They can be
disabled entirely by setting
[](#opt-services.openssh.settings.PermitRootLogin) to `"no"`.
You can declaratively specify authorised public keys for a user
as follows:
```nix
{
users.users.alice.openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
}
```

103
dev/nixos-manual/configuration/sshfs-file-systems.section.md Normal file
View File

@@ -0,0 +1,103 @@
# SSHFS File Systems {#sec-sshfs-file-systems}
[SSHFS][sshfs] is a [FUSE][fuse] filesystem that allows easy access to directories on a remote machine using the SSH File Transfer Protocol (SFTP).
It means that if you have SSH access to a machine, no additional setup is needed to mount a directory.
[sshfs]: https://github.com/libfuse/sshfs
[fuse]: https://en.wikipedia.org/wiki/Filesystem_in_Userspace
## Interactive mounting {#sec-sshfs-interactive}
In NixOS, SSHFS is packaged as `sshfs`.
Once installed, mounting a directory interactively is simple as running:
```ShellSession
$ sshfs my-user@example.com:/my-dir /mnt/my-dir
```
Like any other FUSE file system, the directory is unmounted using:
```ShellSession
$ fusermount -u /mnt/my-dir
```
## Non-interactive mounting {#sec-sshfs-non-interactive}
Mounting non-interactively requires some precautions because `sshfs` will run at boot and under a different user (root).
For obvious reason, you can't input a password, so public key authentication using an unencrypted key is needed.
To create a new key without a passphrase you can do:
```ShellSession
$ ssh-keygen -t ed25519 -P '' -f example-key
Generating public/private ed25519 key pair.
Your identification has been saved in example-key
Your public key has been saved in example-key.pub
The key fingerprint is:
SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation
```
To keep the key safe, change the ownership to `root:root` and make sure the permissions are `600`:
OpenSSH normally refuses to use the key if it's not well-protected.
The file system can be configured in NixOS via the usual [fileSystems](#opt-fileSystems) option.
Here's a typical setup:
```nix
{
fileSystems."/mnt/my-dir" = {
device = "my-user@example.com:/my-dir/";
fsType = "sshfs";
options = [
# Filesystem options
"allow_other" # for non-root access
"_netdev" # this is a network fs
"x-systemd.automount" # mount on demand
# SSH options
"reconnect" # handle connection drops
"ServerAliveInterval=15" # keep connections alive
"IdentityFile=/var/secrets/example-key"
];
};
}
```
More options from `ssh_config(5)` can be given as well, for example you can change the default SSH port or specify a jump proxy:
```nix
{
options = [
"ProxyJump=bastion@example.com"
"Port=22"
];
}
```
It's also possible to change the `ssh` command used by SSHFS to connect to the server.
For example:
```nix
{
options = [
(builtins.replaceStrings [ " " ] [ "\\040" ]
"ssh_command=${pkgs.openssh}/bin/ssh -v -L 8080:localhost:80"
)
];
}
```
::: {.note}
The escaping of spaces is needed because every option is written to the `/etc/fstab` file, which is a space-separated table.
:::
### Troubleshooting {#sec-sshfs-troubleshooting}
If you're having a hard time figuring out why mounting is failing, you can add the option `"debug"`.
This enables a verbose log in SSHFS that you can access via:
```ShellSession
$ journalctl -u $(systemd-escape -p /mnt/my-dir/).mount
Jun 22 11:41:18 workstation mount[87790]: SSHFS version 3.7.1
Jun 22 11:41:18 workstation mount[87793]: executing <ssh> <-x> <-a> <-oClearAllForwardings=yes> <-oServerAliveInterval=15> <-oIdentityFile=/var/secrets/wrong-key> <-2> <my-user@example.com> <-s> <sftp>
Jun 22 11:41:19 workstation mount[87793]: my-user@example.com: Permission denied (publickey).
Jun 22 11:41:19 workstation mount[87790]: read: Connection reset by peer
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Mount process exited, code=exited, status=1/FAILURE
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Failed with result 'exit-code'.
Jun 22 11:41:19 workstation systemd[1]: Failed to mount /mnt/my-dir.
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Consumed 54ms CPU time, received 2.3K IP traffic, sent 2.7K IP traffic.
```
::: {.note}
If the mount point contains special characters it needs to be escaped using `systemd-escape`.
This is due to the way systemd converts paths into unit names.
:::

116
dev/nixos-manual/configuration/subversion.chapter.md Normal file
View File

@@ -0,0 +1,116 @@
# Subversion {#module-services-subversion}
[Subversion](https://subversion.apache.org/) is a centralized
version-control system. It can use a [variety of
protocols](https://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing)
for communication between client and server.
## Subversion inside Apache HTTP {#module-services-subversion-apache-httpd}
This section focuses on configuring a web-based server on top of the
Apache HTTP server, which uses
[WebDAV](http://www.webdav.org/)/[DeltaV](http://www.webdav.org/deltav/WWW10/deltav-intro.htm)
for communication.
For more information on the general setup, please refer to the [the
appropriate section of the Subversion
book](https://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd).
To configure, include in `/etc/nixos/configuration.nix` code to activate
Apache HTTP, setting [](#opt-services.httpd.adminAddr)
appropriately:
```nix
{
services.httpd.enable = true;
services.httpd.adminAddr = "...";
networking.firewall.allowedTCPPorts = [
80
443
];
}
```
For a simple Subversion server with basic authentication, configure the
Subversion module for Apache as follows, setting `hostName` and
`documentRoot` appropriately, and `SVNParentPath` to the parent
directory of the repositories, `AuthzSVNAccessFile` to the location of
the `.authz` file describing access permission, and `AuthUserFile` to
the password file.
```nix
{
services.httpd.extraModules = [
# note that order is *super* important here
{
name = "dav_svn";
path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so";
}
{
name = "authz_svn";
path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so";
}
];
services.httpd.virtualHosts = {
"svn" = {
hostName = HOSTNAME;
documentRoot = DOCUMENTROOT;
locations."/svn".extraConfig = ''
DAV svn
SVNParentPath REPO_PARENT
AuthzSVNAccessFile ACCESS_FILE
AuthName "SVN Repositories"
AuthType Basic
AuthUserFile PASSWORD_FILE
Require valid-user
'';
};
};
}
```
The key `"svn"` is just a symbolic name identifying the virtual host.
The `"/svn"` in `locations."/svn".extraConfig` is the path underneath
which the repositories will be served.
[This page](https://wiki.archlinux.org/index.php/Subversion) explains
how to set up the Subversion configuration itself. This boils down to
the following:
Underneath `REPO_PARENT` repositories can be set up as follows:
```ShellSession
$ svn create REPO_NAME
```
Repository files need to be accessible by `wwwrun`:
```ShellSession
$ chown -R wwwrun:wwwrun REPO_PARENT
```
The password file `PASSWORD_FILE` can be created as follows:
```ShellSession
$ htpasswd -cs PASSWORD_FILE USER_NAME
```
Additional users can be set up similarly, omitting the `c` flag:
```ShellSession
$ htpasswd -s PASSWORD_FILE USER_NAME
```
The file describing access permissions `ACCESS_FILE` will look something
like the following:
```
[/]
* = r
[REPO_NAME:/]
USER_NAME = rw
```
The Subversion repositories will be accessible as
`http://HOSTNAME/svn/REPO_NAME`.

167
dev/nixos-manual/configuration/user-mgmt.chapter.md Normal file
View File

@@ -0,0 +1,167 @@
# User Management {#sec-user-management}
NixOS supports both declarative and imperative styles of user
management. In the declarative style, users are specified in
`configuration.nix`. For instance, the following states that a user
account named `alice` shall exist:
```nix
{
users.users.alice = {
isNormalUser = true;
home = "/home/alice";
description = "Alice Foobar";
extraGroups = [
"wheel"
"networkmanager"
];
openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
};
}
```
Note that `alice` is a member of the `wheel` and `networkmanager`
groups, which allows her to use `sudo` to execute commands as `root` and
to configure the network, respectively. Also note the SSH public key
that allows remote logins with the corresponding private key. Users
created in this way do not have a password by default, so they cannot
log in via mechanisms that require a password. However, you can use the
`passwd` program to set a password, which is retained across invocations
of `nixos-rebuild`.
If you set [](#opt-users.mutableUsers) to
false, then the contents of `/etc/passwd` and `/etc/group` will be congruent
to your NixOS configuration. For instance, if you remove a user from
[](#opt-users.users) and run nixos-rebuild, the user
account will cease to exist. Also, imperative commands for managing users and
groups, such as useradd, are no longer available. Passwords may still be
assigned by setting the user's
[hashedPassword](#opt-users.users._name_.hashedPassword) option. A
hashed password can be generated using `mkpasswd`.
A user ID (uid) is assigned automatically. You can also specify a uid
manually by adding
```nix
{ uid = 1000; }
```
to the user specification.
Groups can be specified similarly. The following states that a group
named `students` shall exist:
```nix
{ users.groups.students.gid = 1000; }
```
As with users, the group ID (gid) is optional and will be assigned
automatically if it's missing.
In the imperative style, users and groups are managed by commands such
as `useradd`, `groupmod` and so on. For instance, to create a user
account named `alice`:
```ShellSession
# useradd -m alice
```
To make all nix tools available to this new user use \`su - USER\` which
opens a login shell (==shell that loads the profile) for given user.
This will create the \~/.nix-defexpr symlink. So run:
```ShellSession
# su - alice -c "true"
```
The flag `-m` causes the creation of a home directory for the new user,
which is generally what you want. The user does not have an initial
password and therefore cannot log in. A password can be set using the
`passwd` utility:
```ShellSession
# passwd alice
Enter new UNIX password: ***
Retype new UNIX password: ***
```
A user can be deleted using `userdel`:
```ShellSession
# userdel -r alice
```
The flag `-r` deletes the user's home directory. Accounts can be
modified using `usermod`. Unix groups can be managed using `groupadd`,
`groupmod` and `groupdel`.
## Create users and groups with `systemd-sysusers` {#sec-systemd-sysusers}
::: {.note}
This is experimental.
Please consider using [Userborn](#sec-userborn) over systemd-sysusers as it's
more feature complete.
:::
Instead of using a custom perl script to create users and groups, you can use
systemd-sysusers:
```nix
{ systemd.sysusers.enable = true; }
```
The primary benefit of this is to remove a dependency on perl.
## Manage users and groups with `userborn` {#sec-userborn}
::: {.note}
This is experimental.
:::
Like systemd-sysusers, Userborn doesn't depend on Perl but offers some more
advantages over systemd-sysusers:
1. It can create "normal" users (with a GID >= 1000).
2. It can update some information about users. Most notably it can update their
passwords.
3. It will warn when users use an insecure or unsupported password hashing
scheme.
Userborn is the recommended way to manage users if you don't want to rely on
the Perl script. It aims to eventually replace the Perl script by default.
You can enable Userborn via:
```nix
{ services.userborn.enable = true; }
```
You can configure Userborn to store the password files
(`/etc/{group,passwd,shadow}`) outside of `/etc` and symlink them from this
location to `/etc`:
```nix
{ services.userborn.passwordFilesLocation = "/persistent/etc"; }
```
This is useful when you store `/etc` on a `tmpfs` or if `/etc` is immutable
(e.g. when using `system.etc.overlay.mutable = false;`). In the latter case the
original files are by default stored in `/var/lib/nixos`.
Userborn implements immutable users by re-mounting the password files
read-only. This means that unlike when using the Perl script, trying to add a
new user (e.g. via `useradd`) will fail right away.
## Restrict usage time {#sec-restrict-usage-time}
[Timekpr-nExT](https://mjasnik.gitlab.io/timekpr-next/) is a screen time managing application that helps optimizing time spent at computer for your subordinates, children or even for yourself.
You can enable it via:
```nix
{ services.timekpr.enable = true; }
```
This will install the `timekpr` package and start the `timekpr` service.
You can then use the `timekpra` application to configure time limits for users.

24
dev/nixos-manual/configuration/wayland.chapter.md Normal file
View File

@@ -0,0 +1,24 @@
# Wayland {#sec-wayland}
While X11 (see [](#sec-x11)) is still the primary display technology
on NixOS, Wayland support is steadily improving. Where X11 separates the
X Server and the window manager, on Wayland those are combined: a
Wayland Compositor is like an X11 window manager, but also embeds the
Wayland 'Server' functionality. This means it is sufficient to install
a Wayland Compositor such as sway without separately enabling a Wayland
server:
```nix
{ programs.sway.enable = true; }
```
This installs the sway compositor along with some essential utilities.
Now you can start sway from the TTY console.
If you are using a wlroots-based compositor, like sway, and want to be
able to share your screen, make sure to configure Pipewire using
[](#opt-services.pipewire.enable)
and related options.
For more helpful tips and tricks, see the
[wiki page about Sway](https://wiki.nixos.org/wiki/Sway).

74
dev/nixos-manual/configuration/wireless.section.md Normal file
View File

@@ -0,0 +1,74 @@
# Wireless Networks {#sec-wireless}
For a desktop installation using NetworkManager (e.g., GNOME), you just
have to make sure the user is in the `networkmanager` group and you can
skip the rest of this section on wireless networks.
NixOS will start wpa_supplicant for you if you enable this setting:
```nix
{ networking.wireless.enable = true; }
```
NixOS lets you specify networks for wpa_supplicant declaratively:
```nix
{
networking.wireless.networks = {
# SSID with no spaces or special characters
echelon = {
psk = "abcdefgh";
};
# SSID with spaces and/or special characters
"echelon's AP" = {
psk = "ijklmnop";
};
# Hidden SSID
echelon = {
hidden = true;
psk = "qrstuvwx";
};
free.wifi = { }; # Public wireless network
};
}
```
Be aware that keys will be written to the nix store in plaintext! When
no networks are set, it will default to using a configuration file at
`/etc/wpa_supplicant.conf`. You should edit this file yourself to define
wireless networks, WPA keys and so on (see wpa_supplicant.conf(5)).
If you are using WPA2 you can generate pskRaw key using
`wpa_passphrase`:
```ShellSession
$ wpa_passphrase ESSID PSK
network={
ssid="echelon"
#psk="abcdefgh"
psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
}
```
```nix
{
networking.wireless.networks = {
echelon = {
pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
};
};
}
```
or you can use it to directly generate the `wpa_supplicant.conf`:
```ShellSession
# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf
```
After you have edited the `wpa_supplicant.conf`, you need to restart the
wpa_supplicant service.
```ShellSession
# systemctl restart wpa_supplicant.service
```

396
dev/nixos-manual/configuration/x-windows.chapter.md Normal file
View File

@@ -0,0 +1,396 @@
# X Window System {#sec-x11}
The X Window System (X11) provides the basis of NixOS' graphical user
interface. It can be enabled as follows:
```nix
{ services.xserver.enable = true; }
```
The X server will automatically detect and use the appropriate video
driver from a set of X.org drivers (such as `vesa` and `intel`). You can
also specify a driver manually, e.g.
```nix
{ services.xserver.videoDrivers = [ "r128" ]; }
```
to enable X.org's `xf86-video-r128` driver.
You also need to enable at least one desktop or window manager.
Otherwise, you can only log into a plain undecorated `xterm` window.
Thus you should pick one or more of the following lines:
```nix
{
services.desktopManager.plasma6.enable = true;
services.xserver.desktopManager.xfce.enable = true;
services.desktopManager.gnome.enable = true;
services.xserver.desktopManager.mate.enable = true;
services.xserver.windowManager.xmonad.enable = true;
services.xserver.windowManager.twm.enable = true;
services.xserver.windowManager.icewm.enable = true;
services.xserver.windowManager.i3.enable = true;
services.xserver.windowManager.herbstluftwm.enable = true;
}
```
NixOS's default *display manager* (the program that provides a graphical
login prompt and manages the X server) is LightDM. You can select an
alternative one by picking one of the following lines:
```nix
{
services.displayManager.sddm.enable = true;
services.displayManager.gdm.enable = true;
}
```
You can set the keyboard layout (and optionally the layout variant):
```nix
{
services.xserver.xkb.layout = "de";
services.xserver.xkb.variant = "neo";
}
```
The X server is started automatically at boot time. If you don't want
this to happen, you can set:
```nix
{ services.xserver.autorun = false; }
```
The X server can then be started manually:
```ShellSession
# systemctl start display-manager.service
```
On 64-bit systems, if you want OpenGL for 32-bit programs such as in
Wine, you should also set the following:
```nix
{ hardware.graphics.enable32Bit = true; }
```
## Auto-login {#sec-x11-auto-login}
The x11 login screen can be skipped entirely, automatically logging you
into your window manager and desktop environment when you boot your
computer.
This is especially helpful if you have disk encryption enabled. Since
you already have to provide a password to decrypt your disk, entering a
second password to login can be redundant.
To enable auto-login, you need to define your default window manager and
desktop environment. If you wanted no desktop environment and i3 as your
your window manager, you'd define:
```nix
{ services.displayManager.defaultSession = "none+i3"; }
```
Every display manager in NixOS supports auto-login, here is an example
using lightdm for a user `alice`:
```nix
{
services.xserver.displayManager.lightdm.enable = true;
services.displayManager.autoLogin.enable = true;
services.displayManager.autoLogin.user = "alice";
}
```
## Running X without a display manager {#sec-x11-startx}
It is possible to avoid a display manager entirely and starting the X server
manually from a virtual terminal. Add to your configuration:
```nix
{
services.xserver.displayManager.startx = {
enable = true;
generateScript = true;
};
}
```
then you can start the X server with the `startx` command.
The second option will generate a base `xinitrc` script that will run your
window manager and set up the systemd user session.
You can extend the script using the
[extraCommands](#opt-services.xserver.displayManager.startx.extraCommands)
option, for example:
```nix
{
services.xserver.displayManager.startx = {
generateScript = true;
extraCommands = ''
xrdb -load .Xresources
xsetroot -solid '#666661'
xsetroot -cursor_name left_ptr
'';
};
}
```
or, alternatively, you can write your own from scratch in `~/.xinitrc`.
In this case, remember you're responsible for starting the window manager, for
example:
```shell
sxhkd &
bspwm &
```
and if you have enabled some systemd user service, you will probably want to
also add these lines too:
```shell
# import required env variables from the current shell
systemctl --user import-environment DISPLAY XDG_SESSION_ID
# start all graphical user services
systemctl --user start nixos-fake-graphical-session.target
# start the user dbus daemon
dbus-daemon --session --address="unix:path=/run/user/$(id -u)/bus" &
```
## Intel Graphics drivers {#sec-x11--graphics-cards-intel}
The default and recommended driver for Intel Graphics in X.org is `modesetting`
(included in the xorg-server package itself).
This is a generic driver which uses the kernel [mode
setting](https://en.wikipedia.org/wiki/Mode_setting) (KMS) mechanism, it
supports Glamor (2D graphics acceleration via OpenGL) and is actively
maintained, it may perform worse in some cases (like in old chipsets).
There is a second driver, `intel` (provided by the xf86-video-intel package),
specific to older Intel iGPUs from generation 2 to 9. It is 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.
Third generation and older iGPUs (15-20+ years old) are not supported by the
`modesetting` driver (X will crash upon startup). Thus, the `intel` driver is
required for these chipsets.
Otherwise, the results vary depending on the hardware, so you may have to try
both drivers. Use the option
[](#opt-services.xserver.videoDrivers)
to set one. The recommended configuration for modern systems is:
```nix
{ services.xserver.videoDrivers = [ "modesetting" ]; }
```
::: {.note}
The `modesetting` driver doesn't currently provide a `TearFree` option (this
will become available in an upcoming X.org release), So, without using a
compositor (for example, see [](#opt-services.picom.enable)) you will
experience screen tearing.
:::
If you experience screen tearing no matter what, this configuration was
reported to resolve the issue:
```nix
{
services.xserver.videoDrivers = [ "intel" ];
services.xserver.deviceSection = ''
Option "DRI" "2"
Option "TearFree" "true"
'';
}
```
Note that this will likely downgrade the performance compared to
`modesetting` or `intel` with DRI 3 (default).
## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia}
NVIDIA provides a proprietary driver for its graphics cards that has
better 3D performance than the X.org drivers. It is not enabled by
default because it's not free software. You can enable it as follows:
```nix
{ services.xserver.videoDrivers = [ "nvidia" ]; }
```
If you have an older card, you may have to use one of the legacy drivers:
```nix
{
hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_470;
hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_390;
hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_340;
}
```
You may need to reboot after enabling this driver to prevent a clash
with other kernel modules.
## Touchpads {#sec-x11-touchpads}
Support for Synaptics touchpads (found in many laptops such as the Dell
Latitude series) can be enabled as follows:
```nix
{ services.libinput.enable = true; }
```
The driver has many options (see [](#ch-options)).
For instance, the following disables tap-to-click behavior:
```nix
{ services.libinput.touchpad.tapping = false; }
```
Note: the use of `services.xserver.synaptics` is deprecated since NixOS
17.09.
## GTK/Qt themes {#sec-x11-gtk-and-qt-themes}
GTK themes can be installed either to user profile or system-wide (via
`environment.systemPackages`). To make Qt 5 applications look similar to
GTK ones, you can use the following configuration:
```nix
{
qt.enable = true;
qt.platformTheme = "gtk2";
qt.style = "gtk2";
}
```
## Custom XKB layouts {#custom-xkb-layouts}
It is possible to install custom [ XKB
](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts
using the option `services.xserver.xkb.extraLayouts`.
As a first example, we are going to create a layout based on the basic
US layout, with an additional layer to type some greek symbols by
pressing the right-alt key.
Create a file called `us-greek` with the following content (under a
directory called `symbols`; it's an XKB peculiarity that will help with
testing):
```
xkb_symbols "us-greek"
{
include "us(basic)" // includes the base US keys
include "level3(ralt_switch)" // configures right alt as a third level switch
key <LatA> { [ a, A, Greek_alpha ] };
key <LatB> { [ b, B, Greek_beta ] };
key <LatG> { [ g, G, Greek_gamma ] };
key <LatD> { [ d, D, Greek_delta ] };
key <LatZ> { [ z, Z, Greek_zeta ] };
};
```
A minimal layout specification must include the following:
```nix
{
services.xserver.xkb.extraLayouts.us-greek = {
description = "US layout with alt-gr greek";
languages = [ "eng" ];
symbolsFile = /yourpath/symbols/us-greek;
};
}
```
::: {.note}
The name (after `extraLayouts.`) should match the one given to the
`xkb_symbols` block.
:::
Applying this customization requires rebuilding several packages, and a
broken XKB file can lead to the X session crashing at login. Therefore,
you're strongly advised to **test your layout before applying it**:
```ShellSession
$ nix-shell -p xorg.xkbcomp
$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
```
You can inspect the predefined XKB files for examples:
```ShellSession
$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
```
Once the configuration is applied, and you did a logout/login cycle, the
layout should be ready to use. You can try it by e.g. running
`setxkbmap us-greek` and then type `<alt>+a` (it may not get applied in
your terminal straight away). To change the default, the usual
`services.xserver.xkb.layout` option can still be used.
A layout can have several other components besides `xkb_symbols`, for
example we will define new keycodes for some multimedia key and bind
these to some symbol.
Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys
of interest, then create a `media-key` file to hold the keycodes
definitions
```
xkb_keycodes "media"
{
<volUp> = 123;
<volDown> = 456;
}
```
Now use the newly define keycodes in `media-sym`:
```
xkb_symbols "media"
{
key.type = "ONE_LEVEL";
key <volUp> { [ XF86AudioLowerVolume ] };
key <volDown> { [ XF86AudioRaiseVolume ] };
}
```
As before, to install the layout do
```nix
{
services.xserver.xkb.extraLayouts.media = {
description = "Multimedia keys remapping";
languages = [ "eng" ];
symbolsFile = /path/to/media-key;
keycodesFile = /path/to/media-sym;
};
}
```
::: {.note}
The function `pkgs.writeText <filename> <content>` can be useful if you
prefer to keep the layout definitions inside the NixOS configuration.
:::
Unfortunately, the Xorg server does not (currently) support setting a
keymap directly but relies instead on XKB rules to select the matching
components (keycodes, types, ...) of a layout. This means that
components other than symbols won't be loaded by default. As a
workaround, you can set the keymap using `setxkbmap` at the start of the
session with:
```nix
{
services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
}
```
If you are manually starting the X server, you should set the argument
`-xkbdir /etc/X11/xkb`, otherwise X won't find your layout files. For
example with `xinit` run
```ShellSession
$ xinit -- -xkbdir /etc/X11/xkb
```
To learn how to write layouts take a look at the XKB [documentation
](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts).
More example layouts can also be found [here
](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples).

61
dev/nixos-manual/configuration/xfce.chapter.md Normal file
View File

@@ -0,0 +1,61 @@
# Xfce Desktop Environment {#sec-xfce}
To enable the Xfce Desktop Environment, set
```nix
{
services.xserver.desktopManager.xfce.enable = true;
services.displayManager.defaultSession = "xfce";
}
```
Optionally, *picom* can be enabled for nice graphical effects, some
example settings:
```nix
{
services.picom = {
enable = true;
fade = true;
inactiveOpacity = 0.9;
shadow = true;
fadeDelta = 4;
};
}
```
Some Xfce programs are not installed automatically. To install them
manually (system wide), put them into your
[](#opt-environment.systemPackages) from `pkgs.xfce`.
## Thunar {#sec-xfce-thunar-plugins}
Thunar (the Xfce file manager) is automatically enabled when Xfce is
enabled. To enable Thunar without enabling Xfce, use the configuration
option [](#opt-programs.thunar.enable) instead of adding
`pkgs.xfce.thunar` to [](#opt-environment.systemPackages).
If you'd like to add extra plugins to Thunar, add them to
[](#opt-programs.thunar.plugins). You shouldn't just add them to
[](#opt-environment.systemPackages).
## Troubleshooting {#sec-xfce-troubleshooting}
Even after enabling udisks2, volume management might not work. Thunar
and/or the desktop takes time to show up. Thunar will spit out this kind
of message on start (look at `journalctl --user -b`).
```plain
Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported
```
This is caused by some needed GNOME services not running. This is all
fixed by enabling "Launch GNOME services on startup" in the Advanced
tab of the Session and Startup settings panel. Alternatively, you can
run this command to do the same thing.
```ShellSession
$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
```
It is necessary to log out and log in again for this to take effect.