treewide: Fix all Nix ASTs in all markdown files

This allows for correct highlighting and maybe future automatic
formatting. The AST was verified to work with nixfmt only.

Changed files
+2888 -2079
doc
maintainers
nixos
doc
manual
administration
configuration
development
installation
release-notes
modules
pkgs
by-name
development
misc
resholve
servers
home-assistant
custom-components
custom-lovelace-modules
nextcloud
packages
web-apps
wordpress
packages
+58 -46
CONTRIBUTING.md
···
```nix
foo {
-
arg = ...;
}
```
···
```nix
foo
{
-
arg = ...;
}
```
Also fine is
```nix
-
foo { arg = ...; }
```
if it's a short call.
···
- In attribute sets or lists that span multiple lines, the attribute names or list elements should be aligned:
```nix
-
# A long list.
-
list = [
-
elem1
-
elem2
-
elem3
-
];
-
# A long attribute set.
-
attrs = {
-
attr1 = short_expr;
-
attr2 =
-
if true then big_expr else big_expr;
-
};
-
# Combined
-
listOfAttrs = [
-
{
-
attr1 = 3;
-
attr2 = "fff";
-
}
-
{
-
attr1 = 5;
-
attr2 = "ggg";
-
}
-
];
```
- Short lists or attribute sets can be written on one line:
```nix
-
# A short list.
-
list = [ elem1 elem2 elem3 ];
-
# A short set.
-
attrs = { x = 1280; y = 1024; };
```
- Breaking in the middle of a function argument can give hard-to-read code, like
···
```nix
{ arg1, arg2 }:
assert system == "i686-linux";
-
stdenv.mkDerivation { ...
```
not
···
```nix
{ arg1, arg2 }:
assert system == "i686-linux";
-
stdenv.mkDerivation { ...
```
- Function formal arguments are written as:
```nix
-
{ arg1, arg2, arg3 }:
```
but if they don't fit on one line they're written as:
```nix
{ arg1, arg2, arg3
-
, arg4, ...
-
, # Some comment...
-
argN
-
}:
```
- Functions should list their expected arguments as precisely as possible. That is, write
```nix
-
{ stdenv, fetchurl, perl }: ...
```
instead of
```nix
-
args: with args; ...
```
or
```nix
-
{ stdenv, fetchurl, perl, ... }: ...
```
For functions that are truly generic in the number of arguments (such as wrappers around `mkDerivation`) that have some required arguments, you should write them using an `@`-pattern:
···
{ stdenv, doCoverageAnalysis ? false, ... } @ args:
stdenv.mkDerivation (args // {
-
... if doCoverageAnalysis then "bla" else "" ...
})
```
···
args:
args.stdenv.mkDerivation (args // {
-
... if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "" ...
})
```
- Unnecessary string conversions should be avoided. Do
```nix
-
rev = version;
```
instead of
```nix
-
rev = "${version}";
```
- Building lists conditionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.
```nix
-
buildInputs = lib.optional stdenv.isDarwin iconv;
```
instead of
```nix
-
buildInputs = if stdenv.isDarwin then [ iconv ] else null;
```
As an exception, an explicit conditional expression with null can be used when fixing a important bug without triggering a mass rebuild.
···
```nix
foo {
+
arg = "...";
}
```
···
```nix
foo
{
+
arg = "...";
}
```
Also fine is
```nix
+
foo { arg = "..."; }
```
if it's a short call.
···
- In attribute sets or lists that span multiple lines, the attribute names or list elements should be aligned:
```nix
+
{
+
# A long list.
+
list = [
+
elem1
+
elem2
+
elem3
+
];
+
# A long attribute set.
+
attrs = {
+
attr1 = short_expr;
+
attr2 =
+
if true then big_expr else big_expr;
+
};
+
# Combined
+
listOfAttrs = [
+
{
+
attr1 = 3;
+
attr2 = "fff";
+
}
+
{
+
attr1 = 5;
+
attr2 = "ggg";
+
}
+
];
+
}
```
- Short lists or attribute sets can be written on one line:
```nix
+
{
+
# A short list.
+
list = [ elem1 elem2 elem3 ];
+
# A short set.
+
attrs = { x = 1280; y = 1024; };
+
}
```
- Breaking in the middle of a function argument can give hard-to-read code, like
···
```nix
{ arg1, arg2 }:
assert system == "i686-linux";
+
stdenv.mkDerivation { /* ... */ }
```
not
···
```nix
{ arg1, arg2 }:
assert system == "i686-linux";
+
stdenv.mkDerivation { /* ... */ }
```
- Function formal arguments are written as:
```nix
+
{ arg1, arg2, arg3 }: { /* ... */ }
```
but if they don't fit on one line they're written as:
```nix
{ arg1, arg2, arg3
+
, arg4
+
# Some comment...
+
, argN
+
}: { }
```
- Functions should list their expected arguments as precisely as possible. That is, write
```nix
+
{ stdenv, fetchurl, perl }: "..."
```
instead of
```nix
+
args: with args; "..."
```
or
```nix
+
{ stdenv, fetchurl, perl, ... }: "..."
```
For functions that are truly generic in the number of arguments (such as wrappers around `mkDerivation`) that have some required arguments, you should write them using an `@`-pattern:
···
{ stdenv, doCoverageAnalysis ? false, ... } @ args:
stdenv.mkDerivation (args // {
+
foo = if doCoverageAnalysis then "bla" else "";
})
```
···
args:
args.stdenv.mkDerivation (args // {
+
foo = if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "";
})
```
- Unnecessary string conversions should be avoided. Do
```nix
+
{
+
rev = version;
+
}
```
instead of
```nix
+
{
+
rev = "${version}";
+
}
```
- Building lists conditionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.
```nix
+
{
+
buildInputs = lib.optional stdenv.isDarwin iconv;
+
}
```
instead of
```nix
+
{
+
buildInputs = if stdenv.isDarwin then [ iconv ] else null;
+
}
```
As an exception, an explicit conditional expression with null can be used when fixing a important bug without triggering a mass rebuild.
+5 -5
doc/build-helpers/fetchers.chapter.md
···
fetchurl {
url = "http://www.example.org/hello-1.0.tar.gz";
hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=";
-
};
```
A common mistake is to update a fetcher’s URL, or a version parameter, without updating the hash.
···
fetchurl {
url = "http://www.example.org/hello-1.1.tar.gz";
hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=";
-
};
```
**This will reuse the old contents**.
···
fetchurl {
url = "http://www.example.org/hello-1.1.tar.gz";
hash = "";
-
};
```
Use the resulting error message to determine the correct hash.
···
buildPythonPackage rec {
pname = "pysimplesoap";
version = "1.16.2";
-
src = ...;
patches = [
(fetchDebianPatch {
···
})
];
-
...
}
```
···
fetchurl {
url = "http://www.example.org/hello-1.0.tar.gz";
hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=";
+
}
```
A common mistake is to update a fetcher’s URL, or a version parameter, without updating the hash.
···
fetchurl {
url = "http://www.example.org/hello-1.1.tar.gz";
hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=";
+
}
```
**This will reuse the old contents**.
···
fetchurl {
url = "http://www.example.org/hello-1.1.tar.gz";
hash = "";
+
}
```
Use the resulting error message to determine the correct hash.
···
buildPythonPackage rec {
pname = "pysimplesoap";
version = "1.16.2";
+
src = "...";
patches = [
(fetchDebianPatch {
···
})
];
+
# ...
}
```
+1
doc/build-helpers/images/dockertools.section.md
···
hello
dockerTools.binSh
];
```
After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container.
···
hello
dockerTools.binSh
];
+
}
```
After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container.
+8 -4
doc/build-helpers/special/checkpoint-build.section.md
···
To change a normal derivation to a checkpoint based build, these steps must be taken:
- apply `prepareCheckpointBuild` on the desired derivation, e.g.
```nix
-
checkpointArtifacts = (pkgs.checkpointBuildTools.prepareCheckpointBuild pkgs.virtualbox);
```
- change something you want in the sources of the package, e.g. use a source override:
```nix
-
changedVBox = pkgs.virtualbox.overrideAttrs (old: {
-
src = path/to/vbox/sources;
-
});
```
- use `mkCheckpointBuild changedVBox checkpointArtifacts`
- enjoy shorter build times
···
To change a normal derivation to a checkpoint based build, these steps must be taken:
- apply `prepareCheckpointBuild` on the desired derivation, e.g.
```nix
+
{
+
checkpointArtifacts = (pkgs.checkpointBuildTools.prepareCheckpointBuild pkgs.virtualbox);
+
}
```
- change something you want in the sources of the package, e.g. use a source override:
```nix
+
{
+
changedVBox = pkgs.virtualbox.overrideAttrs (old: {
+
src = path/to/vbox/sources;
+
});
+
}
```
- use `mkCheckpointBuild changedVBox checkpointArtifacts`
- enjoy shorter build times
+32 -22
doc/build-helpers/testers.chapter.md
···
# Check that `pkg-config` modules are exposed using default values
```nix
-
passthru.tests.pkg-config = testers.hasPkgConfigModules {
-
package = finalAttrs.finalPackage;
-
};
-
meta.pkgConfigModules = [ "libfoo" ];
```
:::
···
# Check that `pkg-config` modules are exposed using explicit module names
```nix
-
passthru.tests.pkg-config = testers.hasPkgConfigModules {
-
package = finalAttrs.finalPackage;
-
moduleNames = [ "libfoo" ];
-
};
```
:::
···
This example will run the command `hello --version`, and then check that the version of the `hello` package is in the output of the command.
```nix
-
passthru.tests.version = testers.testVersion { package = hello; };
```
:::
···
A common usage of the `version` attribute is to specify `version = "v${version}"`.
```nix
-
version = "0.4.2";
-
passthru.tests.version = testers.testVersion {
-
package = leetcode-cli;
-
command = "leetcode -V";
-
version = "leetcode ${version}";
-
};
```
:::
···
grep -F 'failing though' $failed/testBuildFailure.log
[[ 3 = $(cat $failed/testBuildFailure.exit) ]]
touch $out
-
'';
```
:::
···
# Prevent nix from reusing the output of a fetcher
```nix
-
tests.fetchgit = testers.invalidateFetcherByDrvHash fetchgit {
-
name = "nix-source";
-
url = "https://github.com/NixOS/nix";
-
rev = "9d9dbe6ed05854e03811c361a3380e09183f4f4a";
-
hash = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
-
};
```
:::
···
# Check that `pkg-config` modules are exposed using default values
```nix
+
{
+
passthru.tests.pkg-config = testers.hasPkgConfigModules {
+
package = finalAttrs.finalPackage;
+
};
+
meta.pkgConfigModules = [ "libfoo" ];
+
}
```
:::
···
# Check that `pkg-config` modules are exposed using explicit module names
```nix
+
{
+
passthru.tests.pkg-config = testers.hasPkgConfigModules {
+
package = finalAttrs.finalPackage;
+
moduleNames = [ "libfoo" ];
+
};
+
}
```
:::
···
This example will run the command `hello --version`, and then check that the version of the `hello` package is in the output of the command.
```nix
+
{
+
passthru.tests.version = testers.testVersion { package = hello; };
+
}
```
:::
···
A common usage of the `version` attribute is to specify `version = "v${version}"`.
```nix
+
{
+
version = "0.4.2";
+
passthru.tests.version = testers.testVersion {
+
package = leetcode-cli;
+
command = "leetcode -V";
+
version = "leetcode ${version}";
+
};
+
}
```
:::
···
grep -F 'failing though' $failed/testBuildFailure.log
[[ 3 = $(cat $failed/testBuildFailure.exit) ]]
touch $out
+
''
```
:::
···
# Prevent nix from reusing the output of a fetcher
```nix
+
{
+
tests.fetchgit = testers.invalidateFetcherByDrvHash fetchgit {
+
name = "nix-source";
+
url = "https://github.com/NixOS/nix";
+
rev = "9d9dbe6ed05854e03811c361a3380e09183f4f4a";
+
hash = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
+
};
+
}
```
:::
+18 -16
doc/build-helpers/trivial-build-helpers.chapter.md
···
For example, if the file destination is a directory:
```nix
-
my-file = writeTextFile {
-
name = "my-file";
-
text = ''
-
Contents of File
-
'';
-
destination = "/share/my-file";
}
```
···
```nix
writeShellScript "evaluate-my-file.sh" ''
cat ${my-file}/share/my-file
-
'';
```
::::
···
};
allowSubstitutes = true;
preferLocalBuild = false;
-
};
```
:::
···
writeText "my-file"
''
Contents of File
-
'';
```
:::
···
writeTextDir "share/my-file"
''
Contents of File
-
'';
```
:::
···
writeScript "my-file"
''
Contents of File
-
'';
```
:::
···
writeScriptBin "my-script"
''
echo "hi"
-
'';
```
:::
···
writeShellScript "my-script"
''
echo "hi"
-
'';
```
:::
···
writeShellScriptBin "my-script"
''
echo "hi"
-
'';
```
:::
···
produces an output path `/nix/store/<hash>-runtime-deps` containing
-
```nix
/nix/store/<hash>-hello-2.10
/nix/store/<hash>-hi
/nix/store/<hash>-libidn2-2.3.0
···
produces an output path `/nix/store/<hash>-runtime-references` containing
-
```nix
/nix/store/<hash>-hello-2.10
```
···
For example, if the file destination is a directory:
```nix
+
{
+
my-file = writeTextFile {
+
name = "my-file";
+
text = ''
+
Contents of File
+
'';
+
destination = "/share/my-file";
+
};
}
```
···
```nix
writeShellScript "evaluate-my-file.sh" ''
cat ${my-file}/share/my-file
+
''
```
::::
···
};
allowSubstitutes = true;
preferLocalBuild = false;
+
}
```
:::
···
writeText "my-file"
''
Contents of File
+
''
```
:::
···
writeTextDir "share/my-file"
''
Contents of File
+
''
```
:::
···
writeScript "my-file"
''
Contents of File
+
''
```
:::
···
writeScriptBin "my-script"
''
echo "hi"
+
''
```
:::
···
writeShellScript "my-script"
''
echo "hi"
+
''
```
:::
···
writeShellScriptBin "my-script"
''
echo "hi"
+
''
```
:::
···
produces an output path `/nix/store/<hash>-runtime-deps` containing
+
```
/nix/store/<hash>-hello-2.10
/nix/store/<hash>-hi
/nix/store/<hash>-libidn2-2.3.0
···
produces an output path `/nix/store/<hash>-runtime-references` containing
+
```
/nix/store/<hash>-hello-2.10
```
+18 -11
doc/functions/nix-gitignore.section.md
···
`pkgs.nix-gitignore` exports a number of functions, but you'll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
```nix
-
{ pkgs ? import <nixpkgs> {} }:
-
nix-gitignore.gitignoreSource [] ./source
# Simplest version
-
nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source
# This one reads the ./source/.gitignore and concats the auxiliary ignores
-
nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source
# Use this string as gitignore, don't read ./source/.gitignore.
-
nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source
# It also accepts a list (of strings and paths) that will be concatenated
# once the paths are turned to strings via readFile.
```
These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`:
```nix
-
gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
-
gitignoreSource = gitignoreFilterSource (_: _: true);
```
Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it's blacklisted by either your filter or the gitignoreFilter.
···
If you want to make your own filter from scratch, you may use
```nix
-
gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
```
## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive}
···
If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
```nix
-
gitignoreFilterRecursiveSource = filter: patterns: root:
-
# OR
-
gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
```
···
`pkgs.nix-gitignore` exports a number of functions, but you'll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
```nix
+
{ pkgs ? import <nixpkgs> {} }: {
+
src = nix-gitignore.gitignoreSource [] ./source;
# Simplest version
+
src = nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source;
# This one reads the ./source/.gitignore and concats the auxiliary ignores
+
src = nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source;
# Use this string as gitignore, don't read ./source/.gitignore.
+
src = nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n" ~/.gitignore] ./source;
# It also accepts a list (of strings and paths) that will be concatenated
# once the paths are turned to strings via readFile.
+
}
```
These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`:
```nix
+
{
+
gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
+
gitignoreSource = gitignoreFilterSource (_: _: true);
+
}
```
Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it's blacklisted by either your filter or the gitignoreFilter.
···
If you want to make your own filter from scratch, you may use
```nix
+
{
+
gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
+
}
```
## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive}
···
If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
```nix
+
{
+
# gitignoreFilterRecursiveSource = filter: patterns: root:
+
# OR
+
gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
+
}
```
+3 -1
doc/hooks/breakpoint.section.md
···
This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`.
```nix
-
nativeBuildInputs = [ breakpointHook ];
```
When a build failure happens there will be an instruction printed that shows how to attach with `cntr` to the build sandbox.
···
This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`.
```nix
+
{
+
nativeBuildInputs = [ breakpointHook ];
+
}
```
When a build failure happens there will be an instruction printed that shows how to attach with `cntr` to the build sandbox.
+17 -15
doc/hooks/installShellFiles.section.md
···
The `installShellCompletion` function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of `--bash`, `--fish`, or `--zsh`. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag `--name NAME` before the path. If this flag is not provided, zsh completions will be renamed automatically such that `foobar.zsh` becomes `_foobar`. A root name may be provided for all paths using the flag `--cmd NAME`; this synthesizes the appropriate name depending on the shell (e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for zsh). The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which case the shell and name must be provided.
```nix
-
nativeBuildInputs = [ installShellFiles ];
-
postInstall = ''
-
installManPage doc/foobar.1 doc/barfoo.3
-
# explicit behavior
-
installShellCompletion --bash --name foobar.bash share/completions.bash
-
installShellCompletion --fish --name foobar.fish share/completions.fish
-
installShellCompletion --zsh --name _foobar share/completions.zsh
-
# implicit behavior
-
installShellCompletion share/completions/foobar.{bash,fish,zsh}
-
# using named fd
-
installShellCompletion --cmd foobar \
-
--bash <($out/bin/foobar --bash-completion) \
-
--fish <($out/bin/foobar --fish-completion) \
-
--zsh <($out/bin/foobar --zsh-completion)
-
'';
```
···
The `installShellCompletion` function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of `--bash`, `--fish`, or `--zsh`. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag `--name NAME` before the path. If this flag is not provided, zsh completions will be renamed automatically such that `foobar.zsh` becomes `_foobar`. A root name may be provided for all paths using the flag `--cmd NAME`; this synthesizes the appropriate name depending on the shell (e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for zsh). The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which case the shell and name must be provided.
```nix
+
{
+
nativeBuildInputs = [ installShellFiles ];
+
postInstall = ''
+
installManPage doc/foobar.1 doc/barfoo.3
+
# explicit behavior
+
installShellCompletion --bash --name foobar.bash share/completions.bash
+
installShellCompletion --fish --name foobar.fish share/completions.fish
+
installShellCompletion --zsh --name _foobar share/completions.zsh
+
# implicit behavior
+
installShellCompletion share/completions/foobar.{bash,fish,zsh}
+
# using named fd
+
installShellCompletion --cmd foobar \
+
--bash <($out/bin/foobar --bash-completion) \
+
--fish <($out/bin/foobar --fish-completion) \
+
--zsh <($out/bin/foobar --zsh-completion)
+
'';
+
}
```
+7 -6
doc/hooks/mpi-check-hook.section.md
···
```nix
{ mpiCheckPhaseHook, mpi, ... }:
-
...
-
-
nativeCheckInputs = [
-
openssh
-
mpiCheckPhaseHook
-
];
```
···
```nix
{ mpiCheckPhaseHook, mpi, ... }:
+
{
+
# ...
+
nativeCheckInputs = [
+
openssh
+
mpiCheckPhaseHook
+
];
+
}
```
+3 -2
doc/languages-frameworks/agda.section.md
···
```nix
agda.withPackages {
-
pkgs = [ ... ];
ghc = haskell.compiler.ghcHEAD;
}
```
···
```nix
{ mkDerivation, standard-library, fetchFromGitHub }:
```
Note that the derivation function is called with `mkDerivation` set to `agdaPackages.mkDerivation`, therefore you
···
version = "1.5.0";
pname = "iowa-stdlib";
-
src = ...
libraryFile = "";
libraryName = "IAL-1.3";
···
```nix
agda.withPackages {
+
pkgs = [ /* ... */ ];
ghc = haskell.compiler.ghcHEAD;
}
```
···
```nix
{ mkDerivation, standard-library, fetchFromGitHub }:
+
{}
```
Note that the derivation function is called with `mkDerivation` set to `agdaPackages.mkDerivation`, therefore you
···
version = "1.5.0";
pname = "iowa-stdlib";
+
src = "...";
libraryFile = "";
libraryName = "IAL-1.3";
+14 -12
doc/languages-frameworks/android.section.md
···
repo.json to the Nix store based on the given repository XMLs.
```nix
-
repoXmls = {
-
packages = [ ./xml/repository2-1.xml ];
-
images = [
-
./xml/android-sys-img2-1.xml
-
./xml/android-tv-sys-img2-1.xml
-
./xml/android-wear-sys-img2-1.xml
-
./xml/android-wear-cn-sys-img2-1.xml
-
./xml/google_apis-sys-img2-1.xml
-
./xml/google_apis_playstore-sys-img2-1.xml
-
];
-
addons = [ ./xml/addon2-1.xml ];
-
};
```
When building the above expression with:
···
repo.json to the Nix store based on the given repository XMLs.
```nix
+
{
+
repoXmls = {
+
packages = [ ./xml/repository2-1.xml ];
+
images = [
+
./xml/android-sys-img2-1.xml
+
./xml/android-tv-sys-img2-1.xml
+
./xml/android-wear-sys-img2-1.xml
+
./xml/android-wear-cn-sys-img2-1.xml
+
./xml/google_apis-sys-img2-1.xml
+
./xml/google_apis_playstore-sys-img2-1.xml
+
];
+
addons = [ ./xml/addon2-1.xml ];
+
};
+
}
```
When building the above expression with:
+6 -2
doc/languages-frameworks/beam.section.md
···
- From the mix_deps.nix file, remove the dependencies that had git versions and pass them as an override to the import function.
```nix
mixNixDeps = import ./mix.nix {
inherit beamPackages lib;
overrides = (final: prev: {
···
# you can re-use the same beamDeps argument as generated
beamDeps = with final; [ prometheus ];
};
-
});
-
};
```
You will need to run the build process once to fix the hash to correspond to your new git src.
···
- start with the following argument to mixRelease
```nix
mixFodDeps = fetchMixDeps {
pname = "mix-deps-${pname}";
inherit src version;
hash = lib.fakeHash;
};
```
The first build will complain about the hash value, you can replace with the suggested value after that.
···
- From the mix_deps.nix file, remove the dependencies that had git versions and pass them as an override to the import function.
```nix
+
{
mixNixDeps = import ./mix.nix {
inherit beamPackages lib;
overrides = (final: prev: {
···
# you can re-use the same beamDeps argument as generated
beamDeps = with final; [ prometheus ];
};
+
});
+
};
+
}
```
You will need to run the build process once to fix the hash to correspond to your new git src.
···
- start with the following argument to mixRelease
```nix
+
{
mixFodDeps = fetchMixDeps {
pname = "mix-deps-${pname}";
inherit src version;
hash = lib.fakeHash;
};
+
}
```
The first build will complain about the hash value, you can replace with the suggested value after that.
+8 -6
doc/languages-frameworks/bower.section.md
···
(fetchbower "angular" "1.5.3" "~1.5.0" "1749xb0firxdra4rzadm4q9x90v6pzkbd7xmcyjk6qfza09ykk9y")
(fetchbower "bootstrap" "3.3.6" "~3.3.6" "1vvqlpbfcy0k5pncfjaiskj3y6scwifxygfqnw393sjfxiviwmbv")
(fetchbower "jquery" "2.2.2" "1.9.1 - 2" "10sp5h98sqwk90y4k6hbdviwqzvzwqf47r3r51pakch5ii2y7js1")
-
];
```
Using the `bower2nix` command line arguments, the output can be redirected to a file. A name like `bower-packages.nix` would be fine.
···
### Example buildBowerComponents {#ex-buildBowerComponents}
```nix
-
bowerComponents = buildBowerComponents {
-
name = "my-web-app";
-
generated = ./bower-packages.nix; # note 1
-
src = myWebApp; # note 2
-
};
```
In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function:
···
(fetchbower "angular" "1.5.3" "~1.5.0" "1749xb0firxdra4rzadm4q9x90v6pzkbd7xmcyjk6qfza09ykk9y")
(fetchbower "bootstrap" "3.3.6" "~3.3.6" "1vvqlpbfcy0k5pncfjaiskj3y6scwifxygfqnw393sjfxiviwmbv")
(fetchbower "jquery" "2.2.2" "1.9.1 - 2" "10sp5h98sqwk90y4k6hbdviwqzvzwqf47r3r51pakch5ii2y7js1")
+
]; }
```
Using the `bower2nix` command line arguments, the output can be redirected to a file. A name like `bower-packages.nix` would be fine.
···
### Example buildBowerComponents {#ex-buildBowerComponents}
```nix
+
{
+
bowerComponents = buildBowerComponents {
+
name = "my-web-app";
+
generated = ./bower-packages.nix; # note 1
+
src = myWebApp; # note 2
+
};
+
}
```
In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function:
+4 -2
doc/languages-frameworks/chicken.section.md
···
might write:
```nix
buildInputs = [
chicken
chickenPackages.chickenEggs.srfi-189
];
```
Both `chicken` and its eggs have a setup hook which configures the environment
···
chickenEggs = super.chickenEggs.overrideScope' (eggself: eggsuper: {
srfi-180 = eggsuper.srfi-180.overrideAttrs {
# path to a local copy of srfi-180
-
src = ...
};
});
});
in
# Here, `myChickenPackages.chickenEggs.json-rpc`, which depends on `srfi-180` will use
# the local copy of `srfi-180`.
-
# ...
```
···
might write:
```nix
+
{
buildInputs = [
chicken
chickenPackages.chickenEggs.srfi-189
];
+
}
```
Both `chicken` and its eggs have a setup hook which configures the environment
···
chickenEggs = super.chickenEggs.overrideScope' (eggself: eggsuper: {
srfi-180 = eggsuper.srfi-180.overrideAttrs {
# path to a local copy of srfi-180
+
src = "...";
};
});
});
in
# Here, `myChickenPackages.chickenEggs.json-rpc`, which depends on `srfi-180` will use
# the local copy of `srfi-180`.
+
"..."
```
+5 -1
doc/languages-frameworks/crystal.section.md
···
# Insert the path to your shards.nix file here
shardsFile = ./shards.nix;
-
...
}
```
This won't build anything yet, because we haven't told it what files build. We can specify a mapping from binary names to source files with the `crystalBinaries` attribute. The project's compilation instructions should show this. For Mint, the binary is called "mint", which is compiled from the source file `src/mint.cr`, so we'll specify this as follows:
```nix
crystalBinaries.mint.src = "src/mint.cr";
# ...
```
Additionally you can override the default `crystal build` options (which are currently `--release --progress --no-debug --verbose`) with
```nix
crystalBinaries.mint.options = [ "--release" "--verbose" ];
```
Depending on the project, you might need additional steps to get it to compile successfully. In Mint's case, we need to link against openssl, so in the end the Nix file looks as follows:
···
# Insert the path to your shards.nix file here
shardsFile = ./shards.nix;
+
# ...
}
```
This won't build anything yet, because we haven't told it what files build. We can specify a mapping from binary names to source files with the `crystalBinaries` attribute. The project's compilation instructions should show this. For Mint, the binary is called "mint", which is compiled from the source file `src/mint.cr`, so we'll specify this as follows:
```nix
+
{
crystalBinaries.mint.src = "src/mint.cr";
# ...
+
}
```
Additionally you can override the default `crystal build` options (which are currently `--release --progress --no-debug --verbose`) with
```nix
+
{
crystalBinaries.mint.options = [ "--release" "--verbose" ];
+
}
```
Depending on the project, you might need additional steps to get it to compile successfully. In Mint's case, we need to link against openssl, so in the end the Nix file looks as follows:
+11 -7
doc/languages-frameworks/cuda.section.md
···
, cudaSupport ? config.cudaSupport
, cudaPackages ? { }
, ...
-
}:
```
When using `callPackage`, you can choose to pass in a different variant, e.g.
when a different version of the toolkit suffices
```nix
-
mypkg = callPackage { cudaPackages = cudaPackages_11_5; }
```
If another version of say `cudnn` or `cutensor` is needed, you can override the
package set to make it the default. This guarantees you get a consistent package
set.
```nix
-
mypkg = let
-
cudaPackages = cudaPackages_11_5.overrideScope (final: prev: {
-
cudnn = prev.cudnn_8_3;
-
}});
-
in callPackage { inherit cudaPackages; };
```
The CUDA NVCC compiler requires flags to determine which hardware you
···
, cudaSupport ? config.cudaSupport
, cudaPackages ? { }
, ...
+
}: {}
```
When using `callPackage`, you can choose to pass in a different variant, e.g.
when a different version of the toolkit suffices
```nix
+
{
+
mypkg = callPackage { cudaPackages = cudaPackages_11_5; };
+
}
```
If another version of say `cudnn` or `cutensor` is needed, you can override the
package set to make it the default. This guarantees you get a consistent package
set.
```nix
+
{
+
mypkg = let
+
cudaPackages = cudaPackages_11_5.overrideScope (final: prev: {
+
cudnn = prev.cudnn_8_3;
+
});
+
in callPackage { inherit cudaPackages; };
+
}
```
The CUDA NVCC compiler requires flags to determine which hardware you
+9 -1
doc/languages-frameworks/dhall.section.md
···
Dhall overlay like this:
```nix
dhallOverrides = self: super: {
# Enable source for all Dhall packages
buildDhallPackage =
···
true = self.callPackage ./true.nix { };
};
```
… and now the Prelude will contain the fully decoded result of interpreting
···
the Prelude globally for all packages, like this:
```nix
dhallOverrides = self: super: {
true = self.callPackage ./true.nix { };
Prelude = self.callPackage ./Prelude.nix { };
};
```
… or selectively overriding the Prelude dependency for just the `true` package,
like this:
```nix
dhallOverrides = self: super: {
true = self.callPackage ./true.nix {
Prelude = self.callPackage ./Prelude.nix { };
};
};
```
## Overrides {#ssec-dhall-overrides}
···
For example, suppose we wanted to selectively enable `source = true` just for the Prelude. We can do that like this:
```nix
dhallOverrides = self: super: {
Prelude = super.Prelude.overridePackage { source = true; };
-
};
```
[semantic-integrity-checks]: https://docs.dhall-lang.org/tutorials/Language-Tour.html#installing-packages
···
Dhall overlay like this:
```nix
+
{
dhallOverrides = self: super: {
# Enable source for all Dhall packages
buildDhallPackage =
···
true = self.callPackage ./true.nix { };
};
+
}
```
… and now the Prelude will contain the fully decoded result of interpreting
···
the Prelude globally for all packages, like this:
```nix
+
{
dhallOverrides = self: super: {
true = self.callPackage ./true.nix { };
Prelude = self.callPackage ./Prelude.nix { };
};
+
}
```
… or selectively overriding the Prelude dependency for just the `true` package,
like this:
```nix
+
{
dhallOverrides = self: super: {
true = self.callPackage ./true.nix {
Prelude = self.callPackage ./Prelude.nix { };
};
};
+
}
```
## Overrides {#ssec-dhall-overrides}
···
For example, suppose we wanted to selectively enable `source = true` just for the Prelude. We can do that like this:
```nix
+
{
dhallOverrides = self: super: {
Prelude = super.Prelude.overridePackage { source = true; };
+
# ...
};
+
}
```
[semantic-integrity-checks]: https://docs.dhall-lang.org/tutorials/Language-Tour.html#installing-packages
+1 -1
doc/languages-frameworks/dotnet.section.md
···
{ lib, buildDotnetModule, dotnetCorePackages, ffmpeg }:
let
-
referencedProject = import ../../bar { ... };
in buildDotnetModule rec {
pname = "someDotnetApplication";
version = "0.1";
···
{ lib, buildDotnetModule, dotnetCorePackages, ffmpeg }:
let
+
referencedProject = import ../../bar { /* ... */ };
in buildDotnetModule rec {
pname = "someDotnetApplication";
version = "0.1";
+27 -21
doc/languages-frameworks/gnome.section.md
···
In the rare case you need to use icons from dependencies (e.g. when an app forces an icon theme), you can use the following to pick them up:
```nix
buildInputs = [
pantheon.elementary-icon-theme
];
···
--prefix XDG_DATA_DIRS : "$XDG_ICON_DIRS"
)
'';
```
To avoid costly file system access when locating icons, GTK, [as well as Qt](https://woboq.com/blog/qicon-reads-gtk-icon-cache-in-qt57.html), can rely on `icon-theme.cache` files from the themes' top-level directories. These files are generated using `gtk-update-icon-cache`, which is expected to be run whenever an icon is added or removed to an icon theme (typically an application icon into `hicolor` theme) and some programs do indeed run this after icon installation. However, since packages are installed into their own prefix by Nix, this would lead to conflicts. For that reason, `gtk3` provides a [setup hook](#ssec-gnome-hooks-gtk-drop-icon-theme-cache) that will clean the file from installation. Since most applications only ship their own icon that will be loaded on start-up, it should not affect them too much. On the other hand, icon themes are much larger and more widely used so we need to cache them. Because we recommend installing icon themes globally, we will generate the cache files from all packages in a profile using a NixOS module. You can enable the cache generation using `gtk.iconCache.enable` option if your desktop environment does not already do that.
···
Given the requirements above, the package expression would become messy quickly:
```nix
-
preFixup = ''
-
for f in $(find $out/bin/ $out/libexec/ -type f -executable); do
-
wrapProgram "$f" \
-
--prefix GIO_EXTRA_MODULES : "${getLib dconf}/lib/gio/modules" \
-
--prefix XDG_DATA_DIRS : "$out/share" \
-
--prefix XDG_DATA_DIRS : "$out/share/gsettings-schemas/${name}" \
-
--prefix XDG_DATA_DIRS : "${gsettings-desktop-schemas}/share/gsettings-schemas/${gsettings-desktop-schemas.name}" \
-
--prefix XDG_DATA_DIRS : "${hicolor-icon-theme}/share" \
-
--prefix GI_TYPELIB_PATH : "${lib.makeSearchPath "lib/girepository-1.0" [ pango json-glib ]}"
-
done
-
'';
```
Fortunately, there is [`wrapGAppsHook`]{#ssec-gnome-hooks-wrapgappshook}. It works in conjunction with other setup hooks that populate environment variables, and it will then wrap all executables in `bin` and `libexec` directories using said variables.
···
You can also pass additional arguments to `makeWrapper` using `gappsWrapperArgs` in `preFixup` hook:
```nix
-
preFixup = ''
-
gappsWrapperArgs+=(
-
# Thumbnailers
-
--prefix XDG_DATA_DIRS : "${gdk-pixbuf}/share"
-
--prefix XDG_DATA_DIRS : "${librsvg}/share"
-
--prefix XDG_DATA_DIRS : "${shared-mime-info}/share"
-
)
-
'';
```
## Updating GNOME packages {#ssec-gnome-updating}
···
nativeBuildInputs = [
wrapGAppsHook
gobject-introspection
-
...
];
dontWrapGApps = true;
···
nativeBuildInputs = [
wrapGAppsHook
qmake
-
...
];
dontWrapGApps = true;
···
In the rare case you need to use icons from dependencies (e.g. when an app forces an icon theme), you can use the following to pick them up:
```nix
+
{
buildInputs = [
pantheon.elementary-icon-theme
];
···
--prefix XDG_DATA_DIRS : "$XDG_ICON_DIRS"
)
'';
+
}
```
To avoid costly file system access when locating icons, GTK, [as well as Qt](https://woboq.com/blog/qicon-reads-gtk-icon-cache-in-qt57.html), can rely on `icon-theme.cache` files from the themes' top-level directories. These files are generated using `gtk-update-icon-cache`, which is expected to be run whenever an icon is added or removed to an icon theme (typically an application icon into `hicolor` theme) and some programs do indeed run this after icon installation. However, since packages are installed into their own prefix by Nix, this would lead to conflicts. For that reason, `gtk3` provides a [setup hook](#ssec-gnome-hooks-gtk-drop-icon-theme-cache) that will clean the file from installation. Since most applications only ship their own icon that will be loaded on start-up, it should not affect them too much. On the other hand, icon themes are much larger and more widely used so we need to cache them. Because we recommend installing icon themes globally, we will generate the cache files from all packages in a profile using a NixOS module. You can enable the cache generation using `gtk.iconCache.enable` option if your desktop environment does not already do that.
···
Given the requirements above, the package expression would become messy quickly:
```nix
+
{
+
preFixup = ''
+
for f in $(find $out/bin/ $out/libexec/ -type f -executable); do
+
wrapProgram "$f" \
+
--prefix GIO_EXTRA_MODULES : "${getLib dconf}/lib/gio/modules" \
+
--prefix XDG_DATA_DIRS : "$out/share" \
+
--prefix XDG_DATA_DIRS : "$out/share/gsettings-schemas/${name}" \
+
--prefix XDG_DATA_DIRS : "${gsettings-desktop-schemas}/share/gsettings-schemas/${gsettings-desktop-schemas.name}" \
+
--prefix XDG_DATA_DIRS : "${hicolor-icon-theme}/share" \
+
--prefix GI_TYPELIB_PATH : "${lib.makeSearchPath "lib/girepository-1.0" [ pango json-glib ]}"
+
done
+
'';
+
}
```
Fortunately, there is [`wrapGAppsHook`]{#ssec-gnome-hooks-wrapgappshook}. It works in conjunction with other setup hooks that populate environment variables, and it will then wrap all executables in `bin` and `libexec` directories using said variables.
···
You can also pass additional arguments to `makeWrapper` using `gappsWrapperArgs` in `preFixup` hook:
```nix
+
{
+
preFixup = ''
+
gappsWrapperArgs+=(
+
# Thumbnailers
+
--prefix XDG_DATA_DIRS : "${gdk-pixbuf}/share"
+
--prefix XDG_DATA_DIRS : "${librsvg}/share"
+
--prefix XDG_DATA_DIRS : "${shared-mime-info}/share"
+
)
+
'';
+
}
```
## Updating GNOME packages {#ssec-gnome-updating}
···
nativeBuildInputs = [
wrapGAppsHook
gobject-introspection
+
# ...
];
dontWrapGApps = true;
···
nativeBuildInputs = [
wrapGAppsHook
qmake
+
# ...
];
dontWrapGApps = true;
+48 -30
doc/languages-frameworks/go.section.md
···
The following is an example expression using `buildGoModule`:
```nix
-
pet = buildGoModule rec {
-
pname = "pet";
-
version = "0.3.4";
-
src = fetchFromGitHub {
-
owner = "knqyf263";
-
repo = "pet";
-
rev = "v${version}";
-
hash = "sha256-Gjw1dRrgM8D3G7v6WIM2+50r4HmTXvx0Xxme2fH9TlQ=";
-
};
-
vendorHash = "sha256-ciBIR+a1oaYH+H1PcC8cD8ncfJczk1IiJ8iYNM+R6aA=";
-
meta = {
-
description = "Simple command-line snippet manager, written in Go";
-
homepage = "https://github.com/knqyf263/pet";
-
license = lib.licenses.mit;
-
maintainers = with lib.maintainers; [ kalbasit ];
};
}
```
···
- `goDeps` is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate `deps.nix` file for readability. The dependency data structure is described below.
```nix
-
deis = buildGoPackage rec {
-
pname = "deis";
-
version = "1.13.0";
-
goPackagePath = "github.com/deis/deis";
-
src = fetchFromGitHub {
-
owner = "deis";
-
repo = "deis";
-
rev = "v${version}";
-
hash = "sha256-XCPD4LNWtAd8uz7zyCLRfT8rzxycIUmTACjU03GnaeM=";
};
-
-
goDeps = ./deps.nix;
}
```
···
The most common use case for this argument is to make the resulting executable aware of its own version by injecting the value of string variable using the `-X` flag. For example:
```nix
ldflags = [
"-X main.Version=${version}"
"-X main.Commit=${version}"
];
```
### `tags` {#var-go-tags}
···
A string list of [Go build tags (also called build constraints)](https://pkg.go.dev/cmd/go#hdr-Build_constraints) that are passed via the `-tags` argument of `go build`. These constraints control whether Go files from the source should be included in the build. For example:
```nix
tags = [
"production"
"sqlite"
];
```
Tags can also be set conditionally:
```nix
tags = [ "production" ] ++ lib.optionals withSqlite [ "sqlite" ];
```
### `deleteVendor` {#var-go-deleteVendor}
···
Following example could be used to only build the example-cli and example-server binaries:
```nix
-
subPackages = [
-
"cmd/example-cli"
-
"cmd/example-server"
-
];
```
### `excludedPackages` {#var-go-excludedPackages}
···
When a Go program depends on C libraries, place those dependencies in `buildInputs`:
```nix
buildInputs = [
libvirt
libxml2
];
```
`CGO_ENABLED` defaults to `1`.
···
For example, only a selection of tests could be run with:
```nix
# -run and -skip accept regular expressions
checkFlags = [
"-run=^Test(Simple|Fast)$"
];
```
If a larger amount of tests should be skipped, the following pattern can be used:
```nix
checkFlags =
let
# Skip tests that require network access
···
];
in
[ "-skip=^${builtins.concatStringsSep "$|^" skippedTests}$" ];
```
To disable tests altogether, set `doCheck = false;`.
···
The following is an example expression using `buildGoModule`:
```nix
+
{
+
pet = buildGoModule rec {
+
pname = "pet";
+
version = "0.3.4";
+
src = fetchFromGitHub {
+
owner = "knqyf263";
+
repo = "pet";
+
rev = "v${version}";
+
hash = "sha256-Gjw1dRrgM8D3G7v6WIM2+50r4HmTXvx0Xxme2fH9TlQ=";
+
};
+
vendorHash = "sha256-ciBIR+a1oaYH+H1PcC8cD8ncfJczk1IiJ8iYNM+R6aA=";
+
meta = {
+
description = "Simple command-line snippet manager, written in Go";
+
homepage = "https://github.com/knqyf263/pet";
+
license = lib.licenses.mit;
+
maintainers = with lib.maintainers; [ kalbasit ];
+
};
};
}
```
···
- `goDeps` is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate `deps.nix` file for readability. The dependency data structure is described below.
```nix
+
{
+
deis = buildGoPackage rec {
+
pname = "deis";
+
version = "1.13.0";
+
goPackagePath = "github.com/deis/deis";
+
+
src = fetchFromGitHub {
+
owner = "deis";
+
repo = "deis";
+
rev = "v${version}";
+
hash = "sha256-XCPD4LNWtAd8uz7zyCLRfT8rzxycIUmTACjU03GnaeM=";
+
};
+
goDeps = ./deps.nix;
};
}
```
···
The most common use case for this argument is to make the resulting executable aware of its own version by injecting the value of string variable using the `-X` flag. For example:
```nix
+
{
ldflags = [
"-X main.Version=${version}"
"-X main.Commit=${version}"
];
+
}
```
### `tags` {#var-go-tags}
···
A string list of [Go build tags (also called build constraints)](https://pkg.go.dev/cmd/go#hdr-Build_constraints) that are passed via the `-tags` argument of `go build`. These constraints control whether Go files from the source should be included in the build. For example:
```nix
+
{
tags = [
"production"
"sqlite"
];
+
}
```
Tags can also be set conditionally:
```nix
+
{
tags = [ "production" ] ++ lib.optionals withSqlite [ "sqlite" ];
+
}
```
### `deleteVendor` {#var-go-deleteVendor}
···
Following example could be used to only build the example-cli and example-server binaries:
```nix
+
{
+
subPackages = [
+
"cmd/example-cli"
+
"cmd/example-server"
+
];
+
}
```
### `excludedPackages` {#var-go-excludedPackages}
···
When a Go program depends on C libraries, place those dependencies in `buildInputs`:
```nix
+
{
buildInputs = [
libvirt
libxml2
];
+
}
```
`CGO_ENABLED` defaults to `1`.
···
For example, only a selection of tests could be run with:
```nix
+
{
# -run and -skip accept regular expressions
checkFlags = [
"-run=^Test(Simple|Fast)$"
];
+
}
```
If a larger amount of tests should be skipped, the following pattern can be used:
```nix
+
{
checkFlags =
let
# Skip tests that require network access
···
];
in
[ "-skip=^${builtins.concatStringsSep "$|^" skippedTests}$" ];
+
}
```
To disable tests altogether, set `doCheck = false;`.
+2 -2
doc/languages-frameworks/idris.section.md
···
```nix
build-idris-package {
-
idrisBuildOptions = [ "--log" "1" "--verbose" ]
-
...
}
```
···
```nix
build-idris-package {
+
idrisBuildOptions = [ "--log" "1" "--verbose" ];
+
# ...
}
```
+22 -14
doc/languages-frameworks/java.section.md
···
pname = "...";
version = "...";
-
src = fetchurl { ... };
nativeBuildInputs = [
ant
···
another package declares the attribute
```nix
-
buildInputs = [ libfoo ];
-
nativeBuildInputs = [ jdk ];
```
then `CLASSPATH` will be set to
···
script to run it using a JRE. You can use `makeWrapper` for this:
```nix
-
nativeBuildInputs = [ makeWrapper ];
-
installPhase = ''
-
mkdir -p $out/bin
-
makeWrapper ${jre}/bin/java $out/bin/foo \
-
--add-flags "-cp $out/share/java/foo.jar org.foo.Main"
-
'';
```
Since the introduction of the Java Platform Module System in Java 9,
···
something = (pkgs.something.override { jre = my_jre; });
other = (pkgs.other.override { jre = my_jre; });
in
-
...
```
You can also specify what JDK your JRE should be based on, for example
selecting a 'headless' build to avoid including a link to GTK+:
```nix
-
my_jre = pkgs.jre_minimal.override {
-
jdk = jdk11_headless;
-
};
```
Note all JDKs passthru `home`, so if your application requires
···
OpenJDK. For instance, to use the GNU Java Compiler:
```nix
-
nativeBuildInputs = [ gcj ant ];
```
Here, Ant will automatically use `gij` (the GNU Java Runtime) instead of
···
pname = "...";
version = "...";
+
src = fetchurl { /* ... */ };
nativeBuildInputs = [
ant
···
another package declares the attribute
```nix
+
{
+
buildInputs = [ libfoo ];
+
nativeBuildInputs = [ jdk ];
+
}
```
then `CLASSPATH` will be set to
···
script to run it using a JRE. You can use `makeWrapper` for this:
```nix
+
{
+
nativeBuildInputs = [ makeWrapper ];
+
installPhase = ''
+
mkdir -p $out/bin
+
makeWrapper ${jre}/bin/java $out/bin/foo \
+
--add-flags "-cp $out/share/java/foo.jar org.foo.Main"
+
'';
+
}
```
Since the introduction of the Java Platform Module System in Java 9,
···
something = (pkgs.something.override { jre = my_jre; });
other = (pkgs.other.override { jre = my_jre; });
in
+
"..."
```
You can also specify what JDK your JRE should be based on, for example
selecting a 'headless' build to avoid including a link to GTK+:
```nix
+
{
+
my_jre = pkgs.jre_minimal.override {
+
jdk = jdk11_headless;
+
};
+
}
```
Note all JDKs passthru `home`, so if your application requires
···
OpenJDK. For instance, to use the GNU Java Compiler:
```nix
+
{
+
nativeBuildInputs = [ gcj ant ];
+
}
```
Here, Ant will automatically use `gij` (the GNU Java Runtime) instead of
+43 -27
doc/languages-frameworks/javascript.section.md
···
when you need to override a package.json. It's nice to use the one from the upstream source and do some explicit override. Here is an example:
```nix
-
patchedPackageJSON = final.runCommand "package.json" { } ''
-
${jq}/bin/jq '.version = "0.4.0" |
-
.devDependencies."@jsdoc/cli" = "^0.2.5"
-
${sonar-src}/package.json > $out
-
'';
```
You will still need to commit the modified version of the lock files, but at least the overrides are explicit for everyone to see.
···
For example, `dat` requires `node-gyp-build`, so we override its expression in [pkgs/development/node-packages/overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/overrides.nix):
```nix
dat = prev.dat.override (oldAttrs: {
buildInputs = [ final.node-gyp-build pkgs.libtool pkgs.autoconf pkgs.automake ];
meta = oldAttrs.meta // { broken = since "12"; };
});
```
### Adding and Updating Javascript packages in nixpkgs {#javascript-adding-or-updating-packages}
···
If the downloaded files contain the `package.json` and `yarn.lock` files they can be used like this:
```nix
-
offlineCache = fetchYarnDeps {
-
yarnLock = src + "/yarn.lock";
-
hash = "....";
-
};
```
#### mkYarnPackage {#javascript-yarn2nix-mkYarnPackage}
···
It's important to use the `--offline` flag. For example if you script is `"build": "something"` in `package.json` use:
```nix
-
buildPhase = ''
-
export HOME=$(mktemp -d)
-
yarn --offline build
-
'';
```
The `distPhase` is packing the package's dependencies in a tarball using `yarn pack`. You can disable it using:
```nix
-
doDist = false;
```
The configure phase can sometimes fail because it makes many assumptions which may not always apply. One common override is:
```nix
-
configurePhase = ''
-
ln -s $node_modules node_modules
-
'';
```
or if you need a writeable node_modules directory:
```nix
-
configurePhase = ''
-
cp -r $node_modules node_modules
-
chmod +w node_modules
-
'';
```
#### mkYarnModules {#javascript-yarn2nix-mkYarnModules}
···
- Having trouble with `node-gyp`? Try adding these lines to the `yarnPreBuild` steps:
```nix
-
yarnPreBuild = ''
-
mkdir -p $HOME/.node-gyp/${nodejs.version}
-
echo 9 > $HOME/.node-gyp/${nodejs.version}/installVersion
-
ln -sfv ${nodejs}/include $HOME/.node-gyp/${nodejs.version}
-
export npm_config_nodedir=${nodejs}
-
'';
```
- The `echo 9` steps comes from this answer: <https://stackoverflow.com/a/49139496>
···
when you need to override a package.json. It's nice to use the one from the upstream source and do some explicit override. Here is an example:
```nix
+
{
+
patchedPackageJSON = final.runCommand "package.json" { } ''
+
${jq}/bin/jq '.version = "0.4.0" |
+
.devDependencies."@jsdoc/cli" = "^0.2.5"
+
${sonar-src}/package.json > $out
+
'';
+
}
```
You will still need to commit the modified version of the lock files, but at least the overrides are explicit for everyone to see.
···
For example, `dat` requires `node-gyp-build`, so we override its expression in [pkgs/development/node-packages/overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/overrides.nix):
```nix
+
{
dat = prev.dat.override (oldAttrs: {
buildInputs = [ final.node-gyp-build pkgs.libtool pkgs.autoconf pkgs.automake ];
meta = oldAttrs.meta // { broken = since "12"; };
});
+
}
```
### Adding and Updating Javascript packages in nixpkgs {#javascript-adding-or-updating-packages}
···
If the downloaded files contain the `package.json` and `yarn.lock` files they can be used like this:
```nix
+
{
+
offlineCache = fetchYarnDeps {
+
yarnLock = src + "/yarn.lock";
+
hash = "....";
+
};
+
}
```
#### mkYarnPackage {#javascript-yarn2nix-mkYarnPackage}
···
It's important to use the `--offline` flag. For example if you script is `"build": "something"` in `package.json` use:
```nix
+
{
+
buildPhase = ''
+
export HOME=$(mktemp -d)
+
yarn --offline build
+
'';
+
}
```
The `distPhase` is packing the package's dependencies in a tarball using `yarn pack`. You can disable it using:
```nix
+
{
+
doDist = false;
+
}
```
The configure phase can sometimes fail because it makes many assumptions which may not always apply. One common override is:
```nix
+
{
+
configurePhase = ''
+
ln -s $node_modules node_modules
+
'';
+
}
```
or if you need a writeable node_modules directory:
```nix
+
{
+
configurePhase = ''
+
cp -r $node_modules node_modules
+
chmod +w node_modules
+
'';
+
}
```
#### mkYarnModules {#javascript-yarn2nix-mkYarnModules}
···
- Having trouble with `node-gyp`? Try adding these lines to the `yarnPreBuild` steps:
```nix
+
{
+
yarnPreBuild = ''
+
mkdir -p $HOME/.node-gyp/${nodejs.version}
+
echo 9 > $HOME/.node-gyp/${nodejs.version}/installVersion
+
ln -sfv ${nodejs}/include $HOME/.node-gyp/${nodejs.version}
+
export npm_config_nodedir=${nodejs}
+
'';
+
}
```
- The `echo 9` steps comes from this answer: <https://stackoverflow.com/a/49139496>
+5 -3
doc/languages-frameworks/lisp.section.md
···
Such a Lisp can be now used e.g. to compile your sources:
```nix
-
buildPhase = ''
-
${sbcl'}/bin/sbcl --load my-build-file.lisp
-
''
```
## Importing packages from Quicklisp {#lisp-importing-packages-from-quicklisp}
···
Such a Lisp can be now used e.g. to compile your sources:
```nix
+
{
+
buildPhase = ''
+
${sbcl'}/bin/sbcl --load my-build-file.lisp
+
'';
+
}
```
## Importing packages from Quicklisp {#lisp-importing-packages-from-quicklisp}
+21 -16
doc/languages-frameworks/lua.section.md
···
pname = "luarocks-nix";
src = /home/my_luarocks/repository;
});
};
luaPackages = lua.pkgs;
···
within a `toLuaModule` call, for instance
```nix
-
mynewlib = toLuaModule ( stdenv.mkDerivation { ... });
```
There is also the `buildLuaPackage` function that can be used when lua modules
···
The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-luarocks-package.nix`
The following is an example:
```nix
-
luaposix = buildLuarocksPackage {
-
pname = "luaposix";
-
version = "34.0.4-1";
-
src = fetchurl {
-
url = "https://raw.githubusercontent.com/rocks-moonscript-org/moonrocks-mirror/master/luaposix-34.0.4-1.src.rock";
-
hash = "sha256-4mLJG8n4m6y4Fqd0meUDfsOb9RHSR0qa/KD5KCwrNXs=";
-
};
-
disabled = (luaOlder "5.1") || (luaAtLeast "5.4");
-
propagatedBuildInputs = [ bit32 lua std_normalize ];
-
meta = {
-
homepage = "https://github.com/luaposix/luaposix/";
-
description = "Lua bindings for POSIX";
-
maintainers = with lib.maintainers; [ vyp lblasc ];
-
license.fullName = "MIT/X11";
};
-
};
```
The `buildLuarocksPackage` delegates most tasks to luarocks:
···
pname = "luarocks-nix";
src = /home/my_luarocks/repository;
});
+
};
};
luaPackages = lua.pkgs;
···
within a `toLuaModule` call, for instance
```nix
+
{
+
mynewlib = toLuaModule ( stdenv.mkDerivation { /* ... */ });
+
}
```
There is also the `buildLuaPackage` function that can be used when lua modules
···
The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-luarocks-package.nix`
The following is an example:
```nix
+
{
+
luaposix = buildLuarocksPackage {
+
pname = "luaposix";
+
version = "34.0.4-1";
+
src = fetchurl {
+
url = "https://raw.githubusercontent.com/rocks-moonscript-org/moonrocks-mirror/master/luaposix-34.0.4-1.src.rock";
+
hash = "sha256-4mLJG8n4m6y4Fqd0meUDfsOb9RHSR0qa/KD5KCwrNXs=";
+
};
+
disabled = (luaOlder "5.1") || (luaAtLeast "5.4");
+
propagatedBuildInputs = [ bit32 lua std_normalize ];
+
meta = {
+
homepage = "https://github.com/luaposix/luaposix/";
+
description = "Lua bindings for POSIX";
+
maintainers = with lib.maintainers; [ vyp lblasc ];
+
license.fullName = "MIT/X11";
+
};
};
+
}
```
The `buildLuarocksPackage` delegates most tasks to luarocks:
+1 -1
doc/languages-frameworks/maven.section.md
···
license = lib.licenses.gpl3Plus;
maintainers = with lib.maintainers; [ majiir ];
};
-
}:
```
This package calls `maven.buildMavenPackage` to do its work. The primary difference from `stdenv.mkDerivation` is the `mvnHash` variable, which is a hash of all of the Maven dependencies.
···
license = lib.licenses.gpl3Plus;
maintainers = with lib.maintainers; [ majiir ];
};
+
}
```
This package calls `maven.buildMavenPackage` to do its work. The primary difference from `stdenv.mkDerivation` is the `mvnHash` variable, which is a hash of all of the Maven dependencies.
+1
doc/languages-frameworks/ocaml.section.md
···
license = lib.licenses.bsd3;
maintainers = with lib.maintainers; [ sternenseemann ];
};
```
Here is a second example, this time using a source archive generated with `dune-release`. It is a good idea to use this archive when it is available as it will usually contain substituted variables such as a `%%VERSION%%` field. This library does not depend on any other OCaml library and no tests are run after building it.
···
license = lib.licenses.bsd3;
maintainers = with lib.maintainers; [ sternenseemann ];
};
+
}
```
Here is a second example, this time using a source archive generated with `dune-release`. It is a good idea to use this archive when it is available as it will usually contain substituted variables such as a `%%VERSION%%` field. This library does not depend on any other OCaml library and no tests are run after building it.
+41 -33
doc/languages-frameworks/perl.section.md
···
Perl packages from CPAN are defined in [pkgs/top-level/perl-packages.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix) rather than `pkgs/all-packages.nix`. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from `perl-packages.nix`. However, more complicated packages should be put in a separate file, typically in `pkgs/development/perl-modules`. Here is an example of the former:
```nix
-
ClassC3 = buildPerlPackage rec {
-
pname = "Class-C3";
-
version = "0.21";
-
src = fetchurl {
-
url = "mirror://cpan/authors/id/F/FL/FLORA/${pname}-${version}.tar.gz";
-
hash = "sha256-/5GE5xHT0uYGOQxroqj6LMU7CtKn2s6vMVoSXxL4iK4=";
};
-
};
```
Note the use of `mirror://cpan/`, and the `pname` and `version` in the URL definition to ensure that the `pname` attribute is consistent with the source that we’re actually downloading. Perl packages are made available in `all-packages.nix` through the variable `perlPackages`. For instance, if you have a package that needs `ClassC3`, you would typically write
```nix
-
foo = import ../path/to/foo.nix {
-
inherit stdenv fetchurl ...;
-
inherit (perlPackages) ClassC3;
-
};
```
in `all-packages.nix`. You can test building a Perl package as follows:
···
Dependencies on other Perl packages can be specified in the `buildInputs` and `propagatedBuildInputs` attributes. If something is exclusively a build-time dependency, use `buildInputs`; if it’s (also) a runtime dependency, use `propagatedBuildInputs`. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules:
```nix
-
ClassC3Componentised = buildPerlPackage rec {
-
pname = "Class-C3-Componentised";
-
version = "1.0004";
-
src = fetchurl {
-
url = "mirror://cpan/authors/id/A/AS/ASH/${pname}-${version}.tar.gz";
-
hash = "sha256-ASO9rV/FzJYZ0BH572Fxm2ZrFLMZLFATJng1NuU4FHc=";
};
-
propagatedBuildInputs = [
-
ClassC3 ClassInspector TestException MROCompat
-
];
-
};
```
On Darwin, if a script has too many `-Idir` flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the `shortenPerlShebang` function from the `postInstall` phase:
···
```nix
{ lib, stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
-
ImageExifTool = buildPerlPackage {
-
pname = "Image-ExifTool";
-
version = "12.50";
-
src = fetchurl {
-
url = "https://exiftool.org/${pname}-${version}.tar.gz";
-
hash = "sha256-vOhB/FwQMC8PPvdnjDvxRpU6jAZcC6GMQfc0AH4uwKg=";
};
-
-
nativeBuildInputs = lib.optional stdenv.isDarwin shortenPerlShebang;
-
postInstall = lib.optionalString stdenv.isDarwin ''
-
shortenPerlShebang $out/bin/exiftool
-
'';
-
};
```
This will remove the `-I` flags from the shebang line, rewrite them in the `use lib` form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place.
···
Perl packages from CPAN are defined in [pkgs/top-level/perl-packages.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix) rather than `pkgs/all-packages.nix`. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from `perl-packages.nix`. However, more complicated packages should be put in a separate file, typically in `pkgs/development/perl-modules`. Here is an example of the former:
```nix
+
{
+
ClassC3 = buildPerlPackage rec {
+
pname = "Class-C3";
+
version = "0.21";
+
src = fetchurl {
+
url = "mirror://cpan/authors/id/F/FL/FLORA/${pname}-${version}.tar.gz";
+
hash = "sha256-/5GE5xHT0uYGOQxroqj6LMU7CtKn2s6vMVoSXxL4iK4=";
+
};
};
+
}
```
Note the use of `mirror://cpan/`, and the `pname` and `version` in the URL definition to ensure that the `pname` attribute is consistent with the source that we’re actually downloading. Perl packages are made available in `all-packages.nix` through the variable `perlPackages`. For instance, if you have a package that needs `ClassC3`, you would typically write
```nix
+
{
+
foo = import ../path/to/foo.nix {
+
inherit stdenv fetchurl /* ... */;
+
inherit (perlPackages) ClassC3;
+
};
+
}
```
in `all-packages.nix`. You can test building a Perl package as follows:
···
Dependencies on other Perl packages can be specified in the `buildInputs` and `propagatedBuildInputs` attributes. If something is exclusively a build-time dependency, use `buildInputs`; if it’s (also) a runtime dependency, use `propagatedBuildInputs`. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules:
```nix
+
{
+
ClassC3Componentised = buildPerlPackage rec {
+
pname = "Class-C3-Componentised";
+
version = "1.0004";
+
src = fetchurl {
+
url = "mirror://cpan/authors/id/A/AS/ASH/${pname}-${version}.tar.gz";
+
hash = "sha256-ASO9rV/FzJYZ0BH572Fxm2ZrFLMZLFATJng1NuU4FHc=";
+
};
+
propagatedBuildInputs = [
+
ClassC3 ClassInspector TestException MROCompat
+
];
};
+
}
```
On Darwin, if a script has too many `-Idir` flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the `shortenPerlShebang` function from the `postInstall` phase:
···
```nix
{ lib, stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
+
{
+
ImageExifTool = buildPerlPackage {
+
pname = "Image-ExifTool";
+
version = "12.50";
+
+
src = fetchurl {
+
url = "https://exiftool.org/${pname}-${version}.tar.gz";
+
hash = "sha256-vOhB/FwQMC8PPvdnjDvxRpU6jAZcC6GMQfc0AH4uwKg=";
+
};
+
nativeBuildInputs = lib.optional stdenv.isDarwin shortenPerlShebang;
+
postInstall = lib.optionalString stdenv.isDarwin ''
+
shortenPerlShebang $out/bin/exiftool
+
'';
};
+
}
```
This will remove the `-I` flags from the shebang line, rewrite them in the `use lib` form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place.
+3 -3
doc/languages-frameworks/php.section.md
···
myPhp = php.withExtensions ({ all, ... }: with all; [ imagick opcache ]);
in {
services.phpfpm.pools."foo".phpPackage = myPhp;
-
};
```
```nix
···
};
in {
services.phpfpm.pools."foo".phpPackage = myPhp;
-
};
```
#### Example usage with `nix-shell` {#ssec-php-user-guide-installing-with-extensions-nix-shell}
···
extensions = prev.extensions // {
mysqlnd = prev.extensions.mysqlnd.overrideAttrs (attrs: {
patches = attrs.patches or [] ++ [
-
];
});
};
···
myPhp = php.withExtensions ({ all, ... }: with all; [ imagick opcache ]);
in {
services.phpfpm.pools."foo".phpPackage = myPhp;
+
}
```
```nix
···
};
in {
services.phpfpm.pools."foo".phpPackage = myPhp;
+
}
```
#### Example usage with `nix-shell` {#ssec-php-user-guide-installing-with-extensions-nix-shell}
···
extensions = prev.extensions // {
mysqlnd = prev.extensions.mysqlnd.overrideAttrs (attrs: {
patches = attrs.patches or [] ++ [
+
# ...
];
});
};
+2 -2
doc/languages-frameworks/pkg-config.section.md
···
{ pkg-config, testers, ... }:
stdenv.mkDerivation (finalAttrs: {
-
...
nativeBuildInputs = [ pkg-config validatePkgConfig ];
passthru.tests.pkg-config = testers.testMetaPkgConfig finalAttrs.finalPackage;
meta = {
-
...
pkgConfigModules = [ "zlib" ];
};
})
···
{ pkg-config, testers, ... }:
stdenv.mkDerivation (finalAttrs: {
+
/* ... */
nativeBuildInputs = [ pkg-config validatePkgConfig ];
passthru.tests.pkg-config = testers.testMetaPkgConfig finalAttrs.finalPackage;
meta = {
+
/* ... */
pkgConfigModules = [ "zlib" ];
};
})
+65 -25
doc/languages-frameworks/python.section.md
···
be used through out all of the Python package set:
```nix
-
python3MyBlas = pkgs.python3.override {
-
packageOverrides = self: super: {
-
# We need toPythonModule for the package set to evaluate this
-
blas = super.toPythonModule(super.pkgs.blas.override {
-
blasProvider = super.pkgs.mkl;
-
});
-
lapack = super.toPythonModule(super.pkgs.lapack.override {
-
lapackProvider = super.pkgs.mkl;
-
});
};
-
};
```
This is particularly useful for numpy and scipy users who want to gain speed with other blas implementations.
···
This is then added to `all-packages.nix` just as any other application would be.
```nix
-
luigi = callPackage ../applications/networking/cluster/luigi { };
```
Since the package is an application, a consumer doesn't need to care about
···
applied to the reference:
```nix
-
youtube-dl = with python3Packages; toPythonApplication youtube-dl;
```
#### `toPythonModule` function {#topythonmodule-function}
···
modifications.
```nix
-
opencv = toPythonModule (pkgs.opencv.override {
-
enablePython = true;
-
pythonPackages = self;
-
});
```
Do pay attention to passing in the right Python version!
···
test run would be:
```nix
nativeCheckInputs = [ pytest ];
checkPhase = ''
runHook preCheck
···
runHook postCheck
'';
```
However, many repositories' test suites do not translate well to nix's build
···
To filter tests using pytest, one can do the following:
```nix
nativeCheckInputs = [ pytest ];
# avoid tests which need additional data or touch network
checkPhase = ''
···
runHook postCheck
'';
```
`--ignore` will tell pytest to ignore that file or directory from being
···
Using the example above, the analogous `pytestCheckHook` usage would be:
```nix
nativeCheckInputs = [
pytestCheckHook
];
···
disabledTestPaths = [
"tests/test_failing.py"
];
```
This is especially useful when tests need to be conditionally disabled,
for example:
```nix
disabledTests = [
# touches network
"download"
···
# can fail when building with other packages
"socket"
];
```
Trying to concatenate the related strings to disable tests in a regular
···
the listed modules.
```nix
pythonImportsCheck = [
"requests"
"urllib"
];
```
roughly translates to:
```nix
postCheck = ''
PYTHONPATH=$out/${python.sitePackages}:$PYTHONPATH
python -c "import requests; import urllib"
'';
```
However, this is done in its own phase, and not dependent on whether [`doCheck = true;`](#var-stdenv-doCheck).
···
we can do:
```nix
nativeBuildInputs = [
pythonRelaxDepsHook
];
···
pythonRemoveDeps = [
"pkg2"
];
```
which would result in the following `requirements.txt` file:
···
example:
```nix
nativeBuildInputs = [ pythonRelaxDepsHook ];
pythonRelaxDeps = true;
```
which would result in the following `requirements.txt` file:
···
`unittestCheckHook` is a hook which will substitute the setuptools `test` command for a [`checkPhase`](#ssec-check-phase) which runs `python -m unittest discover`:
```nix
nativeCheckInputs = [
unittestCheckHook
];
···
unittestFlagsArray = [
"-s" "tests" "-v"
];
```
#### Using sphinxHook {#using-sphinxhook}
···
render them using the default `html` style.
```nix
outputs = [
"out"
"doc"
···
nativeBuildInputs = [
sphinxHook
];
```
The hook will automatically build and install the artifact into the
···
for the artifacts of the `man` builder into the `man` target.
```nix
outputs = [
"out"
"doc"
···
"singlehtml"
"man"
];
```
Overwrite `sphinxRoot` when the hook is unable to find your
documentation source root.
```nix
# Configure sphinxRoot for uncommon paths
sphinxRoot = "weird/docs/path";
```
The hook is also available to packages outside the python ecosystem by
···
If you need to change a package's attribute(s) from `configuration.nix` you could do:
```nix
nixpkgs.config.packageOverrides = super: {
python3 = super.python3.override {
packageOverrides = python-self: python-super: {
···
};
};
};
```
`python3Packages.twisted` is now globally overridden.
···
this snippet:
```nix
myPythonPackages = python3Packages.override {
overrides = self: super: {
-
twisted = ...;
};
-
}
```
### How to override a Python package using overlays? {#how-to-override-a-python-package-using-overlays}
···
(
python-final: python-prev: {
foo = python-prev.foo.overridePythonAttrs (oldAttrs: {
-
...
});
}
)
···
`extras-require`, while PEP 621 calls these `optional-dependencies`.
```nix
-
optional-dependencies = {
-
complete = [ distributed ];
-
};
```
and letting the package requiring the extra add the list to its dependencies
```nix
-
dependencies = [
-
...
-
] ++ dask.optional-dependencies.complete;
```
This method is using `passthru`, meaning that changing `optional-dependencies` of a package won't cause it to rebuild.
···
be used through out all of the Python package set:
```nix
+
{
+
python3MyBlas = pkgs.python3.override {
+
packageOverrides = self: super: {
+
# We need toPythonModule for the package set to evaluate this
+
blas = super.toPythonModule(super.pkgs.blas.override {
+
blasProvider = super.pkgs.mkl;
+
});
+
lapack = super.toPythonModule(super.pkgs.lapack.override {
+
lapackProvider = super.pkgs.mkl;
+
});
+
};
};
+
}
```
This is particularly useful for numpy and scipy users who want to gain speed with other blas implementations.
···
This is then added to `all-packages.nix` just as any other application would be.
```nix
+
{
+
luigi = callPackage ../applications/networking/cluster/luigi { };
+
}
```
Since the package is an application, a consumer doesn't need to care about
···
applied to the reference:
```nix
+
{
+
youtube-dl = with python3Packages; toPythonApplication youtube-dl;
+
}
```
#### `toPythonModule` function {#topythonmodule-function}
···
modifications.
```nix
+
{
+
opencv = toPythonModule (pkgs.opencv.override {
+
enablePython = true;
+
pythonPackages = self;
+
});
+
}
```
Do pay attention to passing in the right Python version!
···
test run would be:
```nix
+
{
nativeCheckInputs = [ pytest ];
checkPhase = ''
runHook preCheck
···
runHook postCheck
'';
+
}
```
However, many repositories' test suites do not translate well to nix's build
···
To filter tests using pytest, one can do the following:
```nix
+
{
nativeCheckInputs = [ pytest ];
# avoid tests which need additional data or touch network
checkPhase = ''
···
runHook postCheck
'';
+
}
```
`--ignore` will tell pytest to ignore that file or directory from being
···
Using the example above, the analogous `pytestCheckHook` usage would be:
```nix
+
{
nativeCheckInputs = [
pytestCheckHook
];
···
disabledTestPaths = [
"tests/test_failing.py"
];
+
}
```
This is especially useful when tests need to be conditionally disabled,
for example:
```nix
+
{
disabledTests = [
# touches network
"download"
···
# can fail when building with other packages
"socket"
];
+
}
```
Trying to concatenate the related strings to disable tests in a regular
···
the listed modules.
```nix
+
{
pythonImportsCheck = [
"requests"
"urllib"
];
+
}
```
roughly translates to:
```nix
+
{
postCheck = ''
PYTHONPATH=$out/${python.sitePackages}:$PYTHONPATH
python -c "import requests; import urllib"
'';
+
}
```
However, this is done in its own phase, and not dependent on whether [`doCheck = true;`](#var-stdenv-doCheck).
···
we can do:
```nix
+
{
nativeBuildInputs = [
pythonRelaxDepsHook
];
···
pythonRemoveDeps = [
"pkg2"
];
+
}
```
which would result in the following `requirements.txt` file:
···
example:
```nix
+
{
nativeBuildInputs = [ pythonRelaxDepsHook ];
pythonRelaxDeps = true;
+
}
```
which would result in the following `requirements.txt` file:
···
`unittestCheckHook` is a hook which will substitute the setuptools `test` command for a [`checkPhase`](#ssec-check-phase) which runs `python -m unittest discover`:
```nix
+
{
nativeCheckInputs = [
unittestCheckHook
];
···
unittestFlagsArray = [
"-s" "tests" "-v"
];
+
}
```
#### Using sphinxHook {#using-sphinxhook}
···
render them using the default `html` style.
```nix
+
{
outputs = [
"out"
"doc"
···
nativeBuildInputs = [
sphinxHook
];
+
}
```
The hook will automatically build and install the artifact into the
···
for the artifacts of the `man` builder into the `man` target.
```nix
+
{
outputs = [
"out"
"doc"
···
"singlehtml"
"man"
];
+
}
```
Overwrite `sphinxRoot` when the hook is unable to find your
documentation source root.
```nix
+
{
# Configure sphinxRoot for uncommon paths
sphinxRoot = "weird/docs/path";
+
}
```
The hook is also available to packages outside the python ecosystem by
···
If you need to change a package's attribute(s) from `configuration.nix` you could do:
```nix
+
{
nixpkgs.config.packageOverrides = super: {
python3 = super.python3.override {
packageOverrides = python-self: python-super: {
···
};
};
};
+
}
```
`python3Packages.twisted` is now globally overridden.
···
this snippet:
```nix
+
{
myPythonPackages = python3Packages.override {
overrides = self: super: {
+
twisted = "...";
};
+
};
+
}
```
### How to override a Python package using overlays? {#how-to-override-a-python-package-using-overlays}
···
(
python-final: python-prev: {
foo = python-prev.foo.overridePythonAttrs (oldAttrs: {
+
# ...
});
}
)
···
`extras-require`, while PEP 621 calls these `optional-dependencies`.
```nix
+
{
+
optional-dependencies = {
+
complete = [ distributed ];
+
};
+
}
```
and letting the package requiring the extra add the list to its dependencies
```nix
+
{
+
dependencies = [
+
# ...
+
] ++ dask.optional-dependencies.complete;
+
}
```
This method is using `passthru`, meaning that changing `optional-dependencies` of a package won't cause it to rebuild.
+2
doc/languages-frameworks/ruby.section.md
···
Sometimes a Gemfile references other files. Such as `.ruby-version` or vendored gems. When copying the Gemfile to the nix store we need to copy those files alongside. This can be done using `extraConfigPaths`. For example:
```nix
gems = bundlerEnv {
name = "gems-for-some-project";
gemdir = ./.;
extraConfigPaths = [ "${./.}/.ruby-version" ];
};
```
### Gem-specific configurations and workarounds {#gem-specific-configurations-and-workarounds}
···
Sometimes a Gemfile references other files. Such as `.ruby-version` or vendored gems. When copying the Gemfile to the nix store we need to copy those files alongside. This can be done using `extraConfigPaths`. For example:
```nix
+
{
gems = bundlerEnv {
name = "gems-for-some-project";
gemdir = ./.;
extraConfigPaths = [ "${./.}/.ruby-version" ];
};
+
}
```
### Gem-specific configurations and workarounds {#gem-specific-configurations-and-workarounds}
+41 -25
doc/languages-frameworks/rust.section.md
···
To install the rust compiler and cargo put
```nix
-
environment.systemPackages = [
-
rustc
-
cargo
-
];
```
into your `configuration.nix` or bring them into scope with `nix-shell -p rustc cargo`.
···
For example:
```nix
cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
```
Exception: If the application has cargo `git` dependencies, the `cargoHash`/`cargoSha256`
···
`cargoHash` as follows:
```nix
cargoHash = lib.fakeHash;
```
For `cargoSha256` you can use:
```nix
cargoSha256 = lib.fakeSha256;
```
Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
···
required to build a rust package. A simple fix is to use:
```nix
-
postPatch = ''
-
ln -s ${./Cargo.lock} Cargo.lock
-
'';
```
The output hash of each dependency that uses a git source must be
···
```nix
rustPlatform.buildRustPackage rec {
-
(...)
cargoPatches = [
# a patch file to add/update Cargo.lock in the source code
./add-Cargo.lock.patch
···
can be used as follows:
```nix
-
cargoDeps = rustPlatform.fetchCargoTarball {
-
inherit src;
-
hash = "sha256-BoHIN/519Top1NUBjpB/oEMqi86Omt3zTQcXFWqrek0=";
-
};
```
The `src` attribute is required, as well as a hash specified through
···
`importCargoLock` can be used as follows:
```nix
-
cargoDeps = rustPlatform.importCargoLock {
-
lockFile = ./Cargo.lock;
-
};
```
If the `Cargo.lock` file includes git dependencies, then their output
···
lock file. For example:
```nix
-
cargoDeps = rustPlatform.importCargoLock {
-
lockFile = ./Cargo.lock;
-
outputHashes = {
-
"rand-0.8.3" = "0ya2hia3cn31qa8894s3av2s8j5bjwb6yq92k0jsnlx7jid0jwqa";
};
-
};
```
If you do not specify an output hash for a git dependency, building
···
- The version of `rustc` used to compile the crate:
```nix
-
(hello {}).override { rust = pkgs.rust; };
```
- Whether to build in release mode or debug mode (release mode by
default):
```nix
-
(hello {}).override { release = false; };
```
- Whether to print the commands sent to `rustc` when building
(equivalent to `--verbose` in cargo:
```nix
-
(hello {}).override { verbose = false; };
```
- Extra arguments to be passed to `rustc`:
```nix
-
(hello {}).override { extraRustcOpts = "-Z debuginfo=2"; };
```
- Phases, just like in any other derivation, can be specified using
···
preConfigure = ''
echo "pub const PATH=\"${hi.out}\";" >> src/path.rs"
'';
-
};
```
### Setting Up `nix-shell` {#setting-up-nix-shell}
···
To install the rust compiler and cargo put
```nix
+
{
+
environment.systemPackages = [
+
rustc
+
cargo
+
];
+
}
```
into your `configuration.nix` or bring them into scope with `nix-shell -p rustc cargo`.
···
For example:
```nix
+
{
cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
+
}
```
Exception: If the application has cargo `git` dependencies, the `cargoHash`/`cargoSha256`
···
`cargoHash` as follows:
```nix
+
{
cargoHash = lib.fakeHash;
+
}
```
For `cargoSha256` you can use:
```nix
+
{
cargoSha256 = lib.fakeSha256;
+
}
```
Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
···
required to build a rust package. A simple fix is to use:
```nix
+
{
+
postPatch = ''
+
ln -s ${./Cargo.lock} Cargo.lock
+
'';
+
}
```
The output hash of each dependency that uses a git source must be
···
```nix
rustPlatform.buildRustPackage rec {
+
# ...
cargoPatches = [
# a patch file to add/update Cargo.lock in the source code
./add-Cargo.lock.patch
···
can be used as follows:
```nix
+
{
+
cargoDeps = rustPlatform.fetchCargoTarball {
+
inherit src;
+
hash = "sha256-BoHIN/519Top1NUBjpB/oEMqi86Omt3zTQcXFWqrek0=";
+
};
+
}
```
The `src` attribute is required, as well as a hash specified through
···
`importCargoLock` can be used as follows:
```nix
+
{
+
cargoDeps = rustPlatform.importCargoLock {
+
lockFile = ./Cargo.lock;
+
};
+
}
```
If the `Cargo.lock` file includes git dependencies, then their output
···
lock file. For example:
```nix
+
{
+
cargoDeps = rustPlatform.importCargoLock {
+
lockFile = ./Cargo.lock;
+
outputHashes = {
+
"rand-0.8.3" = "0ya2hia3cn31qa8894s3av2s8j5bjwb6yq92k0jsnlx7jid0jwqa";
+
};
};
+
}
```
If you do not specify an output hash for a git dependency, building
···
- The version of `rustc` used to compile the crate:
```nix
+
(hello {}).override { rust = pkgs.rust; }
```
- Whether to build in release mode or debug mode (release mode by
default):
```nix
+
(hello {}).override { release = false; }
```
- Whether to print the commands sent to `rustc` when building
(equivalent to `--verbose` in cargo:
```nix
+
(hello {}).override { verbose = false; }
```
- Extra arguments to be passed to `rustc`:
```nix
+
(hello {}).override { extraRustcOpts = "-Z debuginfo=2"; }
```
- Phases, just like in any other derivation, can be specified using
···
preConfigure = ''
echo "pub const PATH=\"${hi.out}\";" >> src/path.rs"
'';
+
}
```
### Setting Up `nix-shell` {#setting-up-nix-shell}
+17 -9
doc/languages-frameworks/swift.section.md
···
If you'd like to build a different configuration than `release`:
```nix
-
swiftpmBuildConfig = "debug";
```
It is also possible to provide additional flags to `swift build`:
```nix
-
swiftpmFlags = [ "--disable-dead-strip" ];
```
The default `buildPhase` already passes `-j` for parallel building.
···
`checkPhase`, but it must be enabled with:
```nix
-
doCheck = true;
```
This essentially runs: `swift test -c release`
···
with a writable copy:
```nix
-
configurePhase = generated.configure ++ ''
-
# Replace the dependency symlink with a writable copy.
-
swiftpmMakeMutable swift-crypto
-
# Now apply a patch.
-
patch -p1 -d .build/checkouts/swift-crypto -i ${./some-fix.patch}
-
'';
```
## Considerations for custom build tools {#ssec-swift-considerations-for-custom-build-tools}
···
If you'd like to build a different configuration than `release`:
```nix
+
{
+
swiftpmBuildConfig = "debug";
+
}
```
It is also possible to provide additional flags to `swift build`:
```nix
+
{
+
swiftpmFlags = [ "--disable-dead-strip" ];
+
}
```
The default `buildPhase` already passes `-j` for parallel building.
···
`checkPhase`, but it must be enabled with:
```nix
+
{
+
doCheck = true;
+
}
```
This essentially runs: `swift test -c release`
···
with a writable copy:
```nix
+
{
+
configurePhase = generated.configure ++ ''
+
# Replace the dependency symlink with a writable copy.
+
swiftpmMakeMutable swift-crypto
+
# Now apply a patch.
+
patch -p1 -d .build/checkouts/swift-crypto -i ${./some-fix.patch}
+
'';
+
}
```
## Considerations for custom build tools {#ssec-swift-considerations-for-custom-build-tools}
+10 -6
doc/languages-frameworks/vim.section.md
···
Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added:
```nix
-
deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
-
dependencies = with super; [ deoplete-nvim vim-fish ];
-
});
```
Sometimes plugins require an override that must be changed when the plugin is updated. This can cause issues when Vim plugins are auto-updated but the associated override isn't updated. For these plugins, the override should be written so that it specifies all information required to install the plugin, and running `./update.py` doesn't change the derivation for the plugin. Manually updating the override is required to update these types of plugins. An example of such a plugin is `LanguageClient-neovim`.
···
You can then reference the generated vim plugins via:
```nix
-
myVimPlugins = pkgs.vimPlugins.extend (
-
(pkgs.callPackage ./generated.nix {})
-
);
```
···
Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added:
```nix
+
{
+
deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
+
dependencies = with super; [ deoplete-nvim vim-fish ];
+
});
+
}
```
Sometimes plugins require an override that must be changed when the plugin is updated. This can cause issues when Vim plugins are auto-updated but the associated override isn't updated. For these plugins, the override should be written so that it specifies all information required to install the plugin, and running `./update.py` doesn't change the derivation for the plugin. Manually updating the override is required to update these types of plugins. An example of such a plugin is `LanguageClient-neovim`.
···
You can then reference the generated vim plugins via:
```nix
+
{
+
myVimPlugins = pkgs.vimPlugins.extend (
+
(pkgs.callPackage ./generated.nix {})
+
);
+
}
```
+3
doc/packages/darwin-builder.section.md
···
in the example below and rebuild.
```nix
darwin-builder = nixpkgs.lib.nixosSystem {
system = linuxSystem;
modules = [
···
virtualisation.darwin-builder.workingDirectory = "/var/lib/darwin-builder";
}
];
```
You may make any other changes to your VM in this attribute set. For example,
···
in the example below and rebuild.
```nix
+
{
darwin-builder = nixpkgs.lib.nixosSystem {
system = linuxSystem;
modules = [
···
virtualisation.darwin-builder.workingDirectory = "/var/lib/darwin-builder";
}
];
+
};
+
}
```
You may make any other changes to your VM in this attribute set. For example,
+35 -31
doc/packages/eclipse.section.md
···
If you prefer to install plugins in a more declarative manner, then Nixpkgs also offer a number of Eclipse plugins that can be installed in an _Eclipse environment_. This type of environment is created using the function `eclipseWithPlugins` found inside the `nixpkgs.eclipses` attribute set. This function takes as argument `{ eclipse, plugins ? [], jvmArgs ? [] }` where `eclipse` is a one of the Eclipse packages described above, `plugins` is a list of plugin derivations, and `jvmArgs` is a list of arguments given to the JVM running the Eclipse. For example, say you wish to install the latest Eclipse Platform with the popular Eclipse Color Theme plugin and also allow Eclipse to use more RAM. You could then add:
```nix
-
packageOverrides = pkgs: {
-
myEclipse = with pkgs.eclipses; eclipseWithPlugins {
-
eclipse = eclipse-platform;
-
jvmArgs = [ "-Xmx2048m" ];
-
plugins = [ plugins.color-theme ];
};
}
```
···
Expanding the previous example with two plugins using the above functions, we have:
```nix
-
packageOverrides = pkgs: {
-
myEclipse = with pkgs.eclipses; eclipseWithPlugins {
-
eclipse = eclipse-platform;
-
jvmArgs = [ "-Xmx2048m" ];
-
plugins = [
-
plugins.color-theme
-
(plugins.buildEclipsePlugin {
-
name = "myplugin1-1.0";
-
srcFeature = fetchurl {
-
url = "http://…/features/myplugin1.jar";
-
hash = "sha256-123…";
-
};
-
srcPlugin = fetchurl {
-
url = "http://…/plugins/myplugin1.jar";
-
hash = "sha256-123…";
-
};
-
});
-
(plugins.buildEclipseUpdateSite {
-
name = "myplugin2-1.0";
-
src = fetchurl {
-
stripRoot = false;
-
url = "http://…/myplugin2.zip";
-
hash = "sha256-123…";
-
};
-
});
-
];
};
}
```
···
If you prefer to install plugins in a more declarative manner, then Nixpkgs also offer a number of Eclipse plugins that can be installed in an _Eclipse environment_. This type of environment is created using the function `eclipseWithPlugins` found inside the `nixpkgs.eclipses` attribute set. This function takes as argument `{ eclipse, plugins ? [], jvmArgs ? [] }` where `eclipse` is a one of the Eclipse packages described above, `plugins` is a list of plugin derivations, and `jvmArgs` is a list of arguments given to the JVM running the Eclipse. For example, say you wish to install the latest Eclipse Platform with the popular Eclipse Color Theme plugin and also allow Eclipse to use more RAM. You could then add:
```nix
+
{
+
packageOverrides = pkgs: {
+
myEclipse = with pkgs.eclipses; eclipseWithPlugins {
+
eclipse = eclipse-platform;
+
jvmArgs = [ "-Xmx2048m" ];
+
plugins = [ plugins.color-theme ];
+
};
};
}
```
···
Expanding the previous example with two plugins using the above functions, we have:
```nix
+
{
+
packageOverrides = pkgs: {
+
myEclipse = with pkgs.eclipses; eclipseWithPlugins {
+
eclipse = eclipse-platform;
+
jvmArgs = [ "-Xmx2048m" ];
+
plugins = [
+
plugins.color-theme
+
(plugins.buildEclipsePlugin {
+
name = "myplugin1-1.0";
+
srcFeature = fetchurl {
+
url = "http://…/features/myplugin1.jar";
+
hash = "sha256-123…";
+
};
+
srcPlugin = fetchurl {
+
url = "http://…/plugins/myplugin1.jar";
+
hash = "sha256-123…";
+
};
+
})
+
(plugins.buildEclipseUpdateSite {
+
name = "myplugin2-1.0";
+
src = fetchurl {
+
stripRoot = false;
+
url = "http://…/myplugin2.zip";
+
hash = "sha256-123…";
+
};
+
})
+
];
+
};
};
}
```
+8 -5
doc/packages/emacs.section.md
···
projectile
use-package
]));
-
}
}
```
···
Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). But you can't control these priorities when some package is installed as a dependency. You can override it on a per-package-basis, providing all the required dependencies manually, but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package, you can use `overrideScope`.
```nix
-
overrides = self: super: rec {
-
haskell-mode = self.melpaPackages.haskell-mode;
-
...
-
};
((emacsPackagesFor emacs).overrideScope overrides).withPackages
(p: with p; [
# here both these package will use haskell-mode of our own choice
···
dante
])
```
···
projectile
use-package
]));
+
};
}
```
···
Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). But you can't control these priorities when some package is installed as a dependency. You can override it on a per-package-basis, providing all the required dependencies manually, but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package, you can use `overrideScope`.
```nix
+
let
+
overrides = self: super: rec {
+
haskell-mode = self.melpaPackages.haskell-mode;
+
# ...
+
};
+
in
((emacsPackagesFor emacs).overrideScope overrides).withPackages
(p: with p; [
# here both these package will use haskell-mode of our own choice
···
dante
])
```
+
}
+1 -1
doc/packages/steam.section.md
···
you need to add:
```nix
-
steam.override { withJava = true; };
```
## steam-run {#sec-steam-run}
···
you need to add:
```nix
+
steam.override { withJava = true; }
```
## steam-run {#sec-steam-run}
+3 -1
doc/packages/urxvt.section.md
···
If the plugin is itself a Perl package that needs to be imported from other plugins or scripts, add the following passthrough:
```nix
-
passthru.perlPackages = [ "self" ];
```
This will make the urxvt wrapper pick up the dependency and set up the Perl path accordingly.
···
If the plugin is itself a Perl package that needs to be imported from other plugins or scripts, add the following passthrough:
```nix
+
{
+
passthru.perlPackages = [ "self" ];
+
}
```
This will make the urxvt wrapper pick up the dependency and set up the Perl path accordingly.
+3 -3
doc/packages/weechat.section.md
···
WeeChat can be configured to include your choice of plugins, reducing its closure size from the default configuration which includes all available plugins. To make use of this functionality, install an expression that overrides its configuration, such as:
```nix
-
weechat.override {configure = {availablePlugins, ...}: {
plugins = with availablePlugins; [ python perl ];
-
}
}
```
···
];
init = ''
/set plugins.var.python.jabber.key "val"
-
'':
};
}
```
···
WeeChat can be configured to include your choice of plugins, reducing its closure size from the default configuration which includes all available plugins. To make use of this functionality, install an expression that overrides its configuration, such as:
```nix
+
weechat.override {configure = ({availablePlugins, ...}: {
plugins = with availablePlugins; [ python perl ];
+
});
}
```
···
];
init = ''
/set plugins.var.python.jabber.key "val"
+
'';
};
}
```
+19 -9
doc/stdenv/cross-compilation.chapter.md
···
In Nixpkgs, these three platforms are defined as attribute sets under the names `buildPlatform`, `hostPlatform`, and `targetPlatform`. They are always defined as attributes in the standard environment. That means one can access them like:
```nix
-
{ stdenv, fooDep, barDep, ... }: ...stdenv.buildPlatform...
```
`buildPlatform`
···
Many packages assume that an unprefixed binutils (`cc`/`ar`/`ld` etc.) is available, but Nix doesn't provide one. It only provides a prefixed one, just as it only does for all the other binutils programs. It may be necessary to patch the package to fix the build system to use a prefix. For instance, instead of `cc`, use `${stdenv.cc.targetPrefix}cc`.
```nix
-
makeFlags = [ "CC=${stdenv.cc.targetPrefix}cc" ];
```
#### How do I avoid compiling a GCC cross-compiler from source? {#cross-qa-avoid-compiling-gcc-cross-compiler}
···
Add the following to your `mkDerivation` invocation.
```nix
-
depsBuildBuild = [ buildPackages.stdenv.cc ];
```
#### My package’s testsuite needs to run host platform code. {#cross-testsuite-runs-host-code}
···
Add the following to your `mkDerivation` invocation.
```nix
-
doCheck = stdenv.buildPlatform.canExecute stdenv.hostPlatform;
```
#### Package using Meson needs to run binaries for the host platform during build. {#cross-meson-runs-host-code}
···
e.g.
```nix
-
nativeBuildInputs = [
-
meson
-
] ++ lib.optionals (!stdenv.buildPlatform.canExecute stdenv.hostPlatform) [
-
mesonEmulatorHook
-
];
```
Example of an error which this fixes.
···
In Nixpkgs, these three platforms are defined as attribute sets under the names `buildPlatform`, `hostPlatform`, and `targetPlatform`. They are always defined as attributes in the standard environment. That means one can access them like:
```nix
+
{ stdenv, fooDep, barDep, ... }: {
+
# ...stdenv.buildPlatform...
+
}
```
`buildPlatform`
···
Many packages assume that an unprefixed binutils (`cc`/`ar`/`ld` etc.) is available, but Nix doesn't provide one. It only provides a prefixed one, just as it only does for all the other binutils programs. It may be necessary to patch the package to fix the build system to use a prefix. For instance, instead of `cc`, use `${stdenv.cc.targetPrefix}cc`.
```nix
+
{
+
makeFlags = [ "CC=${stdenv.cc.targetPrefix}cc" ];
+
}
```
#### How do I avoid compiling a GCC cross-compiler from source? {#cross-qa-avoid-compiling-gcc-cross-compiler}
···
Add the following to your `mkDerivation` invocation.
```nix
+
{
+
depsBuildBuild = [ buildPackages.stdenv.cc ];
+
}
```
#### My package’s testsuite needs to run host platform code. {#cross-testsuite-runs-host-code}
···
Add the following to your `mkDerivation` invocation.
```nix
+
{
+
doCheck = stdenv.buildPlatform.canExecute stdenv.hostPlatform;
+
}
```
#### Package using Meson needs to run binaries for the host platform during build. {#cross-meson-runs-host-code}
···
e.g.
```nix
+
{
+
nativeBuildInputs = [
+
meson
+
] ++ lib.optionals (!stdenv.buildPlatform.canExecute stdenv.hostPlatform) [
+
mesonEmulatorHook
+
];
+
}
```
Example of an error which this fixes.
+31 -19
doc/stdenv/meta.chapter.md
···
Nix packages can declare *meta-attributes* that contain information about a package such as a description, its homepage, its license, and so on. For instance, the GNU Hello package has a `meta` declaration like this:
```nix
-
meta = {
-
description = "A program that produces a familiar, friendly greeting";
-
longDescription = ''
-
GNU Hello is a program that prints "Hello, world!" when you run it.
-
It is fully customizable.
-
'';
-
homepage = "https://www.gnu.org/software/hello/manual/";
-
license = lib.licenses.gpl3Plus;
-
maintainers = with lib.maintainers; [ eelco ];
-
platforms = lib.platforms.all;
-
};
```
Meta-attributes are not passed to the builder of the package. Thus, a change to a meta-attribute doesn’t trigger a recompilation of the package.
···
The list of Nix platform types on which the package is supported. Hydra builds packages according to the platform specified. If no platform is specified, the package does not have prebuilt binaries. An example is:
```nix
-
meta.platforms = lib.platforms.linux;
```
Attribute Set `lib.platforms` defines [various common lists](https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix) of platforms types.
···
For example, a package which requires dynamic linking and cannot be linked statically could use this:
```nix
-
meta.platforms = lib.platforms.all;
-
meta.badPlatforms = [ lib.systems.inspect.patterns.isStatic ];
```
The [`lib.meta.availableOn`](https://github.com/NixOS/nixpkgs/blob/b03ac42b0734da3e7be9bf8d94433a5195734b19/lib/meta.nix#L95-L106) function can be used to test whether or not a package is available (i.e. buildable) on a given platform.
···
The NixOS tests are available as `nixosTests` in parameters of derivations. For instance, the OpenSMTPD derivation includes lines similar to:
```nix
-
{ /* ... */, nixosTests }:
{
# ...
passthru.tests = {
···
The list of Nix platform types for which the [Hydra](https://github.com/nixos/hydra) [instance at `hydra.nixos.org`](https://nixos.org/hydra) will build the package. (Hydra is the Nix-based continuous build system.) It defaults to the value of `meta.platforms`. Thus, the only reason to set `meta.hydraPlatforms` is if you want `hydra.nixos.org` to build the package on a subset of `meta.platforms`, or not at all, e.g.
```nix
-
meta.platforms = lib.platforms.linux;
-
meta.hydraPlatforms = [];
```
### `broken` {#var-meta-broken}
···
- Does not cross compile
```nix
-
meta.broken = !(stdenv.buildPlatform.canExecute stdenv.hostPlatform)
```
- Broken if all of a certain set of its dependencies are broken
```nix
-
meta.broken = lib.all (map (p: p.meta.broken) [ glibc musl ])
```
This makes `broken` strictly more powerful than `meta.badPlatforms`.
···
Nix packages can declare *meta-attributes* that contain information about a package such as a description, its homepage, its license, and so on. For instance, the GNU Hello package has a `meta` declaration like this:
```nix
+
{
+
meta = {
+
description = "A program that produces a familiar, friendly greeting";
+
longDescription = ''
+
GNU Hello is a program that prints "Hello, world!" when you run it.
+
It is fully customizable.
+
'';
+
homepage = "https://www.gnu.org/software/hello/manual/";
+
license = lib.licenses.gpl3Plus;
+
maintainers = with lib.maintainers; [ eelco ];
+
platforms = lib.platforms.all;
+
};
+
}
```
Meta-attributes are not passed to the builder of the package. Thus, a change to a meta-attribute doesn’t trigger a recompilation of the package.
···
The list of Nix platform types on which the package is supported. Hydra builds packages according to the platform specified. If no platform is specified, the package does not have prebuilt binaries. An example is:
```nix
+
{
+
meta.platforms = lib.platforms.linux;
+
}
```
Attribute Set `lib.platforms` defines [various common lists](https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix) of platforms types.
···
For example, a package which requires dynamic linking and cannot be linked statically could use this:
```nix
+
{
+
meta.platforms = lib.platforms.all;
+
meta.badPlatforms = [ lib.systems.inspect.patterns.isStatic ];
+
}
```
The [`lib.meta.availableOn`](https://github.com/NixOS/nixpkgs/blob/b03ac42b0734da3e7be9bf8d94433a5195734b19/lib/meta.nix#L95-L106) function can be used to test whether or not a package is available (i.e. buildable) on a given platform.
···
The NixOS tests are available as `nixosTests` in parameters of derivations. For instance, the OpenSMTPD derivation includes lines similar to:
```nix
+
{ /* ... , */ nixosTests }:
{
# ...
passthru.tests = {
···
The list of Nix platform types for which the [Hydra](https://github.com/nixos/hydra) [instance at `hydra.nixos.org`](https://nixos.org/hydra) will build the package. (Hydra is the Nix-based continuous build system.) It defaults to the value of `meta.platforms`. Thus, the only reason to set `meta.hydraPlatforms` is if you want `hydra.nixos.org` to build the package on a subset of `meta.platforms`, or not at all, e.g.
```nix
+
{
+
meta.platforms = lib.platforms.linux;
+
meta.hydraPlatforms = [];
+
}
```
### `broken` {#var-meta-broken}
···
- Does not cross compile
```nix
+
{
+
meta.broken = !(stdenv.buildPlatform.canExecute stdenv.hostPlatform);
+
}
```
- Broken if all of a certain set of its dependencies are broken
```nix
+
{
+
meta.broken = lib.all (map (p: p.meta.broken) [ glibc musl ]);
+
}
```
This makes `broken` strictly more powerful than `meta.badPlatforms`.
+3 -1
doc/stdenv/multiple-output.chapter.md
···
In nixpkgs there is a framework supporting multiple-output derivations. It tries to cover most cases by default behavior. You can find the source separated in `<nixpkgs/pkgs/build-support/setup-hooks/multiple-outputs.sh>`; it’s relatively well-readable. The whole machinery is triggered by defining the `outputs` attribute to contain the list of desired output names (strings).
```nix
-
outputs = [ "bin" "dev" "out" "doc" ];
```
Often such a single line is enough. For each output an equally named environment variable is passed to the builder and contains the path in nix store for that output. Typically you also want to have the main `out` output, as it catches any files that didn’t get elsewhere.
···
In nixpkgs there is a framework supporting multiple-output derivations. It tries to cover most cases by default behavior. You can find the source separated in `<nixpkgs/pkgs/build-support/setup-hooks/multiple-outputs.sh>`; it’s relatively well-readable. The whole machinery is triggered by defining the `outputs` attribute to contain the list of desired output names (strings).
```nix
+
{
+
outputs = [ "bin" "dev" "out" "doc" ];
+
}
```
Often such a single line is enough. For each output an equally named environment variable is passed to the builder and contains the path in nix store for that output. Typically you also want to have the main `out` output, as it catches any files that didn’t get elsewhere.
+59 -35
doc/stdenv/stdenv.chapter.md
···
stdenv.mkDerivation {
pname = "libfoo";
version = "1.2.3";
-
...
buildInputs = [libbar perl ncurses];
}
```
···
stdenv.mkDerivation {
pname = "fnord";
version = "4.5";
-
...
buildPhase = ''
gcc foo.c -o foo
'';
···
stdenv.mkDerivation {
pname = "libfoo";
version = "1.2.3";
-
...
builder = ./builder.sh;
}
```
···
This is an attribute set which can be filled with arbitrary values. For example:
```nix
-
passthru = {
-
foo = "bar";
-
baz = {
-
value1 = 4;
-
value2 = 5;
};
}
```
···
- []{#var-passthru-updateScript-command} an executable file, either on the file system:
```nix
-
passthru.updateScript = ./update.sh;
```
or inside the expression itself:
```nix
-
passthru.updateScript = writeScript "update-zoom-us" ''
-
#!/usr/bin/env nix-shell
-
#!nix-shell -i bash -p curl pcre2 common-updater-scripts
-
set -eu -o pipefail
-
version="$(curl -sI https://zoom.us/client/latest/zoom_x86_64.tar.xz | grep -Fi 'Location:' | pcre2grep -o1 '/(([0-9]\.?)+)/')"
-
update-source-version zoom-us "$version"
-
'';
```
- a list, a script followed by arguments to be passed to it:
```nix
-
passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ];
```
- an attribute set containing:
···
- [`supportedFeatures`]{#var-passthru-updateScript-set-supportedFeatures} (optional) – a list of the [extra features](#var-passthru-updateScript-supported-features) the script supports.
```nix
-
passthru.updateScript = {
-
command = [ ../../update.sh pname ];
-
attrPath = pname;
-
supportedFeatures = [ … ];
-
};
```
::: {.tip}
A common pattern is to use the [`nix-update-script`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/common-updater/nix-update.nix) attribute provided in Nixpkgs, which runs [`nix-update`](https://github.com/Mic92/nix-update):
```nix
-
passthru.updateScript = nix-update-script { };
```
For simple packages, this is often enough, and will ensure that the package is updated automatically by [`nixpkgs-update`](https://ryantm.github.io/nixpkgs-update) when a new version is released. The [update bot](https://nix-community.org/update-bot) runs periodically to attempt to automatically update packages, and will run `passthru.updateScript` if set. While not strictly necessary if the project is listed on [Repology](https://repology.org), using `nix-update-script` allows the package to update via many more sources (e.g. GitHub releases).
···
A list of strings passed as additional flags to `make`. These flags are also used by the default install and check phase. For setting make flags specific to the build phase, use `buildFlags` (see below).
```nix
-
makeFlags = [ "PREFIX=$(out)" ];
```
::: {.note}
···
A shell array containing additional arguments passed to `make`. You must use this instead of `makeFlags` if the arguments contain spaces, e.g.
```nix
-
preBuild = ''
-
makeFlagsArray+=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar")
-
'';
```
Note that shell arrays cannot be passed through environment variables, so you cannot set `makeFlagsArray` in a derivation attribute (because those are passed through environment variables): you have to define them in shell code.
···
Controls whether the check phase is executed. By default it is skipped, but if `doCheck` is set to true, the check phase is usually executed. Thus you should set
```nix
-
doCheck = true;
```
in the derivation to enable checks. The exception is cross compilation. Cross compiled builds never run tests, no matter how `doCheck` is set, as the newly-built program won’t run on the platform used to build it.
···
The make targets that perform the installation. Defaults to `install`. Example:
```nix
-
installTargets = "install-bin install-doc";
```
##### `installFlags` / `installFlagsArray` {#var-stdenv-installFlags}
···
```nix
stdenv.mkDerivation {
# ...
-
stripExclude = [ "*.rlib" ]
}
```
···
```nix
stdenv.mkDerivation {
# ...
-
stripExclude = [ "lib/modules/*/build/* ]
}
```
···
Controls whether the installCheck phase is executed. By default it is skipped, but if `doInstallCheck` is set to true, the installCheck phase is usually executed. Thus you should set
```nix
-
doInstallCheck = true;
```
in the derivation to enable install checks. The exception is cross compilation. Cross compiled builds never run tests, no matter how `doInstallCheck` is set, as the newly-built program won’t run on the platform used to build it.
···
As `remove-references-to` is an actual executable and not a shell function, it can be used with `find`.
Example removing all references to the compiler in the output:
```nix
-
postInstall = ''
-
find "$out" -type f -exec remove-references-to -t ${stdenv.cc} '{}' +
-
'';
```
### `substitute` \<infile\> \<outfile\> \<subs\> {#fun-substitute}
···
stdenv.mkDerivation {
pname = "libfoo";
version = "1.2.3";
+
# ...
buildInputs = [libbar perl ncurses];
}
```
···
stdenv.mkDerivation {
pname = "fnord";
version = "4.5";
+
# ...
buildPhase = ''
gcc foo.c -o foo
'';
···
stdenv.mkDerivation {
pname = "libfoo";
version = "1.2.3";
+
# ...
builder = ./builder.sh;
}
```
···
This is an attribute set which can be filled with arbitrary values. For example:
```nix
+
{
+
passthru = {
+
foo = "bar";
+
baz = {
+
value1 = 4;
+
value2 = 5;
+
};
};
}
```
···
- []{#var-passthru-updateScript-command} an executable file, either on the file system:
```nix
+
{
+
passthru.updateScript = ./update.sh;
+
}
```
or inside the expression itself:
```nix
+
{
+
passthru.updateScript = writeScript "update-zoom-us" ''
+
#!/usr/bin/env nix-shell
+
#!nix-shell -i bash -p curl pcre2 common-updater-scripts
+
set -eu -o pipefail
+
version="$(curl -sI https://zoom.us/client/latest/zoom_x86_64.tar.xz | grep -Fi 'Location:' | pcre2grep -o1 '/(([0-9]\.?)+)/')"
+
update-source-version zoom-us "$version"
+
'';
+
}
```
- a list, a script followed by arguments to be passed to it:
```nix
+
{
+
passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ];
+
}
```
- an attribute set containing:
···
- [`supportedFeatures`]{#var-passthru-updateScript-set-supportedFeatures} (optional) – a list of the [extra features](#var-passthru-updateScript-supported-features) the script supports.
```nix
+
{
+
passthru.updateScript = {
+
command = [ ../../update.sh pname ];
+
attrPath = pname;
+
supportedFeatures = [ /* ... */ ];
+
};
+
}
```
::: {.tip}
A common pattern is to use the [`nix-update-script`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/common-updater/nix-update.nix) attribute provided in Nixpkgs, which runs [`nix-update`](https://github.com/Mic92/nix-update):
```nix
+
{
+
passthru.updateScript = nix-update-script { };
+
}
```
For simple packages, this is often enough, and will ensure that the package is updated automatically by [`nixpkgs-update`](https://ryantm.github.io/nixpkgs-update) when a new version is released. The [update bot](https://nix-community.org/update-bot) runs periodically to attempt to automatically update packages, and will run `passthru.updateScript` if set. While not strictly necessary if the project is listed on [Repology](https://repology.org), using `nix-update-script` allows the package to update via many more sources (e.g. GitHub releases).
···
A list of strings passed as additional flags to `make`. These flags are also used by the default install and check phase. For setting make flags specific to the build phase, use `buildFlags` (see below).
```nix
+
{
+
makeFlags = [ "PREFIX=$(out)" ];
+
}
```
::: {.note}
···
A shell array containing additional arguments passed to `make`. You must use this instead of `makeFlags` if the arguments contain spaces, e.g.
```nix
+
{
+
preBuild = ''
+
makeFlagsArray+=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar")
+
'';
+
}
```
Note that shell arrays cannot be passed through environment variables, so you cannot set `makeFlagsArray` in a derivation attribute (because those are passed through environment variables): you have to define them in shell code.
···
Controls whether the check phase is executed. By default it is skipped, but if `doCheck` is set to true, the check phase is usually executed. Thus you should set
```nix
+
{
+
doCheck = true;
+
}
```
in the derivation to enable checks. The exception is cross compilation. Cross compiled builds never run tests, no matter how `doCheck` is set, as the newly-built program won’t run on the platform used to build it.
···
The make targets that perform the installation. Defaults to `install`. Example:
```nix
+
{
+
installTargets = "install-bin install-doc";
+
}
```
##### `installFlags` / `installFlagsArray` {#var-stdenv-installFlags}
···
```nix
stdenv.mkDerivation {
# ...
+
stripExclude = [ "*.rlib" ];
}
```
···
```nix
stdenv.mkDerivation {
# ...
+
stripExclude = [ "lib/modules/*/build/*" ];
}
```
···
Controls whether the installCheck phase is executed. By default it is skipped, but if `doInstallCheck` is set to true, the installCheck phase is usually executed. Thus you should set
```nix
+
{
+
doInstallCheck = true;
+
}
```
in the derivation to enable install checks. The exception is cross compilation. Cross compiled builds never run tests, no matter how `doInstallCheck` is set, as the newly-built program won’t run on the platform used to build it.
···
As `remove-references-to` is an actual executable and not a shell function, it can be used with `find`.
Example removing all references to the compiler in the output:
```nix
+
{
+
postInstall = ''
+
find "$out" -type f -exec remove-references-to -t ${stdenv.cc} '{}' +
+
'';
+
}
```
### `substitute` \<infile\> \<outfile\> \<subs\> {#fun-substitute}
+1 -1
doc/using/configuration.chapter.md
···
```nix
{
packageOverrides = pkgs: rec {
-
foo = pkgs.foo.override { ... };
};
}
```
···
```nix
{
packageOverrides = pkgs: rec {
+
foo = pkgs.foo.override { /* ... */ };
};
}
```
+1 -1
doc/using/overlays.chapter.md
···
assert (!blas.isILP64) && (!lapack.isILP64);
stdenv.mkDerivation {
-
...
}
```
···
assert (!blas.isILP64) && (!lapack.isILP64);
stdenv.mkDerivation {
+
# ...
}
```
+32 -22
doc/using/overrides.chapter.md
···
Example usages:
```nix
-
pkgs.foo.override { arg1 = val1; arg2 = val2; ... }
```
It's also possible to access the previous arguments.
```nix
-
pkgs.foo.override (previous: { arg1 = previous.arg1; ... })
```
<!-- TODO: move below programlisting to a new section about extending and overlays and reference it -->
···
```nix
import pkgs.path { overlays = [ (self: super: {
foo = super.foo.override { barSupport = true ; };
-
})]};
```
```nix
-
mypkg = pkgs.callPackage ./mypkg.nix {
-
mydep = pkgs.mydep.override { ... };
-
}
```
In the first example, `pkgs.foo` is the result of a function call with some default arguments, usually a derivation. Using `pkgs.foo.override` will call the same function with the given new arguments.
···
Example usages:
```nix
-
helloBar = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: {
-
pname = previousAttrs.pname + "-bar";
-
});
```
In the above example, "-bar" is appended to the pname attribute, while all other attributes will be retained from the original `hello` package.
···
Function arguments can be omitted entirely if there is no need to access `previousAttrs` or `finalAttrs`.
```nix
-
helloWithDebug = pkgs.hello.overrideAttrs {
-
separateDebugInfo = true;
-
};
```
In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`.
···
Example usage:
```nix
-
mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
-
name = "sed-4.2.2-pre";
-
src = fetchurl {
-
url = "ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2";
-
hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";
-
};
-
patches = [];
-
});
```
In the above example, the `name`, `src`, and `patches` of the derivation will be overridden, while all other attributes will be retained from the original derivation.
···
Example usage:
```nix
-
f = { a, b }: { result = a+b; };
-
c = lib.makeOverridable f { a = 1; b = 2; };
```
The variable `c` is the value of the `f` function applied with some default arguments. Hence the value of `c.result` is `3`, in this example.
···
Example usages:
```nix
+
pkgs.foo.override { arg1 = val1; arg2 = val2; /* ... */ }
```
It's also possible to access the previous arguments.
```nix
+
pkgs.foo.override (previous: { arg1 = previous.arg1; /* ... */ })
```
<!-- TODO: move below programlisting to a new section about extending and overlays and reference it -->
···
```nix
import pkgs.path { overlays = [ (self: super: {
foo = super.foo.override { barSupport = true ; };
+
})];}
```
```nix
+
{
+
mypkg = pkgs.callPackage ./mypkg.nix {
+
mydep = pkgs.mydep.override { /* ... */ };
+
};
+
}
```
In the first example, `pkgs.foo` is the result of a function call with some default arguments, usually a derivation. Using `pkgs.foo.override` will call the same function with the given new arguments.
···
Example usages:
```nix
+
{
+
helloBar = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: {
+
pname = previousAttrs.pname + "-bar";
+
});
+
}
```
In the above example, "-bar" is appended to the pname attribute, while all other attributes will be retained from the original `hello` package.
···
Function arguments can be omitted entirely if there is no need to access `previousAttrs` or `finalAttrs`.
```nix
+
{
+
helloWithDebug = pkgs.hello.overrideAttrs {
+
separateDebugInfo = true;
+
};
+
}
```
In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`.
···
Example usage:
```nix
+
{
+
mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
+
name = "sed-4.2.2-pre";
+
src = fetchurl {
+
url = "ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2";
+
hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";
+
};
+
patches = [];
+
});
+
}
```
In the above example, the `name`, `src`, and `patches` of the derivation will be overridden, while all other attributes will be retained from the original derivation.
···
Example usage:
```nix
+
{
+
f = { a, b }: { result = a+b; };
+
c = lib.makeOverridable f { a = 1; b = 2; };
+
}
```
The variable `c` is the value of the `f` function applied with some default arguments. Hence the value of `c.result` is `3`, in this example.
+4 -4
maintainers/README.md
···
keys = [{
fingerprint = "0000 0000 2A70 6423 0AED 3C11 F04F 7A19 AAA6 3AFE";
}];
-
}
-
};
```
First receive their key from a keyserver:
···
name = "Example User";
github = "ghost";
githubId = 10137;
-
}
-
};
```
First, make sure that the listed GitHub handle matches the author of
···
keys = [{
fingerprint = "0000 0000 2A70 6423 0AED 3C11 F04F 7A19 AAA6 3AFE";
}];
+
};
+
}
```
First receive their key from a keyserver:
···
name = "Example User";
github = "ghost";
githubId = 10137;
+
};
+
}
```
First, make sure that the listed GitHub handle matches the author of
+4 -2
nixos/doc/manual/administration/cleaning-store.chapter.md
···
at certain points in time, for instance, every night at 03:15:
```nix
-
nix.gc.automatic = true;
-
nix.gc.dates = "03:15";
```
The commands above do not remove garbage collector roots, such as old
···
at certain points in time, for instance, every night at 03:15:
```nix
+
{
+
nix.gc.automatic = true;
+
nix.gc.dates = "03:15";
+
}
```
The commands above do not remove garbage collector roots, such as old
+8 -4
nixos/doc/manual/administration/container-networking.section.md
···
can be accomplished using the following configuration on the host:
```nix
-
networking.nat.enable = true;
-
networking.nat.internalInterfaces = ["ve-+"];
-
networking.nat.externalInterface = "eth0";
```
where `eth0` should be replaced with the desired external interface.
···
managing container interfaces:
```nix
-
networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
```
You may need to restart your system for the changes to take effect.
···
can be accomplished using the following configuration on the host:
```nix
+
{
+
networking.nat.enable = true;
+
networking.nat.internalInterfaces = ["ve-+"];
+
networking.nat.externalInterface = "eth0";
+
}
```
where `eth0` should be replaced with the desired external interface.
···
managing container interfaces:
```nix
+
{
+
networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
+
}
```
You may need to restart your system for the changes to take effect.
+6 -2
nixos/doc/manual/administration/control-groups.chapter.md
···
`configuration.nix`:
```nix
-
systemd.services.httpd.serviceConfig.CPUShares = 512;
```
By default, every cgroup has 1024 CPU shares, so this will halve the CPU
···
`httpd.service` to 512 MiB of RAM (excluding swap):
```nix
-
systemd.services.httpd.serviceConfig.MemoryLimit = "512M";
```
The command `systemd-cgtop` shows a continuously updated list of all
···
`configuration.nix`:
```nix
+
{
+
systemd.services.httpd.serviceConfig.CPUShares = 512;
+
}
```
By default, every cgroup has 1024 CPU shares, so this will halve the CPU
···
`httpd.service` to 512 MiB of RAM (excluding swap):
```nix
+
{
+
systemd.services.httpd.serviceConfig.MemoryLimit = "512M";
+
}
```
The command `systemd-cgtop` shows a continuously updated list of all
+16 -12
nixos/doc/manual/administration/declarative-containers.section.md
···
shall be a container named `database` running PostgreSQL:
```nix
-
containers.database =
-
{ config =
-
{ config, pkgs, ... }:
-
{ services.postgresql.enable = true;
-
services.postgresql.package = pkgs.postgresql_14;
-
};
-
};
```
If you run `nixos-rebuild switch`, the container will be built. If the
···
own network as follows:
```nix
-
containers.database = {
-
privateNetwork = true;
-
hostAddress = "192.168.100.10";
-
localAddress = "192.168.100.11";
-
};
```
This gives the container a private virtual Ethernet interface with IP
···
shall be a container named `database` running PostgreSQL:
```nix
+
{
+
containers.database =
+
{ config =
+
{ config, pkgs, ... }:
+
{ services.postgresql.enable = true;
+
services.postgresql.package = pkgs.postgresql_14;
+
};
+
};
+
}
```
If you run `nixos-rebuild switch`, the container will be built. If the
···
own network as follows:
```nix
+
{
+
containers.database = {
+
privateNetwork = true;
+
hostAddress = "192.168.100.10";
+
localAddress = "192.168.100.11";
+
};
+
}
```
This gives the container a private virtual Ethernet interface with IP
+3 -1
nixos/doc/manual/administration/service-mgmt.chapter.md
···
package, use (e.g):
```nix
-
systemd.packages = [ pkgs.packagekit ];
```
Usually NixOS modules written by the community do the above, plus take
···
package, use (e.g):
```nix
+
{
+
systemd.packages = [ pkgs.packagekit ];
+
}
```
Usually NixOS modules written by the community do the above, plus take
+3 -3
nixos/doc/manual/configuration/abstractions.section.md
···
```nix
{
services.httpd.virtualHosts =
-
let commonConfig = ...; in
-
{ "blog.example.org" = (commonConfig // { ... })
-
"wiki.example.org" = (commonConfig // { ... })
};
}
```
···
```nix
{
services.httpd.virtualHosts =
+
let commonConfig = { /* ... */ }; in
+
{ "blog.example.org" = (commonConfig // { /* ... */ });
+
"wiki.example.org" = (commonConfig // { /* ... */ });
};
}
```
+6 -4
nixos/doc/manual/configuration/ad-hoc-network-config.section.md
···
modules. For instance, to statically configure an IPv6 address:
```nix
-
networking.localCommands =
-
''
-
ip -6 addr add 2001:610:685:1::1/64 dev eth0
-
'';
```
···
modules. For instance, to statically configure an IPv6 address:
```nix
+
{
+
networking.localCommands =
+
''
+
ip -6 addr add 2001:610:685:1::1/64 dev eth0
+
'';
+
}
```
+21 -13
nixos/doc/manual/configuration/adding-custom-packages.section.md
···
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:
···
`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:
···
First you need to install `appimage-run`: add to `/etc/nixos/configuration.nix`
```nix
-
environment.systemPackages = [ pkgs.appimage-run ];
```
Then instead of running the AppImage "as-is", run `appimage-run foo.appimage`.
···
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:
···
`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:
···
First you need to install `appimage-run`: add to `/etc/nixos/configuration.nix`
```nix
+
{
+
environment.systemPackages = [ pkgs.appimage-run ];
+
}
```
Then instead of running the AppImage "as-is", run `appimage-run foo.appimage`.
+38 -22
nixos/doc/manual/configuration/config-file.section.md
···
```nix
{ config, pkgs, ... }:
-
{ option definitions
}
```
···
: Strings are enclosed in double quotes, e.g.
```nix
-
networking.hostName = "dexter";
```
Special characters can be escaped by prefixing them with a backslash
···
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
···
: 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
···
braces, as in the option definition
```nix
-
fileSystems."/boot" =
-
{ device = "/dev/sda1";
-
fsType = "ext4";
-
options = [ "rw" "data=ordered" "relatime" ];
-
};
```
Lists
···
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
···
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
···
```nix
{ config, pkgs, ... }:
+
{ /* option definitions */
}
```
···
: Strings are enclosed in double quotes, e.g.
```nix
+
{
+
networking.hostName = "dexter";
+
}
```
Special characters can be escaped by prefixing them with a backslash
···
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
···
: 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
···
braces, as in the option definition
```nix
+
{
+
fileSystems."/boot" =
+
{ device = "/dev/sda1";
+
fsType = "ext4";
+
options = [ "rw" "data=ordered" "relatime" ];
+
};
+
}
```
Lists
···
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
···
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
+30 -22
nixos/doc/manual/configuration/customizing-packages.section.md
···
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
-
];
```
:::
···
specify that as follows:
```nix
-
environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
```
The function `override` performs the call to the Nix function that
···
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`
···
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
···
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
+
];
+
}
```
:::
···
specify that as follows:
```nix
+
{
+
environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+
}
```
The function `override` performs the call to the Nix function that
···
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`
···
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
+3 -1
nixos/doc/manual/configuration/declarative-packages.section.md
···
email application:
```nix
-
environment.systemPackages = [ pkgs.thunderbird ];
```
The effect of this specification is that the Thunderbird package from
···
email application:
```nix
+
{
+
environment.systemPackages = [ pkgs.thunderbird ];
+
}
```
The effect of this specification is that the Thunderbird package from
+6 -4
nixos/doc/manual/configuration/file-systems.chapter.md
···
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
···
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
+12 -6
nixos/doc/manual/configuration/firewall.section.md
···
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
···
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
···
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
···
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
+34 -24
nixos/doc/manual/configuration/gpu-accel.chapter.md
···
enables OpenCL support:
```nix
-
hardware.opengl.extraPackages = [
-
rocmPackages.clr.icd
-
];
```
### Intel {#sec-gpu-accel-opencl-intel}
···
configuration can be used:
```nix
-
hardware.opengl.extraPackages = [
-
intel-compute-runtime
-
];
```
## Vulkan {#sec-gpu-accel-vulkan}
···
A specific driver can be forced as follows:
```nix
-
hardware.opengl.extraPackages = [
-
pkgs.amdvlk
-
];
-
# To enable Vulkan support for 32-bit applications, also add:
-
hardware.opengl.extraPackages32 = [
-
pkgs.driversi686Linux.amdvlk
-
];
-
# Force radv
-
environment.variables.AMD_VULKAN_ICD = "RADV";
-
# Or
-
environment.variables.VK_ICD_FILENAMES =
-
"/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";
```
## VA-API {#sec-gpu-accel-va-api}
···
Modern Intel GPUs use the iHD driver, which can be installed with:
```nix
-
hardware.opengl.extraPackages = [
-
intel-media-driver
-
];
```
Older Intel GPUs use the i965 driver, which can be installed with:
```nix
-
hardware.opengl.extraPackages = [
-
intel-vaapi-driver
-
];
```
## Common issues {#sec-gpu-accel-common-issues}
···
enables OpenCL support:
```nix
+
{
+
hardware.opengl.extraPackages = [
+
rocmPackages.clr.icd
+
];
+
}
```
### Intel {#sec-gpu-accel-opencl-intel}
···
configuration can be used:
```nix
+
{
+
hardware.opengl.extraPackages = [
+
intel-compute-runtime
+
];
+
}
```
## Vulkan {#sec-gpu-accel-vulkan}
···
A specific driver can be forced as follows:
```nix
+
{
+
hardware.opengl.extraPackages = [
+
pkgs.amdvlk
+
];
+
# To enable Vulkan support for 32-bit applications, also add:
+
hardware.opengl.extraPackages32 = [
+
pkgs.driversi686Linux.amdvlk
+
];
+
# Force radv
+
environment.variables.AMD_VULKAN_ICD = "RADV";
+
# Or
+
environment.variables.VK_ICD_FILENAMES =
+
"/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";
+
}
```
## VA-API {#sec-gpu-accel-va-api}
···
Modern Intel GPUs use the iHD driver, which can be installed with:
```nix
+
{
+
hardware.opengl.extraPackages = [
+
intel-media-driver
+
];
+
}
```
Older Intel GPUs use the i965 driver, which can be installed with:
```nix
+
{
+
hardware.opengl.extraPackages = [
+
intel-vaapi-driver
+
];
+
}
```
## Common issues {#sec-gpu-accel-common-issues}
+13 -7
nixos/doc/manual/configuration/ipv4-config.section.md
···
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}
···
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
···
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}
···
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
+18 -10
nixos/doc/manual/configuration/ipv6-config.section.md
···
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.
···
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.
+19 -11
nixos/doc/manual/configuration/kubernetes.chapter.md
···
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
···
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
···
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
···
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
+34 -20
nixos/doc/manual/configuration/linux-kernel.chapter.md
···
kernel:
```nix
-
boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10;
```
Note that this not only replaces the kernel, but also packages that are
···
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
···
[](#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
···
[](#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
···
To use your custom kernel package in your NixOS configuration, set
```nix
-
boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel;
```
## Rust {#sec-linux-rust}
···
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}
···
kernel:
```nix
+
{
+
boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10;
+
}
```
Note that this not only replaces the kernel, but also packages that are
···
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
···
[](#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
···
[](#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
···
To use your custom kernel package in your NixOS configuration, set
```nix
+
{
+
boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel;
+
}
```
## Rust {#sec-linux-rust}
···
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}
+22 -12
nixos/doc/manual/configuration/luks-file-systems.section.md
···
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}
···
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,
···
as [Trezor](https://trezor.io/).
```nix
-
boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = true;
```
### systemd Stage 1 {#sec-luks-file-systems-fido2-systemd}
···
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
···
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}
···
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,
···
as [Trezor](https://trezor.io/).
```nix
+
{
+
boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = true;
+
}
```
### systemd Stage 1 {#sec-luks-file-systems-fido2-systemd}
···
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
+7 -3
nixos/doc/manual/configuration/modularity.section.md
···
{ imports = [ ./vpn.nix ./kde.nix ];
services.httpd.enable = true;
environment.systemPackages = [ pkgs.emacs ];
-
...
}
```
···
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
···
over the others:
```nix
-
services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";
```
When using multiple modules, you may need to access configuration values
···
{ imports = [ ./vpn.nix ./kde.nix ];
services.httpd.enable = true;
environment.systemPackages = [ pkgs.emacs ];
+
# ...
}
```
···
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
···
over the others:
```nix
+
{
+
services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";
+
}
```
When using multiple modules, you may need to access configuration values
+11 -5
nixos/doc/manual/configuration/network-manager.section.md
···
NetworkManager. You can enable NetworkManager by setting:
```nix
-
networking.networkmanager.enable = true;
```
some desktop managers (e.g., GNOME) enable NetworkManager automatically
···
belong to the `networkmanager` group:
```nix
-
users.users.alice.extraGroups = [ "networkmanager" ];
```
NetworkManager is controlled using either `nmcli` or `nmtui`
···
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
···
NetworkManager. You can enable NetworkManager by setting:
```nix
+
{
+
networking.networkmanager.enable = true;
+
}
```
some desktop managers (e.g., GNOME) enable NetworkManager automatically
···
belong to the `networkmanager` group:
```nix
+
{
+
users.users.alice.extraGroups = [ "networkmanager" ];
+
}
```
NetworkManager is controlled using either `nmcli` or `nmtui`
···
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
+15 -13
nixos/doc/manual/configuration/overlayfs.section.md
···
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
···
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
+5 -3
nixos/doc/manual/configuration/profiles.chapter.md
···
`/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
···
`/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
+12 -8
nixos/doc/manual/configuration/renaming-interfaces.section.md
···
`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
···
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}
···
`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
···
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}
+7 -3
nixos/doc/manual/configuration/ssh.section.md
···
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
···
as follows:
```nix
-
users.users.alice.openssh.authorizedKeys.keys =
-
[ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
```
···
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
···
as follows:
```nix
+
{
+
users.users.alice.openssh.authorizedKeys.keys =
+
[ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
+
}
```
+28 -23
nixos/doc/manual/configuration/subversion.chapter.md
···
appropriately:
```nix
-
services.httpd.enable = true;
-
services.httpd.adminAddr = ...;
-
networking.firewall.allowedTCPPorts = [ 80 443 ];
```
For a simple Subversion server with basic authentication, configure the
···
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 file describing access permissions `ACCESS_FILE` will look something
like the following:
-
```nix
[/]
* = r
···
appropriately:
```nix
+
{
+
services.httpd.enable = true;
+
services.httpd.adminAddr = "...";
+
networking.firewall.allowedTCPPorts = [ 80 443 ];
+
}
```
For a simple Subversion server with basic authentication, configure the
···
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 file describing access permissions `ACCESS_FILE` will look something
like the following:
+
```
[/]
* = r
+18 -10
nixos/doc/manual/configuration/user-mgmt.chapter.md
···
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`
···
manually by adding
```nix
-
uid = 1000;
```
to the user specification.
···
named `students` shall exist:
```nix
-
users.groups.students.gid = 1000;
```
As with users, the group ID (gid) is optional and will be assigned
···
systemd-sysusers:
```nix
-
systemd.sysusers.enable = true;
```
The primary benefit of this is to remove a dependency on perl.
···
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`
···
manually by adding
```nix
+
{
+
uid = 1000;
+
}
```
to the user specification.
···
named `students` shall exist:
```nix
+
{
+
users.groups.students.gid = 1000;
+
}
```
As with users, the group ID (gid) is optional and will be assigned
···
systemd-sysusers:
```nix
+
{
+
systemd.sysusers.enable = true;
+
}
```
The primary benefit of this is to remove a dependency on perl.
+5 -1
nixos/doc/manual/configuration/wayland.chapter.md
···
server:
```nix
programs.sway.enable = true;
```
This installs the sway compositor along with some essential utilities.
···
able to share your screen, you might want to activate this option:
```nix
-
xdg.portal.wlr.enable = true;
```
and configure Pipewire using
···
server:
```nix
+
{
programs.sway.enable = true;
+
}
```
This installs the sway compositor along with some essential utilities.
···
able to share your screen, you might want to activate this option:
```nix
+
{
+
xdg.portal.wlr.enable = true;
+
}
```
and configure Pipewire using
+23 -17
nixos/doc/manual/configuration/wireless.section.md
···
NixOS will start wpa_supplicant for you if you enable this setting:
```nix
-
networking.wireless.enable = true;
```
NixOS lets you specify networks for wpa_supplicant declaratively:
```nix
-
networking.wireless.networks = {
-
echelon = { # SSID with no spaces or special characters
-
psk = "abcdefgh";
-
};
-
"echelon's AP" = { # SSID with spaces and/or special characters
-
psk = "ijklmnop";
-
};
-
echelon = { # Hidden SSID
-
hidden = true;
-
psk = "qrstuvwx";
};
-
free.wifi = {}; # Public wireless network
-
};
```
Be aware that keys will be written to the nix store in plaintext! When
···
```
```nix
-
networking.wireless.networks = {
-
echelon = {
-
pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
};
-
};
```
or you can use it to directly generate the `wpa_supplicant.conf`:
···
NixOS will start wpa_supplicant for you if you enable this setting:
```nix
+
{
+
networking.wireless.enable = true;
+
}
```
NixOS lets you specify networks for wpa_supplicant declaratively:
```nix
+
{
+
networking.wireless.networks = {
+
echelon = { # SSID with no spaces or special characters
+
psk = "abcdefgh";
+
};
+
"echelon's AP" = { # SSID with spaces and/or special characters
+
psk = "ijklmnop";
+
};
+
echelon = { # Hidden SSID
+
hidden = true;
+
psk = "qrstuvwx";
+
};
+
free.wifi = {}; # Public wireless network
};
+
}
```
Be aware that keys will be written to the nix store in plaintext! When
···
```
```nix
+
{
+
networking.wireless.networks = {
+
echelon = {
+
pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
+
};
};
+
}
```
or you can use it to directly generate the `wpa_supplicant.conf`:
+92 -52
nixos/doc/manual/configuration/x-windows.chapter.md
···
interface. It can be enabled as follows:
```nix
-
services.xserver.enable = true;
```
The X server will automatically detect and use the appropriate video
···
also specify a driver manually, e.g.
```nix
-
services.xserver.videoDrivers = [ "r128" ];
```
to enable X.org's `xf86-video-r128` driver.
···
Thus you should pick one or more of the following lines:
```nix
-
services.xserver.desktopManager.plasma5.enable = true;
-
services.xserver.desktopManager.xfce.enable = true;
-
services.xserver.desktopManager.gnome.enable = true;
-
services.xserver.desktopManager.mate.enable = true;
-
services.xserver.windowManager.xmonad.enable = true;
-
services.xserver.windowManager.twm.enable = true;
-
services.xserver.windowManager.icewm.enable = true;
-
services.xserver.windowManager.i3.enable = true;
-
services.xserver.windowManager.herbstluftwm.enable = true;
```
NixOS's default *display manager* (the program that provides a graphical
···
alternative one by picking one of the following lines:
```nix
-
services.xserver.displayManager.sddm.enable = true;
-
services.xserver.displayManager.gdm.enable = true;
```
You can set the keyboard layout (and optionally the layout variant):
```nix
-
services.xserver.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:
···
Wine, you should also set the following:
```nix
-
hardware.opengl.driSupport32Bit = true;
```
## Auto-login {#sec-x11-auto-login}
···
your window manager, you'd define:
```nix
-
services.xserver.displayManager.defaultSession = "none+i3";
```
Every display manager in NixOS supports auto-login, here is an example
using lightdm for a user `alice`:
```nix
-
services.xserver.displayManager.lightdm.enable = true;
-
services.xserver.displayManager.autoLogin.enable = true;
-
services.xserver.displayManager.autoLogin.user = "alice";
```
## Intel Graphics drivers {#sec-x11--graphics-cards-intel}
···
to set one. The recommended configuration for modern systems is:
```nix
-
services.xserver.videoDrivers = [ "modesetting" ];
```
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
···
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
···
set:
```nix
-
services.xserver.videoDrivers = [ "amdgpu-pro" ];
```
You will need to reboot after enabling this driver to prevent a clash
···
Latitude series) can be enabled as follows:
```nix
-
services.xserver.libinput.enable = true;
```
The driver has many options (see [](#ch-options)).
For instance, the following disables tap-to-click behavior:
```nix
-
services.xserver.libinput.touchpad.tapping = false;
```
Note: the use of `services.xserver.synaptics` is deprecated since NixOS
···
GTK ones, you can use the following configuration:
```nix
-
qt.enable = true;
-
qt.platformTheme = "gtk2";
-
qt.style = "gtk2";
```
## Custom XKB layouts {#custom-xkb-layouts}
···
directory called `symbols`; it's an XKB peculiarity that will help with
testing):
-
```nix
xkb_symbols "us-greek"
{
include "us(basic)" // includes the base US keys
···
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}
···
of interest, then create a `media-key` file to hold the keycodes
definitions
-
```nix
xkb_keycodes "media"
{
<volUp> = 123;
···
Now use the newly define keycodes in `media-sym`:
-
```nix
xkb_symbols "media"
{
key.type = "ONE_LEVEL";
···
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}
···
session with:
```nix
-
services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
```
If you are manually starting the X server, you should set the argument
···
interface. It can be enabled as follows:
```nix
+
{
+
services.xserver.enable = true;
+
}
```
The X server will automatically detect and use the appropriate video
···
also specify a driver manually, e.g.
```nix
+
{
+
services.xserver.videoDrivers = [ "r128" ];
+
}
```
to enable X.org's `xf86-video-r128` driver.
···
Thus you should pick one or more of the following lines:
```nix
+
{
+
services.xserver.desktopManager.plasma5.enable = true;
+
services.xserver.desktopManager.xfce.enable = true;
+
services.xserver.desktopManager.gnome.enable = true;
+
services.xserver.desktopManager.mate.enable = true;
+
services.xserver.windowManager.xmonad.enable = true;
+
services.xserver.windowManager.twm.enable = true;
+
services.xserver.windowManager.icewm.enable = true;
+
services.xserver.windowManager.i3.enable = true;
+
services.xserver.windowManager.herbstluftwm.enable = true;
+
}
```
NixOS's default *display manager* (the program that provides a graphical
···
alternative one by picking one of the following lines:
```nix
+
{
+
services.xserver.displayManager.sddm.enable = true;
+
services.xserver.displayManager.gdm.enable = true;
+
}
```
You can set the keyboard layout (and optionally the layout variant):
```nix
+
{
+
services.xserver.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:
···
Wine, you should also set the following:
```nix
+
{
+
hardware.opengl.driSupport32Bit = true;
+
}
```
## Auto-login {#sec-x11-auto-login}
···
your window manager, you'd define:
```nix
+
{
+
services.xserver.displayManager.defaultSession = "none+i3";
+
}
```
Every display manager in NixOS supports auto-login, here is an example
using lightdm for a user `alice`:
```nix
+
{
+
services.xserver.displayManager.lightdm.enable = true;
+
services.xserver.displayManager.autoLogin.enable = true;
+
services.xserver.displayManager.autoLogin.user = "alice";
+
}
```
## Intel Graphics drivers {#sec-x11--graphics-cards-intel}
···
to set one. The recommended configuration for modern systems is:
```nix
+
{
+
services.xserver.videoDrivers = [ "modesetting" ];
+
}
```
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
···
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
···
set:
```nix
+
{
+
services.xserver.videoDrivers = [ "amdgpu-pro" ];
+
}
```
You will need to reboot after enabling this driver to prevent a clash
···
Latitude series) can be enabled as follows:
```nix
+
{
+
services.xserver.libinput.enable = true;
+
}
```
The driver has many options (see [](#ch-options)).
For instance, the following disables tap-to-click behavior:
```nix
+
{
+
services.xserver.libinput.touchpad.tapping = false;
+
}
```
Note: the use of `services.xserver.synaptics` is deprecated since NixOS
···
GTK ones, you can use the following configuration:
```nix
+
{
+
qt.enable = true;
+
qt.platformTheme = "gtk2";
+
qt.style = "gtk2";
+
}
```
## Custom XKB layouts {#custom-xkb-layouts}
···
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
···
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}
···
of interest, then create a `media-key` file to hold the keycodes
definitions
+
```
xkb_keycodes "media"
{
<volUp> = 123;
···
Now use the newly define keycodes in `media-sym`:
+
```
xkb_symbols "media"
{
key.type = "ONE_LEVEL";
···
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}
···
session with:
```nix
+
{
+
services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
+
}
```
If you are manually starting the X server, you should set the argument
+13 -9
nixos/doc/manual/configuration/xfce.chapter.md
···
To enable the Xfce Desktop Environment, set
```nix
-
services.xserver.desktopManager.xfce.enable = true;
-
services.xserver.displayManager.defaultSession = "xfce";
```
Optionally, *picom* can be enabled for nice graphical effects, some
example settings:
```nix
-
services.picom = {
-
enable = true;
-
fade = true;
-
inactiveOpacity = 0.9;
-
shadow = true;
-
fadeDelta = 4;
-
};
```
Some Xfce programs are not installed automatically. To install them
···
To enable the Xfce Desktop Environment, set
```nix
+
{
+
services.xserver.desktopManager.xfce.enable = true;
+
services.xserver.displayManager.defaultSession = "xfce";
+
}
```
Optionally, *picom* can be enabled for nice graphical effects, some
example settings:
```nix
+
{
+
services.picom = {
+
enable = true;
+
fade = true;
+
inactiveOpacity = 0.9;
+
shadow = true;
+
fadeDelta = 4;
+
};
+
}
```
Some Xfce programs are not installed automatically. To install them
+9 -7
nixos/doc/manual/development/activation-script.section.md
···
snippets accordingly. As a simple example:
```nix
-
system.activationScripts.my-activation-script = {
-
deps = [ "etc" ];
-
# supportsDryActivation = true;
-
text = ''
-
echo "Hallo i bims"
-
'';
-
};
```
This example creates an activation script snippet that is run after the `etc`
···
snippets accordingly. As a simple example:
```nix
+
{
+
system.activationScripts.my-activation-script = {
+
deps = [ "etc" ];
+
# supportsDryActivation = true;
+
text = ''
+
echo "Hallo i bims"
+
'';
+
};
+
}
```
This example creates an activation script snippet that is run after the `etc`
+2 -2
nixos/doc/manual/development/assertions.section.md
···
This is known to cause some specific problems in certain situations.
'' ]
else [];
-
}
}
```
···
message = "rsyslogd conflicts with syslogd";
}
];
-
}
}
```
···
This is known to cause some specific problems in certain situations.
'' ]
else [];
+
};
}
```
···
message = "rsyslogd conflicts with syslogd";
}
];
+
};
}
```
+6 -2
nixos/doc/manual/development/etc-overlay.section.md
···
overlay filesystem:
```nix
-
system.etc.overlay.enable = true;
```
Using an overlay has two benefits:
···
setting:
```nix
-
system.etc.overlay.mutable = false;
```
The overlay is atomically replaced during system switch. However, files that
···
overlay filesystem:
```nix
+
{
+
system.etc.overlay.enable = true;
+
}
```
Using an overlay has two benefits:
···
setting:
```nix
+
{
+
system.etc.overlay.mutable = false;
+
}
```
The overlay is atomically replaced during system switch. However, files that
+2 -2
nixos/doc/manual/development/meta-attributes.section.md
···
{ config, lib, pkgs, ... }:
{
options = {
-
...
};
config = {
-
...
};
meta = {
···
{ config, lib, pkgs, ... }:
{
options = {
+
# ...
};
config = {
+
# ...
};
meta = {
+1 -1
nixos/doc/manual/development/non-switchable-systems.section.md
···
```nix
{ modulesPath, ... }: {
-
imports = [ "${modulesPath}/profiles/image-based-appliance.nix" ]
}
```
···
```nix
{ modulesPath, ... }: {
+
imports = [ "${modulesPath}/profiles/image-based-appliance.nix" ];
}
```
+25 -17
nixos/doc/manual/development/option-declarations.section.md
···
looks like this:
```nix
-
options = {
-
name = mkOption {
-
type = type specification;
-
default = default value;
-
example = example value;
-
description = lib.mdDoc "Description for use in the NixOS manual.";
};
-
};
```
The attribute names within the `name` attribute path must be camel
···
::: {#ex-option-declaration-eot-service .example}
### Extensible type placeholder in the service module
```nix
-
services.xserver.displayManager.enable = mkOption {
-
description = "Display manager to use";
-
type = with types; nullOr (enum [ ]);
-
};
```
:::
::: {#ex-option-declaration-eot-backend-gdm .example}
### Extending `services.xserver.displayManager.enable` in the `gdm` module
```nix
-
services.xserver.displayManager.enable = mkOption {
-
type = with types; nullOr (enum [ "gdm" ]);
-
};
```
:::
::: {#ex-option-declaration-eot-backend-sddm .example}
### Extending `services.xserver.displayManager.enable` in the `sddm` module
```nix
-
services.xserver.displayManager.enable = mkOption {
-
type = with types; nullOr (enum [ "sddm" ]);
-
};
```
:::
···
looks like this:
```nix
+
{
+
options = {
+
name = mkOption {
+
type = type specification;
+
default = default value;
+
example = example value;
+
description = lib.mdDoc "Description for use in the NixOS manual.";
+
};
};
+
}
```
The attribute names within the `name` attribute path must be camel
···
::: {#ex-option-declaration-eot-service .example}
### Extensible type placeholder in the service module
```nix
+
{
+
services.xserver.displayManager.enable = mkOption {
+
description = "Display manager to use";
+
type = with types; nullOr (enum [ ]);
+
};
+
}
```
:::
::: {#ex-option-declaration-eot-backend-gdm .example}
### Extending `services.xserver.displayManager.enable` in the `gdm` module
```nix
+
{
+
services.xserver.displayManager.enable = mkOption {
+
type = with types; nullOr (enum [ "gdm" ]);
+
};
+
}
```
:::
::: {#ex-option-declaration-eot-backend-sddm .example}
### Extending `services.xserver.displayManager.enable` in the `sddm` module
```nix
+
{
+
services.xserver.displayManager.enable = mkOption {
+
type = with types; nullOr (enum [ "sddm" ]);
+
};
+
}
```
:::
+47 -31
nixos/doc/manual/development/option-def.section.md
···
option names, like
```nix
-
config = {
-
services.httpd.enable = true;
-
};
```
However, sometimes you need to wrap an option definition or set of
···
option, you may need to use `mkIf`. Consider, for instance:
```nix
-
config = if config.services.httpd.enable then {
-
environment.systemPackages = [ ... ];
-
...
-
} else {};
```
This definition will cause Nix to fail with an "infinite recursion"
···
clearly circular and contradictory:
```nix
-
config = if config.services.httpd.enable then {
-
services.httpd.enable = false;
-
} else {
-
services.httpd.enable = true;
-
};
```
The solution is to write:
```nix
-
config = mkIf config.services.httpd.enable {
-
environment.systemPackages = [ ... ];
-
...
-
};
```
The special function `mkIf` causes the evaluation of the conditional to
be "pushed down" into the individual definitions, as if you had written:
```nix
-
config = {
-
environment.systemPackages = if config.services.httpd.enable then [ ... ] else [];
-
...
-
};
```
## Setting Priorities {#sec-option-definitions-setting-priorities}
···
You can specify an explicit priority by using `mkOverride`, e.g.
```nix
-
services.openssh.enable = mkOverride 10 false;
```
This definition causes all other definitions with priorities above 10 to
···
As an example,
```nix
-
hardware.firmware = mkBefore [ myFirmware ];
```
This definition ensures that `myFirmware` comes before other unordered
···
`mkMerge`:
```nix
-
config = mkMerge
-
[ # Unconditional stuff.
-
{ environment.systemPackages = [ ... ];
-
}
-
# Conditional stuff.
-
(mkIf config.services.bla.enable {
-
environment.systemPackages = [ ... ];
-
})
-
];
```
···
option names, like
```nix
+
{
+
config = {
+
services.httpd.enable = true;
+
};
+
}
```
However, sometimes you need to wrap an option definition or set of
···
option, you may need to use `mkIf`. Consider, for instance:
```nix
+
{
+
config = if config.services.httpd.enable then {
+
environment.systemPackages = [ /* ... */ ];
+
# ...
+
} else {};
+
}
```
This definition will cause Nix to fail with an "infinite recursion"
···
clearly circular and contradictory:
```nix
+
{
+
config = if config.services.httpd.enable then {
+
services.httpd.enable = false;
+
} else {
+
services.httpd.enable = true;
+
};
+
}
```
The solution is to write:
```nix
+
{
+
config = mkIf config.services.httpd.enable {
+
environment.systemPackages = [ /* ... */ ];
+
# ...
+
};
+
}
```
The special function `mkIf` causes the evaluation of the conditional to
be "pushed down" into the individual definitions, as if you had written:
```nix
+
{
+
config = {
+
environment.systemPackages = if config.services.httpd.enable then [ /* ... */ ] else [];
+
# ...
+
};
+
}
```
## Setting Priorities {#sec-option-definitions-setting-priorities}
···
You can specify an explicit priority by using `mkOverride`, e.g.
```nix
+
{
+
services.openssh.enable = mkOverride 10 false;
+
}
```
This definition causes all other definitions with priorities above 10 to
···
As an example,
```nix
+
{
+
hardware.firmware = mkBefore [ myFirmware ];
+
}
```
This definition ensures that `myFirmware` comes before other unordered
···
`mkMerge`:
```nix
+
{
+
config = mkMerge
+
[ # Unconditional stuff.
+
{ environment.systemPackages = [ /* ... */ ];
+
}
+
# Conditional stuff.
+
(mkIf config.services.bla.enable {
+
environment.systemPackages = [ /* ... */ ];
+
})
+
];
+
}
```
+69 -53
nixos/doc/manual/development/option-types.section.md
···
::: {#ex-submodule-direct .example}
### Directly defined submodule
```nix
-
options.mod = mkOption {
-
description = "submodule example";
-
type = with types; submodule {
-
options = {
-
foo = mkOption {
-
type = int;
-
};
-
bar = mkOption {
-
type = str;
};
};
};
-
};
```
:::
···
};
};
in
-
options.mod = mkOption {
-
description = "submodule example";
-
type = with types; submodule modOptions;
-
};
```
:::
···
::: {#ex-submodule-listof-declaration .example}
### Declaration of a list of submodules
```nix
-
options.mod = mkOption {
-
description = "submodule example";
-
type = with types; listOf (submodule {
-
options = {
-
foo = mkOption {
-
type = int;
-
};
-
bar = mkOption {
-
type = str;
};
-
};
-
});
-
};
```
:::
::: {#ex-submodule-listof-definition .example}
### Definition of a list of submodules
```nix
-
config.mod = [
-
{ foo = 1; bar = "one"; }
-
{ foo = 2; bar = "two"; }
-
];
```
:::
···
::: {#ex-submodule-attrsof-declaration .example}
### Declaration of attribute sets of submodules
```nix
-
options.mod = mkOption {
-
description = "submodule example";
-
type = with types; attrsOf (submodule {
-
options = {
-
foo = mkOption {
-
type = int;
};
-
bar = mkOption {
-
type = str;
-
};
-
};
-
});
-
};
```
:::
::: {#ex-submodule-attrsof-definition .example}
### Definition of attribute sets of submodules
```nix
-
config.mod.one = { foo = 1; bar = "one"; };
-
config.mod.two = { foo = 2; bar = "two"; };
```
:::
···
### Adding a type check
```nix
-
byte = mkOption {
-
description = "An integer between 0 and 255.";
-
type = types.addCheck types.int (x: x >= 0 && x <= 255);
-
};
```
:::
···
### Overriding a type check
```nix
-
nixThings = mkOption {
-
description = "words that start with 'nix'";
-
type = types.str // {
-
check = (x: lib.hasPrefix "nix" x)
};
-
};
```
:::
···
::: {#ex-submodule-direct .example}
### Directly defined submodule
```nix
+
{
+
options.mod = mkOption {
+
description = "submodule example";
+
type = with types; submodule {
+
options = {
+
foo = mkOption {
+
type = int;
+
};
+
bar = mkOption {
+
type = str;
+
};
};
};
};
+
}
```
:::
···
};
};
in
+
{
+
options.mod = mkOption {
+
description = "submodule example";
+
type = with types; submodule modOptions;
+
};
+
}
```
:::
···
::: {#ex-submodule-listof-declaration .example}
### Declaration of a list of submodules
```nix
+
{
+
options.mod = mkOption {
+
description = "submodule example";
+
type = with types; listOf (submodule {
+
options = {
+
foo = mkOption {
+
type = int;
+
};
+
bar = mkOption {
+
type = str;
+
};
};
+
});
+
};
+
}
```
:::
::: {#ex-submodule-listof-definition .example}
### Definition of a list of submodules
```nix
+
{
+
config.mod = [
+
{ foo = 1; bar = "one"; }
+
{ foo = 2; bar = "two"; }
+
];
+
}
```
:::
···
::: {#ex-submodule-attrsof-declaration .example}
### Declaration of attribute sets of submodules
```nix
+
{
+
options.mod = mkOption {
+
description = "submodule example";
+
type = with types; attrsOf (submodule {
+
options = {
+
foo = mkOption {
+
type = int;
+
};
+
bar = mkOption {
+
type = str;
+
};
};
+
});
+
};
+
}
```
:::
::: {#ex-submodule-attrsof-definition .example}
### Definition of attribute sets of submodules
```nix
+
{
+
config.mod.one = { foo = 1; bar = "one"; };
+
config.mod.two = { foo = 2; bar = "two"; };
+
}
```
:::
···
### Adding a type check
```nix
+
{
+
byte = mkOption {
+
description = "An integer between 0 and 255.";
+
type = types.addCheck types.int (x: x >= 0 && x <= 255);
+
};
+
}
```
:::
···
### Overriding a type check
```nix
+
{
+
nixThings = mkOption {
+
description = "words that start with 'nix'";
+
type = types.str // {
+
check = (x: lib.hasPrefix "nix" x);
+
};
};
+
}
```
:::
+21 -19
nixos/doc/manual/development/settings-options.section.md
···
::: {#ex-settings-typed-attrs .example}
### Declaring a type-checked `settings` attribute
```nix
-
settings = lib.mkOption {
-
type = lib.types.submodule {
-
freeformType = settingsFormat.type;
-
# Declare an option for the port such that the type is checked and this option
-
# is shown in the manual.
-
options.port = lib.mkOption {
-
type = lib.types.port;
-
default = 8080;
-
description = ''
-
Which port this service should listen on.
-
'';
-
};
};
-
default = {};
-
description = ''
-
Configuration for Foo, see
-
<link xlink:href="https://example.com/docs/foo"/>
-
for supported values.
-
'';
-
};
```
:::
···
::: {#ex-settings-typed-attrs .example}
### Declaring a type-checked `settings` attribute
```nix
+
{
+
settings = lib.mkOption {
+
type = lib.types.submodule {
+
freeformType = settingsFormat.type;
+
# Declare an option for the port such that the type is checked and this option
+
# is shown in the manual.
+
options.port = lib.mkOption {
+
type = lib.types.port;
+
default = 8080;
+
description = ''
+
Which port this service should listen on.
+
'';
+
};
+
};
+
default = {};
+
description = ''
+
Configuration for Foo, see
+
<link xlink:href="https://example.com/docs/foo"/>
+
for supported values.
+
'';
};
+
}
```
:::
+7 -5
nixos/doc/manual/development/unit-handling.section.md
···
have to declare:
```nix
-
systemd.services.my-sysinit = {
-
requiredBy = [ "sysinit-reactivation.target" ];
-
before = [ "sysinit-reactivation.target" ];
-
restartTriggers = [ config.environment.etc."my-sysinit.d".source ];
-
};
```
You need to configure appropriate `restartTriggers` specific to your service.
···
have to declare:
```nix
+
{
+
systemd.services.my-sysinit = {
+
requiredBy = [ "sysinit-reactivation.target" ];
+
before = [ "sysinit-reactivation.target" ];
+
restartTriggers = [ config.environment.etc."my-sysinit.d".source ];
+
};
+
}
```
You need to configure appropriate `restartTriggers` specific to your service.
+4 -4
nixos/doc/manual/development/writing-modules.chapter.md
···
```nix
{ config, pkgs, ... }:
-
{ option definitions
}
```
···
{
imports =
-
[ paths of other modules
];
options = {
-
option declarations
};
config = {
-
option definitions
};
}
```
···
```nix
{ config, pkgs, ... }:
+
{ # option definitions
}
```
···
{
imports =
+
[ # paths of other modules
];
options = {
+
# option declarations
};
config = {
+
# option definitions
};
}
```
+11 -5
nixos/doc/manual/development/writing-nixos-tests.section.md
···
# One or more machines:
nodes =
{ machine =
-
{ config, pkgs, ... }: { … };
machine2 =
-
{ config, pkgs, ... }: { … };
-
};
testScript =
···
Tests that are part of NixOS are added to [`nixos/tests/all-tests.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/all-tests.nix).
```nix
hostname = runTest ./hostname.nix;
```
Overrides can be added by defining an anonymous module in `all-tests.nix`.
```nix
hostname = runTest {
imports = [ ./hostname.nix ];
defaults.networking.firewall.enable = false;
};
```
You can run a test with attribute name `hostname` in `nixos/tests/all-tests.nix` by invoking:
···
skipLint = true;
nodes.machine =
{ config, pkgs, ... }:
-
{ configuration…
};
testScript =
···
repository):
```nix
testScript =
''
# fmt: off
Python code…
# fmt: on
'';
```
Similarly, the type checking of test scripts can be disabled in the following
···
skipTypeCheck = true;
nodes.machine =
{ config, pkgs, ... }:
-
{ configuration…
};
}
```
···
# One or more machines:
nodes =
{ machine =
+
{ config, pkgs, ... }: { /* ... */ };
machine2 =
+
{ config, pkgs, ... }: { /* ... */ };
+
# …
};
testScript =
···
Tests that are part of NixOS are added to [`nixos/tests/all-tests.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/all-tests.nix).
```nix
+
{
hostname = runTest ./hostname.nix;
+
}
```
Overrides can be added by defining an anonymous module in `all-tests.nix`.
```nix
+
{
hostname = runTest {
imports = [ ./hostname.nix ];
defaults.networking.firewall.enable = false;
};
+
}
```
You can run a test with attribute name `hostname` in `nixos/tests/all-tests.nix` by invoking:
···
skipLint = true;
nodes.machine =
{ config, pkgs, ... }:
+
{ # configuration…
};
testScript =
···
repository):
```nix
+
{
testScript =
''
# fmt: off
Python code…
# fmt: on
'';
+
}
```
Similarly, the type checking of test scripts can be disabled in the following
···
skipTypeCheck = true;
nodes.machine =
{ config, pkgs, ... }:
+
{ # configuration…
};
}
```
+15 -13
nixos/doc/manual/installation/building-images-via-systemd-repart.chapter.md
···
partitions = {
"esp" = {
contents = {
-
...
};
repartConfig = {
Type = "esp";
-
...
};
};
"root" = {
···
repartConfig = {
Type = "root";
Label = "nixos";
-
...
};
};
};
···
that the prefix is stripped from the paths before copying them into the image.
```nix
-
fileSystems."/nix/store".device = "/dev/disk/by-partlabel/nix-store"
-
image.repart.partitions = {
-
"store" = {
-
storePaths = [ config.system.build.toplevel ];
-
stripNixStorePrefix = true;
-
repartConfig = {
-
Type = "linux-generic";
-
Label = "nix-store";
-
...
};
};
-
};
```
## Appliance Image {#sec-image-repart-appliance}
···
partitions = {
"esp" = {
contents = {
+
# ...
};
repartConfig = {
Type = "esp";
+
# ...
};
};
"root" = {
···
repartConfig = {
Type = "root";
Label = "nixos";
+
# ...
};
};
};
···
that the prefix is stripped from the paths before copying them into the image.
```nix
+
{
+
fileSystems."/nix/store".device = "/dev/disk/by-partlabel/nix-store";
+
image.repart.partitions = {
+
"store" = {
+
storePaths = [ config.system.build.toplevel ];
+
stripNixStorePrefix = true;
+
repartConfig = {
+
Type = "linux-generic";
+
Label = "nix-store";
+
# ...
+
};
};
};
+
}
```
## Appliance Image {#sec-image-repart-appliance}
+3 -1
nixos/doc/manual/installation/changing-config.chapter.md
···
following to your configuration:
```nix
-
users.users.your-user.initialHashedPassword = "test";
```
*Important:* delete the \$hostname.qcow2 file if you have started the
···
following to your configuration:
```nix
+
{
+
users.users.your-user.initialHashedPassword = "test";
+
}
```
*Important:* delete the \$hostname.qcow2 file if you have started the
+4 -2
nixos/doc/manual/installation/installing-behind-a-proxy.section.md
···
keep the internet accessible after reboot.
```nix
-
networking.proxy.default = "http://user:password@proxy:port/";
-
networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain";
```
1. Setup the proxy environment variables in the shell where you are
···
keep the internet accessible after reboot.
```nix
+
{
+
networking.proxy.default = "http://user:password@proxy:port/";
+
networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain";
+
}
```
1. Setup the proxy environment variables in the shell where you are
+11 -7
nixos/doc/manual/installation/installing-from-other-distro.section.md
···
want to add something like this to your `configuration.nix`:
```nix
-
boot.loader.grub.extraEntries = ''
-
menuentry "Ubuntu" {
-
search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
-
configfile "($ubuntu)/boot/grub/grub.cfg"
-
}
-
'';
```
(You can find the appropriate UUID for your partition in
···
`sudo passwd -l root` if you use `sudo`)
```nix
-
users.users.root.initialHashedPassword = "";
```
1. Build the NixOS closure and install it in the `system` profile:
···
want to add something like this to your `configuration.nix`:
```nix
+
{
+
boot.loader.grub.extraEntries = ''
+
menuentry "Ubuntu" {
+
search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
+
configfile "($ubuntu)/boot/grub/grub.cfg"
+
}
+
'';
+
}
```
(You can find the appropriate UUID for your partition in
···
`sudo passwd -l root` if you use `sudo`)
```nix
+
{
+
users.users.root.initialHashedPassword = "";
+
}
```
1. Build the NixOS closure and install it in the `system` profile:
+6 -2
nixos/doc/manual/installation/installing-virtualbox-guest.section.md
···
Enable booting:
```nix
-
boot.loader.grub.device = "/dev/sda";
```
Also remove the fsck that runs at startup. It will always fail to run,
stopping your boot until you press `*`.
```nix
-
boot.initrd.checkJournalingFS = false;
```
Shared folders can be given a name and a path in the host system in the
···
Enable booting:
```nix
+
{
+
boot.loader.grub.device = "/dev/sda";
+
}
```
Also remove the fsck that runs at startup. It will always fail to run,
stopping your boot until you press `*`.
```nix
+
{
+
boot.initrd.checkJournalingFS = false;
+
}
```
Shared folders can be given a name and a path in the host system in the
+7 -3
nixos/doc/manual/installation/upgrading.chapter.md
···
following to `configuration.nix`:
```nix
-
system.autoUpgrade.enable = true;
-
system.autoUpgrade.allowReboot = true;
```
This enables a periodically executed systemd service named
···
modules. You can also specify a channel explicitly, e.g.
```nix
-
system.autoUpgrade.channel = "https://channels.nixos.org/nixos-23.11";
```
···
following to `configuration.nix`:
```nix
+
{
+
system.autoUpgrade.enable = true;
+
system.autoUpgrade.allowReboot = true;
+
}
```
This enables a periodically executed systemd service named
···
modules. You can also specify a channel explicitly, e.g.
```nix
+
{
+
system.autoUpgrade.channel = "https://channels.nixos.org/nixos-23.11";
+
}
```
+4 -4
nixos/doc/manual/release-notes/rl-1509.section.md
···
{
options = {
-
foo = mkOption { … };
};
-
config = mkIf config.foo { … };
}
```
···
{
options = {
-
foo = mkOption { option declaration };
};
-
config = mkIf config.foo { option definition };
}
```
···
{
options = {
+
foo = mkOption { /* … */ };
};
+
config = mkIf config.foo { /* … */ };
}
```
···
{
options = {
+
foo = mkOption { /* option declaration */ };
};
+
config = mkIf config.foo { /* option definition */ };
}
```
+2 -2
nixos/doc/manual/release-notes/rl-1703.section.md
···
let
pkgs = import <nixpkgs> {};
in
-
pkgs.overridePackages (self: super: ...)
```
should be replaced by:
···
let
pkgs = import <nixpkgs> {};
in
-
import pkgs.path { overlays = [(self: super: ...)]; }
```
- Autoloading connection tracking helpers is now disabled by default. This default was also changed in the Linux kernel and is considered insecure if not configured properly in your firewall. If you need connection tracking helpers (i.e. for active FTP) please enable `networking.firewall.autoLoadConntrackHelpers` and tune `networking.firewall.connectionTrackingModules` to suit your needs.
···
let
pkgs = import <nixpkgs> {};
in
+
pkgs.overridePackages (self: super: { /* ... */ })
```
should be replaced by:
···
let
pkgs = import <nixpkgs> {};
in
+
import pkgs.path { overlays = [(self: super: { /* ... */ })]; }
```
- Autoloading connection tracking helpers is now disabled by default. This default was also changed in the Linux kernel and is considered insecure if not configured properly in your firewall. If you need connection tracking helpers (i.e. for active FTP) please enable `networking.firewall.autoLoadConntrackHelpers` and tune `networking.firewall.connectionTrackingModules` to suit your needs.
+16 -18
nixos/doc/manual/release-notes/rl-2009.section.md
···
- The remaining configuration flags can now be set directly on the `php` attribute. For example, instead of
```nix
-
{
-
php.override {
-
config.php.embed = true;
-
config.php.apxs2 = false;
-
}
}
```
you should now write
```nix
-
{
-
php.override {
-
embedSupport = true;
-
apxs2Support = false;
-
}
}
```
···
{
specialisation.example-sub-configuration = {
configuration = {
-
...
};
-
};
```
Replace a `nesting.children` entry with:
···
specialisation.example-sub-configuration = {
inheritParentConfig = false;
configuration = {
-
...
};
-
};
```
To switch to a specialised configuration at runtime you need to run:
···
services.bitcoind = {
enable = true;
extraConfig = "...";
-
...
};
}
```
···
dataDir = "/var/lib/bitcoind";
user = "bitcoin";
extraConfig = "...";
-
...
};
}
```
···
{
services.dokuwiki = {
enable = true;
-
...
};
}
```
···
forceSSL = true;
enableACME = true;
};
-
...
};
}
```
···
- The remaining configuration flags can now be set directly on the `php` attribute. For example, instead of
```nix
+
php.override {
+
config.php.embed = true;
+
config.php.apxs2 = false;
}
```
you should now write
```nix
+
php.override {
+
embedSupport = true;
+
apxs2Support = false;
}
```
···
{
specialisation.example-sub-configuration = {
configuration = {
+
# ...
};
+
};
+
}
```
Replace a `nesting.children` entry with:
···
specialisation.example-sub-configuration = {
inheritParentConfig = false;
configuration = {
+
# ...
};
+
};
+
}
```
To switch to a specialised configuration at runtime you need to run:
···
services.bitcoind = {
enable = true;
extraConfig = "...";
+
# ...
};
}
```
···
dataDir = "/var/lib/bitcoind";
user = "bitcoin";
extraConfig = "...";
+
# ...
};
}
```
···
{
services.dokuwiki = {
enable = true;
+
# ...
};
}
```
···
forceSSL = true;
enableACME = true;
};
+
# ...
};
}
```
+4
nixos/doc/manual/release-notes/rl-2205.section.md
···
Before:
```nix
services.keycloak = {
enable = true;
httpPort = "8080";
···
"subsystem=undertow"."server=default-server"."http-listener=default".proxy-address-forwarding = true;
};
};
```
After:
```nix
services.keycloak = {
enable = true;
settings = {
···
};
database.passwordFile = "/run/keys/db_password";
};
```
- The MoinMoin wiki engine (`services.moinmoin`) has been removed, because Python 2 is being retired from nixpkgs.
···
Before:
```nix
+
{
services.keycloak = {
enable = true;
httpPort = "8080";
···
"subsystem=undertow"."server=default-server"."http-listener=default".proxy-address-forwarding = true;
};
};
+
}
```
After:
```nix
+
{
services.keycloak = {
enable = true;
settings = {
···
};
database.passwordFile = "/run/keys/db_password";
};
+
}
```
- The MoinMoin wiki engine (`services.moinmoin`) has been removed, because Python 2 is being retired from nixpkgs.
+5 -3
nixos/doc/manual/release-notes/rl-2211.section.md
···
- `services.github-runner` and `services.github-runners.<name>` gained the option `serviceOverrides` which allows overriding the systemd `serviceConfig`. If you have been overriding the systemd service configuration (i.e., by defining `systemd.services.github-runner.serviceConfig`), you have to use the `serviceOverrides` option now. Example:
```nix
-
services.github-runner.serviceOverrides.SupplementaryGroups = [
-
"docker"
-
];
```
<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
···
- `services.github-runner` and `services.github-runners.<name>` gained the option `serviceOverrides` which allows overriding the systemd `serviceConfig`. If you have been overriding the systemd service configuration (i.e., by defining `systemd.services.github-runner.serviceConfig`), you have to use the `serviceOverrides` option now. Example:
```nix
+
{
+
services.github-runner.serviceOverrides.SupplementaryGroups = [
+
"docker"
+
];
+
}
```
<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+38 -26
nixos/doc/manual/release-notes/rl-2305.section.md
···
- NixOS now defaults to using [nsncd](https://github.com/twosigma/nsncd), a non-caching reimplementation of nscd in Rust, as its NSS lookup dispatcher. This replaces the buggy and deprecated nscd implementation provided through glibc. When you find problems, you can switch back by disabling it:
```nix
-
services.nscd.enableNsncd = false;
```
- The internal option `boot.bootspec.enable` is now enabled by default because [RFC 0125](https://github.com/NixOS/rfcs/pull/125) was merged. This means you will have a bootspec document called `boot.json` generated for each system and specialisation in the top-level. This is useful to enable advanced boot use cases in NixOS, such as Secure Boot.
···
- MAC-then-encrypt algorithms were removed from the default selection of `services.openssh.settings.Macs`. If you still require these [MACs](https://en.wikipedia.org/wiki/Message_authentication_code), for example when you are relying on libssh2 (e.g. VLC) or the SSH library shipped on the iPhone, you can re-add them like this:
```nix
-
services.openssh.settings.Macs = [
-
"hmac-sha2-512"
-
"hmac-sha2-256"
-
"umac-128@openssh.com"
-
];
```
- `podman` now uses the `netavark` network stack. Users will need to delete all of their local containers, images, volumes, etc, by running `podman system reset --force` once before upgrading their systems.
···
- The attributes used by `services.snapper.configs.<name>` have changed. Migrate from this:
```nix
-
services.snapper.configs.example = {
-
subvolume = "/example";
-
extraConfig = ''
-
ALLOW_USERS="alice"
-
'';
-
};
```
to this:
```nix
-
services.snapper.configs.example = {
-
SUBVOLUME = "/example";
-
ALLOW_USERS = [ "alice" ];
-
};
```
- The default module options for [services.snapserver.openFirewall](#opt-services.snapserver.openFirewall), [services.tmate-ssh-server.openFirewall](#opt-services.tmate-ssh-server.openFirewall) and [services.unifi-video.openFirewall](#opt-services.unifi-video.openFirewall) have been changed from `true` to `false`. You will need to explicitly set this option to `true`, or configure your firewall.
···
- NixOS swap partitions with random encryption can now control the sector size, cipher, and key size used to set up the plain encryption device over the underlying block device rather than allowing them to be determined by `cryptsetup(8)`. One can use these features like so:
```nix
-
swapDevices = [ {
-
device = "/dev/disk/by-partlabel/swapspace";
-
randomEncryption = {
-
enable = true;
-
cipher = "aes-xts-plain64";
-
keySize = 512;
-
sectorSize = 4096;
-
};
-
} ];
```
- New option `security.pam.zfs` to enable unlocking and mounting of encrypted ZFS home dataset at login.
···
- PostgreSQL has added opt-in support for [JIT compilation](https://www.postgresql.org/docs/current/jit-reason.html). It can be enabled like this:
```nix
-
services.postgresql.enableJIT = true;
```
- `services.netdata` offers a [`services.netdata.deadlineBeforeStopSec`](#opt-services.netdata.deadlineBeforeStopSec) option which will control the deadline (in seconds) after which systemd will consider your netdata instance as dead if it didn't start in the elapsed time. It is helpful when your netdata instance takes longer to start because of a large amount of state or upgrades.
···
- NixOS now defaults to using [nsncd](https://github.com/twosigma/nsncd), a non-caching reimplementation of nscd in Rust, as its NSS lookup dispatcher. This replaces the buggy and deprecated nscd implementation provided through glibc. When you find problems, you can switch back by disabling it:
```nix
+
{
+
services.nscd.enableNsncd = false;
+
}
```
- The internal option `boot.bootspec.enable` is now enabled by default because [RFC 0125](https://github.com/NixOS/rfcs/pull/125) was merged. This means you will have a bootspec document called `boot.json` generated for each system and specialisation in the top-level. This is useful to enable advanced boot use cases in NixOS, such as Secure Boot.
···
- MAC-then-encrypt algorithms were removed from the default selection of `services.openssh.settings.Macs`. If you still require these [MACs](https://en.wikipedia.org/wiki/Message_authentication_code), for example when you are relying on libssh2 (e.g. VLC) or the SSH library shipped on the iPhone, you can re-add them like this:
```nix
+
{
+
services.openssh.settings.Macs = [
+
"hmac-sha2-512"
+
"hmac-sha2-256"
+
"umac-128@openssh.com"
+
];
+
}
```
- `podman` now uses the `netavark` network stack. Users will need to delete all of their local containers, images, volumes, etc, by running `podman system reset --force` once before upgrading their systems.
···
- The attributes used by `services.snapper.configs.<name>` have changed. Migrate from this:
```nix
+
{
+
services.snapper.configs.example = {
+
subvolume = "/example";
+
extraConfig = ''
+
ALLOW_USERS="alice"
+
'';
+
};
+
}
```
to this:
```nix
+
{
+
services.snapper.configs.example = {
+
SUBVOLUME = "/example";
+
ALLOW_USERS = [ "alice" ];
+
};
+
}
```
- The default module options for [services.snapserver.openFirewall](#opt-services.snapserver.openFirewall), [services.tmate-ssh-server.openFirewall](#opt-services.tmate-ssh-server.openFirewall) and [services.unifi-video.openFirewall](#opt-services.unifi-video.openFirewall) have been changed from `true` to `false`. You will need to explicitly set this option to `true`, or configure your firewall.
···
- NixOS swap partitions with random encryption can now control the sector size, cipher, and key size used to set up the plain encryption device over the underlying block device rather than allowing them to be determined by `cryptsetup(8)`. One can use these features like so:
```nix
+
{
+
swapDevices = [ {
+
device = "/dev/disk/by-partlabel/swapspace";
+
randomEncryption = {
+
enable = true;
+
cipher = "aes-xts-plain64";
+
keySize = 512;
+
sectorSize = 4096;
+
};
+
} ];
+
}
```
- New option `security.pam.zfs` to enable unlocking and mounting of encrypted ZFS home dataset at login.
···
- PostgreSQL has added opt-in support for [JIT compilation](https://www.postgresql.org/docs/current/jit-reason.html). It can be enabled like this:
```nix
+
{
+
services.postgresql.enableJIT = true;
+
}
```
- `services.netdata` offers a [`services.netdata.deadlineBeforeStopSec`](#opt-services.netdata.deadlineBeforeStopSec) option which will control the deadline (in seconds) after which systemd will consider your netdata instance as dead if it didn't start in the elapsed time. It is helpful when your netdata instance takes longer to start because of a large amount of state or upgrades.
+23 -17
nixos/doc/manual/release-notes/rl-2311.section.md
···
will probably be removed eventually.
```nix
-
qt = {
-
enable = true;
-
platformTheme = "gnome";
-
style = "adwaita";
-
};
```
- DocBook option documentation is no longer supported, all module documentation
···
to a compatible major version, so they can move at their own pace.
```nix
-
python = python3.override {
-
packageOverrides = self: super: {
-
django = super.django_3;
};
-
};
```
- The `qemu-vm.nix` module by default now identifies block devices via
···
overriding `externalPlugins` and `vendorHash` arguments like this:
```nix
-
services.coredns = {
-
enable = true;
-
package = pkgs.coredns.override {
-
externalPlugins = [
-
{name = "fanout"; repo = "github.com/networkservicemesh/fanout"; version = "v1.9.1";}
-
];
-
vendorHash = "<SRI hash>";
};
-
};
```
To get the necessary SRI hash, set `vendorHash = "";`. The build will fail
···
will probably be removed eventually.
```nix
+
{
+
qt = {
+
enable = true;
+
platformTheme = "gnome";
+
style = "adwaita";
+
};
+
}
```
- DocBook option documentation is no longer supported, all module documentation
···
to a compatible major version, so they can move at their own pace.
```nix
+
{
+
python = python3.override {
+
packageOverrides = self: super: {
+
django = super.django_3;
+
};
};
+
}
```
- The `qemu-vm.nix` module by default now identifies block devices via
···
overriding `externalPlugins` and `vendorHash` arguments like this:
```nix
+
{
+
services.coredns = {
+
enable = true;
+
package = pkgs.coredns.override {
+
externalPlugins = [
+
{name = "fanout"; repo = "github.com/networkservicemesh/fanout"; version = "v1.9.1";}
+
];
+
vendorHash = "<SRI hash>";
+
};
};
+
}
```
To get the necessary SRI hash, set `vendorHash = "";`. The build will fail
+2 -1
nixos/doc/manual/release-notes/rl-2405.section.md
···
Example:
```nix
locations."/".extraConfig = ''
add_header Alt-Svc 'h3=":$server_port"; ma=86400';
'';
locations."^~ /assets/".extraConfig = ''
add_header Alt-Svc 'h3=":$server_port"; ma=86400';
'';
-
```
- The package `optparse-bash` is now dropped due to upstream inactivity. Alternatives available in Nixpkgs include [`argc`](https://github.com/sigoden/argc), [`argbash`](https://github.com/matejak/argbash), [`bashly`](https://github.com/DannyBen/bashly) and [`gum`](https://github.com/charmbracelet/gum), to name a few.
···
Example:
```nix
+
{
locations."/".extraConfig = ''
add_header Alt-Svc 'h3=":$server_port"; ma=86400';
'';
locations."^~ /assets/".extraConfig = ''
add_header Alt-Svc 'h3=":$server_port"; ma=86400';
'';
+
}
```
- The package `optparse-bash` is now dropped due to upstream inactivity. Alternatives available in Nixpkgs include [`argc`](https://github.com/sigoden/argc), [`argbash`](https://github.com/matejak/argbash), [`bashly`](https://github.com/DannyBen/bashly) and [`gum`](https://github.com/charmbracelet/gum), to name a few.
+35 -21
nixos/modules/i18n/input-method/default.md
···
The following snippet can be used to configure IBus:
```nix
-
i18n.inputMethod = {
-
enabled = "ibus";
-
ibus.engines = with pkgs.ibus-engines; [ anthy hangul mozc ];
-
};
```
`i18n.inputMethod.ibus.engines` is optional and can be used
···
`table`. For example:
```nix
-
ibus.engines = with pkgs.ibus-engines; [ table table-others ];
```
To use any input method, the package must be added in the configuration, as
···
The following snippet can be used to configure Fcitx:
```nix
-
i18n.inputMethod = {
-
enabled = "fcitx5";
-
fcitx5.addons = with pkgs; [ fcitx5-mozc fcitx5-hangul fcitx5-m17n ];
-
};
```
`i18n.inputMethod.fcitx5.addons` is optional and can be
···
The following snippet can be used to configure Nabi:
```nix
-
i18n.inputMethod = {
-
enabled = "nabi";
-
};
```
## Uim {#module-services-input-methods-uim}
···
The following snippet can be used to configure uim:
```nix
-
i18n.inputMethod = {
-
enabled = "uim";
-
};
```
Note: The [](#opt-i18n.inputMethod.uim.toolbar) option can be
···
The following snippet can be used to configure Hime:
```nix
-
i18n.inputMethod = {
-
enabled = "hime";
-
};
```
## Kime {#module-services-input-methods-kime}
···
The following snippet can be used to configure Kime:
```nix
-
i18n.inputMethod = {
-
enabled = "kime";
-
};
```
···
The following snippet can be used to configure IBus:
```nix
+
{
+
i18n.inputMethod = {
+
enabled = "ibus";
+
ibus.engines = with pkgs.ibus-engines; [ anthy hangul mozc ];
+
};
+
}
```
`i18n.inputMethod.ibus.engines` is optional and can be used
···
`table`. For example:
```nix
+
{
+
ibus.engines = with pkgs.ibus-engines; [ table table-others ];
+
}
```
To use any input method, the package must be added in the configuration, as
···
The following snippet can be used to configure Fcitx:
```nix
+
{
+
i18n.inputMethod = {
+
enabled = "fcitx5";
+
fcitx5.addons = with pkgs; [ fcitx5-mozc fcitx5-hangul fcitx5-m17n ];
+
};
+
}
```
`i18n.inputMethod.fcitx5.addons` is optional and can be
···
The following snippet can be used to configure Nabi:
```nix
+
{
+
i18n.inputMethod = {
+
enabled = "nabi";
+
};
+
}
```
## Uim {#module-services-input-methods-uim}
···
The following snippet can be used to configure uim:
```nix
+
{
+
i18n.inputMethod = {
+
enabled = "uim";
+
};
+
}
```
Note: The [](#opt-i18n.inputMethod.uim.toolbar) option can be
···
The following snippet can be used to configure Hime:
```nix
+
{
+
i18n.inputMethod = {
+
enabled = "hime";
+
};
+
}
```
## Kime {#module-services-input-methods-kime}
···
The following snippet can be used to configure Kime:
```nix
+
{
+
i18n.inputMethod = {
+
enabled = "kime";
+
};
+
}
```
+18 -10
nixos/modules/programs/digitalbitbox/default.md
···
The `digitalbitbox` programs module may be installed by setting
`programs.digitalbitbox` to `true` in a manner similar to
```nix
-
programs.digitalbitbox.enable = true;
```
and bundles the `digitalbitbox` package (see [](#sec-digitalbitbox-package)),
which contains the `dbb-app` and `dbb-cli` binaries, along with the hardware
···
The binaries, `dbb-app` (a GUI tool) and `dbb-cli` (a CLI tool), are available
through the `digitalbitbox` package which could be installed as follows:
```nix
-
environment.systemPackages = [
-
pkgs.digitalbitbox
-
];
```
## Hardware {#sec-digitalbitbox-hardware-module}
···
The digitalbitbox hardware package enables the udev rules for Digital Bitbox
devices and may be installed as follows:
```nix
-
hardware.digitalbitbox.enable = true;
```
In order to alter the udev rules, one may provide different values for the
`udevRule51` and `udevRule52` attributes by means of overriding as follows:
```nix
-
programs.digitalbitbox = {
-
enable = true;
-
package = pkgs.digitalbitbox.override {
-
udevRule51 = "something else";
};
-
};
```
···
The `digitalbitbox` programs module may be installed by setting
`programs.digitalbitbox` to `true` in a manner similar to
```nix
+
{
+
programs.digitalbitbox.enable = true;
+
}
```
and bundles the `digitalbitbox` package (see [](#sec-digitalbitbox-package)),
which contains the `dbb-app` and `dbb-cli` binaries, along with the hardware
···
The binaries, `dbb-app` (a GUI tool) and `dbb-cli` (a CLI tool), are available
through the `digitalbitbox` package which could be installed as follows:
```nix
+
{
+
environment.systemPackages = [
+
pkgs.digitalbitbox
+
];
+
}
```
## Hardware {#sec-digitalbitbox-hardware-module}
···
The digitalbitbox hardware package enables the udev rules for Digital Bitbox
devices and may be installed as follows:
```nix
+
{
+
hardware.digitalbitbox.enable = true;
+
}
```
In order to alter the udev rules, one may provide different values for the
`udevRule51` and `udevRule52` attributes by means of overriding as follows:
```nix
+
{
+
programs.digitalbitbox = {
+
enable = true;
+
package = pkgs.digitalbitbox.override {
+
udevRule51 = "something else";
+
};
};
+
}
```
+3 -1
nixos/modules/programs/plotinus.md
···
To enable Plotinus, add the following to your
{file}`configuration.nix`:
```nix
-
programs.plotinus.enable = true;
```
···
To enable Plotinus, add the following to your
{file}`configuration.nix`:
```nix
+
{
+
programs.plotinus.enable = true;
+
}
```
+184 -170
nixos/modules/security/acme/default.md
···
`foo.example.com` the config would look like this:
```nix
-
security.acme.acceptTerms = true;
-
security.acme.defaults.email = "admin+acme@example.com";
-
services.nginx = {
-
enable = true;
-
virtualHosts = {
-
"foo.example.com" = {
-
forceSSL = true;
-
enableACME = true;
-
# All serverAliases will be added as extra domain names on the certificate.
-
serverAliases = [ "bar.example.com" ];
-
locations."/" = {
-
root = "/var/www";
};
-
};
-
# We can also add a different vhost and reuse the same certificate
-
# but we have to append extraDomainNames manually beforehand:
-
# security.acme.certs."foo.example.com".extraDomainNames = [ "baz.example.com" ];
-
"baz.example.com" = {
-
forceSSL = true;
-
useACMEHost = "foo.example.com";
-
locations."/" = {
-
root = "/var/www";
};
};
};
-
};
```
## Using ACME certificates in Apache/httpd {#module-security-acme-httpd}
···
everyone to HTTPS.
```nix
-
security.acme.acceptTerms = true;
-
security.acme.defaults.email = "admin+acme@example.com";
-
# /var/lib/acme/.challenges must be writable by the ACME user
-
# and readable by the Nginx user. The easiest way to achieve
-
# this is to add the Nginx user to the ACME group.
-
users.users.nginx.extraGroups = [ "acme" ];
-
services.nginx = {
-
enable = true;
-
virtualHosts = {
-
"acmechallenge.example.com" = {
-
# Catchall vhost, will redirect users to HTTPS for all vhosts
-
serverAliases = [ "*.example.com" ];
-
locations."/.well-known/acme-challenge" = {
-
root = "/var/lib/acme/.challenges";
-
};
-
locations."/" = {
-
return = "301 https://$host$request_uri";
};
};
};
-
};
-
# Alternative config for Apache
-
users.users.wwwrun.extraGroups = [ "acme" ];
-
services.httpd = {
-
enable = true;
-
virtualHosts = {
-
"acmechallenge.example.com" = {
-
# Catchall vhost, will redirect users to HTTPS for all vhosts
-
serverAliases = [ "*.example.com" ];
-
# /var/lib/acme/.challenges must be writable by the ACME user and readable by the Apache user.
-
# By default, this is the case.
-
documentRoot = "/var/lib/acme/.challenges";
-
extraConfig = ''
-
RewriteEngine On
-
RewriteCond %{HTTPS} off
-
RewriteCond %{REQUEST_URI} !^/\.well-known/acme-challenge [NC]
-
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301]
-
'';
};
};
-
};
```
Now you need to configure ACME to generate a certificate.
```nix
-
security.acme.certs."foo.example.com" = {
-
webroot = "/var/lib/acme/.challenges";
-
email = "foo@example.com";
-
# Ensure that the web server you use can read the generated certs
-
# Take a look at the group option for the web server you choose.
-
group = "nginx";
-
# Since we have a wildcard vhost to handle port 80,
-
# we can generate certs for anything!
-
# Just make sure your DNS resolves them.
-
extraDomainNames = [ "mail.example.com" ];
-
};
```
The private key {file}`key.pem` and certificate
···
docs, we will provide a fully self-hosted example using bind.
```nix
-
services.bind = {
-
enable = true;
-
extraConfig = ''
-
include "/var/lib/secrets/dnskeys.conf";
-
'';
-
zones = [
-
rec {
-
name = "example.com";
-
file = "/var/db/bind/${name}";
-
master = true;
-
extraConfig = "allow-update { key rfc2136key.example.com.; };";
-
}
-
];
-
};
-
# Now we can configure ACME
-
security.acme.acceptTerms = true;
-
security.acme.defaults.email = "admin+acme@example.com";
-
security.acme.certs."example.com" = {
-
domain = "*.example.com";
-
dnsProvider = "rfc2136";
-
environmentFile = "/var/lib/secrets/certs.secret";
-
# We don't need to wait for propagation since this is a local DNS server
-
dnsPropagationCheck = false;
-
};
```
The {file}`dnskeys.conf` and {file}`certs.secret`
···
Nix config. Instead, generate them one time with a systemd service:
```nix
-
systemd.services.dns-rfc2136-conf = {
-
requiredBy = ["acme-example.com.service" "bind.service"];
-
before = ["acme-example.com.service" "bind.service"];
-
unitConfig = {
-
ConditionPathExists = "!/var/lib/secrets/dnskeys.conf";
-
};
-
serviceConfig = {
-
Type = "oneshot";
-
UMask = 0077;
-
};
-
path = [ pkgs.bind ];
-
script = ''
-
mkdir -p /var/lib/secrets
-
chmod 755 /var/lib/secrets
-
tsig-keygen rfc2136key.example.com > /var/lib/secrets/dnskeys.conf
-
chown named:root /var/lib/secrets/dnskeys.conf
-
chmod 400 /var/lib/secrets/dnskeys.conf
-
# extract secret value from the dnskeys.conf
-
while read x y; do if [ "$x" = "secret" ]; then secret="''${y:1:''${#y}-3}"; fi; done < /var/lib/secrets/dnskeys.conf
-
cat > /var/lib/secrets/certs.secret << EOF
-
RFC2136_NAMESERVER='127.0.0.1:53'
-
RFC2136_TSIG_ALGORITHM='hmac-sha256.'
-
RFC2136_TSIG_KEY='rfc2136key.example.com'
-
RFC2136_TSIG_SECRET='$secret'
-
EOF
-
chmod 400 /var/lib/secrets/certs.secret
-
'';
-
};
```
Now you're all set to generate certs! You should monitor the first invocation
···
(e.g. [](#opt-security.acme.defaults.dnsProvider)).
```nix
-
# Configure ACME appropriately
-
security.acme.acceptTerms = true;
-
security.acme.defaults.email = "admin+acme@example.com";
-
security.acme.defaults = {
-
dnsProvider = "rfc2136";
-
environmentFile = "/var/lib/secrets/certs.secret";
-
# We don't need to wait for propagation since this is a local DNS server
-
dnsPropagationCheck = false;
-
};
-
# For each virtual host you would like to use DNS-01 validation with,
-
# set acmeRoot = null
-
services.nginx = {
-
enable = true;
-
virtualHosts = {
-
"foo.example.com" = {
-
enableACME = true;
-
acmeRoot = null;
};
};
-
};
```
And that's it! Next time your configuration is rebuilt, or when
···
can be applied to any service.
```nix
-
# Configure ACME however you like (DNS or HTTP validation), adding
-
# the following configuration for the relevant certificate.
-
# Note: You cannot use `systemctl reload` here as that would mean
-
# the LoadCredential configuration below would be skipped and
-
# the service would continue to use old certificates.
-
security.acme.certs."mail.example.com".postRun = ''
-
systemctl restart opensmtpd
-
'';
-
# Now you must augment OpenSMTPD's systemd service to load
-
# the certificate files.
-
systemd.services.opensmtpd.requires = ["acme-finished-mail.example.com.target"];
-
systemd.services.opensmtpd.serviceConfig.LoadCredential = let
-
certDir = config.security.acme.certs."mail.example.com".directory;
-
in [
-
"cert.pem:${certDir}/cert.pem"
-
"key.pem:${certDir}/key.pem"
-
];
-
# Finally, configure OpenSMTPD to use these certs.
-
services.opensmtpd = let
-
credsDir = "/run/credentials/opensmtpd.service";
-
in {
-
enable = true;
-
setSendmail = false;
-
serverConfiguration = ''
-
pki mail.example.com cert "${credsDir}/cert.pem"
-
pki mail.example.com key "${credsDir}/key.pem"
-
listen on localhost tls pki mail.example.com
-
action act1 relay host smtp://127.0.0.1:10027
-
match for local action act1
-
'';
-
};
```
## Regenerating certificates {#module-security-acme-regenerate}
···
`foo.example.com` the config would look like this:
```nix
+
{
+
security.acme.acceptTerms = true;
+
security.acme.defaults.email = "admin+acme@example.com";
+
services.nginx = {
+
enable = true;
+
virtualHosts = {
+
"foo.example.com" = {
+
forceSSL = true;
+
enableACME = true;
+
# All serverAliases will be added as extra domain names on the certificate.
+
serverAliases = [ "bar.example.com" ];
+
locations."/" = {
+
root = "/var/www";
+
};
};
+
# We can also add a different vhost and reuse the same certificate
+
# but we have to append extraDomainNames manually beforehand:
+
# security.acme.certs."foo.example.com".extraDomainNames = [ "baz.example.com" ];
+
"baz.example.com" = {
+
forceSSL = true;
+
useACMEHost = "foo.example.com";
+
locations."/" = {
+
root = "/var/www";
+
};
};
};
};
+
}
```
## Using ACME certificates in Apache/httpd {#module-security-acme-httpd}
···
everyone to HTTPS.
```nix
+
{
+
security.acme.acceptTerms = true;
+
security.acme.defaults.email = "admin+acme@example.com";
+
# /var/lib/acme/.challenges must be writable by the ACME user
+
# and readable by the Nginx user. The easiest way to achieve
+
# this is to add the Nginx user to the ACME group.
+
users.users.nginx.extraGroups = [ "acme" ];
+
services.nginx = {
+
enable = true;
+
virtualHosts = {
+
"acmechallenge.example.com" = {
+
# Catchall vhost, will redirect users to HTTPS for all vhosts
+
serverAliases = [ "*.example.com" ];
+
locations."/.well-known/acme-challenge" = {
+
root = "/var/lib/acme/.challenges";
+
};
+
locations."/" = {
+
return = "301 https://$host$request_uri";
+
};
};
};
};
+
# Alternative config for Apache
+
users.users.wwwrun.extraGroups = [ "acme" ];
+
services.httpd = {
+
enable = true;
+
virtualHosts = {
+
"acmechallenge.example.com" = {
+
# Catchall vhost, will redirect users to HTTPS for all vhosts
+
serverAliases = [ "*.example.com" ];
+
# /var/lib/acme/.challenges must be writable by the ACME user and readable by the Apache user.
+
# By default, this is the case.
+
documentRoot = "/var/lib/acme/.challenges";
+
extraConfig = ''
+
RewriteEngine On
+
RewriteCond %{HTTPS} off
+
RewriteCond %{REQUEST_URI} !^/\.well-known/acme-challenge [NC]
+
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301]
+
'';
+
};
};
};
+
}
```
Now you need to configure ACME to generate a certificate.
```nix
+
{
+
security.acme.certs."foo.example.com" = {
+
webroot = "/var/lib/acme/.challenges";
+
email = "foo@example.com";
+
# Ensure that the web server you use can read the generated certs
+
# Take a look at the group option for the web server you choose.
+
group = "nginx";
+
# Since we have a wildcard vhost to handle port 80,
+
# we can generate certs for anything!
+
# Just make sure your DNS resolves them.
+
extraDomainNames = [ "mail.example.com" ];
+
};
+
}
```
The private key {file}`key.pem` and certificate
···
docs, we will provide a fully self-hosted example using bind.
```nix
+
{
+
services.bind = {
+
enable = true;
+
extraConfig = ''
+
include "/var/lib/secrets/dnskeys.conf";
+
'';
+
zones = [
+
rec {
+
name = "example.com";
+
file = "/var/db/bind/${name}";
+
master = true;
+
extraConfig = "allow-update { key rfc2136key.example.com.; };";
+
}
+
];
+
};
+
# Now we can configure ACME
+
security.acme.acceptTerms = true;
+
security.acme.defaults.email = "admin+acme@example.com";
+
security.acme.certs."example.com" = {
+
domain = "*.example.com";
+
dnsProvider = "rfc2136";
+
environmentFile = "/var/lib/secrets/certs.secret";
+
# We don't need to wait for propagation since this is a local DNS server
+
dnsPropagationCheck = false;
+
};
+
}
```
The {file}`dnskeys.conf` and {file}`certs.secret`
···
Nix config. Instead, generate them one time with a systemd service:
```nix
+
{
+
systemd.services.dns-rfc2136-conf = {
+
requiredBy = ["acme-example.com.service" "bind.service"];
+
before = ["acme-example.com.service" "bind.service"];
+
unitConfig = {
+
ConditionPathExists = "!/var/lib/secrets/dnskeys.conf";
+
};
+
serviceConfig = {
+
Type = "oneshot";
+
UMask = 0077;
+
};
+
path = [ pkgs.bind ];
+
script = ''
+
mkdir -p /var/lib/secrets
+
chmod 755 /var/lib/secrets
+
tsig-keygen rfc2136key.example.com > /var/lib/secrets/dnskeys.conf
+
chown named:root /var/lib/secrets/dnskeys.conf
+
chmod 400 /var/lib/secrets/dnskeys.conf
+
# extract secret value from the dnskeys.conf
+
while read x y; do if [ "$x" = "secret" ]; then secret="''${y:1:''${#y}-3}"; fi; done < /var/lib/secrets/dnskeys.conf
+
cat > /var/lib/secrets/certs.secret << EOF
+
RFC2136_NAMESERVER='127.0.0.1:53'
+
RFC2136_TSIG_ALGORITHM='hmac-sha256.'
+
RFC2136_TSIG_KEY='rfc2136key.example.com'
+
RFC2136_TSIG_SECRET='$secret'
+
EOF
+
chmod 400 /var/lib/secrets/certs.secret
+
'';
+
};
+
}
```
Now you're all set to generate certs! You should monitor the first invocation
···
(e.g. [](#opt-security.acme.defaults.dnsProvider)).
```nix
+
{
+
# Configure ACME appropriately
+
security.acme.acceptTerms = true;
+
security.acme.defaults.email = "admin+acme@example.com";
+
security.acme.defaults = {
+
dnsProvider = "rfc2136";
+
environmentFile = "/var/lib/secrets/certs.secret";
+
# We don't need to wait for propagation since this is a local DNS server
+
dnsPropagationCheck = false;
+
};
+
# For each virtual host you would like to use DNS-01 validation with,
+
# set acmeRoot = null
+
services.nginx = {
+
enable = true;
+
virtualHosts = {
+
"foo.example.com" = {
+
enableACME = true;
+
acmeRoot = null;
+
};
};
};
+
}
```
And that's it! Next time your configuration is rebuilt, or when
···
can be applied to any service.
```nix
+
{
+
# Configure ACME however you like (DNS or HTTP validation), adding
+
# the following configuration for the relevant certificate.
+
# Note: You cannot use `systemctl reload` here as that would mean
+
# the LoadCredential configuration below would be skipped and
+
# the service would continue to use old certificates.
+
security.acme.certs."mail.example.com".postRun = ''
+
systemctl restart opensmtpd
+
'';
+
# Now you must augment OpenSMTPD's systemd service to load
+
# the certificate files.
+
systemd.services.opensmtpd.requires = ["acme-finished-mail.example.com.target"];
+
systemd.services.opensmtpd.serviceConfig.LoadCredential = let
+
certDir = config.security.acme.certs."mail.example.com".directory;
+
in [
+
"cert.pem:${certDir}/cert.pem"
+
"key.pem:${certDir}/key.pem"
+
];
+
# Finally, configure OpenSMTPD to use these certs.
+
services.opensmtpd = let
+
credsDir = "/run/credentials/opensmtpd.service";
+
in {
+
enable = true;
+
setSendmail = false;
+
serverConfiguration = ''
+
pki mail.example.com cert "${credsDir}/cert.pem"
+
pki mail.example.com key "${credsDir}/key.pem"
+
listen on localhost tls pki mail.example.com
+
action act1 relay host smtp://127.0.0.1:10027
+
match for local action act1
+
'';
+
};
+
}
```
## Regenerating certificates {#module-security-acme-regenerate}
+11 -9
nixos/modules/services/audio/castopod.md
···
Use the following configuration to start a public instance of Castopod on `castopod.example.com` domain:
```nix
-
networking.firewall.allowedTCPPorts = [ 80 443 ];
-
services.castopod = {
-
enable = true;
-
database.createLocally = true;
-
nginx.virtualHost = {
-
serverName = "castopod.example.com";
-
enableACME = true;
-
forceSSL = true;
};
-
};
```
Go to `https://castopod.example.com/cp-install` to create superadmin account after applying the above configuration.
···
Use the following configuration to start a public instance of Castopod on `castopod.example.com` domain:
```nix
+
{
+
networking.firewall.allowedTCPPorts = [ 80 443 ];
+
services.castopod = {
+
enable = true;
+
database.createLocally = true;
+
nginx.virtualHost = {
+
serverName = "castopod.example.com";
+
enableACME = true;
+
forceSSL = true;
+
};
};
+
}
```
Go to `https://castopod.example.com/cp-install` to create superadmin account after applying the above configuration.
+12 -13
nixos/modules/services/backup/borgbackup.md
···
```nix
{
opt.services.borgbackup.jobs = {
-
{ rootBackup = {
-
paths = "/";
-
exclude = [ "/nix" "/path/to/local/repo" ];
-
repo = "/path/to/local/repo";
-
doInit = true;
-
encryption = {
-
mode = "repokey";
-
passphrase = "secret";
-
};
-
compression = "auto,lzma";
-
startAt = "weekly";
};
-
}
};
}
```
···
startAt = "hourly";
};
};
-
};
```
The following few commands (run as root) let you test your backup.
···
```nix
{
opt.services.borgbackup.jobs = {
+
rootBackup = {
+
paths = "/";
+
exclude = [ "/nix" "/path/to/local/repo" ];
+
repo = "/path/to/local/repo";
+
doInit = true;
+
encryption = {
+
mode = "repokey";
+
passphrase = "secret";
};
+
compression = "auto,lzma";
+
startAt = "weekly";
+
};
};
}
```
···
startAt = "hourly";
};
};
+
}
```
The following few commands (run as root) let you test your backup.
+10 -4
nixos/modules/services/databases/foundationdb.md
···
To enable FoundationDB, add the following to your
{file}`configuration.nix`:
```nix
-
services.foundationdb.enable = true;
-
services.foundationdb.package = pkgs.foundationdb71; # FoundationDB 7.1.x
```
The {option}`services.foundationdb.package` option is required, and
···
{file}`/var/lib/foundationdb`. You can override this using
{option}`services.foundationdb.dataDir`, e.g.
```nix
-
services.foundationdb.dataDir = "/data/fdb";
```
Similarly, logs are stored under {file}`/var/log/foundationdb`
···
set up the paths in the module options:
```nix
-
services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ];
```
Restart the FoundationDB service, and it will now be able to write to this
···
To enable FoundationDB, add the following to your
{file}`configuration.nix`:
```nix
+
{
+
services.foundationdb.enable = true;
+
services.foundationdb.package = pkgs.foundationdb71; # FoundationDB 7.1.x
+
}
```
The {option}`services.foundationdb.package` option is required, and
···
{file}`/var/lib/foundationdb`. You can override this using
{option}`services.foundationdb.dataDir`, e.g.
```nix
+
{
+
services.foundationdb.dataDir = "/data/fdb";
+
}
```
Similarly, logs are stored under {file}`/var/log/foundationdb`
···
set up the paths in the module options:
```nix
+
{
+
services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ];
+
}
```
Restart the FoundationDB service, and it will now be able to write to this
+22 -8
nixos/modules/services/databases/postgresql.md
···
To enable PostgreSQL, add the following to your {file}`configuration.nix`:
```nix
-
services.postgresql.enable = true;
-
services.postgresql.package = pkgs.postgresql_15;
```
Note that you are required to specify the desired version of PostgreSQL (e.g. `pkgs.postgresql_15`). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for [](#opt-services.postgresql.package) such as the most recent release of PostgreSQL.
···
By default, PostgreSQL stores its databases in {file}`/var/lib/postgresql/$psqlSchema`. You can override this using [](#opt-services.postgresql.dataDir), e.g.
```nix
-
services.postgresql.dataDir = "/data/postgresql";
```
## Initializing {#module-services-postgres-initializing}
···
are already created.
```nix
systemd.services.postgresql.postStart = lib.mkAfter ''
$PSQL service1 -c 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO "extraUser1"'
$PSQL service1 -c 'GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO "extraUser1"'
# ....
'';
```
##### in intermediate oneshot service {#module-services-postgres-initializing-extra-permissions-superuser-oneshot}
```nix
systemd.services."migrate-service1-db1" = {
serviceConfig.Type = "oneshot";
requiredBy = "service1.service";
···
# ....
'';
};
```
#### as service user {#module-services-postgres-initializing-extra-permissions-service-user}
···
##### in service `preStart` {#module-services-postgres-initializing-extra-permissions-service-user-pre-start}
```nix
environment.PSQL = "psql --port=${toString services.postgresql.port}";
path = [ postgresql ];
systemd.services."service1".preStart = ''
···
$PSQL -c 'GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO "extraUser1"'
# ....
'';
```
##### in intermediate oneshot service {#module-services-postgres-initializing-extra-permissions-service-user-oneshot}
```nix
systemd.services."migrate-service1-db1" = {
serviceConfig.Type = "oneshot";
requiredBy = "service1.service";
···
# ....
'';
};
```
## Upgrading {#module-services-postgres-upgrading}
···
To add plugins via NixOS configuration, set `services.postgresql.extraPlugins`:
```nix
-
services.postgresql.package = pkgs.postgresql_12;
-
services.postgresql.extraPlugins = ps: with ps; [
-
pg_repack
-
postgis
-
];
```
You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using function `.withPackages`. For example, creating a custom PostgreSQL package in an overlay can look like:
···
To enable PostgreSQL, add the following to your {file}`configuration.nix`:
```nix
+
{
+
services.postgresql.enable = true;
+
services.postgresql.package = pkgs.postgresql_15;
+
}
```
Note that you are required to specify the desired version of PostgreSQL (e.g. `pkgs.postgresql_15`). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for [](#opt-services.postgresql.package) such as the most recent release of PostgreSQL.
···
By default, PostgreSQL stores its databases in {file}`/var/lib/postgresql/$psqlSchema`. You can override this using [](#opt-services.postgresql.dataDir), e.g.
```nix
+
{
+
services.postgresql.dataDir = "/data/postgresql";
+
}
```
## Initializing {#module-services-postgres-initializing}
···
are already created.
```nix
+
{
systemd.services.postgresql.postStart = lib.mkAfter ''
$PSQL service1 -c 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO "extraUser1"'
$PSQL service1 -c 'GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO "extraUser1"'
# ....
'';
+
}
```
##### in intermediate oneshot service {#module-services-postgres-initializing-extra-permissions-superuser-oneshot}
```nix
+
{
systemd.services."migrate-service1-db1" = {
serviceConfig.Type = "oneshot";
requiredBy = "service1.service";
···
# ....
'';
};
+
}
```
#### as service user {#module-services-postgres-initializing-extra-permissions-service-user}
···
##### in service `preStart` {#module-services-postgres-initializing-extra-permissions-service-user-pre-start}
```nix
+
{
environment.PSQL = "psql --port=${toString services.postgresql.port}";
path = [ postgresql ];
systemd.services."service1".preStart = ''
···
$PSQL -c 'GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO "extraUser1"'
# ....
'';
+
}
```
##### in intermediate oneshot service {#module-services-postgres-initializing-extra-permissions-service-user-oneshot}
```nix
+
{
systemd.services."migrate-service1-db1" = {
serviceConfig.Type = "oneshot";
requiredBy = "service1.service";
···
# ....
'';
};
+
}
```
## Upgrading {#module-services-postgres-upgrading}
···
To add plugins via NixOS configuration, set `services.postgresql.extraPlugins`:
```nix
+
{
+
services.postgresql.package = pkgs.postgresql_12;
+
services.postgresql.extraPlugins = ps: with ps; [
+
pg_repack
+
postgis
+
];
+
}
```
You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using function `.withPackages`. For example, creating a custom PostgreSQL package in an overlay can look like:
+4
nixos/modules/services/databases/tigerbeetle.md
···
To enable TigerBeetle, add the following to your {file}`configuration.nix`:
```nix
services.tigerbeetle.enable = true;
```
When first started, the TigerBeetle service will create its data file at {file}`/var/lib/tigerbeetle` unless the file already exists, in which case it will just use the existing file.
···
Note that the TigerBeetle module won't open any firewall ports automatically, so if you configure it to listen on an external interface, you'll need to ensure that connections can reach it:
```nix
services.tigerbeetle = {
enable = true;
addresses = [ "0.0.0.0:3001" ];
};
networking.firewall.allowedTCPPorts = [ 3001 ];
```
A complete list of options for TigerBeetle can be found [here](#opt-services.tigerbeetle.enable).
···
To enable TigerBeetle, add the following to your {file}`configuration.nix`:
```nix
+
{
services.tigerbeetle.enable = true;
+
}
```
When first started, the TigerBeetle service will create its data file at {file}`/var/lib/tigerbeetle` unless the file already exists, in which case it will just use the existing file.
···
Note that the TigerBeetle module won't open any firewall ports automatically, so if you configure it to listen on an external interface, you'll need to ensure that connections can reach it:
```nix
+
{
services.tigerbeetle = {
enable = true;
addresses = [ "0.0.0.0:3001" ];
};
networking.firewall.allowedTCPPorts = [ 3001 ];
+
}
```
A complete list of options for TigerBeetle can be found [here](#opt-services.tigerbeetle.enable).
+4
nixos/modules/services/desktops/flatpak.md
···
To enable Flatpak, add the following to your {file}`configuration.nix`:
```nix
services.flatpak.enable = true;
```
For the sandboxed apps to work correctly, desktop integration portals need to
···
in other cases, you will need to add something like the following to your
{file}`configuration.nix`:
```nix
xdg.portal.extraPortals = [ pkgs.xdg-desktop-portal-gtk ];
xdg.portal.config.common.default = "gtk";
```
Then, you will need to add a repository, for example,
···
To enable Flatpak, add the following to your {file}`configuration.nix`:
```nix
+
{
services.flatpak.enable = true;
+
}
```
For the sandboxed apps to work correctly, desktop integration portals need to
···
in other cases, you will need to add something like the following to your
{file}`configuration.nix`:
```nix
+
{
xdg.portal.extraPortals = [ pkgs.xdg-desktop-portal-gtk ];
xdg.portal.config.common.default = "gtk";
+
}
```
Then, you will need to add a repository, for example,
+1 -1
nixos/modules/services/development/athens.md
···
```nix
{
environment.variables = {
-
GOPROXY = "http://localhost:3000"
};
}
```
···
```nix
{
environment.variables = {
+
GOPROXY = "http://localhost:3000";
};
}
```
+3 -1
nixos/modules/services/development/livebook.md
···
`extraPackages`:
```nix
-
services.livebook.extraPackages = with pkgs; [ gcc gnumake ];
```
···
`extraPackages`:
```nix
+
{
+
services.livebook.extraPackages = with pkgs; [ gcc gnumake ];
+
}
```
+8 -4
nixos/modules/services/editors/emacs.md
···
rm $out/share/applications/emacs.desktop
'';
});
-
in [...]
```
:::
···
To install and enable the {command}`systemd` user service for Emacs
daemon, add the following to your {file}`configuration.nix`:
```nix
-
services.emacs.enable = true;
```
The {var}`services.emacs.package` option allows a custom
···
Emacs daemon is not wanted for all users, it is possible to install the
service but not globally enable it:
```nix
-
services.emacs.enable = false;
-
services.emacs.install = true;
```
To enable the {command}`systemd` user service for just the
···
rm $out/share/applications/emacs.desktop
'';
});
+
in [ /* ... */ ]
```
:::
···
To install and enable the {command}`systemd` user service for Emacs
daemon, add the following to your {file}`configuration.nix`:
```nix
+
{
+
services.emacs.enable = true;
+
}
```
The {var}`services.emacs.package` option allows a custom
···
Emacs daemon is not wanted for all users, it is possible to install the
service but not globally enable it:
```nix
+
{
+
services.emacs.enable = false;
+
services.emacs.install = true;
+
}
```
To enable the {command}`systemd` user service for just the
+48 -42
nixos/modules/services/matrix/maubot.md
···
2. If you want to use PostgreSQL instead of SQLite, do this:
```nix
-
services.maubot.settings.database = "postgresql://maubot@localhost/maubot";
```
If the PostgreSQL connection requires a password, you will have to
···
3. If you plan to expose your Maubot interface to the web, do something
like this:
```nix
-
services.nginx.virtualHosts."matrix.example.org".locations = {
-
"/_matrix/maubot/" = {
-
proxyPass = "http://127.0.0.1:${toString config.services.maubot.settings.server.port}";
-
proxyWebsockets = true;
};
-
};
-
services.maubot.settings.server.public_url = "matrix.example.org";
-
# do the following only if you want to use something other than /_matrix/maubot...
-
services.maubot.settings.server.ui_base_path = "/another/base/path";
```
4. Optionally, set `services.maubot.pythonPackages` to a list of python3
packages to make available for Maubot plugins.
5. Optionally, set `services.maubot.plugins` to a list of Maubot
plugins (full list available at https://plugins.maubot.xyz/):
```nix
-
services.maubot.plugins = with config.services.maubot.package.plugins; [
-
reactbot
-
# This will only change the default config! After you create a
-
# plugin instance, the default config will be copied into that
-
# instance's config in Maubot's database, and further base config
-
# changes won't affect the running plugin.
-
(rss.override {
-
base_config = {
-
update_interval = 60;
-
max_backoff = 7200;
-
spam_sleep = 2;
-
command_prefix = "rss";
-
admins = [ "@chayleaf:pavluk.org" ];
-
};
-
})
-
];
-
# ...or...
-
services.maubot.plugins = config.services.maubot.package.plugins.allOfficialPlugins;
-
# ...or...
-
services.maubot.plugins = config.services.maubot.package.plugins.allPlugins;
-
# ...or...
-
services.maubot.plugins = with config.services.maubot.package.plugins; [
-
(weather.override {
-
# you can pass base_config as a string
-
base_config = ''
-
default_location: New York
-
default_units: M
-
default_language:
-
show_link: true
-
show_image: false
-
'';
-
})
-
];
```
6. Start Maubot at least once before doing the following steps (it's
necessary to generate the initial config).
···
2. If you want to use PostgreSQL instead of SQLite, do this:
```nix
+
{
+
services.maubot.settings.database = "postgresql://maubot@localhost/maubot";
+
}
```
If the PostgreSQL connection requires a password, you will have to
···
3. If you plan to expose your Maubot interface to the web, do something
like this:
```nix
+
{
+
services.nginx.virtualHosts."matrix.example.org".locations = {
+
"/_matrix/maubot/" = {
+
proxyPass = "http://127.0.0.1:${toString config.services.maubot.settings.server.port}";
+
proxyWebsockets = true;
+
};
};
+
services.maubot.settings.server.public_url = "matrix.example.org";
+
# do the following only if you want to use something other than /_matrix/maubot...
+
services.maubot.settings.server.ui_base_path = "/another/base/path";
+
}
```
4. Optionally, set `services.maubot.pythonPackages` to a list of python3
packages to make available for Maubot plugins.
5. Optionally, set `services.maubot.plugins` to a list of Maubot
plugins (full list available at https://plugins.maubot.xyz/):
```nix
+
{
+
services.maubot.plugins = with config.services.maubot.package.plugins; [
+
reactbot
+
# This will only change the default config! After you create a
+
# plugin instance, the default config will be copied into that
+
# instance's config in Maubot's database, and further base config
+
# changes won't affect the running plugin.
+
(rss.override {
+
base_config = {
+
update_interval = 60;
+
max_backoff = 7200;
+
spam_sleep = 2;
+
command_prefix = "rss";
+
admins = [ "@chayleaf:pavluk.org" ];
+
};
+
})
+
];
+
# ...or...
+
services.maubot.plugins = config.services.maubot.package.plugins.allOfficialPlugins;
+
# ...or...
+
services.maubot.plugins = config.services.maubot.package.plugins.allPlugins;
+
# ...or...
+
services.maubot.plugins = with config.services.maubot.package.plugins; [
+
(weather.override {
+
# you can pass base_config as a string
+
base_config = ''
+
default_location: New York
+
default_units: M
+
default_language:
+
show_link: true
+
show_image: false
+
'';
+
})
+
];
+
}
```
6. Start Maubot at least once before doing the following steps (it's
necessary to generate the initial config).
+18 -16
nixos/modules/services/misc/forgejo.md
···
Make sure to disable `services.gitea`, when doing this.
```nix
-
services.gitea.enable = false;
-
services.forgejo = {
-
enable = true;
-
user = "gitea";
-
group = "gitea";
-
stateDir = "/var/lib/gitea";
-
database.name = "gitea";
-
database.user = "gitea";
-
};
-
users.users.gitea = {
-
home = "/var/lib/gitea";
-
useDefaultShell = true;
-
group = "gitea";
-
isSystemUser = true;
-
};
-
users.groups.gitea = {};
```
···
Make sure to disable `services.gitea`, when doing this.
```nix
+
{
+
services.gitea.enable = false;
+
services.forgejo = {
+
enable = true;
+
user = "gitea";
+
group = "gitea";
+
stateDir = "/var/lib/gitea";
+
database.name = "gitea";
+
database.user = "gitea";
+
};
+
users.users.gitea = {
+
home = "/var/lib/gitea";
+
useDefaultShell = true;
+
group = "gitea";
+
isSystemUser = true;
+
};
+
users.groups.gitea = {};
+
}
```
+41 -37
nixos/modules/services/misc/gitlab.md
···
For instance, the following configuration could be used to use nginx as
frontend proxy:
```nix
-
services.nginx = {
-
enable = true;
-
recommendedGzipSettings = true;
-
recommendedOptimisation = true;
-
recommendedProxySettings = true;
-
recommendedTlsSettings = true;
-
virtualHosts."git.example.com" = {
-
enableACME = true;
-
forceSSL = true;
-
locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";
};
-
};
```
## Configuring {#module-services-gitlab-configuring}
···
A basic configuration with some custom settings could look like this:
```nix
-
services.gitlab = {
-
enable = true;
-
databasePasswordFile = "/var/keys/gitlab/db_password";
-
initialRootPasswordFile = "/var/keys/gitlab/root_password";
-
https = true;
-
host = "git.example.com";
-
port = 443;
-
user = "git";
-
group = "git";
-
smtp = {
enable = true;
-
address = "localhost";
-
port = 25;
-
};
-
secrets = {
-
dbFile = "/var/keys/gitlab/db";
-
secretFile = "/var/keys/gitlab/secret";
-
otpFile = "/var/keys/gitlab/otp";
-
jwsFile = "/var/keys/gitlab/jws";
-
};
-
extraConfig = {
-
gitlab = {
-
email_from = "gitlab-no-reply@example.com";
-
email_display_name = "Example GitLab";
-
email_reply_to = "gitlab-no-reply@example.com";
-
default_projects_features = { builds = false; };
};
};
-
};
```
If you're setting up a new GitLab instance, generate new
···
For instance, the following configuration could be used to use nginx as
frontend proxy:
```nix
+
{
+
services.nginx = {
+
enable = true;
+
recommendedGzipSettings = true;
+
recommendedOptimisation = true;
+
recommendedProxySettings = true;
+
recommendedTlsSettings = true;
+
virtualHosts."git.example.com" = {
+
enableACME = true;
+
forceSSL = true;
+
locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";
+
};
};
+
}
```
## Configuring {#module-services-gitlab-configuring}
···
A basic configuration with some custom settings could look like this:
```nix
+
{
+
services.gitlab = {
enable = true;
+
databasePasswordFile = "/var/keys/gitlab/db_password";
+
initialRootPasswordFile = "/var/keys/gitlab/root_password";
+
https = true;
+
host = "git.example.com";
+
port = 443;
+
user = "git";
+
group = "git";
+
smtp = {
+
enable = true;
+
address = "localhost";
+
port = 25;
+
};
+
secrets = {
+
dbFile = "/var/keys/gitlab/db";
+
secretFile = "/var/keys/gitlab/secret";
+
otpFile = "/var/keys/gitlab/otp";
+
jwsFile = "/var/keys/gitlab/jws";
+
};
+
extraConfig = {
+
gitlab = {
+
email_from = "gitlab-no-reply@example.com";
+
email_display_name = "Example GitLab";
+
email_reply_to = "gitlab-no-reply@example.com";
+
default_projects_features = { builds = false; };
+
};
};
};
+
}
```
If you're setting up a new GitLab instance, generate new
+3 -3
nixos/modules/services/misc/sourcehut/default.md
···
# Settings to setup what certificates are used for which endpoint.
virtualHosts = {
"${fqdn}".enableACME = true;
-
"meta.${fqdn}".useACMEHost = fqdn:
-
"man.${fqdn}".useACMEHost = fqdn:
-
"git.${fqdn}".useACMEHost = fqdn:
};
};
}
···
# Settings to setup what certificates are used for which endpoint.
virtualHosts = {
"${fqdn}".enableACME = true;
+
"meta.${fqdn}".useACMEHost = fqdn;
+
"man.${fqdn}".useACMEHost = fqdn;
+
"git.${fqdn}".useACMEHost = fqdn;
};
};
}
+26 -22
nixos/modules/services/monitoring/certspotter.md
···
domain would look as follows:
```nix
-
services.certspotter = {
-
enable = true;
-
# replace example.org with your domain name
-
watchlist = [ ".example.org" ];
-
emailRecipients = [ "webmaster@example.org" ];
-
};
-
# Configure an SMTP client
-
programs.msmtp.enable = true;
-
# Or you can use any other module that provides sendmail, like
-
# services.nullmailer, services.opensmtpd, services.postfix
```
In this case, the leading dot in `".example.org"` means that Cert
···
notifications manually using the following hook:
```nix
-
services.certspotter.hooks = [
-
(pkgs.writeShellScript "certspotter-hook" ''
-
function print_email() {
-
echo "Subject: [certspotter] $SUMMARY"
-
echo "Mime-Version: 1.0"
-
echo "Content-Type: text/plain; charset=US-ASCII"
-
echo
-
cat "$TEXT_FILENAME"
-
}
-
print_email | ${config.services.certspotter.sendmailPath} -i webmaster@example.org
-
'')
-
];
```
···
domain would look as follows:
```nix
+
{
+
services.certspotter = {
+
enable = true;
+
# replace example.org with your domain name
+
watchlist = [ ".example.org" ];
+
emailRecipients = [ "webmaster@example.org" ];
+
};
+
# Configure an SMTP client
+
programs.msmtp.enable = true;
+
# Or you can use any other module that provides sendmail, like
+
# services.nullmailer, services.opensmtpd, services.postfix
+
}
```
In this case, the leading dot in `".example.org"` means that Cert
···
notifications manually using the following hook:
```nix
+
{
+
services.certspotter.hooks = [
+
(pkgs.writeShellScript "certspotter-hook" ''
+
function print_email() {
+
echo "Subject: [certspotter] $SUMMARY"
+
echo "Mime-Version: 1.0"
+
echo "Content-Type: text/plain; charset=US-ASCII"
+
echo
+
cat "$TEXT_FILENAME"
+
}
+
print_email | ${config.services.certspotter.sendmailPath} -i webmaster@example.org
+
'')
+
];
+
}
```
+65 -59
nixos/modules/services/monitoring/parsedmarc.md
···
like this:
```nix
-
services.parsedmarc = {
-
enable = true;
-
settings.imap = {
-
host = "imap.example.com";
-
user = "alice@example.com";
-
password = "/path/to/imap_password_file";
};
-
provision.geoIp = false; # Not recommended!
-
};
```
Note that GeoIP provisioning is disabled in the example for
···
`dmarc@monitoring.example.com`.
```nix
-
services.parsedmarc = {
-
enable = true;
-
provision = {
-
localMail = {
-
enable = true;
-
hostname = monitoring.example.com;
};
-
geoIp = false; # Not recommended!
};
-
};
```
## Grafana and GeoIP {#module-services-parsedmarc-grafana-geoip}
···
added to Grafana as well.
```nix
-
services.parsedmarc = {
-
enable = true;
-
provision = {
-
localMail = {
-
enable = true;
-
hostname = url;
-
};
-
grafana = {
-
datasource = true;
-
dashboard = true;
};
};
-
};
-
# Not required, but recommended for full functionality
-
services.geoipupdate = {
-
settings = {
-
AccountID = 000000;
-
LicenseKey = "/path/to/license_key_file";
};
-
};
-
services.grafana = {
-
enable = true;
-
addr = "0.0.0.0";
-
domain = url;
-
rootUrl = "https://" + url;
-
protocol = "socket";
-
security = {
-
adminUser = "admin";
-
adminPasswordFile = "/path/to/admin_password_file";
-
secretKeyFile = "/path/to/secret_key_file";
};
-
};
-
services.nginx = {
-
enable = true;
-
recommendedTlsSettings = true;
-
recommendedOptimisation = true;
-
recommendedGzipSettings = true;
-
recommendedProxySettings = true;
-
upstreams.grafana.servers."unix:/${config.services.grafana.socket}" = {};
-
virtualHosts.${url} = {
-
root = config.services.grafana.staticRootPath;
-
enableACME = true;
-
forceSSL = true;
-
locations."/".tryFiles = "$uri @grafana";
-
locations."@grafana".proxyPass = "http://grafana";
};
-
};
-
users.users.nginx.extraGroups = [ "grafana" ];
```
···
like this:
```nix
+
{
+
services.parsedmarc = {
+
enable = true;
+
settings.imap = {
+
host = "imap.example.com";
+
user = "alice@example.com";
+
password = "/path/to/imap_password_file";
+
};
+
provision.geoIp = false; # Not recommended!
};
+
}
```
Note that GeoIP provisioning is disabled in the example for
···
`dmarc@monitoring.example.com`.
```nix
+
{
+
services.parsedmarc = {
+
enable = true;
+
provision = {
+
localMail = {
+
enable = true;
+
hostname = monitoring.example.com;
+
};
+
geoIp = false; # Not recommended!
};
};
+
}
```
## Grafana and GeoIP {#module-services-parsedmarc-grafana-geoip}
···
added to Grafana as well.
```nix
+
{
+
services.parsedmarc = {
+
enable = true;
+
provision = {
+
localMail = {
+
enable = true;
+
hostname = url;
+
};
+
grafana = {
+
datasource = true;
+
dashboard = true;
+
};
};
};
+
# Not required, but recommended for full functionality
+
services.geoipupdate = {
+
settings = {
+
AccountID = 000000;
+
LicenseKey = "/path/to/license_key_file";
+
};
};
+
services.grafana = {
+
enable = true;
+
addr = "0.0.0.0";
+
domain = url;
+
rootUrl = "https://" + url;
+
protocol = "socket";
+
security = {
+
adminUser = "admin";
+
adminPasswordFile = "/path/to/admin_password_file";
+
secretKeyFile = "/path/to/secret_key_file";
+
};
};
+
services.nginx = {
+
enable = true;
+
recommendedTlsSettings = true;
+
recommendedOptimisation = true;
+
recommendedGzipSettings = true;
+
recommendedProxySettings = true;
+
upstreams.grafana.servers."unix:/${config.services.grafana.socket}" = {};
+
virtualHosts.${url} = {
+
root = config.services.grafana.staticRootPath;
+
enableACME = true;
+
forceSSL = true;
+
locations."/".tryFiles = "$uri @grafana";
+
locations."@grafana".proxyPass = "http://grafana";
+
};
};
+
users.users.nginx.extraGroups = [ "grafana" ];
+
}
```
+5 -1
nixos/modules/services/monitoring/prometheus/exporters.md
···
it provides hardware and OS metrics from the host it's
running on. The exporter could be configured as follows:
```nix
services.prometheus.exporters.node = {
enable = true;
port = 9100;
···
openFirewall = true;
firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
};
```
It should now serve all metrics from the collectors that are explicitly
enabled and the ones that are
···
Prometheus can now be configured to consume the metrics produced by the exporter:
```nix
services.prometheus = {
# ...
···
];
# ...
-
}
```
## Adding a new exporter {#module-services-prometheus-exporters-new-exporter}
···
it provides hardware and OS metrics from the host it's
running on. The exporter could be configured as follows:
```nix
+
{
services.prometheus.exporters.node = {
enable = true;
port = 9100;
···
openFirewall = true;
firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
};
+
}
```
It should now serve all metrics from the collectors that are explicitly
enabled and the ones that are
···
Prometheus can now be configured to consume the metrics produced by the exporter:
```nix
+
{
services.prometheus = {
# ...
···
];
# ...
+
};
+
}
```
## Adding a new exporter {#module-services-prometheus-exporters-new-exporter}
+12 -10
nixos/modules/services/networking/firefox-syncserver.md
···
The absolute minimal configuration for the sync server looks like this:
```nix
-
services.mysql.package = pkgs.mariadb;
-
services.firefox-syncserver = {
-
enable = true;
-
secrets = builtins.toFile "sync-secrets" ''
-
SYNC_MASTER_SECRET=this-secret-is-actually-leaked-to-/nix/store
-
'';
-
singleNode = {
enable = true;
-
hostname = "localhost";
-
url = "http://localhost:5000";
};
-
};
```
This will start a sync server that is only accessible locally. Once the services is
···
The absolute minimal configuration for the sync server looks like this:
```nix
+
{
+
services.mysql.package = pkgs.mariadb;
+
services.firefox-syncserver = {
enable = true;
+
secrets = builtins.toFile "sync-secrets" ''
+
SYNC_MASTER_SECRET=this-secret-is-actually-leaked-to-/nix/store
+
'';
+
singleNode = {
+
enable = true;
+
hostname = "localhost";
+
url = "http://localhost:5000";
+
};
};
+
}
```
This will start a sync server that is only accessible locally. Once the services is
+40 -33
nixos/modules/services/networking/mosquitto.md
···
A minimal configuration for Mosquitto is
```nix
-
services.mosquitto = {
-
enable = true;
-
listeners = [ {
-
acl = [ "pattern readwrite #" ];
-
omitPasswordAuth = true;
-
settings.allow_anonymous = true;
-
} ];
-
};
```
This will start a broker on port 1883, listening on all interfaces of the machine, allowing
···
like
```nix
-
services.mosquitto = {
-
enable = true;
-
listeners = [ {
-
users = {
-
monitor = {
-
acl = [ "read #" ];
-
password = "monitor";
};
-
service = {
-
acl = [ "write service/#" ];
-
password = "service";
-
};
-
};
-
} ];
-
};
```
TLS authentication is configured by setting TLS-related options of the listener:
```nix
-
services.mosquitto = {
-
enable = true;
-
listeners = [ {
-
port = 8883; # port change is not required, but helpful to avoid mistakes
-
# ...
-
settings = {
-
cafile = "/path/to/mqtt.ca.pem";
-
certfile = "/path/to/mqtt.pem";
-
keyfile = "/path/to/mqtt.key";
-
};
-
} ];
```
## Configuration {#module-services-mosquitto-config}
···
A minimal configuration for Mosquitto is
```nix
+
{
+
services.mosquitto = {
+
enable = true;
+
listeners = [ {
+
acl = [ "pattern readwrite #" ];
+
omitPasswordAuth = true;
+
settings.allow_anonymous = true;
+
} ];
+
};
+
}
```
This will start a broker on port 1883, listening on all interfaces of the machine, allowing
···
like
```nix
+
{
+
services.mosquitto = {
+
enable = true;
+
listeners = [ {
+
users = {
+
monitor = {
+
acl = [ "read #" ];
+
password = "monitor";
+
};
+
service = {
+
acl = [ "write service/#" ];
+
password = "service";
+
};
};
+
} ];
+
};
+
}
```
TLS authentication is configured by setting TLS-related options of the listener:
```nix
+
{
+
services.mosquitto = {
+
enable = true;
+
listeners = [ {
+
port = 8883; # port change is not required, but helpful to avoid mistakes
+
# ...
+
settings = {
+
cafile = "/path/to/mqtt.ca.pem";
+
certfile = "/path/to/mqtt.pem";
+
keyfile = "/path/to/mqtt.key";
+
};
+
} ];
+
};
+
}
```
## Configuration {#module-services-mosquitto-config}
+17 -9
nixos/modules/services/networking/netbird.md
···
The absolute minimal configuration for the netbird daemon looks like this:
```nix
-
services.netbird.enable = true;
```
This will set up a netbird service listening on the port `51820` associated to the
···
It is strictly equivalent to setting:
```nix
-
services.netbird.tunnels.wt0.stateDir = "netbird";
```
The `enable` option is mainly kept for backward compatibility, as defining netbird
···
the port 51830. Its configuration file will then be located at `/var/lib/netbird-wt1/config.json`.
```nix
-
services.netbird.tunnels = {
-
wt1 = {
-
port = 51830;
};
-
};
```
To interact with it, you will need to specify the correct daemon address:
···
example:
```nix
-
services.netbird.tunnels.wt1.environment = {
-
NB_DAEMON_ADDR = "unix:///var/run/toto.sock"
-
};
```
This will set the socket to interact with the netbird service to `/var/run/toto.sock`.
···
The absolute minimal configuration for the netbird daemon looks like this:
```nix
+
{
+
services.netbird.enable = true;
+
}
```
This will set up a netbird service listening on the port `51820` associated to the
···
It is strictly equivalent to setting:
```nix
+
{
+
services.netbird.tunnels.wt0.stateDir = "netbird";
+
}
```
The `enable` option is mainly kept for backward compatibility, as defining netbird
···
the port 51830. Its configuration file will then be located at `/var/lib/netbird-wt1/config.json`.
```nix
+
{
+
services.netbird.tunnels = {
+
wt1 = {
+
port = 51830;
+
};
};
+
}
```
To interact with it, you will need to specify the correct daemon address:
···
example:
```nix
+
{
+
services.netbird.tunnels.wt1.environment = {
+
NB_DAEMON_ADDR = "unix:///var/run/toto.sock";
+
};
+
}
```
This will set the socket to interact with the netbird service to `/var/run/toto.sock`.
+84 -78
nixos/modules/services/networking/pleroma.md
···
First, the Postgresql service must be enabled in the NixOS configuration
```nix
-
services.postgresql = {
-
enable = true;
-
package = pkgs.postgresql_13;
-
};
```
and activated with the usual
```ShellSession
···
This is an example of configuration, where [](#opt-services.pleroma.configs) option contains the content of the file `config.exs`, generated [in the first section](#module-services-pleroma-generate-config), but with the secrets (database password, endpoint secret key, salts, etc.) removed. Removing secrets is important, because otherwise they will be stored publicly in the Nix store.
```nix
-
services.pleroma = {
-
enable = true;
-
secretConfigFile = "/var/lib/pleroma/secrets.exs";
-
configs = [
-
''
-
import Config
-
config :pleroma, Pleroma.Web.Endpoint,
-
url: [host: "pleroma.example.net", scheme: "https", port: 443],
-
http: [ip: {127, 0, 0, 1}, port: 4000]
-
config :pleroma, :instance,
-
name: "Test",
-
email: "admin@example.net",
-
notify_email: "admin@example.net",
-
limit: 5000,
-
registrations_open: true
-
config :pleroma, :media_proxy,
-
enabled: false,
-
redirect_on_failure: true
-
config :pleroma, Pleroma.Repo,
-
adapter: Ecto.Adapters.Postgres,
-
username: "pleroma",
-
database: "pleroma",
-
hostname: "localhost"
-
# Configure web push notifications
-
config :web_push_encryption, :vapid_details,
-
subject: "mailto:admin@example.net"
-
# ... TO CONTINUE ...
-
''
-
];
-
};
```
Secrets must be moved into a file pointed by [](#opt-services.pleroma.secretConfigFile), in our case `/var/lib/pleroma/secrets.exs`. This file can be created copying the previously generated `config.exs` file and then removing all the settings, except the secrets. This is an example
···
In this configuration, Pleroma is listening only on the local port 4000. Nginx can be configured as a Reverse Proxy, for forwarding requests from public ports to the Pleroma service. This is an example of configuration, using
[Let's Encrypt](https://letsencrypt.org/) for the TLS certificates
```nix
-
security.acme = {
-
email = "root@example.net";
-
acceptTerms = true;
-
};
-
services.nginx = {
-
enable = true;
-
addSSL = true;
-
recommendedTlsSettings = true;
-
recommendedOptimisation = true;
-
recommendedGzipSettings = true;
-
recommendedProxySettings = false;
-
# NOTE: if enabled, the NixOS proxy optimizations will override the Pleroma
-
# specific settings, and they will enter in conflict.
-
virtualHosts = {
-
"pleroma.example.net" = {
-
http2 = true;
-
enableACME = true;
-
forceSSL = true;
-
locations."/" = {
-
proxyPass = "http://127.0.0.1:4000";
-
extraConfig = ''
-
etag on;
-
gzip on;
-
add_header 'Access-Control-Allow-Origin' '*' always;
-
add_header 'Access-Control-Allow-Methods' 'POST, PUT, DELETE, GET, PATCH, OPTIONS' always;
-
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Idempotency-Key' always;
-
add_header 'Access-Control-Expose-Headers' 'Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id' always;
-
if ($request_method = OPTIONS) {
-
return 204;
-
}
-
add_header X-XSS-Protection "1; mode=block";
-
add_header X-Permitted-Cross-Domain-Policies none;
-
add_header X-Frame-Options DENY;
-
add_header X-Content-Type-Options nosniff;
-
add_header Referrer-Policy same-origin;
-
add_header X-Download-Options noopen;
-
proxy_http_version 1.1;
-
proxy_set_header Upgrade $http_upgrade;
-
proxy_set_header Connection "upgrade";
-
proxy_set_header Host $host;
-
client_max_body_size 16m;
-
# NOTE: increase if users need to upload very big files
-
'';
};
};
};
-
};
```
···
First, the Postgresql service must be enabled in the NixOS configuration
```nix
+
{
+
services.postgresql = {
+
enable = true;
+
package = pkgs.postgresql_13;
+
};
+
}
```
and activated with the usual
```ShellSession
···
This is an example of configuration, where [](#opt-services.pleroma.configs) option contains the content of the file `config.exs`, generated [in the first section](#module-services-pleroma-generate-config), but with the secrets (database password, endpoint secret key, salts, etc.) removed. Removing secrets is important, because otherwise they will be stored publicly in the Nix store.
```nix
+
{
+
services.pleroma = {
+
enable = true;
+
secretConfigFile = "/var/lib/pleroma/secrets.exs";
+
configs = [
+
''
+
import Config
+
config :pleroma, Pleroma.Web.Endpoint,
+
url: [host: "pleroma.example.net", scheme: "https", port: 443],
+
http: [ip: {127, 0, 0, 1}, port: 4000]
+
config :pleroma, :instance,
+
name: "Test",
+
email: "admin@example.net",
+
notify_email: "admin@example.net",
+
limit: 5000,
+
registrations_open: true
+
config :pleroma, :media_proxy,
+
enabled: false,
+
redirect_on_failure: true
+
config :pleroma, Pleroma.Repo,
+
adapter: Ecto.Adapters.Postgres,
+
username: "pleroma",
+
database: "pleroma",
+
hostname: "localhost"
+
# Configure web push notifications
+
config :web_push_encryption, :vapid_details,
+
subject: "mailto:admin@example.net"
+
# ... TO CONTINUE ...
+
''
+
];
+
};
+
}
```
Secrets must be moved into a file pointed by [](#opt-services.pleroma.secretConfigFile), in our case `/var/lib/pleroma/secrets.exs`. This file can be created copying the previously generated `config.exs` file and then removing all the settings, except the secrets. This is an example
···
In this configuration, Pleroma is listening only on the local port 4000. Nginx can be configured as a Reverse Proxy, for forwarding requests from public ports to the Pleroma service. This is an example of configuration, using
[Let's Encrypt](https://letsencrypt.org/) for the TLS certificates
```nix
+
{
+
security.acme = {
+
email = "root@example.net";
+
acceptTerms = true;
+
};
+
services.nginx = {
+
enable = true;
+
addSSL = true;
+
recommendedTlsSettings = true;
+
recommendedOptimisation = true;
+
recommendedGzipSettings = true;
+
recommendedProxySettings = false;
+
# NOTE: if enabled, the NixOS proxy optimizations will override the Pleroma
+
# specific settings, and they will enter in conflict.
+
virtualHosts = {
+
"pleroma.example.net" = {
+
http2 = true;
+
enableACME = true;
+
forceSSL = true;
+
locations."/" = {
+
proxyPass = "http://127.0.0.1:4000";
+
extraConfig = ''
+
etag on;
+
gzip on;
+
add_header 'Access-Control-Allow-Origin' '*' always;
+
add_header 'Access-Control-Allow-Methods' 'POST, PUT, DELETE, GET, PATCH, OPTIONS' always;
+
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Idempotency-Key' always;
+
add_header 'Access-Control-Expose-Headers' 'Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id' always;
+
if ($request_method = OPTIONS) {
+
return 204;
+
}
+
add_header X-XSS-Protection "1; mode=block";
+
add_header X-Permitted-Cross-Domain-Policies none;
+
add_header X-Frame-Options DENY;
+
add_header X-Content-Type-Options nosniff;
+
add_header Referrer-Policy same-origin;
+
add_header X-Download-Options noopen;
+
proxy_http_version 1.1;
+
proxy_set_header Upgrade $http_upgrade;
+
proxy_set_header Connection "upgrade";
+
proxy_set_header Host $host;
+
client_max_body_size 16m;
+
# NOTE: increase if users need to upload very big files
+
'';
+
};
};
};
};
+
}
```
+30 -26
nixos/modules/services/networking/prosody.md
···
endpoint as well as a [HTTP File Upload](https://xmpp.org/extensions/xep-0363.html)
endpoint will look like this:
```nix
-
services.prosody = {
-
enable = true;
-
admins = [ "root@example.org" ];
-
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
-
ssl.key = "/var/lib/acme/example.org/key.pem";
-
virtualHosts."example.org" = {
-
enabled = true;
-
domain = "example.org";
-
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
-
ssl.key = "/var/lib/acme/example.org/key.pem";
-
};
-
muc = [ {
-
domain = "conference.example.org";
-
} ];
-
uploadHttp = {
-
domain = "upload.example.org";
};
-
};
```
## Let's Encrypt Configuration {#module-services-prosody-letsencrypt}
···
Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
a TLS certificate for the three endponits:
```nix
-
security.acme = {
-
email = "root@example.org";
-
acceptTerms = true;
-
certs = {
-
"example.org" = {
-
webroot = "/var/www/example.org";
-
email = "root@example.org";
-
extraDomainNames = [ "conference.example.org" "upload.example.org" ];
};
};
-
};
```
···
endpoint as well as a [HTTP File Upload](https://xmpp.org/extensions/xep-0363.html)
endpoint will look like this:
```nix
+
{
+
services.prosody = {
+
enable = true;
+
admins = [ "root@example.org" ];
+
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
+
ssl.key = "/var/lib/acme/example.org/key.pem";
+
virtualHosts."example.org" = {
+
enabled = true;
+
domain = "example.org";
+
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
+
ssl.key = "/var/lib/acme/example.org/key.pem";
+
};
+
muc = [ {
+
domain = "conference.example.org";
+
} ];
+
uploadHttp = {
+
domain = "upload.example.org";
+
};
};
+
}
```
## Let's Encrypt Configuration {#module-services-prosody-letsencrypt}
···
Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
a TLS certificate for the three endponits:
```nix
+
{
+
security.acme = {
+
email = "root@example.org";
+
acceptTerms = true;
+
certs = {
+
"example.org" = {
+
webroot = "/var/www/example.org";
+
email = "root@example.org";
+
extraDomainNames = [ "conference.example.org" "upload.example.org" ];
+
};
};
};
+
}
```
+3 -1
nixos/modules/services/search/meilisearch.md
···
the minimum to start meilisearch is
```nix
-
services.meilisearch.enable = true;
```
this will start the http server included with meilisearch on port 7700.
···
the minimum to start meilisearch is
```nix
+
{
+
services.meilisearch.enable = true;
+
}
```
this will start the http server included with meilisearch on port 7700.
+137 -117
nixos/modules/services/web-apps/akkoma.md
···
```nix
-
services.akkoma.enable = true;
-
services.akkoma.config = {
-
":pleroma" = {
-
":instance" = {
-
name = "My Akkoma instance";
-
description = "More detailed description";
-
email = "admin@example.com";
-
registration_open = false;
-
};
-
"Pleroma.Web.Endpoint" = {
-
url.host = "fediverse.example.com";
};
};
-
};
```
Please refer to the [configuration cheat sheet](https://docs.akkoma.dev/stable/configuration/cheatsheet/)
···
HTTP reverse proxy such as nginx.
```nix
-
services.akkoma.nginx = {
-
enableACME = true;
-
forceSSL = true;
-
};
-
services.nginx = {
-
enable = true;
-
clientMaxBodySize = "16m";
-
recommendedTlsSettings = true;
-
recommendedOptimisation = true;
-
recommendedGzipSettings = true;
-
};
```
Please refer to [](#module-security-acme) for details on how to provision an SSL/TLS certificate.
···
locally, and clients have to fetch them directly from the source server.
```nix
-
# Enable nginx slice module distributed with Tengine
-
services.nginx.package = pkgs.tengine;
-
# Enable media proxy
-
services.akkoma.config.":pleroma".":media_proxy" = {
-
enabled = true;
-
proxy_opts.redirect_on_failure = true;
-
};
-
# Adjust the persistent cache size as needed:
-
# Assuming an average object size of 128 KiB, around 1 MiB
-
# of memory is required for the key zone per GiB of cache.
-
# Ensure that the cache directory exists and is writable by nginx.
-
services.nginx.commonHttpConfig = ''
-
proxy_cache_path /var/cache/nginx/cache/akkoma-media-cache
-
levels= keys_zone=akkoma_media_cache:16m max_size=16g
-
inactive=1y use_temp_path=off;
-
'';
-
services.akkoma.nginx = {
-
locations."/proxy" = {
-
proxyPass = "http://unix:/run/akkoma/socket";
-
extraConfig = ''
-
proxy_cache akkoma_media_cache;
-
# Cache objects in slices of 1 MiB
-
slice 1m;
-
proxy_cache_key $host$uri$is_args$args$slice_range;
-
proxy_set_header Range $slice_range;
-
# Decouple proxy and upstream responses
-
proxy_buffering on;
-
proxy_cache_lock on;
-
proxy_ignore_client_abort on;
-
# Default cache times for various responses
-
proxy_cache_valid 200 1y;
-
proxy_cache_valid 206 301 304 1h;
-
# Allow serving of stale items
-
proxy_cache_use_stale error timeout invalid_header updating;
-
'';
};
-
};
```
#### Prefetch remote media {#modules-services-akkoma-prefetch-remote-media}
···
received by the instance.
```nix
-
services.akkoma.config.":pleroma".":mrf".policies =
-
map (pkgs.formats.elixirConf { }).lib.mkRaw [
-
"Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy"
-
];
```
#### Media previews {#modules-services-akkoma-media-previews}
···
Akkoma can generate previews for media.
```nix
-
services.akkoma.config.":pleroma".":media_preview_proxy" = {
-
enabled = true;
-
thumbnail_max_width = 1920;
-
thumbnail_max_height = 1080;
-
};
```
## Frontend management {#modules-services-akkoma-frontend-management}
···
derivation.
```nix
-
services.akkoma.frontends.primary.package = pkgs.runCommand "akkoma-fe" {
-
config = builtins.toJSON {
-
expertLevel = 1;
-
collapseMessageWithSubject = false;
-
stopGifs = false;
-
replyVisibility = "following";
-
webPushHideIfCW = true;
-
hideScopeNotice = true;
-
renderMisskeyMarkdown = false;
-
hideSiteFavicon = true;
-
postContentType = "text/markdown";
-
showNavShortcuts = false;
-
};
-
nativeBuildInputs = with pkgs; [ jq xorg.lndir ];
-
passAsFile = [ "config" ];
-
} ''
-
mkdir $out
-
lndir ${pkgs.akkoma-frontends.akkoma-fe} $out
-
rm $out/static/config.json
-
jq -s add ${pkgs.akkoma-frontends.akkoma-fe}/static/config.json ${config} \
-
>$out/static/config.json
-
'';
```
## Federation policies {#modules-services-akkoma-federation-policies}
···
```nix
-
services.akkoma.config.":pleroma" = with (pkgs.formats.elixirConf { }).lib; {
-
":mrf".policies = map mkRaw [
-
"Pleroma.Web.ActivityPub.MRF.SimplePolicy"
-
];
-
":mrf_simple" = {
-
# Tag all media as sensitive
-
media_nsfw = mkMap {
-
"nsfw.weird.kinky" = "Untagged NSFW content";
-
};
-
# Reject all activities except deletes
-
reject = mkMap {
-
"kiwifarms.cc" = "Persistent harassment of users, no moderation";
-
};
-
# Force posts to be visible by followers only
-
followers_only = mkMap {
-
"beta.birdsite.live" = "Avoid polluting timelines with Twitter posts";
};
};
-
};
```
## Upload filters {#modules-services-akkoma-upload-filters}
···
the file name.
```nix
-
services.akkoma.config.":pleroma"."Pleroma.Upload".filters =
-
map (pkgs.formats.elixirConf { }).lib.mkRaw [
-
"Pleroma.Upload.Filter.Exiftool"
-
"Pleroma.Upload.Filter.Dedupe"
-
"Pleroma.Upload.Filter.AnonymizeFilename"
-
];
```
## Migration from Pleroma {#modules-services-akkoma-migration-pleroma}
···
Pleroma database and upload directory.
```nix
-
# Adjust these settings according to the database name and upload directory path used by Pleroma
-
services.akkoma.config.":pleroma"."Pleroma.Repo".database = "pleroma";
-
services.akkoma.config.":pleroma".":instance".upload_dir = "/var/lib/pleroma/uploads";
```
Please keep in mind that after the Akkoma service has been started, any migrations applied by
···
The Akkoma systemd service may be confined to a chroot with
```nix
-
services.systemd.akkoma.confinement.enable = true;
```
Confinement of services is not generally supported in NixOS and therefore disabled by default.
···
```nix
+
{
+
services.akkoma.enable = true;
+
services.akkoma.config = {
+
":pleroma" = {
+
":instance" = {
+
name = "My Akkoma instance";
+
description = "More detailed description";
+
email = "admin@example.com";
+
registration_open = false;
+
};
+
"Pleroma.Web.Endpoint" = {
+
url.host = "fediverse.example.com";
+
};
};
};
+
}
```
Please refer to the [configuration cheat sheet](https://docs.akkoma.dev/stable/configuration/cheatsheet/)
···
HTTP reverse proxy such as nginx.
```nix
+
{
+
services.akkoma.nginx = {
+
enableACME = true;
+
forceSSL = true;
+
};
+
services.nginx = {
+
enable = true;
+
clientMaxBodySize = "16m";
+
recommendedTlsSettings = true;
+
recommendedOptimisation = true;
+
recommendedGzipSettings = true;
+
};
+
}
```
Please refer to [](#module-security-acme) for details on how to provision an SSL/TLS certificate.
···
locally, and clients have to fetch them directly from the source server.
```nix
+
{
+
# Enable nginx slice module distributed with Tengine
+
services.nginx.package = pkgs.tengine;
+
# Enable media proxy
+
services.akkoma.config.":pleroma".":media_proxy" = {
+
enabled = true;
+
proxy_opts.redirect_on_failure = true;
+
};
+
# Adjust the persistent cache size as needed:
+
# Assuming an average object size of 128 KiB, around 1 MiB
+
# of memory is required for the key zone per GiB of cache.
+
# Ensure that the cache directory exists and is writable by nginx.
+
services.nginx.commonHttpConfig = ''
+
proxy_cache_path /var/cache/nginx/cache/akkoma-media-cache
+
levels= keys_zone=akkoma_media_cache:16m max_size=16g
+
inactive=1y use_temp_path=off;
+
'';
+
services.akkoma.nginx = {
+
locations."/proxy" = {
+
proxyPass = "http://unix:/run/akkoma/socket";
+
extraConfig = ''
+
proxy_cache akkoma_media_cache;
+
# Cache objects in slices of 1 MiB
+
slice 1m;
+
proxy_cache_key $host$uri$is_args$args$slice_range;
+
proxy_set_header Range $slice_range;
+
# Decouple proxy and upstream responses
+
proxy_buffering on;
+
proxy_cache_lock on;
+
proxy_ignore_client_abort on;
+
# Default cache times for various responses
+
proxy_cache_valid 200 1y;
+
proxy_cache_valid 206 301 304 1h;
+
# Allow serving of stale items
+
proxy_cache_use_stale error timeout invalid_header updating;
+
'';
+
};
};
+
}
```
#### Prefetch remote media {#modules-services-akkoma-prefetch-remote-media}
···
received by the instance.
```nix
+
{
+
services.akkoma.config.":pleroma".":mrf".policies =
+
map (pkgs.formats.elixirConf { }).lib.mkRaw [
+
"Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy"
+
];
+
}
```
#### Media previews {#modules-services-akkoma-media-previews}
···
Akkoma can generate previews for media.
```nix
+
{
+
services.akkoma.config.":pleroma".":media_preview_proxy" = {
+
enabled = true;
+
thumbnail_max_width = 1920;
+
thumbnail_max_height = 1080;
+
};
+
}
```
## Frontend management {#modules-services-akkoma-frontend-management}
···
derivation.
```nix
+
{
+
services.akkoma.frontends.primary.package = pkgs.runCommand "akkoma-fe" {
+
config = builtins.toJSON {
+
expertLevel = 1;
+
collapseMessageWithSubject = false;
+
stopGifs = false;
+
replyVisibility = "following";
+
webPushHideIfCW = true;
+
hideScopeNotice = true;
+
renderMisskeyMarkdown = false;
+
hideSiteFavicon = true;
+
postContentType = "text/markdown";
+
showNavShortcuts = false;
+
};
+
nativeBuildInputs = with pkgs; [ jq xorg.lndir ];
+
passAsFile = [ "config" ];
+
} ''
+
mkdir $out
+
lndir ${pkgs.akkoma-frontends.akkoma-fe} $out
+
rm $out/static/config.json
+
jq -s add ${pkgs.akkoma-frontends.akkoma-fe}/static/config.json ${config} \
+
>$out/static/config.json
+
'';
+
}
```
## Federation policies {#modules-services-akkoma-federation-policies}
···
```nix
+
{
+
services.akkoma.config.":pleroma" = with (pkgs.formats.elixirConf { }).lib; {
+
":mrf".policies = map mkRaw [
+
"Pleroma.Web.ActivityPub.MRF.SimplePolicy"
+
];
+
":mrf_simple" = {
+
# Tag all media as sensitive
+
media_nsfw = mkMap {
+
"nsfw.weird.kinky" = "Untagged NSFW content";
+
};
+
# Reject all activities except deletes
+
reject = mkMap {
+
"kiwifarms.cc" = "Persistent harassment of users, no moderation";
+
};
+
# Force posts to be visible by followers only
+
followers_only = mkMap {
+
"beta.birdsite.live" = "Avoid polluting timelines with Twitter posts";
+
};
};
};
+
}
```
## Upload filters {#modules-services-akkoma-upload-filters}
···
the file name.
```nix
+
{
+
services.akkoma.config.":pleroma"."Pleroma.Upload".filters =
+
map (pkgs.formats.elixirConf { }).lib.mkRaw [
+
"Pleroma.Upload.Filter.Exiftool"
+
"Pleroma.Upload.Filter.Dedupe"
+
"Pleroma.Upload.Filter.AnonymizeFilename"
+
];
+
}
```
## Migration from Pleroma {#modules-services-akkoma-migration-pleroma}
···
Pleroma database and upload directory.
```nix
+
{
+
# Adjust these settings according to the database name and upload directory path used by Pleroma
+
services.akkoma.config.":pleroma"."Pleroma.Repo".database = "pleroma";
+
services.akkoma.config.":pleroma".":instance".upload_dir = "/var/lib/pleroma/uploads";
+
}
```
Please keep in mind that after the Akkoma service has been started, any migrations applied by
···
The Akkoma systemd service may be confined to a chroot with
```nix
+
{
+
services.systemd.akkoma.confinement.enable = true;
+
}
```
Confinement of services is not generally supported in NixOS and therefore disabled by default.
+114 -104
nixos/modules/services/web-apps/discourse.md
···
A minimal configuration using Let's Encrypt for TLS certificates looks like this:
```nix
-
services.discourse = {
-
enable = true;
-
hostname = "discourse.example.com";
-
admin = {
-
email = "admin@example.com";
-
username = "admin";
-
fullName = "Administrator";
-
passwordFile = "/path/to/password_file";
};
-
secretKeyBaseFile = "/path/to/secret_key_base_file";
-
};
-
security.acme.email = "me@example.com";
-
security.acme.acceptTerms = true;
```
Provided a proper DNS setup, you'll be able to connect to the
···
options:
```nix
-
services.discourse = {
-
enable = true;
-
hostname = "discourse.example.com";
-
sslCertificate = "/path/to/ssl_certificate";
-
sslCertificateKey = "/path/to/ssl_certificate_key";
-
admin = {
-
email = "admin@example.com";
-
username = "admin";
-
fullName = "Administrator";
-
passwordFile = "/path/to/password_file";
};
-
secretKeyBaseFile = "/path/to/secret_key_base_file";
-
};
```
## Database access {#module-services-discourse-database}
···
email domain can be done like this:
```nix
-
services.discourse = {
-
enable = true;
-
hostname = "discourse.example.com";
-
sslCertificate = "/path/to/ssl_certificate";
-
sslCertificateKey = "/path/to/ssl_certificate_key";
-
admin = {
-
email = "admin@example.com";
-
username = "admin";
-
fullName = "Administrator";
-
passwordFile = "/path/to/password_file";
};
-
mail.outgoing = {
-
serverAddress = "smtp.emailprovider.com";
-
port = 587;
-
username = "user@emailprovider.com";
-
passwordFile = "/path/to/smtp_password_file";
-
};
-
mail.incoming.enable = true;
-
secretKeyBaseFile = "/path/to/secret_key_base_file";
-
};
```
This assumes you have set up an MX record for the address you've
···
GitHub login in the site settings,
and changes a few request limits in the backend settings:
```nix
-
services.discourse = {
-
enable = true;
-
hostname = "discourse.example.com";
-
sslCertificate = "/path/to/ssl_certificate";
-
sslCertificateKey = "/path/to/ssl_certificate_key";
-
admin = {
-
email = "admin@example.com";
-
username = "admin";
-
fullName = "Administrator";
-
passwordFile = "/path/to/password_file";
-
};
-
mail.outgoing = {
-
serverAddress = "smtp.emailprovider.com";
-
port = 587;
-
username = "user@emailprovider.com";
-
passwordFile = "/path/to/smtp_password_file";
-
};
-
mail.incoming.enable = true;
-
siteSettings = {
-
required = {
-
title = "My Cats";
-
site_description = "Discuss My Cats (and be nice plz)";
};
-
login = {
-
enable_github_logins = true;
-
github_client_id = "a2f6dfe838cb3206ce20";
-
github_client_secret._secret = /run/keys/discourse_github_client_secret;
};
};
-
backendSettings = {
-
max_reqs_per_ip_per_minute = 300;
-
max_reqs_per_ip_per_10_seconds = 60;
-
max_asset_reqs_per_ip_per_10_seconds = 250;
-
max_reqs_per_ip_mode = "warn+block";
-
};
-
secretKeyBaseFile = "/path/to/secret_key_base_file";
-
};
```
In the resulting site settings file, the
···
by default:
```nix
-
services.discourse = {
-
enable = true;
-
hostname = "discourse.example.com";
-
sslCertificate = "/path/to/ssl_certificate";
-
sslCertificateKey = "/path/to/ssl_certificate_key";
-
admin = {
-
email = "admin@example.com";
-
username = "admin";
-
fullName = "Administrator";
-
passwordFile = "/path/to/password_file";
-
};
-
mail.outgoing = {
-
serverAddress = "smtp.emailprovider.com";
-
port = 587;
-
username = "user@emailprovider.com";
-
passwordFile = "/path/to/smtp_password_file";
-
};
-
mail.incoming.enable = true;
-
plugins = with config.services.discourse.package.plugins; [
-
discourse-spoiler-alert
-
discourse-solved
-
];
-
siteSettings = {
-
plugins = {
-
spoiler_enabled = false;
};
};
-
secretKeyBaseFile = "/path/to/secret_key_base_file";
-
};
```
···
A minimal configuration using Let's Encrypt for TLS certificates looks like this:
```nix
+
{
+
services.discourse = {
+
enable = true;
+
hostname = "discourse.example.com";
+
admin = {
+
email = "admin@example.com";
+
username = "admin";
+
fullName = "Administrator";
+
passwordFile = "/path/to/password_file";
+
};
+
secretKeyBaseFile = "/path/to/secret_key_base_file";
};
+
security.acme.email = "me@example.com";
+
security.acme.acceptTerms = true;
+
}
```
Provided a proper DNS setup, you'll be able to connect to the
···
options:
```nix
+
{
+
services.discourse = {
+
enable = true;
+
hostname = "discourse.example.com";
+
sslCertificate = "/path/to/ssl_certificate";
+
sslCertificateKey = "/path/to/ssl_certificate_key";
+
admin = {
+
email = "admin@example.com";
+
username = "admin";
+
fullName = "Administrator";
+
passwordFile = "/path/to/password_file";
+
};
+
secretKeyBaseFile = "/path/to/secret_key_base_file";
};
+
}
```
## Database access {#module-services-discourse-database}
···
email domain can be done like this:
```nix
+
{
+
services.discourse = {
+
enable = true;
+
hostname = "discourse.example.com";
+
sslCertificate = "/path/to/ssl_certificate";
+
sslCertificateKey = "/path/to/ssl_certificate_key";
+
admin = {
+
email = "admin@example.com";
+
username = "admin";
+
fullName = "Administrator";
+
passwordFile = "/path/to/password_file";
+
};
+
mail.outgoing = {
+
serverAddress = "smtp.emailprovider.com";
+
port = 587;
+
username = "user@emailprovider.com";
+
passwordFile = "/path/to/smtp_password_file";
+
};
+
mail.incoming.enable = true;
+
secretKeyBaseFile = "/path/to/secret_key_base_file";
};
+
}
```
This assumes you have set up an MX record for the address you've
···
GitHub login in the site settings,
and changes a few request limits in the backend settings:
```nix
+
{
+
services.discourse = {
+
enable = true;
+
hostname = "discourse.example.com";
+
sslCertificate = "/path/to/ssl_certificate";
+
sslCertificateKey = "/path/to/ssl_certificate_key";
+
admin = {
+
email = "admin@example.com";
+
username = "admin";
+
fullName = "Administrator";
+
passwordFile = "/path/to/password_file";
+
};
+
mail.outgoing = {
+
serverAddress = "smtp.emailprovider.com";
+
port = 587;
+
username = "user@emailprovider.com";
+
passwordFile = "/path/to/smtp_password_file";
+
};
+
mail.incoming.enable = true;
+
siteSettings = {
+
required = {
+
title = "My Cats";
+
site_description = "Discuss My Cats (and be nice plz)";
+
};
+
login = {
+
enable_github_logins = true;
+
github_client_id = "a2f6dfe838cb3206ce20";
+
github_client_secret._secret = /run/keys/discourse_github_client_secret;
+
};
};
+
backendSettings = {
+
max_reqs_per_ip_per_minute = 300;
+
max_reqs_per_ip_per_10_seconds = 60;
+
max_asset_reqs_per_ip_per_10_seconds = 250;
+
max_reqs_per_ip_mode = "warn+block";
};
+
secretKeyBaseFile = "/path/to/secret_key_base_file";
};
+
}
```
In the resulting site settings file, the
···
by default:
```nix
+
{
+
services.discourse = {
+
enable = true;
+
hostname = "discourse.example.com";
+
sslCertificate = "/path/to/ssl_certificate";
+
sslCertificateKey = "/path/to/ssl_certificate_key";
+
admin = {
+
email = "admin@example.com";
+
username = "admin";
+
fullName = "Administrator";
+
passwordFile = "/path/to/password_file";
};
+
mail.outgoing = {
+
serverAddress = "smtp.emailprovider.com";
+
port = 587;
+
username = "user@emailprovider.com";
+
passwordFile = "/path/to/smtp_password_file";
+
};
+
mail.incoming.enable = true;
+
plugins = with config.services.discourse.package.plugins; [
+
discourse-spoiler-alert
+
discourse-solved
+
];
+
siteSettings = {
+
plugins = {
+
spoiler_enabled = false;
+
};
+
};
+
secretKeyBaseFile = "/path/to/secret_key_base_file";
};
+
}
```
+28 -24
nixos/modules/services/web-apps/gotosocial.md
···
GoToSocial to `127.0.0.1:8080`, expecting to be run behind a HTTP proxy on `gotosocial.example.com`.
```nix
-
services.gotosocial = {
-
enable = true;
-
setupPostgresqlDB = true;
-
settings = {
-
application-name = "My GoToSocial";
-
host = "gotosocial.example.com";
-
protocol = "https";
-
bind-address = "127.0.0.1";
-
port = 8080;
};
-
};
```
Please refer to the [GoToSocial Documentation](https://docs.gotosocial.org/en/latest/configuration/general/)
···
HTTP reverse proxy such as nginx.
```nix
-
networking.firewall.allowedTCPPorts = [ 80 443 ];
-
services.nginx = {
-
enable = true;
-
clientMaxBodySize = "40M";
-
virtualHosts = with config.services.gotosocial.settings; {
-
"${host}" = {
-
enableACME = true;
-
forceSSL = true;
-
locations = {
-
"/" = {
-
recommendedProxySettings = true;
-
proxyWebsockets = true;
-
proxyPass = "http://${bind-address}:${toString port}";
};
};
};
};
-
};
```
Please refer to [](#module-security-acme) for details on how to provision an SSL/TLS certificate.
···
GoToSocial to `127.0.0.1:8080`, expecting to be run behind a HTTP proxy on `gotosocial.example.com`.
```nix
+
{
+
services.gotosocial = {
+
enable = true;
+
setupPostgresqlDB = true;
+
settings = {
+
application-name = "My GoToSocial";
+
host = "gotosocial.example.com";
+
protocol = "https";
+
bind-address = "127.0.0.1";
+
port = 8080;
+
};
};
+
}
```
Please refer to the [GoToSocial Documentation](https://docs.gotosocial.org/en/latest/configuration/general/)
···
HTTP reverse proxy such as nginx.
```nix
+
{
+
networking.firewall.allowedTCPPorts = [ 80 443 ];
+
services.nginx = {
+
enable = true;
+
clientMaxBodySize = "40M";
+
virtualHosts = with config.services.gotosocial.settings; {
+
"${host}" = {
+
enableACME = true;
+
forceSSL = true;
+
locations = {
+
"/" = {
+
recommendedProxySettings = true;
+
proxyWebsockets = true;
+
proxyPass = "http://${bind-address}:${toString port}";
+
};
};
};
};
};
+
}
```
Please refer to [](#module-security-acme) for details on how to provision an SSL/TLS certificate.
+12 -10
nixos/modules/services/web-apps/keycloak.md
···
A basic configuration with some custom settings could look like this:
```nix
-
services.keycloak = {
-
enable = true;
-
settings = {
-
hostname = "keycloak.example.com";
-
hostname-strict-backchannel = true;
};
-
initialAdminPassword = "e6Wcm0RrtegMEHl"; # change on first login
-
sslCertificate = "/run/keys/ssl_cert";
-
sslCertificateKey = "/run/keys/ssl_key";
-
database.passwordFile = "/run/keys/db_password";
-
};
```
···
A basic configuration with some custom settings could look like this:
```nix
+
{
+
services.keycloak = {
+
enable = true;
+
settings = {
+
hostname = "keycloak.example.com";
+
hostname-strict-backchannel = true;
+
};
+
initialAdminPassword = "e6Wcm0RrtegMEHl"; # change on first login
+
sslCertificate = "/run/keys/ssl_cert";
+
sslCertificateKey = "/run/keys/ssl_key";
+
database.passwordFile = "/run/keys/db_password";
};
+
}
```
+8 -6
nixos/modules/services/web-apps/lemmy.md
···
the minimum to start lemmy is
```nix
-
services.lemmy = {
-
enable = true;
-
settings = {
-
hostname = "lemmy.union.rocks";
-
database.createLocally = true;
};
-
caddy.enable = true;
}
```
···
the minimum to start lemmy is
```nix
+
{
+
services.lemmy = {
+
enable = true;
+
settings = {
+
hostname = "lemmy.union.rocks";
+
database.createLocally = true;
+
};
+
caddy.enable = true;
};
}
```
+3 -1
nixos/modules/services/web-apps/pict-rs.md
···
the minimum to start pict-rs is
```nix
-
services.pict-rs.enable = true;
```
this will start the http server on port 8080 by default.
···
the minimum to start pict-rs is
```nix
+
{
+
services.pict-rs.enable = true;
+
}
```
this will start the http server on port 8080 by default.
+1 -1
nixos/modules/services/web-apps/suwayomi-server.md
···
server = {
port = 4567;
autoDownloadNewChapters = false;
-
maxSourcesInParallel" = 6;
extensionRepos = [
"https://raw.githubusercontent.com/MY_ACCOUNT/MY_REPO/repo/index.min.json"
];
···
server = {
port = 4567;
autoDownloadNewChapters = false;
+
maxSourcesInParallel = 6;
extensionRepos = [
"https://raw.githubusercontent.com/MY_ACCOUNT/MY_REPO/repo/index.min.json"
];
+53 -35
nixos/modules/services/x11/desktop-managers/gnome.md
···
To enable the GNOME desktop use:
```nix
-
services.xserver.desktopManager.gnome.enable = true;
-
services.xserver.displayManager.gdm.enable = true;
```
::: {.note}
···
If you’d like to only use the GNOME desktop and not the apps, you can disable them with:
```nix
-
services.gnome.core-utilities.enable = false;
```
and none of them will be installed.
···
It is also possible to disable many of the [core services](https://github.com/NixOS/nixpkgs/blob/b8ec4fd2a4edc4e30d02ba7b1a2cc1358f3db1d5/nixos/modules/services/x11/desktop-managers/gnome.nix#L329-L348). For example, if you do not need indexing files, you can disable Tracker with:
```nix
-
services.gnome.tracker-miners.enable = false;
-
services.gnome.tracker.enable = false;
```
Note, however, that doing so is not supported and might break some applications. Notably, GNOME Music cannot work without Tracker.
···
You can install all of the GNOME games with:
```nix
-
services.gnome.games.enable = true;
```
### GNOME core developer tools {#sec-gnome-core-developer-tools}
···
You can install GNOME core developer tools with:
```nix
-
services.gnome.core-developer-tools.enable = true;
```
## Enabling GNOME Flashback {#sec-gnome-enable-flashback}
···
GNOME Flashback provides a desktop environment based on the classic GNOME 2 architecture. You can enable the default GNOME Flashback session, which uses the Metacity window manager, with:
```nix
-
services.xserver.desktopManager.gnome.flashback.enableMetacity = true;
```
It is also possible to create custom sessions that replace Metacity with a different window manager using [](#opt-services.xserver.desktopManager.gnome.flashback.customSessions).
···
The following example uses `xmonad` window manager:
```nix
-
services.xserver.desktopManager.gnome.flashback.customSessions = [
-
{
-
wmName = "xmonad";
-
wmLabel = "XMonad";
-
wmCommand = "${pkgs.haskellPackages.xmonad}/bin/xmonad";
-
enableGnomePanel = false;
-
}
-
];
```
## Icons and GTK Themes {#sec-gnome-icons-and-gtk-themes}
···
You can install them like any other package:
```nix
-
environment.systemPackages = [
-
gnomeExtensions.dash-to-dock
-
gnomeExtensions.gsconnect
-
gnomeExtensions.mpris-indicator-button
-
];
```
Unfortunately, we lack a way for these to be managed in a completely declarative way.
···
### Example {#sec-gnome-gsettings-overrides-example}
```nix
-
services.xserver.desktopManager.gnome = {
-
extraGSettingsOverrides = ''
-
# Change default background
-
[org.gnome.desktop.background]
-
picture-uri='file://${pkgs.nixos-artwork.wallpapers.mosaic-blue.gnomeFilePath}'
-
# Favorite apps in gnome-shell
-
[org.gnome.shell]
-
favorite-apps=['org.gnome.Console.desktop', 'org.gnome.Nautilus.desktop']
-
'';
-
extraGSettingsOverridePackages = [
-
pkgs.gsettings-desktop-schemas # for org.gnome.desktop
-
pkgs.gnome.gnome-shell # for org.gnome.shell
-
];
-
};
```
## Frequently Asked Questions {#sec-gnome-faq}
···
To enable the GNOME desktop use:
```nix
+
{
+
services.xserver.desktopManager.gnome.enable = true;
+
services.xserver.displayManager.gdm.enable = true;
+
}
```
::: {.note}
···
If you’d like to only use the GNOME desktop and not the apps, you can disable them with:
```nix
+
{
+
services.gnome.core-utilities.enable = false;
+
}
```
and none of them will be installed.
···
It is also possible to disable many of the [core services](https://github.com/NixOS/nixpkgs/blob/b8ec4fd2a4edc4e30d02ba7b1a2cc1358f3db1d5/nixos/modules/services/x11/desktop-managers/gnome.nix#L329-L348). For example, if you do not need indexing files, you can disable Tracker with:
```nix
+
{
+
services.gnome.tracker-miners.enable = false;
+
services.gnome.tracker.enable = false;
+
}
```
Note, however, that doing so is not supported and might break some applications. Notably, GNOME Music cannot work without Tracker.
···
You can install all of the GNOME games with:
```nix
+
{
+
services.gnome.games.enable = true;
+
}
```
### GNOME core developer tools {#sec-gnome-core-developer-tools}
···
You can install GNOME core developer tools with:
```nix
+
{
+
services.gnome.core-developer-tools.enable = true;
+
}
```
## Enabling GNOME Flashback {#sec-gnome-enable-flashback}
···
GNOME Flashback provides a desktop environment based on the classic GNOME 2 architecture. You can enable the default GNOME Flashback session, which uses the Metacity window manager, with:
```nix
+
{
+
services.xserver.desktopManager.gnome.flashback.enableMetacity = true;
+
}
```
It is also possible to create custom sessions that replace Metacity with a different window manager using [](#opt-services.xserver.desktopManager.gnome.flashback.customSessions).
···
The following example uses `xmonad` window manager:
```nix
+
{
+
services.xserver.desktopManager.gnome.flashback.customSessions = [
+
{
+
wmName = "xmonad";
+
wmLabel = "XMonad";
+
wmCommand = "${pkgs.haskellPackages.xmonad}/bin/xmonad";
+
enableGnomePanel = false;
+
}
+
];
+
}
```
## Icons and GTK Themes {#sec-gnome-icons-and-gtk-themes}
···
You can install them like any other package:
```nix
+
{
+
environment.systemPackages = [
+
gnomeExtensions.dash-to-dock
+
gnomeExtensions.gsconnect
+
gnomeExtensions.mpris-indicator-button
+
];
+
}
```
Unfortunately, we lack a way for these to be managed in a completely declarative way.
···
### Example {#sec-gnome-gsettings-overrides-example}
```nix
+
{
+
services.xserver.desktopManager.gnome = {
+
extraGSettingsOverrides = ''
+
# Change default background
+
[org.gnome.desktop.background]
+
picture-uri='file://${pkgs.nixos-artwork.wallpapers.mosaic-blue.gnomeFilePath}'
+
# Favorite apps in gnome-shell
+
[org.gnome.shell]
+
favorite-apps=['org.gnome.Console.desktop', 'org.gnome.Nautilus.desktop']
+
'';
+
extraGSettingsOverridePackages = [
+
pkgs.gsettings-desktop-schemas # for org.gnome.desktop
+
pkgs.gnome.gnome-shell # for org.gnome.shell
+
];
+
};
+
}
```
## Frequently Asked Questions {#sec-gnome-faq}
+18 -9
nixos/modules/services/x11/desktop-managers/pantheon.md
···
All of Pantheon is working in NixOS and the applications should be available, aside from a few [exceptions](https://github.com/NixOS/nixpkgs/issues/58161). To enable Pantheon, set
```nix
-
services.xserver.desktopManager.pantheon.enable = true;
```
This automatically enables LightDM and Pantheon's LightDM greeter. If you'd like to disable this, set
```nix
-
services.xserver.displayManager.lightdm.greeters.pantheon.enable = false;
-
services.xserver.displayManager.lightdm.enable = false;
```
but please be aware using Pantheon without LightDM as a display manager will break screenlocking from the UI. The NixOS module for Pantheon installs all of Pantheon's default applications. If you'd like to not install Pantheon's apps, set
```nix
-
services.pantheon.apps.enable = false;
```
You can also use [](#opt-environment.pantheon.excludePackages) to remove any other app (like `elementary-mail`).
···
indicators = [
pkgs.some-special-indicator
];
-
};
switchboard-with-plugs.override {
plugs = [
pkgs.some-special-plug
];
-
};
```
please note that, like how the NixOS options describe these as extra plugins, this would only add to the default plugins included with the programs. If for some reason you'd like to configure which plugins to use exactly, both packages have an argument for this:
```nix
wingpanel-with-indicators.override {
useDefaultIndicators = false;
indicators = specialListOfIndicators;
-
};
-
switchboard-with-plugs.override {
useDefaultPlugs = false;
plugs = specialListOfPlugs;
-
};
```
this could be most useful for testing a particular plug-in in isolation.
···
All of Pantheon is working in NixOS and the applications should be available, aside from a few [exceptions](https://github.com/NixOS/nixpkgs/issues/58161). To enable Pantheon, set
```nix
+
{
+
services.xserver.desktopManager.pantheon.enable = true;
+
}
```
This automatically enables LightDM and Pantheon's LightDM greeter. If you'd like to disable this, set
```nix
+
{
+
services.xserver.displayManager.lightdm.greeters.pantheon.enable = false;
+
services.xserver.displayManager.lightdm.enable = false;
+
}
```
but please be aware using Pantheon without LightDM as a display manager will break screenlocking from the UI. The NixOS module for Pantheon installs all of Pantheon's default applications. If you'd like to not install Pantheon's apps, set
```nix
+
{
+
services.pantheon.apps.enable = false;
+
}
```
You can also use [](#opt-environment.pantheon.excludePackages) to remove any other app (like `elementary-mail`).
···
indicators = [
pkgs.some-special-indicator
];
+
}
+
```
+
```nix
switchboard-with-plugs.override {
plugs = [
pkgs.some-special-plug
];
+
}
```
please note that, like how the NixOS options describe these as extra plugins, this would only add to the default plugins included with the programs. If for some reason you'd like to configure which plugins to use exactly, both packages have an argument for this:
```nix
wingpanel-with-indicators.override {
useDefaultIndicators = false;
indicators = specialListOfIndicators;
+
}
+
```
+
```nix
switchboard-with-plugs.override {
useDefaultPlugs = false;
plugs = specialListOfPlugs;
+
}
```
this could be most useful for testing a particular plug-in in isolation.
+6 -2
nixos/modules/system/boot/clevis.md
···
In order to activate unattended decryption of a resource at boot, enable the `clevis` module:
```nix
-
boot.initrd.clevis.enable = true;
```
Then, specify the device you want to decrypt using a given clevis secret. Clevis will automatically try to decrypt the device at boot and will fallback to interactive unlocking if the decryption policy is not fulfilled.
```nix
-
boot.initrd.clevis.devices."/dev/nvme0n1p1".secretFile = ./nvme0n1p1.jwe;
```
Only `bcachefs`, `zfs` and `luks` encrypted devices are supported at this time.
···
In order to activate unattended decryption of a resource at boot, enable the `clevis` module:
```nix
+
{
+
boot.initrd.clevis.enable = true;
+
}
```
Then, specify the device you want to decrypt using a given clevis secret. Clevis will automatically try to decrypt the device at boot and will fallback to interactive unlocking if the decryption policy is not fulfilled.
```nix
+
{
+
boot.initrd.clevis.devices."/dev/nvme0n1p1".secretFile = ./nvme0n1p1.jwe;
+
}
```
Only `bcachefs`, `zfs` and `luks` encrypted devices are supported at this time.
+40 -28
pkgs/README.md
···
- Bad: Uses `git://` which won't be proxied.
```nix
-
src = fetchgit {
-
url = "git://github.com/NixOS/nix.git";
-
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-
hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
}
```
- Better: This is ok, but an archive fetch will still be faster.
```nix
-
src = fetchgit {
-
url = "https://github.com/NixOS/nix.git";
-
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-
hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
}
```
- Best: Fetches a snapshot archive and you get the rev you want.
```nix
-
src = fetchFromGitHub {
-
owner = "NixOS";
-
repo = "nix";
-
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-
hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
}
```
···
Patches available online should be retrieved using `fetchpatch`.
```nix
-
patches = [
-
(fetchpatch {
-
name = "fix-check-for-using-shared-freetype-lib.patch";
-
url = "http://git.ghostscript.com/?p=ghostpdl.git;a=patch;h=8f5d285";
-
hash = "sha256-uRcxaCjd+WAuGrXOmGfFeu79cUILwkRdBu48mwcBE7g=";
-
})
-
];
```
Otherwise, you can add a `.patch` file to the `nixpkgs` repository. In the interest of keeping our maintenance burden to a minimum, only patches that are unique to `nixpkgs` should be added in this way.
···
If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch`. Check [the `fetchpatch` reference](https://nixos.org/manual/nixpkgs/unstable/#fetchpatch) for details.
```nix
-
patches = [ ./0001-changes.patch ];
```
If you do need to do create this sort of patch file, one way to do so is with git:
···
For example in this case:
```nix
-
jbidwatcher = throw "jbidwatcher was discontinued in march 2021"; # added 2021-03-15
```
The throw message should explain in short why the package was removed for users that still have it installed.
···
For very simple tests, they can be written inline:
```nix
-
{ …, yq-go }:
buildGoModule rec {
-
passthru.tests = {
simple = runCommand "${pname}-test" {} ''
···
{ stdenv, lib, fetchurl, callPackage }:
stdenv.mkDerivation {
-
passthru.tests = {
simple-execution = callPackage ./tests.nix { };
};
-
meta = { … };
}
```
···
{ stdenv, lib, nixosTests }:
stdenv.mkDerivation {
-
...
passthru.tests = {
nginx = nixosTests.nginx;
};
-
...
}
```
···
- Bad: Uses `git://` which won't be proxied.
```nix
+
{
+
src = fetchgit {
+
url = "git://github.com/NixOS/nix.git";
+
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
+
hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
+
};
}
```
- Better: This is ok, but an archive fetch will still be faster.
```nix
+
{
+
src = fetchgit {
+
url = "https://github.com/NixOS/nix.git";
+
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
+
hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
+
};
}
```
- Best: Fetches a snapshot archive and you get the rev you want.
```nix
+
{
+
src = fetchFromGitHub {
+
owner = "NixOS";
+
repo = "nix";
+
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
+
hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
+
};
}
```
···
Patches available online should be retrieved using `fetchpatch`.
```nix
+
{
+
patches = [
+
(fetchpatch {
+
name = "fix-check-for-using-shared-freetype-lib.patch";
+
url = "http://git.ghostscript.com/?p=ghostpdl.git;a=patch;h=8f5d285";
+
hash = "sha256-uRcxaCjd+WAuGrXOmGfFeu79cUILwkRdBu48mwcBE7g=";
+
})
+
];
+
}
```
Otherwise, you can add a `.patch` file to the `nixpkgs` repository. In the interest of keeping our maintenance burden to a minimum, only patches that are unique to `nixpkgs` should be added in this way.
···
If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch`. Check [the `fetchpatch` reference](https://nixos.org/manual/nixpkgs/unstable/#fetchpatch) for details.
```nix
+
{
+
patches = [ ./0001-changes.patch ];
+
}
```
If you do need to do create this sort of patch file, one way to do so is with git:
···
For example in this case:
```nix
+
{
+
jbidwatcher = throw "jbidwatcher was discontinued in march 2021"; # added 2021-03-15
+
}
```
The throw message should explain in short why the package was removed for users that still have it installed.
···
For very simple tests, they can be written inline:
```nix
+
{ /* ... , */ yq-go }:
buildGoModule rec {
+
# …
passthru.tests = {
simple = runCommand "${pname}-test" {} ''
···
{ stdenv, lib, fetchurl, callPackage }:
stdenv.mkDerivation {
+
# …
passthru.tests = {
simple-execution = callPackage ./tests.nix { };
};
+
meta = { /* … */ };
}
```
···
{ stdenv, lib, nixosTests }:
stdenv.mkDerivation {
+
# ...
passthru.tests = {
nginx = nixosTests.nginx;
};
+
# ...
}
```
+15 -3
pkgs/by-name/README.md
···
and override its value in [`pkgs/top-level/all-packages.nix`](../top-level/all-packages.nix):
```nix
-
libfoo = callPackage ../by-name/so/some-package/package.nix {
-
libbar = libbar_2;
-
};
```
## Manual migration guidelines
···
This is often the case for packages with multiple versions, such as
```nix
foo_1 = callPackage ../tools/foo/1.nix { };
foo_2 = callPackage ../tools/foo/2.nix { };
```
The best way to resolve this is to not use `callPackage` directly, such that check 1 doesn't trigger.
This can be done by using `inherit` on a local package set:
```nix
inherit
({
foo_1 = callPackage ../tools/foo/1.nix { };
···
foo_1
foo_2
;
```
While this may seem pointless, this can in fact help with future package set refactorings,
···
This is not required, but the above solution also allows refactoring the definitions into a separate file:
```nix
inherit (import ../tools/foo pkgs)
foo_1 foo_2;
```
```nix
···
if `callPackage` isn't used underneath and you want the same `.override` arguments for all attributes:
```nix
inherit (callPackages ../tools/foo { })
foo_1 foo_2;
```
```nix
···
This is not required, but the above solution also allows exposing the package set as an attribute:
```nix
foo-versions = import ../tools/foo pkgs;
# Or using callPackages
# foo-versions = callPackages ../tools/foo { };
inherit (foo-versions) foo_1 foo_2;
```
···
and override its value in [`pkgs/top-level/all-packages.nix`](../top-level/all-packages.nix):
```nix
+
{
+
libfoo = callPackage ../by-name/so/some-package/package.nix {
+
libbar = libbar_2;
+
};
+
}
```
## Manual migration guidelines
···
This is often the case for packages with multiple versions, such as
```nix
+
{
foo_1 = callPackage ../tools/foo/1.nix { };
foo_2 = callPackage ../tools/foo/2.nix { };
+
}
```
The best way to resolve this is to not use `callPackage` directly, such that check 1 doesn't trigger.
This can be done by using `inherit` on a local package set:
```nix
+
{
inherit
({
foo_1 = callPackage ../tools/foo/1.nix { };
···
foo_1
foo_2
;
+
}
```
While this may seem pointless, this can in fact help with future package set refactorings,
···
This is not required, but the above solution also allows refactoring the definitions into a separate file:
```nix
+
{
inherit (import ../tools/foo pkgs)
foo_1 foo_2;
+
}
```
```nix
···
if `callPackage` isn't used underneath and you want the same `.override` arguments for all attributes:
```nix
+
{
inherit (callPackages ../tools/foo { })
foo_1 foo_2;
+
}
```
```nix
···
This is not required, but the above solution also allows exposing the package set as an attribute:
```nix
+
{
foo-versions = import ../tools/foo pkgs;
# Or using callPackages
# foo-versions = callPackages ../tools/foo { };
inherit (foo-versions) foo_1 foo_2;
+
}
```
+61 -55
pkgs/development/misc/resholve/README.md
···
- [shell.nix from abathur/tdverpy](https://github.com/abathur/tdverpy/blob/e1f956df3ed1c7097a5164e0c85b178772e277f5/shell.nix#L6-L13)
```nix
-
resholvedScript = resholve.writeScript "name" {
-
inputs = [ file ];
-
interpreter = "${bash}/bin/bash";
-
} ''
-
echo "Hello"
-
file .
-
'';
-
resholvedScriptBin = resholve.writeScriptBin "name" {
-
inputs = [ file ];
-
interpreter = "${bash}/bin/bash";
-
} ''
-
echo "Hello"
-
file .
-
'';
```
···
from the manpage, and the Nix equivalents:
```nix
-
# --fake 'f:setUp;tearDown builtin:setopt source:/etc/bashrc'
-
fake = {
-
# fake accepts the initial of valid identifier types as a CLI convenience.
-
# Use full names in the Nix API.
-
function = [ "setUp" "tearDown" ];
-
builtin = [ "setopt" ];
-
source = [ "/etc/bashrc" ];
-
};
-
# --fix 'aliases $GIT:gix /bin/bash'
-
fix = {
-
# all single-word directives use `true` as value
-
aliases = true;
-
"$GIT" = [ "gix" ];
-
"/bin/bash";
-
};
-
# --keep 'source:$HOME /etc/bashrc ~/.bashrc'
-
keep = {
-
source = [ "$HOME" ];
-
"/etc/bashrc" = true;
-
"~/.bashrc" = true;
-
};
```
···
do it piecemeal:
```nix
-
# --execer 'cannot:${openssl.bin}/bin/openssl can:${openssl.bin}/bin/c_rehash'
-
execer = [
-
/*
-
This is the same verdict binlore will
-
come up with. It's a no-op just to demo
-
how to fiddle lore via the Nix API.
-
*/
-
"cannot:${openssl.bin}/bin/openssl"
-
# different verdict, but not used
-
"can:${openssl.bin}/bin/c_rehash"
-
];
-
# --wrapper '${gnugrep}/bin/egrep:${gnugrep}/bin/grep'
-
wrapper = [
-
/*
-
This is the same verdict binlore will
-
come up with. It's a no-op just to demo
-
how to fiddle lore via the Nix API.
-
*/
-
"${gnugrep}/bin/egrep:${gnugrep}/bin/grep"
-
];
```
···
- [shell.nix from abathur/tdverpy](https://github.com/abathur/tdverpy/blob/e1f956df3ed1c7097a5164e0c85b178772e277f5/shell.nix#L6-L13)
```nix
+
{
+
resholvedScript = resholve.writeScript "name" {
+
inputs = [ file ];
+
interpreter = "${bash}/bin/bash";
+
} ''
+
echo "Hello"
+
file .
+
'';
+
resholvedScriptBin = resholve.writeScriptBin "name" {
+
inputs = [ file ];
+
interpreter = "${bash}/bin/bash";
+
} ''
+
echo "Hello"
+
file .
+
'';
+
}
```
···
from the manpage, and the Nix equivalents:
```nix
+
{
+
# --fake 'f:setUp;tearDown builtin:setopt source:/etc/bashrc'
+
fake = {
+
# fake accepts the initial of valid identifier types as a CLI convenience.
+
# Use full names in the Nix API.
+
function = [ "setUp" "tearDown" ];
+
builtin = [ "setopt" ];
+
source = [ "/etc/bashrc" ];
+
};
+
# --fix 'aliases $GIT:gix /bin/bash'
+
fix = {
+
# all single-word directives use `true` as value
+
aliases = true;
+
"$GIT" = [ "gix" ];
+
interpreter = "/bin/bash";
+
};
+
# --keep 'source:$HOME /etc/bashrc ~/.bashrc'
+
keep = {
+
source = [ "$HOME" ];
+
"/etc/bashrc" = true;
+
"~/.bashrc" = true;
+
};
+
}
```
···
do it piecemeal:
```nix
+
{
+
# --execer 'cannot:${openssl.bin}/bin/openssl can:${openssl.bin}/bin/c_rehash'
+
execer = [
+
/*
+
This is the same verdict binlore will
+
come up with. It's a no-op just to demo
+
how to fiddle lore via the Nix API.
+
*/
+
"cannot:${openssl.bin}/bin/openssl"
+
# different verdict, but not used
+
"can:${openssl.bin}/bin/c_rehash"
+
];
+
# --wrapper '${gnugrep}/bin/egrep:${gnugrep}/bin/grep'
+
wrapper = [
+
/*
+
This is the same verdict binlore will
+
come up with. It's a no-op just to demo
+
how to fiddle lore via the Nix API.
+
*/
+
"${gnugrep}/bin/egrep:${gnugrep}/bin/grep"
+
];
+
}
```
+1 -1
pkgs/servers/home-assistant/custom-components/README.md
···
meta = with lib; {
# changelog, description, homepage, license, maintainers
-
}
}
```
···
meta = with lib; {
# changelog, description, homepage, license, maintainers
+
};
}
```
+3 -1
pkgs/servers/home-assistant/custom-lovelace-modules/README.md
···
The entrypoint used can be overridden in `passthru` like this:
```nix
-
passthru.entrypoint = "demo-card-bundle.js";
```
···
The entrypoint used can be overridden in `passthru` like this:
```nix
+
{
+
passthru.entrypoint = "demo-card-bundle.js";
+
}
```
+11 -9
pkgs/servers/nextcloud/packages/README.md
···
Using it together with the Nextcloud module could look like this:
```nix
-
services.nextcloud = {
-
enable = true;
-
package = pkgs.nextcloud25;
-
hostName = "localhost";
-
config.adminpassFile = "${pkgs.writeText "adminpass" "hunter2"}";
-
extraApps = with pkgs.nextcloud25Packages.apps; {
-
inherit mail calendar contact;
};
-
extraAppsEnable = true;
-
};
```
Adapt the version number in the Nextcloud package and nextcloudPackages set
···
Using it together with the Nextcloud module could look like this:
```nix
+
{
+
services.nextcloud = {
+
enable = true;
+
package = pkgs.nextcloud25;
+
hostName = "localhost";
+
config.adminpassFile = "${pkgs.writeText "adminpass" "hunter2"}";
+
extraApps = with pkgs.nextcloud25Packages.apps; {
+
inherit mail calendar contact;
+
};
+
extraAppsEnable = true;
};
+
}
```
Adapt the version number in the Nextcloud package and nextcloudPackages set
+12 -10
pkgs/servers/web-apps/wordpress/packages/README.md
···
Using it together with the Wordpress module could look like this:
```nix
-
services.wordpress = {
-
sites."blog.${config.networking.domain}" = {
-
plugins = with pkgs.wordpressPackages.plugins; [
-
anti-spam-bee
-
code-syntax-block
-
cookie-notice
-
lightbox-with-photoswipe
-
wp-gdpr-compliance
-
];
};
-
};
```
The same scheme applies to `themes` and `languages`.
···
Using it together with the Wordpress module could look like this:
```nix
+
{
+
services.wordpress = {
+
sites."blog.${config.networking.domain}" = {
+
plugins = with pkgs.wordpressPackages.plugins; [
+
anti-spam-bee
+
code-syntax-block
+
cookie-notice
+
lightbox-with-photoswipe
+
wp-gdpr-compliance
+
];
+
};
};
+
}
```
The same scheme applies to `themes` and `languages`.