Project import generated by Copybara.

GitOrigin-RevId: bc9b956714ed6eac5f8888322aac5bc41389defa
This commit is contained in:
Default email 2021-09-18 12:52:07 +02:00
parent 8ea060fa0c
commit 88abffb7d2
2835 changed files with 92202 additions and 38334 deletions

View file

@ -19,7 +19,7 @@
# Libraries
/lib @edolstra @nbp @infinisil
/lib/systems @nbp @ericson2314 @matthewbauer
/lib/systems @alyssais @nbp @ericson2314 @matthewbauer
/lib/generators.nix @edolstra @nbp @Profpatsch
/lib/cli.nix @edolstra @nbp @Profpatsch
/lib/debug.nix @edolstra @nbp @Profpatsch
@ -42,6 +42,12 @@
# Nixpkgs build-support
/pkgs/build-support/writers @lassulus @Profpatsch
# Nixpkgs documentation
/maintainers/scripts/db-to-md.sh @jtojnar @ryantm
/maintainers/scripts/doc @jtojnar @ryantm
/doc/build-aux/pandoc-filters @jtojnar
/doc/contributing/contributing-to-documentation.chapter.md @jtojnar
# NixOS Internals
/nixos/default.nix @nbp @infinisil
/nixos/lib/from-env.nix @nbp @infinisil
@ -104,7 +110,7 @@
# Rust
/pkgs/development/compilers/rust @Mic92 @LnL7 @zowoq
/pkgs/build-support/rust @andir @danieldk @zowoq
/pkgs/build-support/rust @andir @zowoq
# Darwin-related
/pkgs/stdenv/darwin @NixOS/darwin-maintainers

View file

@ -15,6 +15,6 @@ jobs:
# we don't limit this action to only NixOS repo since the checks are cheap and useful developer feedback
steps:
- uses: actions/checkout@v2
- uses: cachix/install-nix-action@v13
- uses: cachix/install-nix-action@v14
# explicit list of supportedSystems is needed until aarch64-darwin becomes part of the trunk jobset
- run: nix-build pkgs/top-level/release.nix -A tarball.nixpkgs-basic-release-checks --arg supportedSystems '[ "aarch64-darwin" "aarch64-linux" "x86_64-linux" "x86_64-darwin" ]'

View file

@ -28,7 +28,7 @@ jobs:
# pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge
if: env.PR_DIFF
- uses: cachix/install-nix-action@v13
- uses: cachix/install-nix-action@v14
if: env.PR_DIFF
with:
# nixpkgs commit is pinned so that it doesn't break

View file

@ -18,7 +18,7 @@ jobs:
with:
# pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge
- uses: cachix/install-nix-action@v13
- uses: cachix/install-nix-action@v14
with:
# explicitly enable sandbox
extra_nix_config: sandbox = true

View file

@ -18,7 +18,7 @@ jobs:
with:
# pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge
- uses: cachix/install-nix-action@v13
- uses: cachix/install-nix-action@v14
with:
# explicitly enable sandbox
extra_nix_config: sandbox = true

View file

@ -19,7 +19,7 @@ jobs:
with:
# pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge
- uses: cachix/install-nix-action@v12
- uses: cachix/install-nix-action@v14
- name: Check DocBook files generated from Markdown are consistent
run: |
nixos/doc/manual/md-to-db.sh

View file

@ -33,7 +33,7 @@ jobs:
- uses: actions/checkout@v2
- name: ${{ matrix.pairs.from }} → ${{ matrix.pairs.into }}
uses: devmasx/merge-branch@v1.3.1
uses: devmasx/merge-branch@1.4.0
with:
type: now
from_branch: ${{ matrix.pairs.from }}

View file

@ -39,7 +39,7 @@ jobs:
- uses: actions/checkout@v2
- name: ${{ matrix.pairs.from }} → ${{ matrix.pairs.into }}
uses: devmasx/merge-branch@v1.3.1
uses: devmasx/merge-branch@1.4.0
with:
type: now
from_branch: ${{ matrix.pairs.from }}

View file

@ -2,6 +2,7 @@
,*
.*.swp
.*.swo
.idea/
result
result-*
/doc/NEWS.html

View file

@ -3,12 +3,17 @@ MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$'
PANDOC ?= pandoc
pandoc_media_dir = media
# NOTE: Keep in sync with NixOS manual (/nixos/doc/manual/md-to-db.sh).
# NOTE: Keep in sync with NixOS manual (/nixos/doc/manual/md-to-db.sh) and conversion script (/maintainers/scripts/db-to-md.sh).
# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
# Not needed:
# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
pandoc_flags = --extract-media=$(pandoc_media_dir) \
--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
--lua-filter=labelless-link-is-xref.lua \
--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
--lua-filter=build-aux/pandoc-filters/link-unix-man-references.lua \
--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
.PHONY: all

View file

@ -0,0 +1,23 @@
--[[
Converts Code AST nodes produced by pandocs DocBook reader
from citerefentry elements into AST for corresponding role
for reStructuredText.
We use subset of MyST syntax (CommonMark with features from rST)
so lets use the rST AST for rST features.
Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage
]]
function Code(elem)
elem.classes = elem.classes:map(function (x)
if x == 'citerefentry' then
elem.attributes['role'] = 'manpage'
return 'interpreted-text'
else
return x
end
end)
return elem
end

View file

@ -1,3 +1,13 @@
--[[
Converts Link AST nodes with empty label to DocBook xref elements.
This is a temporary script to be able use cross-references conveniently
using syntax taken from MyST, while we still use docbook-xsl
for generating the documentation.
Reference: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing
]]
local function starts_with(start, str)
return str:sub(1, #start) == start
end

View file

@ -0,0 +1,36 @@
--[[
Converts AST for reStructuredText roles into corresponding
DocBook elements.
Currently, only a subset of roles is supported.
Reference:
List of roles:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
manpage:
https://tdg.docbook.org/tdg/5.1/citerefentry.html
file:
https://tdg.docbook.org/tdg/5.1/filename.html
]]
function Code(elem)
if elem.classes:includes('interpreted-text') then
local tag = nil
local content = elem.text
if elem.attributes['role'] == 'manpage' then
tag = 'citerefentry'
local title, volnum = content:match('^(.+)%((%w+)%)$')
if title == nil then
-- No volnum in parentheses.
title = content
end
content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '')
elseif elem.attributes['role'] == 'file' then
tag = 'filename'
end
if tag ~= nil then
return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>')
end
end
end

View file

@ -0,0 +1,18 @@
--[[
Turns a manpage reference into a link, when a mapping is defined
in the unix-man-urls.lua file.
]]
local man_urls = {
["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file",
["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
}
function Code(elem)
local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
if is_man_role and man_urls[elem.text] ~= nil then
return pandoc.Link(elem, man_urls[elem.text])
end
end

View file

@ -0,0 +1,29 @@
--[[
Replaces Str AST nodes containing {role}, followed by a Code node
by a Code node with attrs that would be produced by rST reader
from the role syntax.
This is to emulate MyST syntax in Pandoc.
(MyST is a CommonMark flavour with rST features mixed in.)
Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
]]
function Inlines(inlines)
for i = #inlines-1,1,-1 do
local first = inlines[i]
local second = inlines[i+1]
local correct_tags = first.tag == 'Str' and second.tag == 'Code'
if correct_tags then
-- docutils supports alphanumeric strings separated by [-._:]
-- We are slightly more liberal for simplicity.
local role = first.text:match('^{([-._+:%w]+)}$')
if role ~= nil then
inlines:remove(i)
second.attributes['role'] = role
second.classes:insert('interpreted-text')
end
end
end
return inlines
end

View file

@ -0,0 +1,25 @@
--[[
Replaces Code nodes with attrs that would be produced by rST reader
from the role syntax by a Str AST node containing {role}, followed by a Code node.
This is to emulate MyST syntax in Pandoc.
(MyST is a CommonMark flavour with rST features mixed in.)
Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
]]
function Code(elem)
local role = elem.attributes['role']
if elem.classes:includes('interpreted-text') and role ~= nil then
elem.classes = elem.classes:filter(function (c)
return c ~= 'interpreted-text'
end)
elem.attributes['role'] = nil
return {
pandoc.Str('{' .. role .. '}'),
elem,
}
end
end

View file

@ -16,7 +16,7 @@ How to add a new (major) version of the Linux kernel to Nixpkgs:
1. Copy the old Nix expression (e.g. `linux-2.6.21.nix`) to the new one (e.g. `linux-2.6.22.nix`) and update it.
2. Add the new kernel to `all-packages.nix` (e.g., create an attribute `kernel_2_6_22`).
2. Add the new kernel to the `kernels` attribute set in `linux-kernels.nix` (e.g., create an attribute `kernel_2_6_22`).
3. Now were going to update the kernel configuration. First unpack the kernel. Then for each supported platform (`i686`, `x86_64`, `uml`) do the following:
@ -36,6 +36,6 @@ How to add a new (major) version of the Linux kernel to Nixpkgs:
5. Copy `.config` over the new config file (e.g. `config-2.6.22-i686-smp`).
4. Test building the kernel: `nix-build -A kernel_2_6_22`. If it compiles, ship it! For extra credit, try booting NixOS with it.
4. Test building the kernel: `nix-build -A linuxKernel.kernels.kernel_2_6_22`. If it compiles, ship it! For extra credit, try booting NixOS with it.
5. It may be that the new kernel requires updating the external kernel modules and kernel-dependent packages listed in the `linuxPackagesFor` function in `all-packages.nix` (such as the NVIDIA drivers, AUFS, etc.). If the updated packages arent backwards compatible with older kernels, you may need to keep the older versions around.
5. It may be that the new kernel requires updating the external kernel modules and kernel-dependent packages listed in the `linuxPackagesFor` function in `linux-kernels.nix` (such as the NVIDIA drivers, AUFS, etc.). If the updated packages arent backwards compatible with older kernels, you may need to keep the older versions around.

View file

@ -52,6 +52,13 @@ Additionally, the following syntax extensions are currently used:
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
- []{#ssec-contributing-markup-inline-roles}
If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`.
The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/unix-man-urls.lua`.
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.
- []{#ssec-contributing-markup-admonitions}
**Admonitions**, set off from the text to bring attention to something.

View file

@ -68,27 +68,107 @@ Erlang.mk functions similarly to Rebar3, except we use `buildErlangMk` instead o
`mixRelease` is used to make a release in the mix sense. Dependencies will need to be fetched with `fetchMixDeps` and passed to it.
#### mixRelease - Elixir Phoenix example {#mixrelease---elixir-phoenix-example}
#### mixRelease - Elixir Phoenix example {#mix-release-elixir-phoenix-example}
Here is how your `default.nix` file would look.
there are 3 steps, frontend dependencies (javascript), backend dependencies (elixir) and the final derivation that puts both of those together
##### mixRelease - Frontend dependencies (javascript) {#mix-release-javascript-deps}
for phoenix projects, inside of nixpkgs you can either use yarn2nix (mkYarnModule) or node2nix. An example with yarn2nix can be found [here](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/web-apps/plausible/default.nix#L39). An example with node2nix will follow. To package something outside of nixpkgs, you have alternatives like [npmlock2nix](https://github.com/nix-community/npmlock2nix) or [nix-npm-buildpackage](https://github.com/serokell/nix-npm-buildpackage)
##### mixRelease - backend dependencies (mix) {#mix-release-mix-deps}
There are 2 ways to package backend dependencies. With mix2nix and with a fixed-output-derivation (FOD).
###### mix2nix {#mix2nix}
mix2nix is a cli tool available in nixpkgs. it will generate a nix expression from a mix.lock file. It is quite standard in the 2nix tool series.
Note that currently mix2nix can't handle git dependencies inside the mix.lock file. If you have git dependencies, you can either add them manually (see [example](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/pleroma/default.nix#L20)) or use the FOD method.
The advantage of using mix2nix is that nix will know your whole dependency graph. On a dependency update, this won't trigger a full rebuild and download of all the dependencies, where FOD will do so.
practical steps:
- run `mix2nix > mix_deps.nix` in the upstream repo.
- pass `mixNixDeps = with pkgs; import ./mix_deps.nix { inherit lib beamPackages; };` as an argument to mixRelease.
If there are git depencencies.
- You'll need to fix the version artificially in mix.exs and regenerate the mix.lock with fixed version (on upstream). This will enable you to run `mix2nix > mix_deps.nix`.
- 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: {
# mix2nix does not support git dependencies yet,
# so we need to add them manually
prometheus_ex = beamPackages.buildMix rec {
name = "prometheus_ex";
version = "3.0.5";
# Change the argument src with the git src that you actually need
src = fetchFromGitLab {
domain = "git.pleroma.social";
group = "pleroma";
owner = "elixir-libraries";
repo = "prometheus.ex";
rev = "a4e9beb3c1c479d14b352fd9d6dd7b1f6d7deee5";
sha256 = "1v0q4bi7sb253i8q016l7gwlv5562wk5zy3l2sa446csvsacnpjk";
};
# 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 sha256 to correspond to your new git src.
###### FOD {#fixed-output-derivation}
A fixed output derivation will download mix dependencies from the internet. To ensure reproducibility, a hash will be supplied. Note that mix is relatively reproducible. An FOD generating a different hash on each run hasn't been observed (as opposed to npm where the chances are relatively high). See [elixir_ls](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/beam-modules/elixir_ls.nix) for a usage example of FOD.
Practical steps
- start with the following argument to mixRelease
```nix
mixFodDeps = fetchMixDeps {
pname = "mix-deps-${pname}";
inherit src version;
sha256 = lib.fakeSha256;
};
```
The first build will complain about the sha256 value, you can replace with the suggested value after that.
Note that if after you've replaced the value, nix suggests another sha256, then mix is not fetching the dependencies reproducibly. An FOD will not work in that case and you will have to use mix2nix.
##### mixRelease - example {#mix-release-example}
Here is how your `default.nix` file would look for a phoenix project.
```nix
with import <nixpkgs> { };
let
# beam.interpreters.erlangR23 is available if you need a particular version
packages = beam.packagesWith beam.interpreters.erlang;
pname = "your_project";
version = "0.0.1";
src = builtins.fetchgit {
url = "ssh://git@github.com/your_id/your_repo";
rev = "replace_with_your_commit";
};
pname = "your_project";
version = "0.0.1";
mixEnv = "prod";
# if using mix2nix you can use the mixNixDeps attribute
mixFodDeps = packages.fetchMixDeps {
pname = "mix-deps-${pname}";
inherit src mixEnv version;
inherit src version;
# nix will complain and tell you the right value to replace this with
sha256 = lib.fakeSha256;
# if you have build time environment variables add them here
@ -97,45 +177,19 @@ let
nodeDependencies = (pkgs.callPackage ./assets/default.nix { }).shell.nodeDependencies;
frontEndFiles = stdenvNoCC.mkDerivation {
pname = "frontend-${pname}";
nativeBuildInputs = [ nodejs ];
inherit version src;
buildPhase = ''
cp -r ./assets $TEMPDIR
mkdir -p $TEMPDIR/assets/node_modules/.cache
cp -r ${nodeDependencies}/lib/node_modules $TEMPDIR/assets
export PATH="${nodeDependencies}/bin:$PATH"
cd $TEMPDIR/assets
webpack --config ./webpack.config.js
cd ..
'';
installPhase = ''
cp -r ./priv/static $out/
'';
outputHashAlgo = "sha256";
outputHashMode = "recursive";
# nix will complain and tell you the right value to replace this with
outputHash = lib.fakeSha256;
impureEnvVars = lib.fetchers.proxyImpureEnvVars;
};
in packages.mixRelease {
inherit src pname version mixEnv mixFodDeps;
inherit src pname version mixFodDeps;
# if you have build time environment variables add them here
MY_ENV_VAR="my_value";
preInstall = ''
mkdir -p ./priv/static
cp -r ${frontEndFiles} ./priv/static
postBuild = ''
ln -sf ${nodeDependencies}/lib/node_modules assets/node_modules
npm run deploy --prefix ./assets
# for external task you need a workaround for the no deps check flag
# https://github.com/phoenixframework/phoenix/issues/2690
mix do deps.loadpaths --no-deps-check, phx.digest
mix phx.digest --no-deps-check
'';
}
```
@ -165,6 +219,8 @@ in
systemd.services.${release_name} = {
wantedBy = [ "multi-user.target" ];
after = [ "network.target" "postgresql.service" ];
# note that if you are connecting to a postgres instance on a different host
# postgresql.service should not be included in the requires.
requires = [ "network-online.target" "postgresql.service" ];
description = "my app";
environment = {
@ -201,6 +257,7 @@ in
path = [ pkgs.bash ];
};
# in case you have migration scripts or you want to use a remote shell
environment.systemPackages = [ release ];
}
```
@ -215,16 +272,11 @@ Usually, we need to create a `shell.nix` file and do our development inside of t
{ pkgs ? import <nixpkgs> {} }:
with pkgs;
let
elixir = beam.packages.erlangR22.elixir_1_9;
elixir = beam.packages.erlangR24.elixir_1_12;
in
mkShell {
buildInputs = [ elixir ];
ERL_INCLUDE_PATH="${erlang}/lib/erlang/usr/include";
}
```
@ -264,6 +316,7 @@ let
# TODO: not sure how to make hex available without installing it afterwards.
mix local.hex --if-missing
export LANG=en_US.UTF-8
# keep your shell history in iex
export ERL_AFLAGS="-kernel shell_history enabled"
# postges related

View file

@ -2,7 +2,7 @@
## Introduction {#javascript-introduction}
This contains instructions on how to package javascript applications. For instructions on how to add a cli package from npm please consult the #node.js section
This contains instructions on how to package javascript applications.
The various tools available will be listed in the [tools-overview](#javascript-tools-overview). Some general principles for packaging will follow. Finally some tool specific instructions will be given.

View file

@ -1513,7 +1513,7 @@ If you need to change a package's attribute(s) from `configuration.nix` you coul
python = super.python.override {
packageOverrides = python-self: python-super: {
twisted = python-super.twisted.overrideAttrs (oldAttrs: {
src = super.fetchPipy {
src = super.fetchPypi {
pname = "twisted";
version = "19.10.0";
sha256 = "7394ba7f272ae722a74f3d969dcf599bc4ef093bc392038748a490f1724a515d";

View file

@ -138,6 +138,8 @@ All programs that are built with [MPI](https://en.wikipedia.org/wiki/Message_Pas
- [MPICH](https://www.mpich.org/), attribute name `mpich`
- [MVAPICH](https://mvapich.cse.ohio-state.edu/), attribute name `mvapich`
To provide MPI enabled applications that use `MPICH`, instead of the default `Open MPI`, simply use the following overlay:
```nix

View file

@ -35,6 +35,8 @@ rec {
("generators.mkValueStringDefault: " +
"${t} not supported: ${toPretty {} v}");
in if isInt v then toString v
# convert derivations to store paths
else if lib.isDerivation v then toString v
# we default to not quoting strings
else if isString v then v
# isString returns "1", which is not a good default
@ -169,7 +171,7 @@ rec {
# converts { a.b.c = 5; } to { "a.b".c = 5; } for toINI
gitFlattenAttrs = let
recurse = path: value:
if isAttrs value then
if isAttrs value && !lib.isDerivation value then
lib.mapAttrsToList (name: value: recurse ([ name ] ++ path) value) value
else if length path > 1 then {
${concatStringsSep "." (lib.reverseList (tail path))}.${head path} = value;

View file

@ -43,7 +43,9 @@ let
lib.hasSuffix ".o" baseName ||
lib.hasSuffix ".so" baseName ||
# Filter out nix-build result symlinks
(type == "symlink" && lib.hasPrefix "result" baseName)
(type == "symlink" && lib.hasPrefix "result" baseName) ||
# Filter out sockets and other types of files we can't have in the store.
(type == "unknown")
);
# Filters a source tree removing version control files and directories using cleanSourceWith

View file

@ -89,7 +89,7 @@ rec {
=> "usr/local/bin"
*/
concatStringsSep = builtins.concatStringsSep or (separator: list:
concatStrings (intersperse separator list));
lib.foldl' (x: y: x + y) "" (intersperse separator list));
/* Maps a function over a list of strings and then concatenates the
result with the specified separator interspersed between

View file

@ -107,6 +107,7 @@ rec {
else if final.isMips then "mips"
else if final.isPower then "powerpc"
else if final.isRiscV then "riscv"
else if final.isS390 then "s390"
else final.parsed.cpu.name;
qemuArch =

View file

@ -28,7 +28,7 @@ let
"aarch64-linux" "armv5tel-linux" "armv6l-linux" "armv7a-linux"
"armv7l-linux" "i686-linux" "m68k-linux" "mipsel-linux"
"powerpc64-linux" "powerpc64le-linux" "riscv32-linux"
"riscv64-linux" "s390-linux" "x86_64-linux"
"riscv64-linux" "s390-linux" "s390x-linux" "x86_64-linux"
# MMIXware
"mmix-mmixware"
@ -41,7 +41,8 @@ let
# none
"aarch64-none" "arm-none" "armv6l-none" "avr-none" "i686-none"
"msp430-none" "or1k-none" "m68k-none" "powerpc-none"
"riscv32-none" "riscv64-none" "s390-none" "vc4-none" "x86_64-none"
"riscv32-none" "riscv64-none" "s390-none" "s390x-none" "vc4-none"
"x86_64-none"
# OpenBSD
"i686-openbsd" "x86_64-openbsd"

View file

@ -152,6 +152,10 @@ rec {
config = "s390-unknown-linux-gnu";
};
s390x = {
config = "s390x-unknown-linux-gnu";
};
arm-embedded = {
config = "arm-none-eabi";
libc = "newlib";

View file

@ -106,6 +106,7 @@ rec {
riscv64 = { bits = 64; significantByte = littleEndian; family = "riscv"; };
s390 = { bits = 32; significantByte = bigEndian; family = "s390"; };
s390x = { bits = 64; significantByte = bigEndian; family = "s390"; };
sparc = { bits = 32; significantByte = bigEndian; family = "sparc"; };
sparc64 = { bits = 64; significantByte = bigEndian; family = "sparc"; };

View file

@ -28,7 +28,7 @@ with lib.systems.doubles; lib.runTests {
testredox = mseteq redox [ "x86_64-redox" ];
testgnu = mseteq gnu (linux /* ++ kfreebsd ++ ... */);
testillumos = mseteq illumos [ "x86_64-solaris" ];
testlinux = mseteq linux [ "aarch64-linux" "armv5tel-linux" "armv6l-linux" "armv7a-linux" "armv7l-linux" "i686-linux" "mipsel-linux" "riscv32-linux" "riscv64-linux" "x86_64-linux" "powerpc64-linux" "powerpc64le-linux" "m68k-linux" "s390-linux" ];
testlinux = mseteq linux [ "aarch64-linux" "armv5tel-linux" "armv6l-linux" "armv7a-linux" "armv7l-linux" "i686-linux" "mipsel-linux" "riscv32-linux" "riscv64-linux" "x86_64-linux" "powerpc64-linux" "powerpc64le-linux" "m68k-linux" "s390-linux" "s390x-linux" ];
testnetbsd = mseteq netbsd [ "aarch64-netbsd" "armv6l-netbsd" "armv7a-netbsd" "armv7l-netbsd" "i686-netbsd" "m68k-netbsd" "mipsel-netbsd" "powerpc-netbsd" "riscv32-netbsd" "riscv64-netbsd" "x86_64-netbsd" ];
testopenbsd = mseteq openbsd [ "i686-openbsd" "x86_64-openbsd" ];
testwindows = mseteq windows [ "i686-cygwin" "x86_64-cygwin" "i686-windows" "x86_64-windows" ];

View file

@ -80,6 +80,12 @@
githubId = 791309;
name = "Jan Hrnko";
};
_1000teslas = {
name = "Kevin Tran";
email = "47207223+1000teslas@users.noreply.github.com";
github = "1000teslas";
githubId = 47207223;
};
_3699n = {
email = "nicholas@nvk.pm";
github = "3699n";
@ -348,6 +354,12 @@
githubId = 4732885;
name = "Ivan Jager";
};
airwoodix = {
email = "airwoodix@posteo.me";
github = "airwoodix";
githubId = 44871469;
name = "Etienne Wodey";
};
ajs124 = {
email = "nix@ajs124.de";
github = "ajs124";
@ -450,6 +462,12 @@
githubId = 2335822;
name = "Alexandre Esteves";
};
alexnortung = {
name = "alexnortung";
email = "alex_nortung@live.dk";
github = "alexnortung";
githubId = 1552267;
};
alexvorobiev = {
email = "alexander.vorobiev@gmail.com";
github = "alexvorobiev";
@ -526,6 +544,16 @@
fingerprint = "B422 CFB1 C9EF 73F7 E1E2 698D F53E 3233 42F7 A6D3A";
}];
};
alyaeanyx = {
email = "alexandra.hollmeier@mailbox.org";
github = "alyaeanyx";
githubId = 74795488;
name = "Alexandra Hollmeier";
keys = [{
longkeyid = "rsa3072/0x87D1AADCD25B8DEE";
fingerprint = "1F73 8879 5E5A 3DFC E2B3 FA32 87D1 AADC D25B 8DEE";
}];
};
amanjeev = {
email = "aj@amanjeev.com";
github = "amanjeev";
@ -1318,6 +1346,12 @@
githubId = 7346933;
name = "betaboon";
};
bew = {
email = "benoit.dechezelles@gmail.com";
github = "bew";
githubId = 9730330;
name = "Benoit de Chezelles";
};
bfortz = {
email = "bernard.fortz@gmail.com";
github = "bfortz";
@ -1348,6 +1382,12 @@
githubId = 28444296;
name = "Benjamin Hougland";
};
billewanick = {
email = "bill@ewanick.com";
github = "billewanick";
githubId = 13324165;
name = "Bill Ewanick";
};
binarin = {
email = "binarin@binarin.ru";
github = "binarin";
@ -1508,12 +1548,6 @@
githubId = 355401;
name = "Brian Hicks";
};
bricewge = {
email = "bricewge@gmail.com";
github = "bricewge";
githubId = 5525646;
name = "Brice Waegeneire";
};
Br1ght0ne = {
email = "brightone@protonmail.com";
github = "Br1ght0ne";
@ -1671,6 +1705,12 @@
githubId = 7435854;
name = "Victor Calvert";
};
cameronnemo = {
email = "cnemo@tutanota.com";
github = "cameronnemo";
githubId = 3212452;
name = "Cameron Nemo";
};
campadrenalin = {
email = "campadrenalin@gmail.com";
github = "campadrenalin";
@ -1869,6 +1909,12 @@
githubId = 3086255;
name = "Barry Moore II";
};
chisui = {
email = "chisui.pd@gmail.com";
github = "chisui";
githubId = 4526429;
name = "Philipp Dargel";
};
chivay = {
email = "hubert.jasudowicz@gmail.com";
github = "chivay";
@ -2257,6 +2303,12 @@
githubId = 1382175;
name = "Oliver Matthews";
};
cyounkins = {
name = "Craig Younkins";
email = "cyounkins@gmail.com";
github = "cyounkins";
githubId = 346185;
};
cypherpunk2140 = {
email = "stefan.mihaila@pm.me";
github = "stefan-mihaila";
@ -3621,6 +3673,12 @@
fingerprint = "2F93 661D AC17 EA98 A104 F780 ECC7 55EE 583C 1672";
}];
};
flexagoon = {
email = "flexagoon@pm.me";
github = "flexagoon";
githubId = 66178592;
name = "Pavel Zolotarevskiy";
};
flexw = {
email = "felix.weilbach@t-online.de";
github = "FlexW";
@ -4235,6 +4293,12 @@
githubId = 731722;
name = "Ryan Scheel";
};
hawkw = {
email = "eliza@elizas.website";
github = "hawkw";
githubId = 2796466;
name = "Eliza Weisman";
};
hax404 = {
email = "hax404foogit@hax404.de";
github = "hax404";
@ -4621,6 +4685,12 @@
githubId = 993484;
name = "Greg Hale";
};
imgabe = {
email = "gabrielpmonte@hotmail.com";
github = "imgabe";
githubId = 24387926;
name = "Gabriel Pereira";
};
imlonghao = {
email = "nixos@esd.cc";
github = "imlonghao";
@ -4747,6 +4817,12 @@
githubId = 26877687;
name = "Yurii Izorkin";
};
j0xaf = {
email = "j0xaf@j0xaf.de";
name = "Jörn Gersdorf";
github = "j0xaf";
githubId = 932697;
};
j0hax = {
name = "Johannes Arnold";
email = "johannes.arnold@stud.uni-hannover.de";
@ -5408,6 +5484,12 @@
githubId = 39434424;
name = "Felix Springer";
};
junjihashimoto = {
email = "junji.hashimoto@gmail.com";
github = "junjihashimoto";
githubId = 2469618;
name = "Junji Hashimoto";
};
justinas = {
email = "justinas@justinas.org";
github = "justinas";
@ -5472,6 +5554,12 @@
githubId = 66669;
name = "Jeff Zellner";
};
k4leg = {
name = "k4leg";
email = "python.bogdan@gmail.com";
github = "k4leg";
githubId = 39882583;
};
kaction = {
name = "Dmitry Bogatov";
email = "KAction@disroot.org";
@ -6694,6 +6782,12 @@
githubId = 775189;
name = "Jordi Masip";
};
MaskedBelgian = {
email = "michael.colicchia@imio.be";
github = "MaskedBelgian";
githubId = 29855073;
name = "Michael Colicchia";
};
matdsoupe = {
github = "matdsoupe";
githubId = 44469426;
@ -7445,6 +7539,16 @@
name = "Maxim Schuwalow";
email = "maxim.schuwalow@gmail.com";
};
msfjarvis = {
github = "msfjarvis";
githubId = 3348378;
name = "Harsh Shandilya";
email = "nixos@msfjarvis.dev";
keys = [{
longkeyid = "rsa4096/0xB7843F823355E9B9";
fingerprint = "8F87 050B 0F9C B841 1515 7399 B784 3F82 3355 E9B9";
}];
};
msiedlarek = {
email = "mikolaj@siedlarek.pl";
github = "msiedlarek";
@ -7649,6 +7753,12 @@
githubId = 2590830;
name = "Sage Raflik";
};
neosimsim = {
email = "me@abn.sh";
github = "neosimsim";
githubId = 1771772;
name = "Alexander Ben Nasrallah";
};
nequissimus = {
email = "tim@nequissimus.com";
github = "nequissimus";
@ -8514,7 +8624,7 @@
githubId = 1719781;
name = "Pablo Ovelleiro Corral";
keys = [{
longkeyid = "sa4096/0x823A6154426408D3";
longkeyid = "rsa4096/0x823A6154426408D3";
fingerprint = "D03B 218C AE77 1F77 D7F9 20D9 823A 6154 4264 08D3";
}];
};
@ -8772,6 +8882,12 @@
githubId = 33375;
name = "Peter Sanford";
};
pshirshov = {
email = "pshirshov@eml.cc";
github = "pshirshov";
githubId = 295225;
name = "Pavel Shirshov";
};
psibi = {
email = "sibi@psibi.in";
github = "psibi";
@ -9526,6 +9642,12 @@
github = "s1341";
githubId = 5682183;
};
samalws = {
email = "sam@samalws.com";
name = "Sam Alws";
github = "samalws";
githubId = 20981725;
};
samb96 = {
email = "samb96@gmail.com";
github = "samb96";
@ -9560,6 +9682,12 @@
githubId = 115821;
name = "Sam Rose";
};
samuela = {
email = "skainsworth@gmail.com";
github = "samuela";
githubId = 226872;
name = "Samuel Ainsworth";
};
samueldr = {
email = "samuel@dionne-riel.com";
github = "samueldr";
@ -10250,6 +10378,12 @@
githubId = 8668915;
name = "Stephane Schitter";
};
staccato = {
name = "staccato";
email = "moveq@riseup.net";
github = "staccato";
githubId = 86573128;
};
steell = {
email = "steve@steellworks.com";
github = "Steell";
@ -11024,6 +11158,12 @@
githubId = 10110;
name = "Travis B. Hartwell";
};
travisdavis-ops = {
email = "travisdavismedia@gmail.com";
github = "travisdavis-ops";
githubId = 52011418;
name = "Travis Davis";
};
TredwellGit = {
email = "tredwell@tutanota.com";
github = "TredwellGit";
@ -11281,10 +11421,14 @@
name = "Jos van den Oever";
};
vanilla = {
email = "neko@hydev.org";
email = "osu_vanilla@126.com";
github = "VergeDX";
githubId = 25173827;
name = "Vanilla";
keys = [{
longkeyid = "rsa4096/0x4DFA2BDD7305E739";
fingerprint = "5C16 5178 7DE2 EE5A AF98 3EA3 4DFA 2BDD 7305 E739";
}];
};
vanschelven = {
email = "klaas@vanschelven.com";
@ -11736,6 +11880,12 @@
githubId = 3992240;
name = "Elijah Rum";
};
x3ro = {
name = "^x3ro";
email = "nix@x3ro.dev";
github = "x3rAx";
githubId = 2268851;
};
xaverdh = {
email = "hoe.dom@gmx.de";
github = "xaverdh";
@ -12362,6 +12512,16 @@
fingerprint = "61AE D40F 368B 6F26 9DAE 3892 6861 6B2D 8AC4 DCC5";
}];
};
zenithal = {
name = "zenithal";
email = "i@zenithal.me";
github = "ZenithalHourlyRate";
githubId = 19512674;
keys = [{
longkeyid = "rsa4096/0x87E17EEF9B18B6C9";
fingerprint = "1127 F188 280A E312 3619 3329 87E1 7EEF 9B18 B6C9";
}];
};
zeri = {
name = "zeri";
email = "68825133+zeri42@users.noreply.github.com";
@ -12390,4 +12550,11 @@
github = "rski";
githubId = 2960312;
};
mbprtpmnr = {
name = "mbprtpmnr";
email = "mbprtpmnr@pm.me";
github = "mbprtpmnr";
githubId = 88109321;
};
}

View file

@ -0,0 +1,88 @@
#! /usr/bin/env nix-shell
#! nix-shell -I nixpkgs=. -i bash -p pandoc
# This script is temporarily needed while we transition the manual to
# CommonMark. It converts DocBook files into our CommonMark flavour.
debug=
files=()
while [ "$#" -gt 0 ]; do
i="$1"; shift 1
case "$i" in
--debug)
debug=1
;;
*)
files+=("$i")
;;
esac
done
echo "WARNING: This is an experimental script and might not preserve all formatting." > /dev/stderr
echo "Please report any issues you discover." > /dev/stderr
outExtension="md"
if [[ $debug ]]; then
outExtension="json"
fi
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
# NOTE: Keep in sync with Nixpkgs manual (/doc/Makefile).
# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
targetLang="commonmark${pandoc_commonmark_enabled_extensions}+smart"
if [[ $debug ]]; then
targetLang=json
fi
pandoc_flags=(
# Not needed:
# - diagram-generator.lua (we do not support that in NixOS manual to limit dependencies)
# - media extraction (was only required for diagram generator)
# - myst-reader/roles.lua (only relevant for MyST → DocBook)
# - link-unix-man-references.lua (links should only be added to display output)
# - docbook-writer/rst-roles.lua (only relevant for → DocBook)
# - docbook-writer/labelless-link-is-xref.lua (only relevant for → DocBook)
"--lua-filter=$DIR/../../doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua"
"--lua-filter=$DIR/../../doc/build-aux/pandoc-filters/myst-writer/roles.lua"
"--lua-filter=$DIR/doc/unknown-code-language.lua"
-f docbook
-t "$targetLang"
--tab-stop=2
--wrap=none
)
for file in "${files[@]}"; do
if [[ ! -f "$file" ]]; then
echo "db-to-md.sh: $file does not exist" > /dev/stderr
exit 1
else
rootElement=$(xmllint --xpath 'name(//*)' "$file")
if [[ $rootElement = chapter ]]; then
extension=".chapter.$outExtension"
elif [[ $rootElement = section ]]; then
extension=".section.$outExtension"
else
echo "db-to-md.sh: $file contains an unsupported root element $rootElement" > /dev/stderr
exit 1
fi
outFile="${file%".section.xml"}"
outFile="${outFile%".chapter.xml"}"
outFile="${outFile%".xml"}$extension"
temp1=$(mktemp)
$DIR/doc/escape-code-markup.py "$file" "$temp1"
if [[ $debug ]]; then
echo "Converted $file to $temp1" > /dev/stderr
fi
temp2=$(mktemp)
$DIR/doc/replace-xrefs-by-empty-links.py "$temp1" "$temp2"
if [[ $debug ]]; then
echo "Converted $temp1 to $temp2" > /dev/stderr
fi
pandoc "$temp2" -o "$outFile" "${pandoc_flags[@]}"
echo "Converted $file to $outFile" > /dev/stderr
fi
done

View file

@ -0,0 +1,97 @@
#! /usr/bin/env nix-shell
#! nix-shell -I nixpkgs=channel:nixos-unstable -i python3 -p python3 -p python3.pkgs.lxml
"""
Pandoc will strip any markup within code elements so
lets escape them so that they can be handled manually.
"""
import lxml.etree as ET
import re
import sys
def replace_element_by_text(el: ET.Element, text: str) -> None:
"""
Author: bernulf
Source: https://stackoverflow.com/a/10520552/160386
SPDX-License-Identifier: CC-BY-SA-3.0
"""
text = text + (el.tail or "")
parent = el.getparent()
if parent is not None:
previous = el.getprevious()
if previous is not None:
previous.tail = (previous.tail or "") + text
else:
parent.text = (parent.text or "") + text
parent.remove(el)
DOCBOOK_NS = "http://docbook.org/ns/docbook"
# List of elements that pandocs DocBook reader strips markup from.
# https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Readers/DocBook.hs
code_elements = [
# CodeBlock
"literallayout",
"screen",
"programlisting",
# Code (inline)
"classname",
"code",
"filename",
"envar",
"literal",
"computeroutput",
"prompt",
"parameter",
"option",
"markup",
"wordasword",
"command",
"varname",
"function",
"type",
"symbol",
"constant",
"userinput",
"systemitem",
]
XMLNS_REGEX = re.compile(r'\s+xmlns(?::[^=]+)?="[^"]*"')
ROOT_ELEMENT_REGEX = re.compile(r'^\s*<[^>]+>')
def remove_xmlns(match: re.Match) -> str:
"""
Removes xmlns attributes.
Expects a match containing an opening tag.
"""
return XMLNS_REGEX.sub('', match.group(0))
if __name__ == '__main__':
assert len(sys.argv) >= 3, "usage: escape-code-markup.py <input> <output>"
tree = ET.parse(sys.argv[1])
name_predicate = " or ".join([f"local-name()='{el}'" for el in code_elements])
for markup in tree.xpath(f"//*[({name_predicate}) and namespace-uri()='{DOCBOOK_NS}']/*"):
text = ET.tostring(markup, encoding=str)
# tostring adds xmlns attributes to the element we want to stringify
# as if it was supposed to be usable standalone.
# We are just converting it to CDATA so we do not care.
# Lets strip the namespace declarations to keep the code clean.
#
# Note that this removes even namespaces that were potentially
# in the original file. Though, that should be very rare
# most of the time, we will stringify empty DocBook elements
# like <xref> or <co> or, at worst, <link> with xlink:href attribute.
#
# Also note that the regex expects the root element to be first
# thing in the string. But that should be fine, the tostring method
# does not produce XML declaration or doctype by default.
text = ROOT_ELEMENT_REGEX.sub(remove_xmlns, text)
replace_element_by_text(markup, text)
tree.write(sys.argv[2])

View file

@ -0,0 +1,32 @@
#! /usr/bin/env nix-shell
#! nix-shell -I nixpkgs=channel:nixos-unstable -i python3 -p python3 -p python3.pkgs.lxml
"""
Pandoc will try to resolve xrefs and replace them with regular links.
lets replace them with links with empty labels which MyST
and our pandoc filters recognize as cross-references.
"""
import lxml.etree as ET
import sys
XLINK_NS = "http://www.w3.org/1999/xlink"
ns = {
"db": "http://docbook.org/ns/docbook",
}
if __name__ == '__main__':
assert len(sys.argv) >= 3, "usage: replace-xrefs-by-empty-links.py <input> <output>"
tree = ET.parse(sys.argv[1])
for xref in tree.findall(".//db:xref", ns):
text = ET.tostring(xref, encoding=str)
parent = xref.getparent()
link = parent.makeelement('link')
target_name = xref.get("linkend")
link.set(f"{{{XLINK_NS}}}href", f"#{target_name}")
parent.replace(xref, link)
tree.write(sys.argv[2])

View file

@ -0,0 +1,12 @@
--[[
Adds unknown class to CodeBlock AST nodes without any classes.
This will cause Pandoc to use fenced code block, which we prefer.
]]
function CodeBlock(elem)
if #elem.classes == 0 then
elem.classes:insert('unknown')
return elem
end
end

View file

@ -1,89 +1,86 @@
name,server,version,luaversion,maintainers
alt-getopt,,,,arobyn
ansicolors,,,,
bit32,,5.3.0-1,lua5_1,lblasc
argparse,,,,
basexx,,,,
binaryheap,,,,vcunat
busted,,,,
cassowary,,,,marsam alerque
compat53,,0.7-1,,vcunat
cosmo,,,,marsam
coxpcall,,1.17.0-1,,
cqueues,,,,vcunat
cyrussasl,,,,
digestif,,0.2-1,lua5_3,
dkjson,,,,
fifo,,,,
gitsigns.nvim,,,lua5_1,
http,,0.3-0,,vcunat
inspect,,,,
ldbus,http://luarocks.org/dev,,,
ldoc,,,,
lgi,,,,
linenoise,,,,
ljsyscall,,,lua5_1,lblasc
lpeg,,,,vyp
lpeg_patterns,,,,
lpeglabel,,,,
lpty,,,,
lrexlib-gnu,,,,
lrexlib-pcre,,,,vyp
lrexlib-posix,,,,
ltermbox,,,,
lua-cjson,,,,
lua-cmsgpack,,,,
lua-iconv,,,,
lua-lsp,http://luarocks.org/dev,,,
lua-messagepack,,,,
lua-resty-http,,,,
lua-resty-jwt,,,,
lua-resty-openidc,,,,
lua-resty-openssl,,,,
lua-resty-session,,,,
lua-term,,,,
lua-toml,,,,
lua-zlib,,,,koral
lua_cliargs,,,,
luabitop,,,,
luacheck,,,,
luacov,,,,
luadbi,,,,
luadbi-mysql,,,,
luadbi-postgresql,,,,
luadbi-sqlite3,,,,
luadoc,,,,
luaepnf,,,,
luaevent,,,,
luaexpat,,1.3.0-1,,arobyn flosse
luaffi,http://luarocks.org/dev,,,
luafilesystem,,1.7.0-2,,flosse
lualogging,,,,
luaossl,,,lua5_1,
luaposix,,34.1.1-1,,vyp lblasc
luarepl,,,,
luasec,,,,flosse
luasocket,,,,
luasql-sqlite3,,,,vyp
luassert,,,,
luasystem,,,,
luautf8,,,,pstn
luazip,,,,
lua-yajl,,,,pstn
luuid,,,,
luv,,1.30.0-0,,
lyaml,,,,lblasc
markdown,,,,
mediator_lua,,,,
mpack,,,,
moonscript,,,,arobyn
nvim-client,,,,
penlight,,,,
plenary.nvim,,,lua5_1,
rapidjson,,,,
readline,,,,
say,,,,
std._debug,,,,
std.normalize,,,,
stdlib,,,,vyp
vstruct,,,,
name,src,ref,server,version,luaversion,maintainers
alt-getopt,,,,,,arobyn
bit32,,,,5.3.0-1,lua5_1,lblasc
argparse,https://github.com/luarocks/argparse.git,,,,,
basexx,https://github.com/teto/basexx.git,,,,,
binaryheap,https://github.com/Tieske/binaryheap.lua,,,,,vcunat
busted,,,,,,
cassowary,,,,,,marsam alerque
compat53,,,,0.7-1,,vcunat
cosmo,,,,,,marsam
coxpcall,,,,1.17.0-1,,
cqueues,,,,,,vcunat
cyrussasl,https://github.com/JorjBauer/lua-cyrussasl.git,,,,,
digestif,https://github.com/astoff/digestif.git,,,0.2-1,lua5_3,
dkjson,,,,,,
fifo,,,,,,
gitsigns.nvim,https://github.com/lewis6991/gitsigns.nvim.git,,,,lua5_1,
http,,,,0.3-0,,vcunat
inspect,,,,,,
ldbus,,,http://luarocks.org/dev,,,
ldoc,https://github.com/stevedonovan/LDoc.git,,,,,
lgi,,,,,,
linenoise,https://github.com/hoelzro/lua-linenoise.git,,,,,
ljsyscall,,,,,lua5_1,lblasc
lpeg,,,,,,vyp
lpeg_patterns,,,,,,
lpeglabel,,,,,,
lpty,,,,,,
lrexlib-gnu,,,,,,
lrexlib-pcre,,,,,,vyp
lrexlib-posix,,,,,,
lua-cjson,,,,,,
lua-cmsgpack,,,,,,
lua-iconv,,,,,,
lua-lsp,,,,,,
lua-messagepack,,,,,,
lua-resty-http,,,,,,
lua-resty-jwt,,,,,,
lua-resty-openidc,,,,,,
lua-resty-openssl,,,,,,
lua-resty-session,,,,,,
lua-term,,,,,,
lua-toml,,,,,,
lua-zlib,,,,,,koral
lua_cliargs,https://github.com/amireh/lua_cliargs.git,,,,,
luabitop,https://github.com/teto/luabitop.git,,,,,
luacheck,,,,,,
luacov,,,,,,
luadbi,,,,,,
luadbi-mysql,,,,,,
luadbi-postgresql,,,,,,
luadbi-sqlite3,,,,,,
luaepnf,,,,,,
luaevent,,,,,,
luaexpat,,,,1.3.0-1,,arobyn flosse
luaffi,,,http://luarocks.org/dev,,,
luafilesystem,,,,1.7.0-2,,flosse
lualogging,,,,,,
luaossl,,,,,lua5_1,
luaposix,,,,34.1.1-1,,vyp lblasc
luarepl,,,,,,
luasec,,,,,,flosse
luasocket,,,,,,
luasql-sqlite3,,,,,,vyp
luassert,,,,,,
luasystem,,,,,,
luautf8,,,,,,pstn
luazip,,,,,,
lua-yajl,,,,,,pstn
luuid,,,,,,
luv,,,,1.30.0-0,,
lyaml,,,,,,lblasc
markdown,,,,,,
mediator_lua,,,,,,
mpack,,,,,,
moonscript,,,,,,arobyn
nvim-client,https://github.com/neovim/lua-client.git,,,,,
penlight,https://github.com/lunarmodules/Penlight.git,,,,,alerque
plenary.nvim,https://github.com/nvim-lua/plenary.nvim.git,,,,lua5_1,
rapidjson,https://github.com/xpol/lua-rapidjson.git,,,,,
readline,,,,,,
say,https://github.com/Olivine-Labs/say.git,,,,,
std._debug,https://github.com/lua-stdlib/_debug.git,,,,,
std.normalize,git://github.com/lua-stdlib/normalize.git,,,,,
stdlib,,,,41.2.2,,vyp
vstruct,https://github.com/ToxicFrog/vstruct.git,,,,,

1 name src ref server version luaversion maintainers
2 alt-getopt arobyn
3 ansicolors bit32 5.3.0-1 lua5_1 lblasc
4 bit32 argparse https://github.com/luarocks/argparse.git 5.3.0-1 lua5_1 lblasc
5 argparse basexx https://github.com/teto/basexx.git
6 basexx binaryheap https://github.com/Tieske/binaryheap.lua vcunat
7 binaryheap busted vcunat
8 busted cassowary marsam alerque
9 cassowary compat53 0.7-1 marsam alerque vcunat
10 compat53 cosmo 0.7-1 vcunat marsam
11 cosmo coxpcall 1.17.0-1 marsam
12 coxpcall cqueues 1.17.0-1 vcunat
13 cqueues cyrussasl https://github.com/JorjBauer/lua-cyrussasl.git vcunat
14 cyrussasl digestif https://github.com/astoff/digestif.git 0.2-1 lua5_3
15 digestif dkjson 0.2-1 lua5_3
16 dkjson fifo
17 fifo gitsigns.nvim https://github.com/lewis6991/gitsigns.nvim.git lua5_1
18 gitsigns.nvim http 0.3-0 lua5_1 vcunat
19 http inspect 0.3-0 vcunat
20 inspect ldbus http://luarocks.org/dev
21 ldbus ldoc https://github.com/stevedonovan/LDoc.git http://luarocks.org/dev
22 ldoc lgi
23 lgi linenoise https://github.com/hoelzro/lua-linenoise.git
24 linenoise ljsyscall lua5_1 lblasc
25 ljsyscall lpeg lua5_1 lblasc vyp
26 lpeg lpeg_patterns vyp
27 lpeg_patterns lpeglabel
28 lpeglabel lpty
29 lpty lrexlib-gnu
30 lrexlib-gnu lrexlib-pcre vyp
31 lrexlib-pcre lrexlib-posix vyp
32 lrexlib-posix lua-cjson
33 ltermbox lua-cmsgpack
34 lua-cjson lua-iconv
35 lua-cmsgpack lua-lsp
36 lua-iconv lua-messagepack
37 lua-lsp lua-resty-http http://luarocks.org/dev
38 lua-messagepack lua-resty-jwt
39 lua-resty-http lua-resty-openidc
40 lua-resty-jwt lua-resty-openssl
41 lua-resty-openidc lua-resty-session
42 lua-resty-openssl lua-term
43 lua-resty-session lua-toml
44 lua-term lua-zlib koral
45 lua-toml lua_cliargs https://github.com/amireh/lua_cliargs.git
46 lua-zlib luabitop https://github.com/teto/luabitop.git koral
47 lua_cliargs luacheck
48 luabitop luacov
49 luacheck luadbi
50 luacov luadbi-mysql
51 luadbi luadbi-postgresql
52 luadbi-mysql luadbi-sqlite3
53 luadbi-postgresql luaepnf
54 luadbi-sqlite3 luaevent
55 luadoc luaexpat 1.3.0-1 arobyn flosse
56 luaepnf luaffi http://luarocks.org/dev
57 luaevent luafilesystem 1.7.0-2 flosse
58 luaexpat lualogging 1.3.0-1 arobyn flosse
59 luaffi luaossl http://luarocks.org/dev lua5_1
60 luafilesystem luaposix 1.7.0-2 34.1.1-1 flosse vyp lblasc
61 lualogging luarepl
62 luaossl luasec lua5_1 flosse
63 luaposix luasocket 34.1.1-1 vyp lblasc
64 luarepl luasql-sqlite3 vyp
65 luasec luassert flosse
66 luasocket luasystem
67 luasql-sqlite3 luautf8 vyp pstn
68 luassert luazip
69 luasystem lua-yajl pstn
70 luautf8 luuid pstn
71 luazip luv 1.30.0-0
72 lua-yajl lyaml pstn lblasc
73 luuid markdown
74 luv mediator_lua 1.30.0-0
75 lyaml mpack lblasc
76 markdown moonscript arobyn
77 mediator_lua nvim-client https://github.com/neovim/lua-client.git
78 mpack penlight https://github.com/lunarmodules/Penlight.git alerque
79 moonscript plenary.nvim https://github.com/nvim-lua/plenary.nvim.git lua5_1 arobyn
80 nvim-client rapidjson https://github.com/xpol/lua-rapidjson.git
81 penlight readline
82 plenary.nvim say https://github.com/Olivine-Labs/say.git lua5_1
83 rapidjson std._debug https://github.com/lua-stdlib/_debug.git
84 readline std.normalize git://github.com/lua-stdlib/normalize.git
85 say stdlib 41.2.2 vyp
86 std._debug vstruct https://github.com/ToxicFrog/vstruct.git
std.normalize
stdlib vyp
vstruct

View file

@ -547,7 +547,6 @@ def update_plugins(editor: Editor, args):
log.setLevel(LOG_LEVELS[args.debug])
log.info("Start updating plugins")
nixpkgs_repo = git.Repo(editor.root, search_parent_directories=True)
update = editor.get_update(args.input_file, args.outfile, args.proc)
redirects = update()
@ -556,6 +555,7 @@ def update_plugins(editor: Editor, args):
autocommit = not args.no_commit
if autocommit:
nixpkgs_repo = git.Repo(editor.root, search_parent_directories=True)
commit(nixpkgs_repo, f"{editor.attr_path}: update", [args.outfile])
if redirects:

View file

@ -1,5 +1,5 @@
#!/usr/bin/env nix-shell
#!nix-shell -p nix-prefetch-git luarocks-nix python3 python3Packages.GitPython nix -i python3
#!nix-shell update-luarocks-shell.nix -i python3
# format:
# $ nix run nixpkgs.python3Packages.black -c black update.py
@ -19,7 +19,7 @@ import logging
import textwrap
from multiprocessing.dummy import Pool
from typing import List, Tuple
from typing import List, Tuple, Optional
from pathlib import Path
log = logging.getLogger()
@ -50,10 +50,21 @@ FOOTER="""
@dataclass
class LuaPlugin:
name: str
version: str
server: str
luaversion: str
maintainers: str
'''Name of the plugin, as seen on luarocks.org'''
src: str
'''address to the git repository'''
ref: Optional[str]
'''git reference (branch name/tag)'''
version: Optional[str]
'''Set it to pin a package '''
server: Optional[str]
'''luarocks.org registers packages under different manifests.
Its value can be 'http://luarocks.org/dev'
'''
luaversion: Optional[str]
'''Attribue of the lua interpreter if a package is available only for a specific lua version'''
maintainers: Optional[str]
''' Optional string listing maintainers separated by spaces'''
@property
def normalized_name(self) -> str:
@ -149,17 +160,34 @@ def generate_pkg_nix(plug: LuaPlugin):
Our cache key associates "p.name-p.version" to its rockspec
'''
log.debug("Generating nix expression for %s", plug.name)
cmd = [ "luarocks", "nix", plug.name]
cmd = [ "luarocks", "nix"]
if plug.server:
cmd.append(f"--only-server={plug.server}")
if plug.maintainers:
cmd.append(f"--maintainers={plug.maintainers}")
if plug.version:
# updates plugin directly from its repository
print("server: [%s]" % plug.server)
# if plug.server == "src":
if plug.src != "":
if plug.src is None:
msg = "src must be set when 'version' is set to \"src\" for package %s" % plug.name
log.error(msg)
raise RuntimeError(msg)
log.debug("Updating from source %s", plug.src)
cmd.append(plug.src)
# update the plugin from luarocks
else:
cmd.append(plug.name)
if plug.version and plug.version != "src":
cmd.append(plug.version)
#
if plug.server != "src" and plug.server:
cmd.append(f"--only-server={plug.server}")
if plug.luaversion:
with CleanEnvironment():
local_pkgs = str(ROOT.resolve())
@ -169,7 +197,7 @@ def generate_pkg_nix(plug: LuaPlugin):
lua_drv_path=subprocess.check_output(cmd2, text=True).strip()
cmd.append(f"--lua-dir={lua_drv_path}/bin")
log.debug("running %s", cmd)
log.debug("running %s", ' '.join(cmd))
output = subprocess.check_output(cmd, text=True)
return (plug, output)
@ -191,3 +219,4 @@ if __name__ == "__main__":
main()
# vim: set ft=python noet fdm=manual fenc=utf-8 ff=unix sts=0 sw=4 ts=4 :

View file

@ -1,12 +1,13 @@
{ nixpkgs ? import ../.. { }
}:
with nixpkgs;
let
pyEnv = python3.withPackages(ps: [ ps.GitPython ]);
in
mkShell {
packages = [
bash
pyEnv
luarocks-nix
nix-prefetch-scripts
parallel
];
LUAROCKS_NIXPKGS_PATH = toString nixpkgs.path;
}

View file

@ -103,7 +103,7 @@ let
pathContent = lib.attrByPath prefix null pkgs;
in
if pathContent == null then
builtins.throw "Attribute path `${path}` does not exists."
builtins.throw "Attribute path `${path}` does not exist."
else
packagesWithPath prefix (path: pkg: builtins.hasAttr "updateScript" pkg)
pathContent;
@ -115,7 +115,7 @@ let
package = lib.attrByPath (lib.splitString "." path) null pkgs;
in
if package == null then
builtins.throw "Package with an attribute name `${path}` does not exists."
builtins.throw "Package with an attribute name `${path}` does not exist."
else if ! builtins.hasAttr "updateScript" package then
builtins.throw "Package with an attribute name `${path}` does not have a `passthru.updateScript` attribute defined."
else

View file

@ -178,6 +178,15 @@ with lib.maintainers; {
scope = "Maintain the ecosystem around Matrix, a decentralized messenger.";
};
openstack = {
members = [
angustrau
superherointj
SuperSandro2000
];
scope = "Maintain the ecosystem around OpenStack";
};
pantheon = {
members = [
davidak

View file

@ -16,7 +16,7 @@ If NixOS fails to boot, there are a number of kernel command line parameters tha
`boot.debug1mounts`
: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](options.html#opt-fileSystems._name_.neededForBoot) on a file system.
: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](#opt-fileSystems._name_.neededForBoot) on a file system.
`boot.trace`

View file

@ -0,0 +1,62 @@
# Cleaning the Nix Store {#sec-nix-gc}
Nix has a purely functional model, meaning that packages are never
upgraded in place. Instead new versions of packages end up in a
different location in the Nix store (`/nix/store`). You should
periodically run Nix's *garbage collector* to remove old, unreferenced
packages. This is easy:
```ShellSession
$ nix-collect-garbage
```
Alternatively, you can use a systemd unit that does the same in the
background:
```ShellSession
# systemctl start nix-gc.service
```
You can tell NixOS in `configuration.nix` to run this unit automatically
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
system configurations. Thus they do not remove the ability to roll back
to previous configurations. The following command deletes old roots,
removing the ability to roll back to them:
```ShellSession
$ nix-collect-garbage -d
```
You can also do this for specific profiles, e.g.
```ShellSession
$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
```
Note that NixOS system configurations are stored in the profile
`/nix/var/nix/profiles/system`.
Another way to reclaim disk space (often as much as 40% of the size of
the Nix store) is to run Nix's store optimiser, which seeks out
identical files in the store and replaces them with hard links to a
single copy.
```ShellSession
$ nix-store --optimise
```
Since this command needs to read the entire Nix store, it can take quite
a while to finish.
## NixOS Boot Entries {#sect-nixos-gc-boot-entries}
If your `/boot` partition runs out of space, after clearing old profiles
you must rebuild your system with `nixos-rebuild` to update the `/boot`
partition and clear space.

View file

@ -1,63 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-gc">
<title>Cleaning the Nix Store</title>
<para>
Nix has a purely functional model, meaning that packages are never upgraded
in place. Instead new versions of packages end up in a different location in
the Nix store (<filename>/nix/store</filename>). You should periodically run
Nixs <emphasis>garbage collector</emphasis> to remove old, unreferenced
packages. This is easy:
<screen>
<prompt>$ </prompt>nix-collect-garbage
</screen>
Alternatively, you can use a systemd unit that does the same in the
background:
<screen>
<prompt># </prompt>systemctl start nix-gc.service
</screen>
You can tell NixOS in <filename>configuration.nix</filename> to run this unit
automatically at certain points in time, for instance, every night at 03:15:
<programlisting>
<xref linkend="opt-nix.gc.automatic"/> = true;
<xref linkend="opt-nix.gc.dates"/> = "03:15";
</programlisting>
</para>
<para>
The commands above do not remove garbage collector roots, such as old system
configurations. Thus they do not remove the ability to roll back to previous
configurations. The following command deletes old roots, removing the ability
to roll back to them:
<screen>
<prompt>$ </prompt>nix-collect-garbage -d
</screen>
You can also do this for specific profiles, e.g.
<screen>
<prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
</screen>
Note that NixOS system configurations are stored in the profile
<filename>/nix/var/nix/profiles/system</filename>.
</para>
<para>
Another way to reclaim disk space (often as much as 40% of the size of the
Nix store) is to run Nixs store optimiser, which seeks out identical files
in the store and replaces them with hard links to a single copy.
<screen>
<prompt>$ </prompt>nix-store --optimise
</screen>
Since this command needs to read the entire Nix store, it can take quite a
while to finish.
</para>
<section xml:id="sect-nixos-gc-boot-entries">
<title>NixOS Boot Entries</title>
<para>
If your <filename>/boot</filename> partition runs out of space, after
clearing old profiles you must rebuild your system with
<literal>nixos-rebuild</literal> to update the <filename>/boot</filename>
partition and clear space.
</para>
</section>
</chapter>

View file

@ -0,0 +1,44 @@
# Container Networking {#sec-container-networking}
When you create a container using `nixos-container create`, it gets it
own private IPv4 address in the range `10.233.0.0/16`. You can get the
container's IPv4 address as follows:
```ShellSession
# nixos-container show-ip foo
10.233.4.2
$ ping -c1 10.233.4.2
64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms
```
Networking is implemented using a pair of virtual Ethernet devices. The
network interface in the container is called `eth0`, while the matching
interface in the host is called `ve-container-name` (e.g., `ve-foo`).
The container has its own network namespace and the `CAP_NET_ADMIN`
capability, so it can perform arbitrary network configuration such as
setting up firewall rules, without affecting or having access to the
host's network.
By default, containers cannot talk to the outside network. If you want
that, you should set up Network Address Translation (NAT) rules on the
host to rewrite container traffic to use your external IP address. This
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.
Note that `ve-+` is a wildcard that matches all container interfaces.
If you are using Network Manager, you need to explicitly prevent it from
managing container interfaces:
```nix
networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
```
You may need to restart your system for the changes to take effect.

View file

@ -1,59 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-container-networking">
<title>Container Networking</title>
<para>
When you create a container using <literal>nixos-container create</literal>,
it gets it own private IPv4 address in the range
<literal>10.233.0.0/16</literal>. You can get the containers IPv4 address
as follows:
<screen>
<prompt># </prompt>nixos-container show-ip foo
10.233.4.2
<prompt>$ </prompt>ping -c1 10.233.4.2
64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms
</screen>
</para>
<para>
Networking is implemented using a pair of virtual Ethernet devices. The
network interface in the container is called <literal>eth0</literal>, while
the matching interface in the host is called
<literal>ve-<replaceable>container-name</replaceable></literal> (e.g.,
<literal>ve-foo</literal>). The container has its own network namespace and
the <literal>CAP_NET_ADMIN</literal> capability, so it can perform arbitrary
network configuration such as setting up firewall rules, without affecting or
having access to the hosts network.
</para>
<para>
By default, containers cannot talk to the outside network. If you want that,
you should set up Network Address Translation (NAT) rules on the host to
rewrite container traffic to use your external IP address. This can be
accomplished using the following configuration on the host:
<programlisting>
<xref linkend="opt-networking.nat.enable"/> = true;
<xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"];
<xref linkend="opt-networking.nat.externalInterface"/> = "eth0";
</programlisting>
where <literal>eth0</literal> should be replaced with the desired external
interface. Note that <literal>ve-+</literal> is a wildcard that matches all
container interfaces.
</para>
<para>
If you are using Network Manager, you need to explicitly prevent it from
managing container interfaces:
<programlisting>
networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
</programlisting>
</para>
<para>
You may need to restart your system for the changes to take effect.
</para>
</section>

View file

@ -0,0 +1,28 @@
# Container Management {#ch-containers}
NixOS allows you to easily run other NixOS instances as *containers*.
Containers are a light-weight approach to virtualisation that runs
software in the container at the same speed as in the host system. NixOS
containers share the Nix store of the host, making container creation
very efficient.
::: {.warning}
Currently, NixOS containers are not perfectly isolated from the host
system. This means that a user with root access to the container can do
things that affect the host. So you should not give container root
access to untrusted users.
:::
NixOS containers can be created in two ways: imperatively, using the
command `nixos-container`, and declaratively, by specifying them in your
`configuration.nix`. The declarative approach implies that containers
get upgraded along with your host system when you run `nixos-rebuild`,
which is often not what you want. By contrast, in the imperative
approach, containers are configured and updated independently from the
host system.
```{=docbook}
<xi:include href="imperative-containers.section.xml" />
<xi:include href="declarative-containers.section.xml" />
<xi:include href="container-networking.section.xml" />
```

View file

@ -1,34 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-containers">
<title>Container Management</title>
<para>
NixOS allows you to easily run other NixOS instances as
<emphasis>containers</emphasis>. Containers are a light-weight approach to
virtualisation that runs software in the container at the same speed as in
the host system. NixOS containers share the Nix store of the host, making
container creation very efficient.
</para>
<warning>
<para>
Currently, NixOS containers are not perfectly isolated from the host system.
This means that a user with root access to the container can do things that
affect the host. So you should not give container root access to untrusted
users.
</para>
</warning>
<para>
NixOS containers can be created in two ways: imperatively, using the command
<command>nixos-container</command>, and declaratively, by specifying them in
your <filename>configuration.nix</filename>. The declarative approach implies
that containers get upgraded along with your host system when you run
<command>nixos-rebuild</command>, which is often not what you want. By
contrast, in the imperative approach, containers are configured and updated
independently from the host system.
</para>
<xi:include href="imperative-containers.xml" />
<xi:include href="declarative-containers.xml" />
<xi:include href="container-networking.xml" />
</chapter>

View file

@ -0,0 +1,59 @@
# Control Groups {#sec-cgroups}
To keep track of the processes in a running system, systemd uses
*control groups* (cgroups). A control group is a set of processes used
to allocate resources such as CPU, memory or I/O bandwidth. There can be
multiple control group hierarchies, allowing each kind of resource to be
managed independently.
The command `systemd-cgls` lists all control groups in the `systemd`
hierarchy, which is what systemd uses to keep track of the processes
belonging to each service or user session:
```ShellSession
$ systemd-cgls
├─user
│ └─eelco
│ └─c1
│ ├─ 2567 -:0
│ ├─ 2682 kdeinit4: kdeinit4 Running...
│ ├─ ...
│ └─10851 sh -c less -R
└─system
├─httpd.service
│ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH
│ └─...
├─dhcpcd.service
│ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
└─ ...
```
Similarly, `systemd-cgls cpu` shows the cgroups in the CPU hierarchy,
which allows per-cgroup CPU scheduling priorities. By default, every
systemd service gets its own CPU cgroup, while all user sessions are in
the top-level CPU cgroup. This ensures, for instance, that a thousand
run-away processes in the `httpd.service` cgroup cannot starve the CPU
for one process in the `postgresql.service` cgroup. (By contrast, it
they were in the same cgroup, then the PostgreSQL process would get
1/1001 of the cgroup's CPU time.) You can limit a service's CPU share in
`configuration.nix`:
```nix
systemd.services.httpd.serviceConfig.CPUShares = 512;
```
By default, every cgroup has 1024 CPU shares, so this will halve the CPU
allocation of the `httpd.service` cgroup.
There also is a `memory` hierarchy that controls memory allocation
limits; by default, all processes are in the top-level cgroup, so any
service or session can exhaust all available memory. Per-cgroup memory
limits can be specified in `configuration.nix`; for instance, to limit
`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
cgroups with their CPU and memory usage.

View file

@ -1,65 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-cgroups">
<title>Control Groups</title>
<para>
To keep track of the processes in a running system, systemd uses
<emphasis>control groups</emphasis> (cgroups). A control group is a set of
processes used to allocate resources such as CPU, memory or I/O bandwidth.
There can be multiple control group hierarchies, allowing each kind of
resource to be managed independently.
</para>
<para>
The command <command>systemd-cgls</command> lists all control groups in the
<literal>systemd</literal> hierarchy, which is what systemd uses to keep
track of the processes belonging to each service or user session:
<screen>
<prompt>$ </prompt>systemd-cgls
├─user
│ └─eelco
│ └─c1
│ ├─ 2567 -:0
│ ├─ 2682 kdeinit4: kdeinit4 Running...
│ ├─ <replaceable>...</replaceable>
│ └─10851 sh -c less -R
└─system
├─httpd.service
│ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH
│ └─<replaceable>...</replaceable>
├─dhcpcd.service
│ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
└─ <replaceable>...</replaceable>
</screen>
Similarly, <command>systemd-cgls cpu</command> shows the cgroups in the CPU
hierarchy, which allows per-cgroup CPU scheduling priorities. By default,
every systemd service gets its own CPU cgroup, while all user sessions are in
the top-level CPU cgroup. This ensures, for instance, that a thousand
run-away processes in the <literal>httpd.service</literal> cgroup cannot
starve the CPU for one process in the <literal>postgresql.service</literal>
cgroup. (By contrast, it they were in the same cgroup, then the PostgreSQL
process would get 1/1001 of the cgroups CPU time.) You can limit a
services CPU share in <filename>configuration.nix</filename>:
<programlisting>
<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512;
</programlisting>
By default, every cgroup has 1024 CPU shares, so this will halve the CPU
allocation of the <literal>httpd.service</literal> cgroup.
</para>
<para>
There also is a <literal>memory</literal> hierarchy that controls memory
allocation limits; by default, all processes are in the top-level cgroup, so
any service or session can exhaust all available memory. Per-cgroup memory
limits can be specified in <filename>configuration.nix</filename>; for
instance, to limit <literal>httpd.service</literal> to 512 MiB of RAM
(excluding swap):
<programlisting>
<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.MemoryLimit = "512M";
</programlisting>
</para>
<para>
The command <command>systemd-cgtop</command> shows a continuously updated
list of all cgroups with their CPU and memory usage.
</para>
</chapter>

View file

@ -0,0 +1,48 @@
# Declarative Container Specification {#sec-declarative-containers}
You can also specify containers and their configuration in the host's
`configuration.nix`. For example, the following specifies that there
shall be a container named `database` running PostgreSQL:
```nix
containers.database =
{ config =
{ config, pkgs, ... }:
{ services.postgresql.enable = true;
services.postgresql.package = pkgs.postgresql_9_6;
};
};
```
If you run `nixos-rebuild switch`, the container will be built. If the
container was already running, it will be updated in place, without
rebooting. The container can be configured to start automatically by
setting `containers.database.autoStart = true` in its configuration.
By default, declarative containers share the network namespace of the
host, meaning that they can listen on (privileged) ports. However, they
cannot change the network configuration. You can give a container its
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
address `192.168.100.11`, which is hooked up to a virtual Ethernet
interface on the host with IP address `192.168.100.10`. (See the next
section for details on container networking.)
To disable the container, just remove it from `configuration.nix` and
run `nixos-rebuild
switch`. Note that this will not delete the root directory of the
container in `/var/lib/containers`. Containers can be destroyed using
the imperative method: `nixos-container destroy foo`.
Declarative containers can be started and stopped using the
corresponding systemd service, e.g.
`systemctl start container@database`.

View file

@ -1,60 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-declarative-containers">
<title>Declarative Container Specification</title>
<para>
You can also specify containers and their configuration in the hosts
<filename>configuration.nix</filename>. For example, the following specifies
that there shall be a container named <literal>database</literal> running
PostgreSQL:
<programlisting>
containers.database =
{ config =
{ config, pkgs, ... }:
{ <xref linkend="opt-services.postgresql.enable"/> = true;
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_9_6;
};
};
</programlisting>
If you run <literal>nixos-rebuild switch</literal>, the container will be
built. If the container was already running, it will be updated in place,
without rebooting. The container can be configured to start automatically by
setting <literal>containers.database.autoStart = true</literal> in its
configuration.
</para>
<para>
By default, declarative containers share the network namespace of the host,
meaning that they can listen on (privileged) ports. However, they cannot
change the network configuration. You can give a container its own network as
follows:
<programlisting>
containers.database = {
<link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true;
<link linkend="opt-containers._name_.hostAddress">hostAddress</link> = "192.168.100.10";
<link linkend="opt-containers._name_.localAddress">localAddress</link> = "192.168.100.11";
};
</programlisting>
This gives the container a private virtual Ethernet interface with IP address
<literal>192.168.100.11</literal>, which is hooked up to a virtual Ethernet
interface on the host with IP address <literal>192.168.100.10</literal>. (See
the next section for details on container networking.)
</para>
<para>
To disable the container, just remove it from
<filename>configuration.nix</filename> and run <literal>nixos-rebuild
switch</literal>. Note that this will not delete the root directory of the
container in <literal>/var/lib/containers</literal>. Containers can be
destroyed using the imperative method: <literal>nixos-container destroy
foo</literal>.
</para>
<para>
Declarative containers can be started and stopped using the corresponding
systemd service, e.g. <literal>systemctl start container@database</literal>.
</para>
</section>

View file

@ -0,0 +1,115 @@
# Imperative Container Management {#sec-imperative-containers}
We'll cover imperative container management using `nixos-container`
first. Be aware that container management is currently only possible as
`root`.
You create a container with identifier `foo` as follows:
```ShellSession
# nixos-container create foo
```
This creates the container's root directory in `/var/lib/containers/foo`
and a small configuration file in `/etc/containers/foo.conf`. It also
builds the container's initial system configuration and stores it in
`/nix/var/nix/profiles/per-container/foo/system`. You can modify the
initial configuration of the container on the command line. For
instance, to create a container that has `sshd` running, with the given
public key for `root`:
```ShellSession
# nixos-container create foo --config '
services.openssh.enable = true;
users.users.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];
'
```
By default the next free address in the `10.233.0.0/16` subnet will be
chosen as container IP. This behavior can be altered by setting
`--host-address` and `--local-address`:
```ShellSession
# nixos-container create test --config-file test-container.nix \
--local-address 10.235.1.2 --host-address 10.235.1.1
```
Creating a container does not start it. To start the container, run:
```ShellSession
# nixos-container start foo
```
This command will return as soon as the container has booted and has
reached `multi-user.target`. On the host, the container runs within a
systemd unit called `container@container-name.service`. Thus, if
something went wrong, you can get status info using `systemctl`:
```ShellSession
# systemctl status container@foo
```
If the container has started successfully, you can log in as root using
the `root-login` operation:
```ShellSession
# nixos-container root-login foo
[root@foo:~]#
```
Note that only root on the host can do this (since there is no
authentication). You can also get a regular login prompt using the
`login` operation, which is available to all users on the host:
```ShellSession
# nixos-container login foo
foo login: alice
Password: ***
```
With `nixos-container run`, you can execute arbitrary commands in the
container:
```ShellSession
# nixos-container run foo -- uname -a
Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
```
There are several ways to change the configuration of the container.
First, on the host, you can edit
`/var/lib/container/name/etc/nixos/configuration.nix`, and run
```ShellSession
# nixos-container update foo
```
This will build and activate the new configuration. You can also specify
a new configuration on the command line:
```ShellSession
# nixos-container update foo --config '
services.httpd.enable = true;
services.httpd.adminAddr = "foo@example.org";
networking.firewall.allowedTCPPorts = [ 80 ];
'
# curl http://$(nixos-container show-ip foo)/
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
```
However, note that this will overwrite the container's
`/etc/nixos/configuration.nix`.
Alternatively, you can change the configuration from within the
container itself by running `nixos-rebuild switch` inside the container.
Note that the container by default does not have a copy of the NixOS
channel, so you should run `nix-channel --update` first.
Containers can be stopped and started using `nixos-container
stop` and `nixos-container start`, respectively, or by using
`systemctl` on the container's service unit. To destroy a container,
including its file system, do
```ShellSession
# nixos-container destroy foo
```

View file

@ -1,123 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-imperative-containers">
<title>Imperative Container Management</title>
<para>
Well cover imperative container management using
<command>nixos-container</command> first. Be aware that container management
is currently only possible as <literal>root</literal>.
</para>
<para>
You create a container with identifier <literal>foo</literal> as follows:
<screen>
<prompt># </prompt>nixos-container create <replaceable>foo</replaceable>
</screen>
This creates the containers root directory in
<filename>/var/lib/containers/<replaceable>foo</replaceable></filename> and a small configuration file
in <filename>/etc/containers/<replaceable>foo</replaceable>.conf</filename>. It also builds the
containers initial system configuration and stores it in
<filename>/nix/var/nix/profiles/per-container/<replaceable>foo</replaceable>/system</filename>. You can
modify the initial configuration of the container on the command line. For
instance, to create a container that has <command>sshd</command> running,
with the given public key for <literal>root</literal>:
<screen>
<prompt># </prompt>nixos-container create <replaceable>foo</replaceable> --config '
<xref linkend="opt-services.openssh.enable"/> = true;
<link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"];
'
</screen>
By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen
as container IP. This behavior can be altered by setting <literal>--host-address</literal> and
<literal>--local-address</literal>:
<screen>
<prompt># </prompt>nixos-container create test --config-file test-container.nix \
--local-address 10.235.1.2 --host-address 10.235.1.1
</screen>
</para>
<para>
Creating a container does not start it. To start the container, run:
<screen>
<prompt># </prompt>nixos-container start <replaceable>foo</replaceable>
</screen>
This command will return as soon as the container has booted and has reached
<literal>multi-user.target</literal>. On the host, the container runs within
a systemd unit called
<literal>container@<replaceable>container-name</replaceable>.service</literal>.
Thus, if something went wrong, you can get status info using
<command>systemctl</command>:
<screen>
<prompt># </prompt>systemctl status container@<replaceable>foo</replaceable>
</screen>
</para>
<para>
If the container has started successfully, you can log in as root using the
<command>root-login</command> operation:
<screen>
<prompt># </prompt>nixos-container root-login <replaceable>foo</replaceable>
<prompt>[root@foo:~]#</prompt>
</screen>
Note that only root on the host can do this (since there is no
authentication). You can also get a regular login prompt using the
<command>login</command> operation, which is available to all users on the
host:
<screen>
<prompt># </prompt>nixos-container login <replaceable>foo</replaceable>
foo login: alice
Password: ***
</screen>
With <command>nixos-container run</command>, you can execute arbitrary
commands in the container:
<screen>
<prompt># </prompt>nixos-container run <replaceable>foo</replaceable> -- uname -a
Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
</screen>
</para>
<para>
There are several ways to change the configuration of the container. First,
on the host, you can edit
<literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>,
and run
<screen>
<prompt># </prompt>nixos-container update <replaceable>foo</replaceable>
</screen>
This will build and activate the new configuration. You can also specify a
new configuration on the command line:
<screen>
<prompt># </prompt>nixos-container update <replaceable>foo</replaceable> --config '
<xref linkend="opt-services.httpd.enable"/> = true;
<xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org";
<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ];
'
<prompt># </prompt>curl http://$(nixos-container show-ip <replaceable>foo</replaceable>)/
&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
</screen>
However, note that this will overwrite the containers
<filename>/etc/nixos/configuration.nix</filename>.
</para>
<para>
Alternatively, you can change the configuration from within the container
itself by running <command>nixos-rebuild switch</command> inside the
container. Note that the container by default does not have a copy of the
NixOS channel, so you should run <command>nix-channel --update</command>
first.
</para>
<para>
Containers can be stopped and started using <literal>nixos-container
stop</literal> and <literal>nixos-container start</literal>, respectively, or
by using <command>systemctl</command> on the containers service unit. To
destroy a container, including its file system, do
<screen>
<prompt># </prompt>nixos-container destroy <replaceable>foo</replaceable>
</screen>
</para>
</section>

View file

@ -0,0 +1,38 @@
# Logging {#sec-logging}
System-wide logging is provided by systemd's *journal*, which subsumes
traditional logging daemons such as syslogd and klogd. Log entries are
kept in binary files in `/var/log/journal/`. The command `journalctl`
allows you to see the contents of the journal. For example,
```ShellSession
$ journalctl -b
```
shows all journal entries since the last reboot. (The output of
`journalctl` is piped into `less` by default.) You can use various
options and match operators to restrict output to messages of interest.
For instance, to get all messages from PostgreSQL:
```ShellSession
$ journalctl -u postgresql.service
-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --
...
Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down
-- Reboot --
Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET
Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections
```
Or to get all messages since the last reboot that have at least a
"critical" severity level:
```ShellSession
$ journalctl -b -p crit
Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]
Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1)
```
The system journal is readable by root and by users in the `wheel` and
`systemd-journal` groups. All users have a private journal that can be
read using `journalctl`.

View file

@ -1,43 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-logging">
<title>Logging</title>
<para>
System-wide logging is provided by systemds <emphasis>journal</emphasis>,
which subsumes traditional logging daemons such as syslogd and klogd. Log
entries are kept in binary files in <filename>/var/log/journal/</filename>.
The command <literal>journalctl</literal> allows you to see the contents of
the journal. For example,
<screen>
<prompt>$ </prompt>journalctl -b
</screen>
shows all journal entries since the last reboot. (The output of
<command>journalctl</command> is piped into <command>less</command> by
default.) You can use various options and match operators to restrict output
to messages of interest. For instance, to get all messages from PostgreSQL:
<screen>
<prompt>$ </prompt>journalctl -u postgresql.service
-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --
...
Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down
-- Reboot --
Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET
Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections
</screen>
Or to get all messages since the last reboot that have at least a
“critical” severity level:
<screen>
<prompt>$ </prompt>journalctl -b -p crit
Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]
Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1)
</screen>
</para>
<para>
The system journal is readable by root and by users in the
<literal>wheel</literal> and <literal>systemd-journal</literal> groups. All
users have a private journal that can be read using
<command>journalctl</command>.
</para>
</chapter>

View file

@ -0,0 +1,11 @@
# Maintenance Mode {#sec-maintenance-mode}
You can enter rescue mode by running:
```ShellSession
# systemctl rescue
```
This will eventually give you a single-user root shell. Systemd will
stop (almost) all system services. To get out of maintenance mode, just
exit from the rescue shell.

View file

@ -1,16 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-maintenance-mode">
<title>Maintenance Mode</title>
<para>
You can enter rescue mode by running:
<screen>
<prompt># </prompt>systemctl rescue</screen>
This will eventually give you a single-user root shell. Systemd will stop
(almost) all system services. To get out of maintenance mode, just exit from
the rescue shell.
</para>
</section>

View file

@ -0,0 +1,21 @@
# Network Problems {#sec-nix-network-issues}
Nix uses a so-called *binary cache* to optimise building a package from
source into downloading it as a pre-built binary. That is, whenever a
command like `nixos-rebuild` needs a path in the Nix store, Nix will try
to download that path from the Internet rather than build it from
source. The default binary cache is `https://cache.nixos.org/`. If this
cache is unreachable, Nix operations may take a long time due to HTTP
connection timeouts. You can disable the use of the binary cache by
adding `--option use-binary-caches false`, e.g.
```ShellSession
# nixos-rebuild switch --option use-binary-caches false
```
If you have an alternative binary cache at your disposal, you can use it
instead:
```ShellSession
# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
```

View file

@ -1,27 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-network-issues">
<title>Network Problems</title>
<para>
Nix uses a so-called <emphasis>binary cache</emphasis> to optimise building a
package from source into downloading it as a pre-built binary. That is,
whenever a command like <command>nixos-rebuild</command> needs a path in the
Nix store, Nix will try to download that path from the Internet rather than
build it from source. The default binary cache is
<uri>https://cache.nixos.org/</uri>. If this cache is unreachable, Nix
operations may take a long time due to HTTP connection timeouts. You can
disable the use of the binary cache by adding <option>--option
use-binary-caches false</option>, e.g.
<screen>
<prompt># </prompt>nixos-rebuild switch --option use-binary-caches false
</screen>
If you have an alternative binary cache at your disposal, you can use it
instead:
<screen>
<prompt># </prompt>nixos-rebuild switch --option binary-caches <replaceable>http://my-cache.example.org/</replaceable>
</screen>
</para>
</section>

View file

@ -0,0 +1,30 @@
# Rebooting and Shutting Down {#sec-rebooting}
The system can be shut down (and automatically powered off) by doing:
```ShellSession
# shutdown
```
This is equivalent to running `systemctl poweroff`.
To reboot the system, run
```ShellSession
# reboot
```
which is equivalent to `systemctl reboot`. Alternatively, you can
quickly reboot the system using `kexec`, which bypasses the BIOS by
directly loading the new kernel into memory:
```ShellSession
# systemctl kexec
```
The machine can be suspended to RAM (if supported) using `systemctl suspend`,
and suspended to disk using `systemctl hibernate`.
These commands can be run by any user who is logged in locally, i.e. on
a virtual console or in X11; otherwise, the user is asked for
authentication.

View file

@ -1,35 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-rebooting">
<title>Rebooting and Shutting Down</title>
<para>
The system can be shut down (and automatically powered off) by doing:
<screen>
<prompt># </prompt>shutdown
</screen>
This is equivalent to running <command>systemctl poweroff</command>.
</para>
<para>
To reboot the system, run
<screen>
<prompt># </prompt>reboot
</screen>
which is equivalent to <command>systemctl reboot</command>. Alternatively,
you can quickly reboot the system using <literal>kexec</literal>, which
bypasses the BIOS by directly loading the new kernel into memory:
<screen>
<prompt># </prompt>systemctl kexec
</screen>
</para>
<para>
The machine can be suspended to RAM (if supported) using <command>systemctl
suspend</command>, and suspended to disk using <command>systemctl
hibernate</command>.
</para>
<para>
These commands can be run by any user who is logged in locally, i.e. on a
virtual console or in X11; otherwise, the user is asked for authentication.
</para>
</chapter>

View file

@ -0,0 +1,38 @@
# Rolling Back Configuration Changes {#sec-rollback}
After running `nixos-rebuild` to switch to a new configuration, you may
find that the new configuration doesn't work very well. In that case,
there are several ways to return to a previous configuration.
First, the GRUB boot manager allows you to boot into any previous
configuration that hasn't been garbage-collected. These configurations
can be found under the GRUB submenu "NixOS - All configurations". This
is especially useful if the new configuration fails to boot. After the
system has booted, you can make the selected configuration the default
for subsequent boots:
```ShellSession
# /run/current-system/bin/switch-to-configuration boot
```
Second, you can switch to the previous configuration in a running
system:
```ShellSession
# nixos-rebuild switch --rollback
```
This is equivalent to running:
```ShellSession
# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch
```
where `N` is the number of the NixOS system configuration. To get a
list of the available configurations, do:
```ShellSession
$ ls -l /nix/var/nix/profiles/system-*-link
...
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
```

View file

@ -1,41 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-rollback">
<title>Rolling Back Configuration Changes</title>
<para>
After running <command>nixos-rebuild</command> to switch to a new
configuration, you may find that the new configuration doesnt work very
well. In that case, there are several ways to return to a previous
configuration.
</para>
<para>
First, the GRUB boot manager allows you to boot into any previous
configuration that hasnt been garbage-collected. These configurations can
be found under the GRUB submenu “NixOS - All configurations”. This is
especially useful if the new configuration fails to boot. After the system
has booted, you can make the selected configuration the default for
subsequent boots:
<screen>
<prompt># </prompt>/run/current-system/bin/switch-to-configuration boot</screen>
</para>
<para>
Second, you can switch to the previous configuration in a running system:
<screen>
<prompt># </prompt>nixos-rebuild switch --rollback</screen>
This is equivalent to running:
<screen>
<prompt># </prompt>/nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
where <replaceable>N</replaceable> is the number of the NixOS system
configuration. To get a list of the available configurations, do:
<screen>
<prompt>$ </prompt>ls -l /nix/var/nix/profiles/system-*-link
<replaceable>...</replaceable>
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
</screen>
</para>
</section>

View file

@ -10,12 +10,12 @@
such as how to use the <command>systemd</command> service manager.
</para>
</partintro>
<xi:include href="service-mgmt.xml" />
<xi:include href="rebooting.xml" />
<xi:include href="user-sessions.xml" />
<xi:include href="control-groups.xml" />
<xi:include href="logging.xml" />
<xi:include href="cleaning-store.xml" />
<xi:include href="containers.xml" />
<xi:include href="troubleshooting.xml" />
<xi:include href="../from_md/administration/service-mgmt.chapter.xml" />
<xi:include href="../from_md/administration/rebooting.chapter.xml" />
<xi:include href="../from_md/administration/user-sessions.chapter.xml" />
<xi:include href="../from_md/administration/control-groups.chapter.xml" />
<xi:include href="../from_md/administration/logging.chapter.xml" />
<xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
<xi:include href="../from_md/administration/containers.chapter.xml" />
<xi:include href="../from_md/administration/troubleshooting.chapter.xml" />
</part>

View file

@ -0,0 +1,120 @@
# Service Management {#sec-systemctl}
In NixOS, all system services are started and monitored using the
systemd program. systemd is the "init" process of the system (i.e. PID
1), the parent of all other processes. It manages a set of so-called
"units", which can be things like system services (programs), but also
mount points, swap files, devices, targets (groups of units) and more.
Units can have complex dependencies; for instance, one unit can require
that another unit must be successfully started before the first unit can
be started. When the system boots, it starts a unit named
`default.target`; the dependencies of this unit cause all system
services to be started, file systems to be mounted, swap files to be
activated, and so on.
## Interacting with a running systemd {#sect-nixos-systemd-general}
The command `systemctl` is the main way to interact with `systemd`. The
following paragraphs demonstrate ways to interact with any OS running
systemd as init system. NixOS is of no exception. The [next section
](#sect-nixos-systemd-nixos) explains NixOS specific things worth
knowing.
Without any arguments, `systemctl` the status of active units:
```ShellSession
$ systemctl
-.mount loaded active mounted /
swapfile.swap loaded active active /swapfile
sshd.service loaded active running SSH Daemon
graphical.target loaded active active Graphical Interface
...
```
You can ask for detailed status information about a unit, for instance,
the PostgreSQL database service:
```ShellSession
$ systemctl status postgresql.service
postgresql.service - PostgreSQL Server
Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago
Main PID: 2390 (postgres)
CGroup: name=systemd:/system/postgresql.service
├─2390 postgres
├─2418 postgres: writer process
├─2419 postgres: wal writer process
├─2420 postgres: autovacuum launcher process
├─2421 postgres: stats collector process
└─2498 postgres: zabbix zabbix [local] idle
Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET
Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections
Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started
Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
```
Note that this shows the status of the unit (active and running), all
the processes belonging to the service, as well as the most recent log
messages from the service.
Units can be stopped, started or restarted:
```ShellSession
# systemctl stop postgresql.service
# systemctl start postgresql.service
# systemctl restart postgresql.service
```
These operations are synchronous: they wait until the service has
finished starting or stopping (or has failed). Starting a unit will
cause the dependencies of that unit to be started as well (if
necessary).
## systemd in NixOS {#sect-nixos-systemd-nixos}
Packages in Nixpkgs sometimes provide systemd units with them, usually
in e.g `#pkg-out#/lib/systemd/`. Putting such a package in
`environment.systemPackages` doesn\'t make the service available to
users or the system.
In order to enable a systemd *system* service with provided upstream
package, use (e.g):
```nix
systemd.packages = [ pkgs.packagekit ];
```
Usually NixOS modules written by the community do the above, plus take
care of other details. If a module was written for a service you are
interested in, you\'d probably need only to use
`services.#name#.enable = true;`. These services are defined in
Nixpkgs\' [ `nixos/modules/` directory
](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules). In case
the service is simple enough, the above method should work, and start
the service on boot.
*User* systemd services on the other hand, should be treated
differently. Given a package that has a systemd unit file at
`#pkg-out#/lib/systemd/user/`, using [](#opt-systemd.packages) will
make you able to start the service via `systemctl --user start`, but it
won\'t start automatically on login. However, You can imperatively
enable it by adding the package\'s attribute to
[](#opt-systemd.packages) and then do this (e.g):
```ShellSession
$ mkdir -p ~/.config/systemd/user/default.target.wants
$ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
$ systemctl --user daemon-reload
$ systemctl --user enable syncthing.service
```
If you are interested in a timer file, use `timers.target.wants` instead
of `default.target.wants` in the 1st and 2nd command.
Using `systemctl --user enable syncthing.service` instead of the above,
will work, but it\'ll use the absolute path of `syncthing.service` for
the symlink, and this path is in `/nix/store/.../lib/systemd/user/`.
Hence [garbage collection](#sec-nix-gc) will remove that file and you
will wind up with a broken symlink in your systemd configuration, which
in turn will not make the service / timer start on login.

View file

@ -1,140 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-systemctl">
<title>Service Management</title>
<para>
In NixOS, all system services are started and monitored using the systemd
program. systemd is the “init” process of the system (i.e. PID 1), the
parent of all other processes. It manages a set of so-called “units”,
which can be things like system services (programs), but also mount points,
swap files, devices, targets (groups of units) and more. Units can have
complex dependencies; for instance, one unit can require that another unit
must be successfully started before the first unit can be started. When the
system boots, it starts a unit named <literal>default.target</literal>; the
dependencies of this unit cause all system services to be started, file
systems to be mounted, swap files to be activated, and so on.
</para>
<section xml:id="sect-nixos-systemd-general">
<title>Interacting with a running systemd</title>
<para>
The command <command>systemctl</command> is the main way to interact with
<command>systemd</command>. The following paragraphs demonstrate ways to
interact with any OS running systemd as init system. NixOS is of no
exception. The <link xlink:href="#sect-nixos-systemd-nixos">next section
</link> explains NixOS specific things worth knowing.
</para>
<para>
Without any arguments, <literal>systmctl</literal> the status of active units:
<screen>
<prompt>$ </prompt>systemctl
-.mount loaded active mounted /
swapfile.swap loaded active active /swapfile
sshd.service loaded active running SSH Daemon
graphical.target loaded active active Graphical Interface
<replaceable>...</replaceable>
</screen>
</para>
<para>
You can ask for detailed status information about a unit, for instance, the
PostgreSQL database service:
<screen>
<prompt>$ </prompt>systemctl status postgresql.service
postgresql.service - PostgreSQL Server
Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago
Main PID: 2390 (postgres)
CGroup: name=systemd:/system/postgresql.service
├─2390 postgres
├─2418 postgres: writer process
├─2419 postgres: wal writer process
├─2420 postgres: autovacuum launcher process
├─2421 postgres: stats collector process
└─2498 postgres: zabbix zabbix [local] idle
Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET
Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections
Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started
Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
</screen>
Note that this shows the status of the unit (active and running), all the
processes belonging to the service, as well as the most recent log messages
from the service.
</para>
<para>
Units can be stopped, started or restarted:
<screen>
<prompt># </prompt>systemctl stop postgresql.service
<prompt># </prompt>systemctl start postgresql.service
<prompt># </prompt>systemctl restart postgresql.service
</screen>
These operations are synchronous: they wait until the service has finished
starting or stopping (or has failed). Starting a unit will cause the
dependencies of that unit to be started as well (if necessary).
</para>
<!-- TODO: document cgroups, draft:
each service and user session is a cgroup
- cgroup resource management -->
</section>
<section xml:id="sect-nixos-systemd-nixos">
<title>systemd in NixOS</title>
<para>
Packages in Nixpkgs sometimes provide systemd units with them, usually in
e.g <literal>#pkg-out#/lib/systemd/</literal>. Putting such a package in
<literal>environment.systemPackages</literal> doesn't make the service
available to users or the system.
</para>
<para>
In order to enable a systemd <emphasis>system</emphasis> service with
provided upstream package, use (e.g):
<programlisting>
<xref linkend="opt-systemd.packages"/> = [ pkgs.packagekit ];
</programlisting>
</para>
<para>
Usually NixOS modules written by the community do the above, plus take care of
other details. If a module was written for a service you are interested in,
you'd probably need only to use
<literal>services.#name#.enable = true;</literal>. These services are defined
in Nixpkgs'
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">
<literal>nixos/modules/</literal> directory </link>. In case the service is
simple enough, the above method should work, and start the service on boot.
</para>
<para>
<emphasis>User</emphasis> systemd services on the other hand, should be
treated differently. Given a package that has a systemd unit file at
<literal>#pkg-out#/lib/systemd/user/</literal>, using
<xref linkend="opt-systemd.packages"/> will make you able to start the service via
<literal>systemctl --user start</literal>, but it won't start automatically on login.
<!-- TODO: Document why systemd.packages doesn't work for user services or fix this.
https://github.com/NixOS/nixpkgs/blob/2cd6594a8710a801038af2b72348658f732ce84a/nixos/modules/system/boot/systemd-lib.nix#L177-L198
This has been talked over at https://discourse.nixos.org/t/how-to-enable-upstream-systemd-user-services-declaratively/7649/5
-->
However, You can imperatively enable it by adding the package's attribute to
<link linkend="opt-environment.systemPackages">
<literal>systemd.packages</literal></link> and then do this (e.g):
<screen>
<prompt>$ </prompt>mkdir -p ~/.config/systemd/user/default.target.wants
<prompt>$ </prompt>ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
<prompt>$ </prompt>systemctl --user daemon-reload
<prompt>$ </prompt>systemctl --user enable syncthing.service
</screen>
If you are interested in a timer file, use <literal>timers.target.wants</literal>
instead of <literal>default.target.wants</literal> in the 1st and 2nd command.
</para>
<para>
Using <literal>systemctl --user enable syncthing.service</literal> instead of
the above, will work, but it'll use the absolute path of
<literal>syncthing.service</literal> for the symlink, and this path is in
<literal>/nix/store/.../lib/systemd/user/</literal>. Hence
<link xlink:href="#sec-nix-gc">garbage collection</link> will remove that file
and you will wind up with a broken symlink in your systemd configuration, which
in turn will not make the service / timer start on login.
</para>
</section>
</chapter>

View file

@ -0,0 +1,28 @@
# Nix Store Corruption {#sec-nix-store-corruption}
After a system crash, it's possible for files in the Nix store to become
corrupted. (For instance, the Ext4 file system has the tendency to
replace un-synced files with zero bytes.) NixOS tries hard to prevent
this from happening: it performs a `sync` before switching to a new
configuration, and Nix's database is fully transactional. If corruption
still occurs, you may be able to fix it automatically.
If the corruption is in a path in the closure of the NixOS system
configuration, you can fix it by doing
```ShellSession
# nixos-rebuild switch --repair
```
This will cause Nix to check every path in the closure, and if its
cryptographic hash differs from the hash recorded in Nix's database, the
path is rebuilt or redownloaded.
You can also scan the entire Nix store for corrupt paths:
```ShellSession
# nix-store --verify --check-contents --repair
```
Any corrupt paths will be redownloaded if they're available in a binary
cache; otherwise, they cannot be repaired.

View file

@ -1,36 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-store-corruption">
<title>Nix Store Corruption</title>
<para>
After a system crash, its possible for files in the Nix store to become
corrupted. (For instance, the Ext4 file system has the tendency to replace
un-synced files with zero bytes.) NixOS tries hard to prevent this from
happening: it performs a <command>sync</command> before switching to a new
configuration, and Nixs database is fully transactional. If corruption
still occurs, you may be able to fix it automatically.
</para>
<para>
If the corruption is in a path in the closure of the NixOS system
configuration, you can fix it by doing
<screen>
<prompt># </prompt>nixos-rebuild switch --repair
</screen>
This will cause Nix to check every path in the closure, and if its
cryptographic hash differs from the hash recorded in Nixs database, the
path is rebuilt or redownloaded.
</para>
<para>
You can also scan the entire Nix store for corrupt paths:
<screen>
<prompt># </prompt>nix-store --verify --check-contents --repair
</screen>
Any corrupt paths will be redownloaded if theyre available in a binary
cache; otherwise, they cannot be repaired.
</para>
</section>

View file

@ -0,0 +1,12 @@
# Troubleshooting {#ch-troubleshooting}
This chapter describes solutions to common problems you might encounter
when you manage your NixOS system.
```{=docbook}
<xi:include href="boot-problems.section.xml" />
<xi:include href="maintenance-mode.section.xml" />
<xi:include href="rollback.section.xml" />
<xi:include href="store-corruption.section.xml" />
<xi:include href="network-problems.section.xml" />
```

View file

@ -1,16 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-troubleshooting">
<title>Troubleshooting</title>
<para>
This chapter describes solutions to common problems you might encounter when
you manage your NixOS system.
</para>
<xi:include href="../from_md/administration/boot-problems.section.xml" />
<xi:include href="maintenance-mode.xml" />
<xi:include href="rollback.xml" />
<xi:include href="store-corruption.xml" />
<xi:include href="network-problems.xml" />
</chapter>

View file

@ -0,0 +1,43 @@
# User Sessions {#sec-user-sessions}
Systemd keeps track of all users who are logged into the system (e.g. on
a virtual console or remotely via SSH). The command `loginctl` allows
querying and manipulating user sessions. For instance, to list all user
sessions:
```ShellSession
$ loginctl
SESSION UID USER SEAT
c1 500 eelco seat0
c3 0 root seat0
c4 500 alice
```
This shows that two users are logged in locally, while another is logged
in remotely. ("Seats" are essentially the combinations of displays and
input devices attached to the system; usually, there is only one seat.)
To get information about a session:
```ShellSession
$ loginctl session-status c3
c3 - root (0)
Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago
Leader: 2536 (login)
Seat: seat0; vc3
TTY: /dev/tty3
Service: login; type tty; class user
State: online
CGroup: name=systemd:/user/root/c3
├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --
├─10339 -bash
└─10355 w3m nixos.org
```
This shows that the user is logged in on virtual console 3. It also
lists the processes belonging to this session. Since systemd keeps track
of this, you can terminate a session in a way that ensures that all the
session's processes are gone:
```ShellSession
# loginctl terminate-session c3
```

View file

@ -1,45 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-user-sessions">
<title>User Sessions</title>
<para>
Systemd keeps track of all users who are logged into the system (e.g. on a
virtual console or remotely via SSH). The command <command>loginctl</command>
allows querying and manipulating user sessions. For instance, to list all
user sessions:
<screen>
<prompt>$ </prompt>loginctl
SESSION UID USER SEAT
c1 500 eelco seat0
c3 0 root seat0
c4 500 alice
</screen>
This shows that two users are logged in locally, while another is logged in
remotely. (“Seats” are essentially the combinations of displays and input
devices attached to the system; usually, there is only one seat.) To get
information about a session:
<screen>
<prompt>$ </prompt>loginctl session-status c3
c3 - root (0)
Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago
Leader: 2536 (login)
Seat: seat0; vc3
TTY: /dev/tty3
Service: login; type tty; class user
State: online
CGroup: name=systemd:/user/root/c3
├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --
├─10339 -bash
└─10355 w3m nixos.org
</screen>
This shows that the user is logged in on virtual console 3. It also lists the
processes belonging to this session. Since systemd keeps track of this, you
can terminate a session in a way that ensures that all the sessions
processes are gone:
<screen>
<prompt># </prompt>loginctl terminate-session c3
</screen>
</para>
</chapter>

View file

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

View file

@ -1,20 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ad-hoc-network-config">
<title>Ad-Hoc Configuration</title>
<para>
You can use <xref linkend="opt-networking.localCommands"/> to specify shell
commands to be run at the end of <literal>network-setup.service</literal>.
This is useful for doing network configuration not covered by the existing
NixOS modules. For instance, to statically configure an IPv6 address:
<programlisting>
<xref linkend="opt-networking.localCommands"/> =
''
ip -6 addr add 2001:610:685:1::1/64 dev eth0
'';
</programlisting>
</para>
</section>

View file

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

View file

@ -1,61 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-ad-hoc-packages">
<title>Ad-Hoc Package Management</title>
<para>
With the command <command>nix-env</command>, you can install and uninstall
packages from the command line. For instance, to install Mozilla Thunderbird:
<screen>
<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen>
If you invoke this as root, the package is installed in the Nix profile
<filename>/nix/var/nix/profiles/default</filename> and visible to all users
of the system; otherwise, the package ends up in
<filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename>
and is not visible to other users. The <option>-A</option> flag specifies the
package by its attribute name; without it, the package is installed by
matching against its package name (e.g. <literal>thunderbird</literal>). The
latter is slower because it requires matching against all available Nix
packages, and is ambiguous if there are multiple matching packages.
</para>
<para>
Packages come from the NixOS channel. You typically upgrade a package by
updating to the latest version of the NixOS channel:
<screen>
<prompt>$ </prompt>nix-channel --update nixos
</screen>
and then running <literal>nix-env -i</literal> again. Other packages in the
profile are <emphasis>not</emphasis> affected; this is the crucial difference
with the declarative style of package management, where running
<command>nixos-rebuild switch</command> causes all packages to be updated to
their current versions in the NixOS channel. You can however upgrade all
packages for which there is a newer version by doing:
<screen>
<prompt>$ </prompt>nix-env -u '*'
</screen>
</para>
<para>
A package can be uninstalled using the <option>-e</option> flag:
<screen>
<prompt>$ </prompt>nix-env -e thunderbird
</screen>
</para>
<para>
Finally, you can roll back an undesirable <command>nix-env</command> action:
<screen>
<prompt>$ </prompt>nix-env --rollback
</screen>
</para>
<para>
<command>nix-env</command> has many more flags. For details, see the
<citerefentry>
<refentrytitle>nix-env</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> manpage or the Nix manual.
</para>
</section>

View file

@ -0,0 +1,74 @@
# Adding Custom Packages {#sec-custom-packages}
It's possible that a package you need is not available in NixOS. In that
case, you can do two things. First, you can clone the Nixpkgs
repository, add the package to your clone, and (optionally) submit a
patch or pull request to have it accepted into the main Nixpkgs repository.
This is described in detail in the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).
In short, you clone Nixpkgs:
```ShellSession
$ git clone https://github.com/NixOS/nixpkgs
$ cd nixpkgs
```
Then you write and test the package as described in the Nixpkgs manual.
Finally, you add it to [](#opt-environment.systemPackages), e.g.
```nix
environment.systemPackages = [ pkgs.my-package ];
```
and you run `nixos-rebuild`, specifying your own Nixpkgs tree:
```ShellSession
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
```
The second possibility is to add the package outside of the Nixpkgs
tree. For instance, here is how you specify a build of the
[GNU Hello](https://www.gnu.org/software/hello/) package directly in
`configuration.nix`:
```nix
environment.systemPackages =
let
my-hello = with pkgs; stdenv.mkDerivation rec {
name = "hello-2.8";
src = fetchurl {
url = "mirror://gnu/hello/${name}.tar.gz";
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
};
};
in
[ my-hello ];
```
Of course, you can also move the definition of `my-hello` into a
separate Nix expression, e.g.
```nix
environment.systemPackages = [ (import ./my-hello.nix) ];
```
where `my-hello.nix` contains:
```nix
with import <nixpkgs> {}; # bring all of Nixpkgs into scope
stdenv.mkDerivation rec {
name = "hello-2.8";
src = fetchurl {
url = "mirror://gnu/hello/${name}.tar.gz";
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
};
}
```
This allows testing the package easily:
```ShellSession
$ nix-build my-hello.nix
$ ./result/bin/hello
Hello, world!
```

View file

@ -1,73 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-custom-packages">
<title>Adding Custom Packages</title>
<para>
Its possible that a package you need is not available in NixOS. In that
case, you can do two things. First, you can clone the Nixpkgs repository, add
the package to your clone, and (optionally) submit a patch or pull request to
have it accepted into the main Nixpkgs repository. This is described in
detail in the <link
xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
manual</link>. In short, you clone Nixpkgs:
<screen>
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
<prompt>$ </prompt>cd nixpkgs
</screen>
Then you write and test the package as described in the Nixpkgs manual.
Finally, you add it to <literal>environment.systemPackages</literal>, e.g.
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];
</programlisting>
and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs
tree:
<screen>
<prompt># </prompt>nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
</para>
<para>
The second possibility is to add the package outside of the Nixpkgs tree. For
instance, here is how you specify a build of the
<link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link>
package directly in <filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> =
let
my-hello = with pkgs; stdenv.mkDerivation rec {
name = "hello-2.8";
src = fetchurl {
url = "mirror://gnu/hello/${name}.tar.gz";
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
};
};
in
[ my-hello ];
</programlisting>
Of course, you can also move the definition of <literal>my-hello</literal>
into a separate Nix expression, e.g.
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];
</programlisting>
where <filename>my-hello.nix</filename> contains:
<programlisting>
with import &lt;nixpkgs> {}; # bring all of Nixpkgs into scope
stdenv.mkDerivation rec {
name = "hello-2.8";
src = fetchurl {
url = "mirror://gnu/hello/${name}.tar.gz";
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
};
}
</programlisting>
This allows testing the package easily:
<screen>
<prompt>$ </prompt>nix-build my-hello.nix
<prompt>$ </prompt>./result/bin/hello
Hello, world!
</screen>
</para>
</section>

View file

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

View file

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

View file

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

View file

@ -1,25 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-configuration-syntax">
<title>Configuration Syntax</title>
<para>
The NixOS configuration file
<filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix
expression</emphasis>, which is the Nix package managers purely functional
language for describing how to build packages and configurations. This means
you have all the expressive power of that language at your disposal,
including the ability to abstract over common patterns, which is very useful
when managing complex systems. The syntax and semantics of the Nix language
are fully described in the
<link
xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
manual</link>, but here we give a short overview of the most important
constructs useful in NixOS configuration files.
</para>
<xi:include href="config-file.xml" />
<xi:include href="../from_md/configuration/abstractions.section.xml" />
<xi:include href="modularity.xml" />
<xi:include href="summary.xml" />
</chapter>

View file

@ -13,19 +13,19 @@
effect after you run <command>nixos-rebuild</command>.
</para>
</partintro>
<xi:include href="config-syntax.xml" />
<xi:include href="package-mgmt.xml" />
<xi:include href="user-mgmt.xml" />
<xi:include href="file-systems.xml" />
<xi:include href="x-windows.xml" />
<xi:include href="wayland.xml" />
<xi:include href="gpu-accel.xml" />
<xi:include href="xfce.xml" />
<xi:include href="networking.xml" />
<xi:include href="linux-kernel.xml" />
<xi:include href="subversion.xml" />
<xi:include href="../from_md/configuration/config-syntax.chapter.xml" />
<xi:include href="../from_md/configuration/package-mgmt.chapter.xml" />
<xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />
<xi:include href="../from_md/configuration/file-systems.chapter.xml" />
<xi:include href="../from_md/configuration/x-windows.chapter.xml" />
<xi:include href="../from_md/configuration/wayland.chapter.xml" />
<xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />
<xi:include href="../from_md/configuration/xfce.chapter.xml" />
<xi:include href="../from_md/configuration/networking.chapter.xml" />
<xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
<xi:include href="../from_md/configuration/subversion.chapter.xml" />
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
<xi:include href="profiles.xml" />
<xi:include href="kubernetes.xml" />
<xi:include href="../from_md/configuration/profiles.chapter.xml" />
<xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
<!-- Apache; libvirtd virtualisation -->
</part>

View file

@ -0,0 +1,74 @@
# Customising Packages {#sec-customising-packages}
Some packages in Nixpkgs have options to enable or disable optional
functionality or change other aspects of the package. For instance, the
Firefox wrapper package (which provides Firefox with a set of plugins
such as the Adobe Flash player) has an option to enable the Google Talk
plugin. It can be set in `configuration.nix` as follows:
`nixpkgs.config.firefox.enableGoogleTalkPlugin = true;`
::: {.warning}
Unfortunately, Nixpkgs currently lacks a way to query available
configuration options.
:::
Apart from high-level options, it's possible to tweak a package in
almost arbitrary ways, such as changing or disabling dependencies of a
package. For instance, the Emacs package in Nixpkgs by default has a
dependency on GTK 2. If you want to build it against GTK 3, you can
specify that as follows:
```nix
environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
```
The function `override` performs the call to the Nix function that
produces Emacs, with the original arguments amended by the set of
arguments specified by you. So here the function argument `gtk` gets the
value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses
are necessary because in Nix, function application binds more weakly
than list construction, so without them,
[](#opt-environment.systemPackages)
would be a list with two elements.)
Even greater customisation is possible using the function
`overrideAttrs`. While the `override` mechanism above overrides the
arguments of a package function, `overrideAttrs` allows changing the
*attributes* passed to `mkDerivation`. This permits changing any aspect
of the package, such as the source code. For instance, if you want to
override the source code of Emacs, you can say:
```nix
environment.systemPackages = [
(pkgs.emacs.overrideAttrs (oldAttrs: {
name = "emacs-25.0-pre";
src = /path/to/my/emacs/tree;
}))
];
```
Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs`
and produces a new derivation in which the original's `name` and `src`
attribute have been replaced by the given values by re-calling
`stdenv.mkDerivation`. The original attributes are accessible via the
function argument, which is conventionally named `oldAttrs`.
The overrides shown above are not global. They do not affect the
original package; other packages in Nixpkgs continue to depend on the
original rather than the customised package. This means that if another
package in your system depends on the original package, you end up with
two instances of the package. If you want to have everything depend on
your customised instance, you can apply a *global* override as follows:
```nix
nixpkgs.config.packageOverrides = pkgs:
{ emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
};
```
The effect of this definition is essentially equivalent to modifying the
`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs
that depends on `emacs` will be passed your customised instance.
(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides`
refers to the original rather than overridden instance, to prevent an
infinite recursion.)

View file

@ -1,86 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-customising-packages">
<title>Customising Packages</title>
<para>
Some packages in Nixpkgs have options to enable or disable optional
functionality or change other aspects of the package. For instance, the
Firefox wrapper package (which provides Firefox with a set of plugins such as
the Adobe Flash player) has an option to enable the Google Talk plugin. It
can be set in <filename>configuration.nix</filename> as follows: <filename>
nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename>
</para>
<warning>
<para>
Unfortunately, Nixpkgs currently lacks a way to query available
configuration options.
</para>
</warning>
<para>
Apart from high-level options, its possible to tweak a package in almost
arbitrary ways, such as changing or disabling dependencies of a package. For
instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2.
If you want to build it against GTK 3, you can specify that as follows:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
</programlisting>
The function <varname>override</varname> performs the call to the Nix
function that produces Emacs, with the original arguments amended by the set
of arguments specified by you. So here the function argument
<varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing
Emacs to depend on GTK 3. (The parentheses are necessary because in Nix,
function application binds more weakly than list construction, so without
them, <xref linkend="opt-environment.systemPackages"/> would be a list with
two elements.)
</para>
<para>
Even greater customisation is possible using the function
<varname>overrideAttrs</varname>. While the <varname>override</varname>
mechanism above overrides the arguments of a package function,
<varname>overrideAttrs</varname> allows changing the
<emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>.
This permits changing any aspect of the package, such as the source code. For
instance, if you want to override the source code of Emacs, you can say:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [
(pkgs.emacs.overrideAttrs (oldAttrs: {
name = "emacs-25.0-pre";
src = /path/to/my/emacs/tree;
}))
];
</programlisting>
Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by
<varname>pkgs.emacs</varname> and produces a new derivation in which the
originals <literal>name</literal> and <literal>src</literal> attribute
have been replaced by the given values by re-calling
<literal>stdenv.mkDerivation</literal>. The original attributes are
accessible via the function argument, which is conventionally named
<varname>oldAttrs</varname>.
</para>
<para>
The overrides shown above are not global. They do not affect the original
package; other packages in Nixpkgs continue to depend on the original rather
than the customised package. This means that if another package in your
system depends on the original package, you end up with two instances of the
package. If you want to have everything depend on your customised instance,
you can apply a <emphasis>global</emphasis> override as follows:
<screen>
nixpkgs.config.packageOverrides = pkgs:
{ emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
};
</screen>
The effect of this definition is essentially equivalent to modifying the
<literal>emacs</literal> attribute in the Nixpkgs source tree. Any package in
Nixpkgs that depends on <literal>emacs</literal> will be passed your
customised instance. (However, the value <literal>pkgs.emacs</literal> in
<varname>nixpkgs.config.packageOverrides</varname> refers to the original
rather than overridden instance, to prevent an infinite recursion.)
</para>
</section>

View file

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

View file

@ -1,54 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-declarative-package-mgmt">
<title>Declarative Package Management</title>
<para>
With declarative package management, you specify which packages you want on
your system by setting the option
<xref linkend="opt-environment.systemPackages"/>. For instance, adding the
following line to <filename>configuration.nix</filename> enables the Mozilla
Thunderbird email application:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
</programlisting>
The effect of this specification is that the Thunderbird package from Nixpkgs
will be built or downloaded as part of the system when you run
<command>nixos-rebuild switch</command>.
</para>
<note>
<para>
Some packages require additional global configuration such as D-Bus or systemd service registration so adding them to <xref linkend="opt-environment.systemPackages"/> might not be sufficient. You are advised to check the <link xlink:href="#ch-options">list of options</link> whether a NixOS module for the package does not exist.
</para>
</note>
<para>
You can get a list of the available packages as follows:
<screen>
<prompt>$ </prompt>nix-env -qaP '*' --description
nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
<replaceable>...</replaceable>
</screen>
The first column in the output is the <emphasis>attribute name</emphasis>,
such as <literal>nixos.thunderbird</literal>.
</para>
<para>
Note: the <literal>nixos</literal> prefix tells us that we want to get the
package from the <literal>nixos</literal> channel and works only in CLI tools.
In declarative configuration use <literal>pkgs</literal> prefix (variable).
</para>
<para>
To “uninstall” a package, simply remove it from
<xref linkend="opt-environment.systemPackages"/> and run
<command>nixos-rebuild switch</command>.
</para>
<xi:include href="customizing-packages.xml" />
<xi:include href="adding-custom-packages.xml" />
</section>

View file

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

View file

@ -1,58 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-file-systems">
<title>File Systems</title>
<para>
You can define file systems using the <option>fileSystems</option>
configuration option. For instance, the following definition causes NixOS to
mount the Ext4 file system on device
<filename>/dev/disk/by-label/data</filename> onto the mount point
<filename>/data</filename>:
<programlisting>
<xref linkend="opt-fileSystems"/>."/data" =
{ device = "/dev/disk/by-label/data";
fsType = "ext4";
};
</programlisting>
This will create an entry in <filename>/etc/fstab</filename>, which will
generate a corresponding
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.mount.html">systemd.mount</link>
unit via
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html">systemd-fstab-generator</link>.
The filesystem will be mounted automatically unless
<literal>"noauto"</literal> is present in <link
linkend="opt-fileSystems._name_.options">options</link>.
<literal>"noauto"</literal> filesystems can be mounted explicitly using
<command>systemctl</command> e.g. <command>systemctl start
data.mount</command>.
Mount points are created automatically if they dont already exist. For
<option><link linkend="opt-fileSystems._name_.device">device</link></option>,
its best to use the topology-independent device aliases in
<filename>/dev/disk/by-label</filename> and
<filename>/dev/disk/by-uuid</filename>, as these dont change if the
topology changes (e.g. if a disk is moved to another IDE controller).
</para>
<para>
You can usually omit the file system type
(<option><link linkend="opt-fileSystems._name_.fsType">fsType</link></option>),
since <command>mount</command> can usually detect the type and load the
necessary kernel module automatically. However, if the file system is needed
at early boot (in the initial ramdisk) and is not <literal>ext2</literal>,
<literal>ext3</literal> or <literal>ext4</literal>, then its best to
specify <option>fsType</option> to ensure that the kernel module is
available.
</para>
<note>
<para>
System startup will fail if any of the filesystems fails to mount, dropping
you to the emergency shell. You can make a mount asynchronous and
non-critical by adding
<literal><link linkend="opt-fileSystems._name_.options">options</link> = [
"nofail" ];</literal>.
</para>
</note>
<xi:include href="luks-file-systems.xml" />
<xi:include href="../from_md/configuration/sshfs-file-systems.section.xml" />
</chapter>

View file

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

View file

@ -1,37 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-firewall">
<title>Firewall</title>
<para>
NixOS has a simple stateful firewall that blocks incoming connections and
other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic.
It is enabled by default. It can be disabled as follows:
<programlisting>
<xref linkend="opt-networking.firewall.enable"/> = false;
</programlisting>
If the firewall is enabled, you can open specific TCP ports to the outside
world:
<programlisting>
<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 443 ];
</programlisting>
Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is
enabled (<option><xref linkend="opt-services.openssh.enable"/> =
true</option>). UDP ports can be opened through
<xref linkend="opt-networking.firewall.allowedUDPPorts"/>.
</para>
<para>
To open ranges of TCP ports:
<programlisting>
<xref linkend="opt-networking.firewall.allowedTCPPortRanges"/> = [
{ from = 4000; to = 4007; }
{ from = 8000; to = 8010; }
];
</programlisting>
Similarly, UDP port ranges can be opened through
<xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>.
</para>
</section>

View file

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

View file

@ -1,262 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-gpu-accel">
<title>GPU acceleration</title>
<para>
NixOS provides various APIs that benefit from GPU hardware
acceleration, such as VA-API and VDPAU for video playback; OpenGL and
Vulkan for 3D graphics; and OpenCL for general-purpose computing.
This chapter describes how to set up GPU hardware acceleration (as far
as this is not done automatically) and how to verify that hardware
acceleration is indeed used.
</para>
<para>
Most of the aforementioned APIs are agnostic with regards to which
display server is used. Consequently, these instructions should apply
both to the X Window System and Wayland compositors.
</para>
<section xml:id="sec-gpu-accel-opencl">
<title>OpenCL</title>
<para>
<link xlink:href="https://en.wikipedia.org/wiki/OpenCL">OpenCL</link> is a
general compute API. It is used by various applications such as
Blender and Darktable to accelerate certain operations.
</para>
<para>
OpenCL applications load drivers through the <emphasis>Installable Client
Driver</emphasis> (ICD) mechanism. In this mechanism, an ICD file
specifies the path to the OpenCL driver for a particular GPU family.
In NixOS, there are two ways to make ICD files visible to the ICD
loader. The first is through the <varname>OCL_ICD_VENDORS</varname>
environment variable. This variable can contain a directory which
is scanned by the ICL loader for ICD files. For example:
<screen><prompt>$</prompt> export \
OCL_ICD_VENDORS=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/</screen>
</para>
<para>
The second mechanism is to add the OpenCL driver package to
<xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
ICD file under <filename>/run/opengl-driver</filename>, where it will
be visible to the ICD loader.
</para>
<para>
The proper installation of OpenCL drivers can be verified through
the <command>clinfo</command> command of the <package>clinfo</package>
package. This command will report the number of hardware devices
that is found and give detailed information for each device:
</para>
<screen><prompt>$</prompt> clinfo | head -n3
Number of platforms 1
Platform Name AMD Accelerated Parallel Processing
Platform Vendor Advanced Micro Devices, Inc.</screen>
<section xml:id="sec-gpu-accel-opencl-amd">
<title>AMD</title>
<para>
Modern AMD <link
xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
Core Next</link> (GCN) GPUs are supported through the
<package>rocm-opencl-icd</package> package. Adding this package to
<xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL
support:
<programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
rocm-opencl-icd
];</programlisting>
</para>
</section>
<section xml:id="sec-gpu-accel-opencl-intel">
<title>Intel</title>
<para>
<link
xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8">Intel
Gen8 and later GPUs</link> are supported by the Intel NEO OpenCL
runtime that is provided by the
<package>intel-compute-runtime</package> package. For Gen7 GPUs,
the deprecated Beignet runtime can be used, which is provided
by the <package>beignet</package> package. The proprietary Intel
OpenCL runtime, in the <package>intel-ocl</package> package, is
an alternative for Gen7 GPUs.
</para>
<para>
The <package>intel-compute-runtime</package>, <package>beignet</package>,
or <package>intel-ocl</package> package can be added to
<xref linkend="opt-hardware.opengl.extraPackages"/> to enable OpenCL
support. For example, for Gen8 and later GPUs, the following
configuration can be used:
<programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
intel-compute-runtime
];</programlisting>
</para>
</section>
</section>
<section xml:id="sec-gpu-accel-vulkan">
<title>Vulkan</title>
<para>
<link xlink:href="https://en.wikipedia.org/wiki/Vulkan_(API)">Vulkan</link> is a
graphics and compute API for GPUs. It is used directly by games or indirectly though
compatibility layers like <link xlink:href="https://github.com/doitsujin/dxvk/wiki">DXVK</link>.
</para>
<para>
By default, if <xref linkend="opt-hardware.opengl.driSupport"/> is enabled,
<package>mesa</package> is installed and provides Vulkan for supported hardware.
</para>
<para>
Similar to OpenCL, Vulkan drivers are loaded through the <emphasis>Installable Client
Driver</emphasis> (ICD) mechanism. ICD files for Vulkan are JSON files that specify
the path to the driver library and the supported Vulkan version. All successfully
loaded drivers are exposed to the application as different GPUs.
In NixOS, there are two ways to make ICD files visible to Vulkan applications: an
environment variable and a module option.
</para>
<para>
The first option is through the <varname>VK_ICD_FILENAMES</varname>
environment variable. This variable can contain multiple JSON files, separated by
<literal>:</literal>. For example:
<screen><prompt>$</prompt> export \
VK_ICD_FILENAMES=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json</screen>
</para>
<para>
The second mechanism is to add the Vulkan driver package to
<xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
ICD file under <filename>/run/opengl-driver</filename>, where it will
be visible to the ICD loader.
</para>
<para>
The proper installation of Vulkan drivers can be verified through
the <command>vulkaninfo</command> command of the <package>vulkan-tools</package>
package. This command will report the hardware devices and drivers found,
in this example output amdvlk and radv:
</para>
<screen><prompt>$</prompt> vulkaninfo | grep GPU
GPU id : 0 (Unknown AMD GPU)
GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
...
GPU0:
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
deviceName = Unknown AMD GPU
GPU1:
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU</screen>
<para>
A simple graphical application that uses Vulkan is <command>vkcube</command>
from the <package>vulkan-tools</package> package.
</para>
<section xml:id="sec-gpu-accel-vulkan-amd">
<title>AMD</title>
<para>
Modern AMD <link
xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
Core Next</link> (GCN) GPUs are supported through either radv, which is
part of <package>mesa</package>, or the <package>amdvlk</package> package.
Adding the <package>amdvlk</package> package to
<xref linkend="opt-hardware.opengl.extraPackages"/> makes amdvlk the
default driver and hides radv and lavapipe from the device list. A
specific driver can be forced as follows:
<programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
pkgs.<package>amdvlk</package>
];
# To enable Vulkan support for 32-bit applications, also add:
<xref linkend="opt-hardware.opengl.extraPackages32"/> = [
pkgs.driversi686Linux.<package>amdvlk</package>
];
# Force radv
<xref linkend="opt-environment.variables"/>.AMD_VULKAN_ICD = "RADV";
# Or
<xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES =
"/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";
</programlisting>
</para>
</section>
</section>
<section xml:id="sec-gpu-accel-common-issues">
<title>Common issues</title>
<section xml:id="sec-gpu-accel-common-issues-permissions">
<title>User permissions</title>
<para>
Except where noted explicitly, it should not be necessary to
adjust user permissions to use these acceleration APIs. In the default
configuration, GPU devices have world-read/write permissions
(<filename>/dev/dri/renderD*</filename>) or are tagged as
<code>uaccess</code> (<filename>/dev/dri/card*</filename>). The
access control lists of devices with the <varname>uaccess</varname>
tag will be updated automatically when a user logs in through
<command>systemd-logind</command>. For example, if the user
<emphasis>jane</emphasis> is logged in, the access control list
should look as follows:
<screen><prompt>$</prompt> getfacl /dev/dri/card0
# file: dev/dri/card0
# owner: root
# group: video
user::rw-
user:jane:rw-
group::rw-
mask::rw-
other::---</screen>
If you disabled (this functionality of) <command>systemd-logind</command>,
you may need to add the user to the <code>video</code> group and
log in again.
</para>
</section>
<section xml:id="sec-gpu-accel-common-issues-mixing-nixpkgs">
<title>Mixing different versions of nixpkgs</title>
<para>
The <emphasis>Installable Client Driver</emphasis> (ICD)
mechanism used by OpenCL and Vulkan loads runtimes into its address
space using <code>dlopen</code>. Mixing an ICD loader mechanism and
runtimes from different version of nixpkgs may not work. For example,
if the ICD loader uses an older version of <package>glibc</package>
than the runtime, the runtime may not be loadable due to
missing symbols. Unfortunately, the loader will generally be quiet
about such issues.
</para>
<para>
If you suspect that you are running into library version mismatches
between an ICL loader and a runtime, you could run an application with
the <code>LD_DEBUG</code> variable set to get more diagnostic
information. For example, OpenCL can be tested with
<code>LD_DEBUG=files clinfo</code>, which should report missing
symbols.
</para>
</section>
</section>
</chapter>

View file

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

View file

@ -1,43 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-ipv4">
<title>IPv4 Configuration</title>
<para>
By default, NixOS uses DHCP (specifically, <command>dhcpcd</command>) to
automatically configure network interfaces. However, you can configure an
interface manually as follows:
<programlisting>
<link linkend="opt-networking.interfaces._name_.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ {
address = "192.168.1.2";
prefixLength = 24;
} ];
</programlisting>
Typically youll also want to set a default gateway and set of name
servers:
<programlisting>
<xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1";
<xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ];
</programlisting>
</para>
<note>
<para>
Statically configured interfaces are set up by the systemd service
<replaceable>interface-name</replaceable><literal>-cfg.service</literal>.
The default gateway and name server configuration is performed by
<literal>network-setup.service</literal>.
</para>
</note>
<para>
The host name is set using <xref linkend="opt-networking.hostName"/>:
<programlisting>
<xref linkend="opt-networking.hostName"/> = "cartman";
</programlisting>
The default host name is <literal>nixos</literal>. Set it to the empty string
(<literal>""</literal>) to allow the DHCP server to provide the host name.
</para>
</section>

View file

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

View file

@ -1,54 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-ipv6">
<title>IPv6 Configuration</title>
<para>
IPv6 is enabled by default. Stateless address autoconfiguration is used to
automatically assign IPv6 addresses to all interfaces, and Privacy
Extensions (RFC 4946) are enabled by default. You can adjust the default
for this by setting <xref linkend="opt-networking.tempAddresses"/>.
This option may be overridden on a per-interface basis by
<xref linkend="opt-networking.interfaces._name_.tempAddress"/>.
You can disable IPv6 support globally by setting:
<programlisting>
<xref linkend="opt-networking.enableIPv6"/> = false;
</programlisting>
</para>
<para>
You can disable IPv6 on a single interface using a normal sysctl (in this
example, we use interface <varname>eth0</varname>):
<programlisting>
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv6.conf.eth0.disable_ipv6" = true;
</programlisting>
</para>
<para>
As with IPv4 networking interfaces are automatically configured via DHCPv6.
You can configure an interface manually:
<programlisting>
<link linkend="opt-networking.interfaces._name_.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ {
address = "fe00:aa:bb:cc::2";
prefixLength = 64;
} ];
</programlisting>
</para>
<para>
For configuring a gateway, optionally with explicitly specified interface:
<programlisting>
<xref linkend="opt-networking.defaultGateway6"/> = {
address = "fe00::1";
interface = "enp0s3";
};
</programlisting>
</para>
<para>
See <xref linkend='sec-ipv4' /> for similar examples and additional
information.
</para>
</section>

View file

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

View file

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

Some files were not shown because too many files have changed in this diff Show more