mirror of
https://github.com/ilyakooo0/nixpkgs.git
synced 2024-10-18 19:17:31 +03:00
Merge master into haskell-updates
This commit is contained in:
commit
314256eb0f
6
.github/CODEOWNERS
vendored
6
.github/CODEOWNERS
vendored
@ -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
|
||||
|
@ -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
|
||||
|
@ -0,0 +1,23 @@
|
||||
--[[
|
||||
Converts Code AST nodes produced by pandoc’s DocBook reader
|
||||
from citerefentry elements into AST for corresponding role
|
||||
for reStructuredText.
|
||||
|
||||
We use subset of MyST syntax (CommonMark with features from rST)
|
||||
so let’s 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
|
@ -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
|
36
doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
Normal file
36
doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
Normal 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
|
18
doc/build-aux/pandoc-filters/link-unix-man-references.lua
Normal file
18
doc/build-aux/pandoc-filters/link-unix-man-references.lua
Normal 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
|
29
doc/build-aux/pandoc-filters/myst-reader/roles.lua
Normal file
29
doc/build-aux/pandoc-filters/myst-reader/roles.lua
Normal 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
|
25
doc/build-aux/pandoc-filters/myst-writer/roles.lua
Normal file
25
doc/build-aux/pandoc-filters/myst-writer/roles.lua
Normal 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
|
@ -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.
|
||||
|
||||
|
88
maintainers/scripts/db-to-md.sh
Executable file
88
maintainers/scripts/db-to-md.sh
Executable 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
|
97
maintainers/scripts/doc/escape-code-markup.py
Executable file
97
maintainers/scripts/doc/escape-code-markup.py
Executable 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
|
||||
let’s 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 pandoc’s 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.
|
||||
# Let’s 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])
|
32
maintainers/scripts/doc/replace-xrefs-by-empty-links.py
Executable file
32
maintainers/scripts/doc/replace-xrefs-by-empty-links.py
Executable 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.
|
||||
let’s 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])
|
12
maintainers/scripts/doc/unknown-code-language.lua
Normal file
12
maintainers/scripts/doc/unknown-code-language.lua
Normal 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
|
@ -75,7 +75,7 @@ mediator_lua,,,,,,
|
||||
mpack,,,,,,
|
||||
moonscript,,,,,,arobyn
|
||||
nvim-client,https://github.com/neovim/lua-client.git,,,,,
|
||||
penlight,https://github.com/Tieske/Penlight.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,,,,,,
|
||||
|
|
@ -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`
|
||||
|
||||
|
62
nixos/doc/manual/administration/cleaning-store.chapter.md
Normal file
62
nixos/doc/manual/administration/cleaning-store.chapter.md
Normal 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.
|
@ -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
|
||||
Nix’s <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 Nix’s 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>
|
@ -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.
|
@ -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 container’s 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 host’s 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>
|
@ -28,7 +28,7 @@
|
||||
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" />
|
||||
<xi:include href="../from_md/administration/imperative-containers.section.xml" />
|
||||
<xi:include href="../from_md/administration/declarative-containers.section.xml" />
|
||||
<xi:include href="../from_md/administration/container-networking.section.xml" />
|
||||
</chapter>
|
||||
|
59
nixos/doc/manual/administration/control-groups.chapter.md
Normal file
59
nixos/doc/manual/administration/control-groups.chapter.md
Normal 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.
|
@ -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 cgroup’s CPU time.) You can limit a
|
||||
service’s 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>
|
@ -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`.
|
@ -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 host’s
|
||||
<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>
|
115
nixos/doc/manual/administration/imperative-containers.section.md
Normal file
115
nixos/doc/manual/administration/imperative-containers.section.md
Normal 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
|
||||
```
|
@ -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>
|
||||
We’ll 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 container’s 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
|
||||
container’s 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>)/
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
|
||||
</screen>
|
||||
However, note that this will overwrite the container’s
|
||||
<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 container’s service unit. To
|
||||
destroy a container, including its file system, do
|
||||
<screen>
|
||||
<prompt># </prompt>nixos-container destroy <replaceable>foo</replaceable>
|
||||
</screen>
|
||||
</para>
|
||||
</section>
|
38
nixos/doc/manual/administration/logging.chapter.md
Normal file
38
nixos/doc/manual/administration/logging.chapter.md
Normal 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`.
|
@ -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 systemd’s <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>
|
11
nixos/doc/manual/administration/maintenance-mode.section.md
Normal file
11
nixos/doc/manual/administration/maintenance-mode.section.md
Normal 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.
|
@ -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>
|
21
nixos/doc/manual/administration/network-problems.section.md
Normal file
21
nixos/doc/manual/administration/network-problems.section.md
Normal 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/
|
||||
```
|
@ -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>
|
30
nixos/doc/manual/administration/rebooting.chapter.md
Normal file
30
nixos/doc/manual/administration/rebooting.chapter.md
Normal 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.
|
@ -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>
|
38
nixos/doc/manual/administration/rollback.section.md
Normal file
38
nixos/doc/manual/administration/rollback.section.md
Normal 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
|
||||
```
|
@ -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 doesn’t 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 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:
|
||||
<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>
|
@ -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="../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="containers.xml" />
|
||||
<xi:include href="troubleshooting.xml" />
|
||||
</part>
|
||||
|
120
nixos/doc/manual/administration/service-mgmt.chapter.md
Normal file
120
nixos/doc/manual/administration/service-mgmt.chapter.md
Normal 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.
|
@ -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>
|
||||
|
28
nixos/doc/manual/administration/store-corruption.section.md
Normal file
28
nixos/doc/manual/administration/store-corruption.section.md
Normal 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.
|
@ -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, 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 <command>sync</command> 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.
|
||||
</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 Nix’s 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 they’re available in a binary
|
||||
cache; otherwise, they cannot be repaired.
|
||||
</para>
|
||||
</section>
|
@ -9,8 +9,8 @@
|
||||
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" />
|
||||
<xi:include href="../from_md/administration/maintenance-mode.section.xml" />
|
||||
<xi:include href="../from_md/administration/rollback.section.xml" />
|
||||
<xi:include href="../from_md/administration/store-corruption.section.xml" />
|
||||
<xi:include href="../from_md/administration/network-problems.section.xml" />
|
||||
</chapter>
|
||||
|
43
nixos/doc/manual/administration/user-sessions.chapter.md
Normal file
43
nixos/doc/manual/administration/user-sessions.chapter.md
Normal 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
|
||||
```
|
@ -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 session’s
|
||||
processes are gone:
|
||||
<screen>
|
||||
<prompt># </prompt>loginctl terminate-session c3
|
||||
</screen>
|
||||
</para>
|
||||
</chapter>
|
@ -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
|
||||
'';
|
||||
```
|
@ -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>
|
51
nixos/doc/manual/configuration/ad-hoc-packages.section.md
Normal file
51
nixos/doc/manual/configuration/ad-hoc-packages.section.md
Normal 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.
|
@ -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>
|
@ -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!
|
||||
```
|
@ -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>
|
||||
It’s possible that a package you need is not available in NixOS. In that
|
||||
case, you can do two things. First, you can clone the Nixpkgs repository, add
|
||||
the package to your clone, and (optionally) submit a patch or pull request to
|
||||
have it accepted into the main Nixpkgs repository. This is described in
|
||||
detail in the <link
|
||||
xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
|
||||
manual</link>. In short, you clone Nixpkgs:
|
||||
<screen>
|
||||
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
|
||||
<prompt>$ </prompt>cd nixpkgs
|
||||
</screen>
|
||||
Then you write and test the package as described in the Nixpkgs manual.
|
||||
Finally, you add it to <literal>environment.systemPackages</literal>, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];
|
||||
</programlisting>
|
||||
and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs
|
||||
tree:
|
||||
<screen>
|
||||
<prompt># </prompt>nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The second possibility is to add the package outside of the Nixpkgs tree. For
|
||||
instance, here is how you specify a build of the
|
||||
<link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link>
|
||||
package directly in <filename>configuration.nix</filename>:
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> =
|
||||
let
|
||||
my-hello = with pkgs; stdenv.mkDerivation rec {
|
||||
name = "hello-2.8";
|
||||
src = fetchurl {
|
||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||
};
|
||||
};
|
||||
in
|
||||
[ my-hello ];
|
||||
</programlisting>
|
||||
Of course, you can also move the definition of <literal>my-hello</literal>
|
||||
into a separate Nix expression, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];
|
||||
</programlisting>
|
||||
where <filename>my-hello.nix</filename> contains:
|
||||
<programlisting>
|
||||
with import <nixpkgs> {}; # bring all of Nixpkgs into scope
|
||||
|
||||
stdenv.mkDerivation rec {
|
||||
name = "hello-2.8";
|
||||
src = fetchurl {
|
||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||
};
|
||||
}
|
||||
</programlisting>
|
||||
This allows testing the package easily:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-build my-hello.nix
|
||||
<prompt>$ </prompt>./result/bin/hello
|
||||
Hello, world!
|
||||
</screen>
|
||||
</para>
|
||||
</section>
|
175
nixos/doc/manual/configuration/config-file.section.md
Normal file
175
nixos/doc/manual/configuration/config-file.section.md
Normal 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).
|
@ -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 doesn’t exist (that is, doesn’t have a
|
||||
corresponding <emphasis>option declaration</emphasis>),
|
||||
<command>nixos-rebuild</command> will give an error like:
|
||||
<screen>
|
||||
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
|
||||
</screen>
|
||||
Likewise, values in option definitions must have a correct type. For
|
||||
instance, <option>services.httpd.enable</option> must be a Boolean
|
||||
(<literal>true</literal> or <literal>false</literal>). Trying to give it a
|
||||
value of another type, such as a string, will cause an error:
|
||||
<screen>
|
||||
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Options have various types of values. The most important are:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
Strings
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Strings are enclosed in double quotes, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-networking.hostName"/> = "dexter";
|
||||
</programlisting>
|
||||
Special characters can be escaped by prefixing them with a backslash
|
||||
(e.g. <literal>\"</literal>).
|
||||
</para>
|
||||
<para>
|
||||
Multi-line strings can be enclosed in <emphasis>double single
|
||||
quotes</emphasis>, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-networking.extraHosts"/> =
|
||||
''
|
||||
127.0.0.2 other-localhost
|
||||
10.0.0.1 server
|
||||
'';
|
||||
</programlisting>
|
||||
The main difference is that it strips from each line a number of spaces
|
||||
equal to the minimal indentation of the string as a whole (disregarding
|
||||
the indentation of empty lines), and that characters like
|
||||
<literal>"</literal> and <literal>\</literal> are not special (making it
|
||||
more convenient for including things like shell code). See more info
|
||||
about this in the Nix manual
|
||||
<link
|
||||
xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
Booleans
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
These can be <literal>true</literal> or <literal>false</literal>, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-networking.firewall.enable"/> = true;
|
||||
<xref linkend="opt-networking.firewall.allowPing"/> = false;
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
Integers
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
For example,
|
||||
<programlisting>
|
||||
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
|
||||
</programlisting>
|
||||
(Note that here the attribute name
|
||||
<literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to
|
||||
prevent it from being interpreted as a set named <literal>net</literal>
|
||||
containing a set named <literal>ipv4</literal>, and so on. This is
|
||||
because it’s not a NixOS option but the literal name of a Linux kernel
|
||||
setting.)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
Sets
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets were introduced above. They are name/value pairs enclosed in braces,
|
||||
as in the option definition
|
||||
<programlisting>
|
||||
<xref linkend="opt-fileSystems"/>."/boot" =
|
||||
{ device = "/dev/sda1";
|
||||
fsType = "ext4";
|
||||
options = [ "rw" "data=ordered" "relatime" ];
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
Lists
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The important thing to note about lists is that list elements are
|
||||
separated by whitespace, like this:
|
||||
<programlisting>
|
||||
<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
|
||||
</programlisting>
|
||||
List elements can be any other type, e.g. sets:
|
||||
<programlisting>
|
||||
swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
Packages
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Usually, the packages you need are already part of the Nix Packages
|
||||
collection, which is a set that can be accessed through the function
|
||||
argument <varname>pkgs</varname>. Typical uses:
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> =
|
||||
[ pkgs.thunderbird
|
||||
pkgs.emacs
|
||||
];
|
||||
|
||||
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10;
|
||||
</programlisting>
|
||||
The latter option definition changes the default PostgreSQL package used
|
||||
by NixOS’s PostgreSQL service to 10.x. For more information on
|
||||
packages, including how to add new ones, see
|
||||
<xref linkend="sec-custom-packages"/>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</section>
|
@ -18,8 +18,8 @@ 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/config-file.section.xml" />
|
||||
<xi:include href="../from_md/configuration/abstractions.section.xml" />
|
||||
<xi:include href="modularity.xml" />
|
||||
<xi:include href="summary.xml" />
|
||||
<xi:include href="../from_md/configuration/modularity.section.xml" />
|
||||
<xi:include href="../from_md/configuration/summary.section.xml" />
|
||||
</chapter>
|
||||
|
@ -15,17 +15,17 @@
|
||||
</partintro>
|
||||
<xi:include href="config-syntax.xml" />
|
||||
<xi:include href="package-mgmt.xml" />
|
||||
<xi:include href="user-mgmt.xml" />
|
||||
<xi:include href="../from_md/configuration/user-mgmt.chapter.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="../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="networking.xml" />
|
||||
<xi:include href="linux-kernel.xml" />
|
||||
<xi:include href="subversion.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/kubernetes.chapter.xml" />
|
||||
<!-- Apache; libvirtd virtualisation -->
|
||||
</part>
|
||||
|
@ -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.)
|
@ -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, it’s possible to tweak a package in almost
|
||||
arbitrary ways, such as changing or disabling dependencies of a package. For
|
||||
instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2.
|
||||
If you want to build it against GTK 3, you can specify that as follows:
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
|
||||
</programlisting>
|
||||
The function <varname>override</varname> performs the call to the Nix
|
||||
function that produces Emacs, with the original arguments amended by the set
|
||||
of arguments specified by you. So here the function argument
|
||||
<varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing
|
||||
Emacs to depend on GTK 3. (The parentheses are necessary because in Nix,
|
||||
function application binds more weakly than list construction, so without
|
||||
them, <xref linkend="opt-environment.systemPackages"/> would be a list with
|
||||
two elements.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Even greater customisation is possible using the function
|
||||
<varname>overrideAttrs</varname>. While the <varname>override</varname>
|
||||
mechanism above overrides the arguments of a package function,
|
||||
<varname>overrideAttrs</varname> allows changing the
|
||||
<emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>.
|
||||
This permits changing any aspect of the package, such as the source code. For
|
||||
instance, if you want to override the source code of Emacs, you can say:
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> = [
|
||||
(pkgs.emacs.overrideAttrs (oldAttrs: {
|
||||
name = "emacs-25.0-pre";
|
||||
src = /path/to/my/emacs/tree;
|
||||
}))
|
||||
];
|
||||
</programlisting>
|
||||
Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by
|
||||
<varname>pkgs.emacs</varname> and produces a new derivation in which the
|
||||
original’s <literal>name</literal> and <literal>src</literal> attribute
|
||||
have been replaced by the given values by re-calling
|
||||
<literal>stdenv.mkDerivation</literal>. The original attributes are
|
||||
accessible via the function argument, which is conventionally named
|
||||
<varname>oldAttrs</varname>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The overrides shown above are not global. They do not affect the original
|
||||
package; other packages in Nixpkgs continue to depend on the original rather
|
||||
than the customised package. This means that if another package in your
|
||||
system depends on the original package, you end up with two instances of the
|
||||
package. If you want to have everything depend on your customised instance,
|
||||
you can apply a <emphasis>global</emphasis> override as follows:
|
||||
<screen>
|
||||
nixpkgs.config.packageOverrides = pkgs:
|
||||
{ emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
|
||||
};
|
||||
</screen>
|
||||
The effect of this definition is essentially equivalent to modifying the
|
||||
<literal>emacs</literal> attribute in the Nixpkgs source tree. Any package in
|
||||
Nixpkgs that depends on <literal>emacs</literal> will be passed your
|
||||
customised instance. (However, the value <literal>pkgs.emacs</literal> in
|
||||
<varname>nixpkgs.config.packageOverrides</varname> refers to the original
|
||||
rather than overridden instance, to prevent an infinite recursion.)
|
||||
</para>
|
||||
</section>
|
@ -48,7 +48,7 @@ nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
|
||||
<command>nixos-rebuild switch</command>.
|
||||
</para>
|
||||
|
||||
<xi:include href="customizing-packages.xml" />
|
||||
<xi:include href="../from_md/configuration/customizing-packages.section.xml" />
|
||||
|
||||
<xi:include href="adding-custom-packages.xml" />
|
||||
<xi:include href="../from_md/configuration/adding-custom-packages.section.xml" />
|
||||
</section>
|
||||
|
@ -53,6 +53,6 @@
|
||||
"nofail" ];</literal>.
|
||||
</para>
|
||||
</note>
|
||||
<xi:include href="luks-file-systems.xml" />
|
||||
<xi:include href="../from_md/configuration/luks-file-systems.section.xml" />
|
||||
<xi:include href="../from_md/configuration/sshfs-file-systems.section.xml" />
|
||||
</chapter>
|
||||
|
32
nixos/doc/manual/configuration/firewall.section.md
Normal file
32
nixos/doc/manual/configuration/firewall.section.md
Normal 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).
|
@ -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>
|
204
nixos/doc/manual/configuration/gpu-accel.chapter.md
Normal file
204
nixos/doc/manual/configuration/gpu-accel.chapter.md
Normal 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.
|
@ -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 '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The second mechanism is to add the OpenCL driver package to
|
||||
<xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
|
||||
ICD file under <filename>/run/opengl-driver</filename>, where it will
|
||||
be visible to the ICD loader.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The proper installation of OpenCL drivers can be verified through
|
||||
the <command>clinfo</command> command of the <package>clinfo</package>
|
||||
package. This command will report the number of hardware devices
|
||||
that is found and give detailed information for each device:
|
||||
</para>
|
||||
|
||||
<screen><prompt>$</prompt> clinfo | head -n3
|
||||
Number of platforms 1
|
||||
Platform Name AMD Accelerated Parallel Processing
|
||||
Platform Vendor Advanced Micro Devices, Inc.</screen>
|
||||
|
||||
<section xml:id="sec-gpu-accel-opencl-amd">
|
||||
<title>AMD</title>
|
||||
|
||||
<para>
|
||||
Modern AMD <link
|
||||
xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
|
||||
Core Next</link> (GCN) GPUs are supported through the
|
||||
<package>rocm-opencl-icd</package> package. Adding this package to
|
||||
<xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL
|
||||
support:
|
||||
|
||||
<programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
|
||||
rocm-opencl-icd
|
||||
];</programlisting>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="sec-gpu-accel-opencl-intel">
|
||||
<title>Intel</title>
|
||||
|
||||
<para>
|
||||
<link
|
||||
xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8">Intel
|
||||
Gen8 and later GPUs</link> are supported by the Intel NEO OpenCL
|
||||
runtime that is provided by the
|
||||
<package>intel-compute-runtime</package> package. For Gen7 GPUs,
|
||||
the deprecated Beignet runtime can be used, which is provided
|
||||
by the <package>beignet</package> package. The proprietary Intel
|
||||
OpenCL runtime, in the <package>intel-ocl</package> package, is
|
||||
an alternative for Gen7 GPUs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <package>intel-compute-runtime</package>, <package>beignet</package>,
|
||||
or <package>intel-ocl</package> package can be added to
|
||||
<xref linkend="opt-hardware.opengl.extraPackages"/> to enable OpenCL
|
||||
support. For example, for Gen8 and later GPUs, the following
|
||||
configuration can be used:
|
||||
|
||||
<programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
|
||||
intel-compute-runtime
|
||||
];</programlisting>
|
||||
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section xml:id="sec-gpu-accel-vulkan">
|
||||
<title>Vulkan</title>
|
||||
|
||||
<para>
|
||||
<link xlink:href="https://en.wikipedia.org/wiki/Vulkan_(API)">Vulkan</link> is a
|
||||
graphics and compute API for GPUs. It is used directly by games or indirectly though
|
||||
compatibility layers like <link xlink:href="https://github.com/doitsujin/dxvk/wiki">DXVK</link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
By default, if <xref linkend="opt-hardware.opengl.driSupport"/> is enabled,
|
||||
<package>mesa</package> is installed and provides Vulkan for supported hardware.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Similar to OpenCL, Vulkan drivers are loaded through the <emphasis>Installable Client
|
||||
Driver</emphasis> (ICD) mechanism. ICD files for Vulkan are JSON files that specify
|
||||
the path to the driver library and the supported Vulkan version. All successfully
|
||||
loaded drivers are exposed to the application as different GPUs.
|
||||
In NixOS, there are two ways to make ICD files visible to Vulkan applications: an
|
||||
environment variable and a module option.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The first option is through the <varname>VK_ICD_FILENAMES</varname>
|
||||
environment variable. This variable can contain multiple JSON files, separated by
|
||||
<literal>:</literal>. For example:
|
||||
|
||||
<screen><prompt>$</prompt> export \
|
||||
VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The second mechanism is to add the Vulkan driver package to
|
||||
<xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
|
||||
ICD file under <filename>/run/opengl-driver</filename>, where it will
|
||||
be visible to the ICD loader.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The proper installation of Vulkan drivers can be verified through
|
||||
the <command>vulkaninfo</command> command of the <package>vulkan-tools</package>
|
||||
package. This command will report the hardware devices and drivers found,
|
||||
in this example output amdvlk and radv:
|
||||
</para>
|
||||
|
||||
<screen><prompt>$</prompt> vulkaninfo | grep GPU
|
||||
GPU id : 0 (Unknown AMD GPU)
|
||||
GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
|
||||
...
|
||||
GPU0:
|
||||
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
|
||||
deviceName = Unknown AMD GPU
|
||||
GPU1:
|
||||
deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU</screen>
|
||||
|
||||
<para>
|
||||
A simple graphical application that uses Vulkan is <command>vkcube</command>
|
||||
from the <package>vulkan-tools</package> package.
|
||||
</para>
|
||||
|
||||
<section xml:id="sec-gpu-accel-vulkan-amd">
|
||||
<title>AMD</title>
|
||||
|
||||
<para>
|
||||
Modern AMD <link
|
||||
xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
|
||||
Core Next</link> (GCN) GPUs are supported through either radv, which is
|
||||
part of <package>mesa</package>, or the <package>amdvlk</package> package.
|
||||
Adding the <package>amdvlk</package> package to
|
||||
<xref linkend="opt-hardware.opengl.extraPackages"/> makes 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>
|
35
nixos/doc/manual/configuration/ipv4-config.section.md
Normal file
35
nixos/doc/manual/configuration/ipv4-config.section.md
Normal 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.
|
@ -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 you’ll also want to set a default gateway and set of name
|
||||
servers:
|
||||
<programlisting>
|
||||
<xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1";
|
||||
<xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ];
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Statically configured interfaces are set up by the systemd service
|
||||
<replaceable>interface-name</replaceable><literal>-cfg.service</literal>.
|
||||
The default gateway and name server configuration is performed by
|
||||
<literal>network-setup.service</literal>.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
The host name is set using <xref linkend="opt-networking.hostName"/>:
|
||||
<programlisting>
|
||||
<xref linkend="opt-networking.hostName"/> = "cartman";
|
||||
</programlisting>
|
||||
The default host name is <literal>nixos</literal>. Set it to the empty string
|
||||
(<literal>""</literal>) to allow the DHCP server to provide the host name.
|
||||
</para>
|
||||
</section>
|
42
nixos/doc/manual/configuration/ipv6-config.section.md
Normal file
42
nixos/doc/manual/configuration/ipv6-config.section.md
Normal 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.
|
@ -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>
|
104
nixos/doc/manual/configuration/kubernetes.chapter.md
Normal file
104
nixos/doc/manual/configuration/kubernetes.chapter.md
Normal 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.
|
@ -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>
|
135
nixos/doc/manual/configuration/linux-kernel.chapter.md
Normal file
135
nixos/doc/manual/configuration/linux-kernel.chapter.md
Normal file
@ -0,0 +1,135 @@
|
||||
# Linux Kernel {#sec-kernel-config}
|
||||
|
||||
You can override the Linux kernel and associated packages using the
|
||||
option `boot.kernelPackages`. For instance, this selects the Linux 3.10
|
||||
kernel:
|
||||
|
||||
```nix
|
||||
boot.kernelPackages = pkgs.linuxPackages_3_10;
|
||||
```
|
||||
|
||||
Note that this not only replaces the kernel, but also packages that are
|
||||
specific to the kernel version, such as the NVIDIA video drivers. This
|
||||
ensures that driver packages are consistent with the kernel.
|
||||
|
||||
The default Linux kernel configuration should be fine for most users.
|
||||
You can see the configuration of your current kernel with the following
|
||||
command:
|
||||
|
||||
```ShellSession
|
||||
zcat /proc/config.gz
|
||||
```
|
||||
|
||||
If you want to change the kernel configuration, you can use the
|
||||
`packageOverrides` feature (see [](#sec-customising-packages)). For
|
||||
instance, to enable support for the kernel debugger KGDB:
|
||||
|
||||
```nix
|
||||
nixpkgs.config.packageOverrides = pkgs:
|
||||
{ linux_3_4 = pkgs.linux_3_4.override {
|
||||
extraConfig =
|
||||
''
|
||||
KGDB y
|
||||
'';
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
`extraConfig` takes a list of Linux kernel configuration options, one
|
||||
per line. The name of the option should not include the prefix
|
||||
`CONFIG_`. The option value is typically `y`, `n` or `m` (to build
|
||||
something as a kernel module).
|
||||
|
||||
Kernel modules for hardware devices are generally loaded automatically
|
||||
by `udev`. You can force a module to be loaded via
|
||||
[](#opt-boot.kernelModules), e.g.
|
||||
|
||||
```nix
|
||||
boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
|
||||
```
|
||||
|
||||
If the module is required early during the boot (e.g. to mount the root
|
||||
file system), you can use [](#opt-boot.initrd.kernelModules):
|
||||
|
||||
```nix
|
||||
boot.initrd.kernelModules = [ "cifs" ];
|
||||
```
|
||||
|
||||
This causes the specified modules and their dependencies to be added to
|
||||
the initial ramdisk.
|
||||
|
||||
Kernel runtime parameters can be set through
|
||||
[](#opt-boot.kernel.sysctl), e.g.
|
||||
|
||||
```nix
|
||||
boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
|
||||
```
|
||||
|
||||
sets the kernel's TCP keepalive time to 120 seconds. To see the
|
||||
available parameters, run `sysctl -a`.
|
||||
|
||||
## Customize your kernel {#sec-linux-config-customizing}
|
||||
|
||||
The first step before compiling the kernel is to generate an appropriate
|
||||
`.config` configuration. Either you pass your own config via the
|
||||
`configfile` setting of `linuxManualConfig`:
|
||||
|
||||
```nix
|
||||
custom-kernel = super.linuxManualConfig {
|
||||
inherit (super) stdenv hostPlatform;
|
||||
inherit (linux_4_9) src;
|
||||
version = "${linux_4_9.version}-custom";
|
||||
|
||||
configfile = /home/me/my_kernel_config;
|
||||
allowImportFromDerivation = true;
|
||||
};
|
||||
```
|
||||
|
||||
You can edit the config with this snippet (by default `make
|
||||
menuconfig` won\'t work out of the box on nixos):
|
||||
|
||||
```ShellSession
|
||||
nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
|
||||
```
|
||||
|
||||
or you can let nixpkgs generate the configuration. Nixpkgs generates it
|
||||
via answering the interactive kernel utility `make config`. The answers
|
||||
depend on parameters passed to
|
||||
`pkgs/os-specific/linux/kernel/generic.nix` (which you can influence by
|
||||
overriding `extraConfig, autoModules,
|
||||
modDirVersion, preferBuiltin, extraConfig`).
|
||||
|
||||
```nix
|
||||
mptcp93.override ({
|
||||
name="mptcp-local";
|
||||
|
||||
ignoreConfigErrors = true;
|
||||
autoModules = false;
|
||||
kernelPreferBuiltin = true;
|
||||
|
||||
enableParallelBuilding = true;
|
||||
|
||||
extraConfig = ''
|
||||
DEBUG_KERNEL y
|
||||
FRAME_POINTER y
|
||||
KGDB y
|
||||
KGDB_SERIAL_CONSOLE y
|
||||
DEBUG_INFO y
|
||||
'';
|
||||
});
|
||||
```
|
||||
|
||||
## Developing kernel modules {#sec-linux-config-developing-modules}
|
||||
|
||||
When developing kernel modules it\'s often convenient to run
|
||||
edit-compile-run loop as quickly as possible. See below snippet as an
|
||||
example of developing `mellanox` drivers.
|
||||
|
||||
```ShellSession
|
||||
$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
|
||||
$ nix-shell '<nixpkgs>' -A linuxPackages.kernel
|
||||
$ unpackPhase
|
||||
$ cd linux-*
|
||||
$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
|
||||
# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
|
||||
```
|
@ -1,138 +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-kernel-config">
|
||||
<title>Linux Kernel</title>
|
||||
<para>
|
||||
You can override the Linux kernel and associated packages using the option
|
||||
<option>boot.kernelPackages</option>. For instance, this selects the Linux
|
||||
3.10 kernel:
|
||||
<programlisting>
|
||||
<xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10;
|
||||
</programlisting>
|
||||
Note that this not only replaces the kernel, but also packages that are
|
||||
specific to the kernel version, such as the NVIDIA video drivers. This
|
||||
ensures that driver packages are consistent with the kernel.
|
||||
</para>
|
||||
<para>
|
||||
The default Linux kernel configuration should be fine for most users. You can
|
||||
see the configuration of your current kernel with the following command:
|
||||
<programlisting>
|
||||
zcat /proc/config.gz
|
||||
</programlisting>
|
||||
If you want to change the kernel configuration, you can use the
|
||||
<option>packageOverrides</option> feature (see
|
||||
<xref
|
||||
linkend="sec-customising-packages" />). For instance, to enable support
|
||||
for the kernel debugger KGDB:
|
||||
<programlisting>
|
||||
nixpkgs.config.packageOverrides = pkgs:
|
||||
{ linux_3_4 = pkgs.linux_3_4.override {
|
||||
extraConfig =
|
||||
''
|
||||
KGDB y
|
||||
'';
|
||||
};
|
||||
};
|
||||
</programlisting>
|
||||
<varname>extraConfig</varname> takes a list of Linux kernel configuration
|
||||
options, one per line. The name of the option should not include the prefix
|
||||
<literal>CONFIG_</literal>. The option value is typically
|
||||
<literal>y</literal>, <literal>n</literal> or <literal>m</literal> (to build
|
||||
something as a kernel module).
|
||||
</para>
|
||||
<para>
|
||||
Kernel modules for hardware devices are generally loaded automatically by
|
||||
<command>udev</command>. You can force a module to be loaded via
|
||||
<xref linkend="opt-boot.kernelModules"/>, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
|
||||
</programlisting>
|
||||
If the module is required early during the boot (e.g. to mount the root file
|
||||
system), you can use <xref linkend="opt-boot.initrd.kernelModules"/>:
|
||||
<programlisting>
|
||||
<xref linkend="opt-boot.initrd.kernelModules"/> = [ "cifs" ];
|
||||
</programlisting>
|
||||
This causes the specified modules and their dependencies to be added to the
|
||||
initial ramdisk.
|
||||
</para>
|
||||
<para>
|
||||
Kernel runtime parameters can be set through
|
||||
<xref linkend="opt-boot.kernel.sysctl"/>, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120;
|
||||
</programlisting>
|
||||
sets the kernel’s TCP keepalive time to 120 seconds. To see the available
|
||||
parameters, run <command>sysctl -a</command>.
|
||||
</para>
|
||||
<section xml:id="sec-linux-config-customizing">
|
||||
<title>Customize your kernel</title>
|
||||
|
||||
<para>
|
||||
The first step before compiling the kernel is to generate an appropriate
|
||||
<literal>.config</literal> configuration. Either you pass your own config
|
||||
via the <literal>configfile</literal> setting of
|
||||
<literal>linuxManualConfig</literal>:
|
||||
<screen><![CDATA[
|
||||
custom-kernel = super.linuxManualConfig {
|
||||
inherit (super) stdenv hostPlatform;
|
||||
inherit (linux_4_9) src;
|
||||
version = "${linux_4_9.version}-custom";
|
||||
|
||||
configfile = /home/me/my_kernel_config;
|
||||
allowImportFromDerivation = true;
|
||||
};
|
||||
]]></screen>
|
||||
You can edit the config with this snippet (by default <command>make
|
||||
menuconfig</command> won't work out of the box on nixos):
|
||||
<screen><![CDATA[
|
||||
nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
|
||||
]]></screen>
|
||||
or you can let nixpkgs generate the configuration. Nixpkgs generates it via
|
||||
answering the interactive kernel utility <command>make config</command>. The
|
||||
answers depend on parameters passed to
|
||||
<filename>pkgs/os-specific/linux/kernel/generic.nix</filename> (which you
|
||||
can influence by overriding <literal>extraConfig, autoModules,
|
||||
modDirVersion, preferBuiltin, extraConfig</literal>).
|
||||
<screen><![CDATA[
|
||||
|
||||
mptcp93.override ({
|
||||
name="mptcp-local";
|
||||
|
||||
ignoreConfigErrors = true;
|
||||
autoModules = false;
|
||||
kernelPreferBuiltin = true;
|
||||
|
||||
enableParallelBuilding = true;
|
||||
|
||||
extraConfig = ''
|
||||
DEBUG_KERNEL y
|
||||
FRAME_POINTER y
|
||||
KGDB y
|
||||
KGDB_SERIAL_CONSOLE y
|
||||
DEBUG_INFO y
|
||||
'';
|
||||
});
|
||||
]]></screen>
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-linux-config-developing-modules">
|
||||
<title>Developing kernel modules</title>
|
||||
|
||||
<para>
|
||||
When developing kernel modules it's often convenient to run edit-compile-run
|
||||
loop as quickly as possible. See below snippet as an example of developing
|
||||
<literal>mellanox</literal> drivers.
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
|
||||
<prompt>$ </prompt>nix-shell '<nixpkgs>' -A linuxPackages.kernel
|
||||
<prompt>$ </prompt>unpackPhase
|
||||
<prompt>$ </prompt>cd linux-*
|
||||
<prompt>$ </prompt>make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
|
||||
<prompt># </prompt>insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
|
||||
</screen>
|
||||
</section>
|
||||
</chapter>
|
77
nixos/doc/manual/configuration/luks-file-systems.section.md
Normal file
77
nixos/doc/manual/configuration/luks-file-systems.section.md
Normal file
@ -0,0 +1,77 @@
|
||||
# LUKS-Encrypted File Systems {#sec-luks-file-systems}
|
||||
|
||||
NixOS supports file systems that are encrypted using *LUKS* (Linux
|
||||
Unified Key Setup). For example, here is how you create an encrypted
|
||||
Ext4 file system on the device
|
||||
`/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d`:
|
||||
|
||||
```ShellSession
|
||||
# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d
|
||||
|
||||
WARNING!
|
||||
========
|
||||
This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably.
|
||||
|
||||
Are you sure? (Type uppercase yes): YES
|
||||
Enter LUKS passphrase: ***
|
||||
Verify passphrase: ***
|
||||
|
||||
# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
|
||||
Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***
|
||||
|
||||
# mkfs.ext4 /dev/mapper/crypted
|
||||
```
|
||||
|
||||
The LUKS volume should be automatically picked up by
|
||||
`nixos-generate-config`, but you might want to verify that your
|
||||
`hardware-configuration.nix` looks correct. To manually ensure that the
|
||||
system is automatically mounted at boot time as `/`, add the following
|
||||
to `configuration.nix`:
|
||||
|
||||
```nix
|
||||
boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
|
||||
fileSystems."/".device = "/dev/mapper/crypted";
|
||||
```
|
||||
|
||||
Should grub be used as bootloader, and `/boot` is located on an
|
||||
encrypted partition, it is necessary to add the following grub option:
|
||||
|
||||
```nix
|
||||
boot.loader.grub.enableCryptodisk = true;
|
||||
```
|
||||
|
||||
## FIDO2 {#sec-luks-file-systems-fido2}
|
||||
|
||||
NixOS also supports unlocking your LUKS-Encrypted file system using a
|
||||
FIDO2 compatible token. In the following example, we will create a new
|
||||
FIDO2 credential and add it as a new key to our existing device
|
||||
`/dev/sda2`:
|
||||
|
||||
```ShellSession
|
||||
# export FIDO2_LABEL="/dev/sda2 @ $HOSTNAME"
|
||||
# fido2luks credential "$FIDO2_LABEL"
|
||||
f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
|
||||
|
||||
# fido2luks -i add-key /dev/sda2 f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
|
||||
Password:
|
||||
Password (again):
|
||||
Old password:
|
||||
Old password (again):
|
||||
Added to key to device /dev/sda2, slot: 2
|
||||
```
|
||||
|
||||
To ensure that this file system is decrypted using the FIDO2 compatible
|
||||
key, add the following to `configuration.nix`:
|
||||
|
||||
```nix
|
||||
boot.initrd.luks.fido2Support = true;
|
||||
boot.initrd.luks.devices."/dev/sda2".fido2.credential = "f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7";
|
||||
```
|
||||
|
||||
You can also use the FIDO2 passwordless setup, but for security reasons,
|
||||
you might want to enable it only when your device is PIN protected, such
|
||||
as [Trezor](https://trezor.io/).
|
||||
|
||||
```nix
|
||||
boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = true;
|
||||
```
|
@ -1,78 +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-luks-file-systems">
|
||||
<title>LUKS-Encrypted File Systems</title>
|
||||
|
||||
<para>
|
||||
NixOS supports file systems that are encrypted using
|
||||
<emphasis>LUKS</emphasis> (Linux Unified Key Setup). For example, here is how
|
||||
you create an encrypted Ext4 file system on the device
|
||||
<filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>:
|
||||
<screen>
|
||||
<prompt># </prompt>cryptsetup luksFormat <replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable>
|
||||
|
||||
WARNING!
|
||||
========
|
||||
This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably.
|
||||
|
||||
Are you sure? (Type uppercase yes): YES
|
||||
Enter LUKS passphrase: ***
|
||||
Verify passphrase: ***
|
||||
|
||||
<prompt># </prompt>cryptsetup luksOpen <replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable> <replaceable>crypted</replaceable>
|
||||
Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***
|
||||
|
||||
<prompt># </prompt>mkfs.ext4 /dev/mapper/<replaceable>crypted</replaceable>
|
||||
</screen>
|
||||
The LUKS volume should be automatically picked up by
|
||||
<command>nixos-generate-config</command>, but you might want to verify that your
|
||||
<filename>hardware-configuration.nix</filename> looks correct.
|
||||
|
||||
To manually ensure that the system is automatically mounted at boot time as
|
||||
<filename>/</filename>, add the following to
|
||||
<filename>configuration.nix</filename>:
|
||||
<programlisting>
|
||||
<link linkend="opt-boot.initrd.luks.devices._name_.device">boot.initrd.luks.devices.crypted.device</link> = "<replaceable>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</replaceable>";
|
||||
<xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/<replaceable>crypted</replaceable>";
|
||||
</programlisting>
|
||||
Should grub be used as bootloader, and <filename>/boot</filename> is located
|
||||
on an encrypted partition, it is necessary to add the following grub option:
|
||||
<programlisting><xref linkend="opt-boot.loader.grub.enableCryptodisk"/> = true;</programlisting>
|
||||
</para>
|
||||
<section xml:id="sec-luks-file-systems-fido2">
|
||||
<title>FIDO2</title>
|
||||
|
||||
<para>
|
||||
NixOS also supports unlocking your LUKS-Encrypted file system using a FIDO2 compatible token. In the following example, we will create a new FIDO2 credential
|
||||
and add it as a new key to our existing device <filename>/dev/sda2</filename>:
|
||||
|
||||
<screen>
|
||||
<prompt># </prompt>export FIDO2_LABEL="<replaceable>/dev/sda2</replaceable> @ $HOSTNAME"
|
||||
<prompt># </prompt>fido2luks credential "$FIDO2_LABEL"
|
||||
f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
|
||||
|
||||
<prompt># </prompt>fido2luks -i add-key <replaceable>/dev/sda2</replaceable> <replaceable>f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7</replaceable>
|
||||
Password:
|
||||
Password (again):
|
||||
Old password:
|
||||
Old password (again):
|
||||
Added to key to device /dev/sda2, slot: 2
|
||||
</screen>
|
||||
|
||||
To ensure that this file system is decrypted using the FIDO2 compatible key, add the following to <filename>configuration.nix</filename>:
|
||||
<programlisting>
|
||||
<link linkend="opt-boot.initrd.luks.fido2Support">boot.initrd.luks.fido2Support</link> = true;
|
||||
<link linkend="opt-boot.initrd.luks.devices._name_.fido2.credential">boot.initrd.luks.devices."<replaceable>/dev/sda2</replaceable>".fido2.credential</link> = "<replaceable>f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7</replaceable>";
|
||||
</programlisting>
|
||||
|
||||
You can also use the FIDO2 passwordless setup, but for security reasons, you might want to enable it only when your device is PIN protected, such as <link xlink:href="https://trezor.io/">Trezor</link>.
|
||||
|
||||
<programlisting>
|
||||
<link linkend="opt-boot.initrd.luks.devices._name_.fido2.passwordLess">boot.initrd.luks.devices."<replaceable>/dev/sda2</replaceable>".fido2.passwordLess</link> = true;
|
||||
</programlisting>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
</section>
|
133
nixos/doc/manual/configuration/modularity.section.md
Normal file
133
nixos/doc/manual/configuration/modularity.section.md
Normal file
@ -0,0 +1,133 @@
|
||||
# Modularity {#sec-modularity}
|
||||
|
||||
The NixOS configuration mechanism is modular. If your
|
||||
`configuration.nix` becomes too big, you can split it into multiple
|
||||
files. Likewise, if you have multiple NixOS configurations (e.g. for
|
||||
different computers) with some commonality, you can move the common
|
||||
configuration into a shared file.
|
||||
|
||||
Modules have exactly the same syntax as `configuration.nix`. In fact,
|
||||
`configuration.nix` is itself a module. You can use other modules by
|
||||
including them from `configuration.nix`, e.g.:
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{ imports = [ ./vpn.nix ./kde.nix ];
|
||||
services.httpd.enable = true;
|
||||
environment.systemPackages = [ pkgs.emacs ];
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Here, we include two modules from the same directory, `vpn.nix` and
|
||||
`kde.nix`. The latter might look like this:
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{ services.xserver.enable = true;
|
||||
services.xserver.displayManager.sddm.enable = true;
|
||||
services.xserver.desktopManager.plasma5.enable = true;
|
||||
environment.systemPackages = [ pkgs.vim ];
|
||||
}
|
||||
```
|
||||
|
||||
Note that both `configuration.nix` and `kde.nix` define the option
|
||||
[](#opt-environment.systemPackages). When multiple modules define an
|
||||
option, NixOS will try to *merge* the definitions. In the case of
|
||||
[](#opt-environment.systemPackages), that's easy: the lists of
|
||||
packages can simply be concatenated. The value in `configuration.nix` is
|
||||
merged last, so for list-type options, it will appear at the end of the
|
||||
merged list. If you want it to appear first, you can use `mkBefore`:
|
||||
|
||||
```nix
|
||||
boot.kernelModules = mkBefore [ "kvm-intel" ];
|
||||
```
|
||||
|
||||
This causes the `kvm-intel` kernel module to be loaded before any other
|
||||
kernel modules.
|
||||
|
||||
For other types of options, a merge may not be possible. For instance,
|
||||
if two modules define [](#opt-services.httpd.adminAddr),
|
||||
`nixos-rebuild` will give an error:
|
||||
|
||||
```plain
|
||||
The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.
|
||||
```
|
||||
|
||||
When that happens, it's possible to force one definition take precedence
|
||||
over the others:
|
||||
|
||||
```nix
|
||||
services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";
|
||||
```
|
||||
|
||||
When using multiple modules, you may need to access configuration values
|
||||
defined in other modules. This is what the `config` function argument is
|
||||
for: it contains the complete, merged system configuration. That is,
|
||||
`config` is the result of combining the configurations returned by every
|
||||
module [^1] . For example, here is a module that adds some packages to
|
||||
[](#opt-environment.systemPackages) only if
|
||||
[](#opt-services.xserver.enable) is set to `true` somewhere else:
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{ environment.systemPackages =
|
||||
if config.services.xserver.enable then
|
||||
[ pkgs.firefox
|
||||
pkgs.thunderbird
|
||||
]
|
||||
else
|
||||
[ ];
|
||||
}
|
||||
```
|
||||
|
||||
With multiple modules, it may not be obvious what the final value of a
|
||||
configuration option is. The command `nixos-option` allows you to find
|
||||
out:
|
||||
|
||||
```ShellSession
|
||||
$ nixos-option services.xserver.enable
|
||||
true
|
||||
|
||||
$ nixos-option boot.kernelModules
|
||||
[ "tun" "ipv6" "loop" ... ]
|
||||
```
|
||||
|
||||
Interactive exploration of the configuration is possible using `nix
|
||||
repl`, a read-eval-print loop for Nix expressions. A typical use:
|
||||
|
||||
```ShellSession
|
||||
$ nix repl '<nixpkgs/nixos>'
|
||||
|
||||
nix-repl> config.networking.hostName
|
||||
"mandark"
|
||||
|
||||
nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts
|
||||
[ "example.org" "example.gov" ]
|
||||
```
|
||||
|
||||
While abstracting your configuration, you may find it useful to generate
|
||||
modules using code, instead of writing files. The example below would
|
||||
have the same effect as importing a file which sets those options.
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
let netConfig = hostName: {
|
||||
networking.hostName = hostName;
|
||||
networking.useDHCP = false;
|
||||
};
|
||||
|
||||
in
|
||||
|
||||
{ imports = [ (netConfig "nixos.localdomain") ]; }
|
||||
```
|
||||
|
||||
[^1]: If you're wondering how it's possible that the (indirect) *result*
|
||||
of a function is passed as an *input* to that same function: that's
|
||||
because Nix is a "lazy" language --- it only computes values when
|
||||
they are needed. This works as long as no individual configuration
|
||||
value depends on itself.
|
@ -1,146 +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-modularity">
|
||||
<title>Modularity</title>
|
||||
|
||||
<para>
|
||||
The NixOS configuration mechanism is modular. If your
|
||||
<filename>configuration.nix</filename> becomes too big, you can split it into
|
||||
multiple files. Likewise, if you have multiple NixOS configurations (e.g. for
|
||||
different computers) with some commonality, you can move the common
|
||||
configuration into a shared file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Modules have exactly the same syntax as
|
||||
<filename>configuration.nix</filename>. In fact,
|
||||
<filename>configuration.nix</filename> is itself a module. You can use other
|
||||
modules by including them from <filename>configuration.nix</filename>, e.g.:
|
||||
<programlisting>
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{ imports = [ ./vpn.nix ./kde.nix ];
|
||||
<xref linkend="opt-services.httpd.enable"/> = true;
|
||||
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.emacs ];
|
||||
<replaceable>...</replaceable>
|
||||
}
|
||||
</programlisting>
|
||||
Here, we include two modules from the same directory,
|
||||
<filename>vpn.nix</filename> and <filename>kde.nix</filename>. The latter
|
||||
might look like this:
|
||||
<programlisting>
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{ <xref linkend="opt-services.xserver.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;
|
||||
<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;
|
||||
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.vim ];
|
||||
}
|
||||
</programlisting>
|
||||
Note that both <filename>configuration.nix</filename> and
|
||||
<filename>kde.nix</filename> define the option
|
||||
<xref linkend="opt-environment.systemPackages"/>. When multiple modules
|
||||
define an option, NixOS will try to <emphasis>merge</emphasis> the
|
||||
definitions. In the case of <xref linkend="opt-environment.systemPackages"/>,
|
||||
that’s easy: the lists of packages can simply be concatenated. The value in
|
||||
<filename>configuration.nix</filename> is merged last, so for list-type
|
||||
options, it will appear at the end of the merged list. If you want it to
|
||||
appear first, you can use <varname>mkBefore</varname>:
|
||||
<programlisting>
|
||||
<xref linkend="opt-boot.kernelModules"/> = mkBefore [ "kvm-intel" ];
|
||||
</programlisting>
|
||||
This causes the <literal>kvm-intel</literal> kernel module to be loaded
|
||||
before any other kernel modules.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For other types of options, a merge may not be possible. For instance, if two
|
||||
modules define <xref linkend="opt-services.httpd.adminAddr"/>,
|
||||
<command>nixos-rebuild</command> will give an error:
|
||||
<screen>
|
||||
The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.
|
||||
</screen>
|
||||
When that happens, it’s possible to force one definition take precedence
|
||||
over the others:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.httpd.adminAddr"/> = pkgs.lib.mkForce "bob@example.org";
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When using multiple modules, you may need to access configuration values
|
||||
defined in other modules. This is what the <varname>config</varname> function
|
||||
argument is for: it contains the complete, merged system configuration. That
|
||||
is, <varname>config</varname> is the result of combining the configurations
|
||||
returned by every module
|
||||
<footnote xml:id="footnote-nix-is-lazy">
|
||||
<para>
|
||||
If you’re wondering how it’s possible that the (indirect)
|
||||
<emphasis>result</emphasis> of a function is passed as an
|
||||
<emphasis>input</emphasis> to that same function: that’s because Nix is a
|
||||
“lazy” language — it only computes values when they are needed. This
|
||||
works as long as no individual configuration value depends on itself.
|
||||
</para>
|
||||
</footnote>
|
||||
. For example, here is a module that adds some packages to
|
||||
<xref linkend="opt-environment.systemPackages"/> only if
|
||||
<xref linkend="opt-services.xserver.enable"/> is set to
|
||||
<literal>true</literal> somewhere else:
|
||||
<programlisting>
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{ <xref linkend="opt-environment.systemPackages"/> =
|
||||
if config.<xref linkend="opt-services.xserver.enable"/> then
|
||||
[ pkgs.firefox
|
||||
pkgs.thunderbird
|
||||
]
|
||||
else
|
||||
[ ];
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
With multiple modules, it may not be obvious what the final value of a
|
||||
configuration option is. The command <option>nixos-option</option> allows you
|
||||
to find out:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nixos-option <xref linkend="opt-services.xserver.enable"/>
|
||||
true
|
||||
|
||||
<prompt>$ </prompt>nixos-option <xref linkend="opt-boot.kernelModules"/>
|
||||
[ "tun" "ipv6" "loop" <replaceable>...</replaceable> ]
|
||||
</screen>
|
||||
Interactive exploration of the configuration is possible using <command>nix
|
||||
repl</command>, a read-eval-print loop for Nix expressions. A typical use:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix repl '<nixpkgs/nixos>'
|
||||
|
||||
<prompt>nix-repl> </prompt>config.<xref linkend="opt-networking.hostName"/>
|
||||
"mandark"
|
||||
|
||||
<prompt>nix-repl> </prompt>map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/>
|
||||
[ "example.org" "example.gov" ]
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
While abstracting your configuration, you may find it useful to generate
|
||||
modules using code, instead of writing files. The example below would have
|
||||
the same effect as importing a file which sets those options.
|
||||
<programlisting>
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
let netConfig = hostName: {
|
||||
networking.hostName = hostName;
|
||||
networking.useDHCP = false;
|
||||
};
|
||||
|
||||
in
|
||||
|
||||
{ imports = [ (netConfig "nixos.localdomain") ]; }
|
||||
</programlisting>
|
||||
</para>
|
||||
</section>
|
42
nixos/doc/manual/configuration/network-manager.section.md
Normal file
42
nixos/doc/manual/configuration/network-manager.section.md
Normal file
@ -0,0 +1,42 @@
|
||||
# NetworkManager {#sec-networkmanager}
|
||||
|
||||
To facilitate network configuration, some desktop environments use
|
||||
NetworkManager. You can enable NetworkManager by setting:
|
||||
|
||||
```nix
|
||||
networking.networkmanager.enable = true;
|
||||
```
|
||||
|
||||
some desktop managers (e.g., GNOME) enable NetworkManager automatically
|
||||
for you.
|
||||
|
||||
All users that should have permission to change network settings must
|
||||
belong to the `networkmanager` group:
|
||||
|
||||
```nix
|
||||
users.users.alice.extraGroups = [ "networkmanager" ];
|
||||
```
|
||||
|
||||
NetworkManager is controlled using either `nmcli` or `nmtui`
|
||||
(curses-based terminal user interface). See their manual pages for
|
||||
details on their usage. Some desktop environments (GNOME, KDE) have
|
||||
their own configuration tools for NetworkManager. On XFCE, there is no
|
||||
configuration tool for NetworkManager by default: by enabling
|
||||
[](#opt-programs.nm-applet.enable), the graphical applet will be
|
||||
installed and will launch automatically when the graphical session is
|
||||
started.
|
||||
|
||||
::: {.note}
|
||||
`networking.networkmanager` and `networking.wireless` (WPA Supplicant)
|
||||
can be used together if desired. To do this you need to instruct
|
||||
NetworkManager to ignore those interfaces like:
|
||||
|
||||
```nix
|
||||
networking.networkmanager.unmanaged = [
|
||||
"*" "except:type:wwan" "except:type:gsm"
|
||||
];
|
||||
```
|
||||
|
||||
Refer to the option description for the exact syntax and references to
|
||||
external documentation.
|
||||
:::
|
@ -1,48 +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-networkmanager">
|
||||
<title>NetworkManager</title>
|
||||
|
||||
<para>
|
||||
To facilitate network configuration, some desktop environments use
|
||||
NetworkManager. You can enable NetworkManager by setting:
|
||||
<programlisting>
|
||||
<xref linkend="opt-networking.networkmanager.enable"/> = true;
|
||||
</programlisting>
|
||||
some desktop managers (e.g., GNOME) enable NetworkManager automatically for
|
||||
you.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All users that should have permission to change network settings must belong
|
||||
to the <code>networkmanager</code> group:
|
||||
<programlisting>
|
||||
<link linkend="opt-users.users._name_.extraGroups">users.users.alice.extraGroups</link> = [ "networkmanager" ];
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
NetworkManager is controlled using either <command>nmcli</command> or
|
||||
<command>nmtui</command> (curses-based terminal user interface). See their
|
||||
manual pages for details on their usage. Some desktop environments (GNOME,
|
||||
KDE) have their own configuration tools for NetworkManager. On XFCE, there is
|
||||
no configuration tool for NetworkManager by default: by enabling <xref linkend="opt-programs.nm-applet.enable"/>, the
|
||||
graphical applet will be installed and will launch automatically when the graphical session is started.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
<code>networking.networkmanager</code> and <code>networking.wireless</code>
|
||||
(WPA Supplicant) can be used together if desired. To do this you need to instruct
|
||||
NetworkManager to ignore those interfaces like:
|
||||
<programlisting>
|
||||
<xref linkend="opt-networking.networkmanager.unmanaged"/> = [
|
||||
"*" "except:type:wwan" "except:type:gsm"
|
||||
];
|
||||
</programlisting>
|
||||
Refer to the option description for the exact syntax and references to external documentation.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
@ -8,13 +8,13 @@
|
||||
This section describes how to configure networking components on your NixOS
|
||||
machine.
|
||||
</para>
|
||||
<xi:include href="network-manager.xml" />
|
||||
<xi:include href="ssh.xml" />
|
||||
<xi:include href="ipv4-config.xml" />
|
||||
<xi:include href="ipv6-config.xml" />
|
||||
<xi:include href="firewall.xml" />
|
||||
<xi:include href="wireless.xml" />
|
||||
<xi:include href="ad-hoc-network-config.xml" />
|
||||
<xi:include href="renaming-interfaces.xml" />
|
||||
<xi:include href="../from_md/configuration/network-manager.section.xml" />
|
||||
<xi:include href="../from_md/configuration/ssh.section.xml" />
|
||||
<xi:include href="../from_md/configuration/ipv4-config.section.xml" />
|
||||
<xi:include href="../from_md/configuration/ipv6-config.section.xml" />
|
||||
<xi:include href="../from_md/configuration/firewall.section.xml" />
|
||||
<xi:include href="../from_md/configuration/wireless.section.xml" />
|
||||
<xi:include href="../from_md/configuration/ad-hoc-network-config.section.xml" />
|
||||
<xi:include href="../from_md/configuration/renaming-interfaces.section.xml" />
|
||||
<!-- TODO: OpenVPN, NAT -->
|
||||
</chapter>
|
||||
|
@ -27,5 +27,5 @@
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<xi:include href="declarative-packages.xml" />
|
||||
<xi:include href="ad-hoc-packages.xml" />
|
||||
<xi:include href="../from_md/configuration/ad-hoc-packages.section.xml" />
|
||||
</chapter>
|
||||
|
@ -25,15 +25,15 @@
|
||||
What follows is a brief explanation on the purpose and use-case for each
|
||||
profile. Detailing each option configured by each one is out of scope.
|
||||
</para>
|
||||
<xi:include href="profiles/all-hardware.xml" />
|
||||
<xi:include href="profiles/base.xml" />
|
||||
<xi:include href="profiles/clone-config.xml" />
|
||||
<xi:include href="profiles/demo.xml" />
|
||||
<xi:include href="profiles/docker-container.xml" />
|
||||
<xi:include href="profiles/graphical.xml" />
|
||||
<xi:include href="profiles/hardened.xml" />
|
||||
<xi:include href="profiles/headless.xml" />
|
||||
<xi:include href="profiles/installation-device.xml" />
|
||||
<xi:include href="profiles/minimal.xml" />
|
||||
<xi:include href="profiles/qemu-guest.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/all-hardware.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/base.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/clone-config.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/demo.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/docker-container.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/graphical.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/hardened.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/headless.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/installation-device.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/minimal.section.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles/qemu-guest.section.xml" />
|
||||
</chapter>
|
||||
|
@ -0,0 +1,11 @@
|
||||
# All Hardware {#sec-profile-all-hardware}
|
||||
|
||||
Enables all hardware supported by NixOS: i.e., all firmware is included, and
|
||||
all devices from which one may boot are enabled in the initrd. Its primary
|
||||
use is in the NixOS installation CDs.
|
||||
|
||||
The enabled kernel modules include support for SATA and PATA, SCSI
|
||||
(partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and
|
||||
Hyper-V. Additionally, [](#opt-hardware.enableAllFirmware) is
|
||||
enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically
|
||||
installed.
|
@ -1,21 +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-profile-all-hardware">
|
||||
<title>All Hardware</title>
|
||||
|
||||
<para>
|
||||
Enables all hardware supported by NixOS: i.e., all firmware is included, and
|
||||
all devices from which one may boot are enabled in the initrd. Its primary
|
||||
use is in the NixOS installation CDs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The enabled kernel modules include support for SATA and PATA, SCSI
|
||||
(partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and
|
||||
Hyper-V. Additionally, <xref linkend="opt-hardware.enableAllFirmware"/> is
|
||||
enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically
|
||||
installed.
|
||||
</para>
|
||||
</section>
|
7
nixos/doc/manual/configuration/profiles/base.section.md
Normal file
7
nixos/doc/manual/configuration/profiles/base.section.md
Normal file
@ -0,0 +1,7 @@
|
||||
# Base {#sec-profile-base}
|
||||
|
||||
Defines the software packages included in the "minimal" installation CD. It
|
||||
installs several utilities useful in a simple recovery or install media, such
|
||||
as a text-mode web browser, and tools for manipulating block devices,
|
||||
networking, hardware diagnostics, and filesystems (with their respective
|
||||
kernel modules).
|
@ -1,15 +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-profile-base">
|
||||
<title>Base</title>
|
||||
|
||||
<para>
|
||||
Defines the software packages included in the "minimal" installation CD. It
|
||||
installs several utilities useful in a simple recovery or install media, such
|
||||
as a text-mode web browser, and tools for manipulating block devices,
|
||||
networking, hardware diagnostics, and filesystems (with their respective
|
||||
kernel modules).
|
||||
</para>
|
||||
</section>
|
@ -0,0 +1,11 @@
|
||||
# Clone Config {#sec-profile-clone-config}
|
||||
|
||||
This profile is used in installer images. It provides an editable
|
||||
configuration.nix that imports all the modules that were also used when
|
||||
creating the image in the first place. As a result it allows users to edit
|
||||
and rebuild the live-system.
|
||||
|
||||
On images where the installation media also becomes an installation target,
|
||||
copying over `configuration.nix` should be disabled by
|
||||
setting `installer.cloneConfig` to `false`.
|
||||
For example, this is done in `sd-image-aarch64-installer.nix`.
|
@ -1,21 +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-profile-clone-config">
|
||||
<title>Clone Config</title>
|
||||
|
||||
<para>
|
||||
This profile is used in installer images. It provides an editable
|
||||
configuration.nix that imports all the modules that were also used when
|
||||
creating the image in the first place. As a result it allows users to edit
|
||||
and rebuild the live-system.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
On images where the installation media also becomes an installation target,
|
||||
copying over <literal>configuration.nix</literal> should be disabled by
|
||||
setting <literal>installer.cloneConfig</literal> to <literal>false</literal>.
|
||||
For example, this is done in <literal>sd-image-aarch64-installer.nix</literal>.
|
||||
</para>
|
||||
</section>
|
4
nixos/doc/manual/configuration/profiles/demo.section.md
Normal file
4
nixos/doc/manual/configuration/profiles/demo.section.md
Normal file
@ -0,0 +1,4 @@
|
||||
# Demo {#sec-profile-demo}
|
||||
|
||||
This profile just enables a `demo` user, with password `demo`, uid `1000`, `wheel` group and
|
||||
[autologin in the SDDM display manager](#opt-services.xserver.displayManager.autoLogin).
|
@ -1,14 +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-profile-demo">
|
||||
<title>Demo</title>
|
||||
|
||||
<para>
|
||||
This profile just enables a <systemitem class="username">demo</systemitem>
|
||||
user, with password <literal>demo</literal>, uid <literal>1000</literal>,
|
||||
<systemitem class="groupname">wheel</systemitem> group and
|
||||
<link linkend="opt-services.xserver.displayManager.autoLogin">autologin in the SDDM display manager</link>.
|
||||
</para>
|
||||
</section>
|
@ -0,0 +1,7 @@
|
||||
# Docker Container {#sec-profile-docker-container}
|
||||
|
||||
This is the profile from which the Docker images are generated. It prepares a
|
||||
working system by importing the [Minimal](#sec-profile-minimal) and
|
||||
[Clone Config](#sec-profile-clone-config) profiles, and
|
||||
setting appropriate configuration options that are useful inside a container
|
||||
context, like [](#opt-boot.isContainer).
|
@ -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-profile-docker-container">
|
||||
<title>Docker Container</title>
|
||||
|
||||
<para>
|
||||
This is the profile from which the Docker images are generated. It prepares a
|
||||
working system by importing the
|
||||
<link linkend="sec-profile-minimal">Minimal</link> and
|
||||
<link linkend="sec-profile-clone-config">Clone Config</link> profiles, and
|
||||
setting appropriate configuration options that are useful inside a container
|
||||
context, like <xref linkend="opt-boot.isContainer"/>.
|
||||
</para>
|
||||
</section>
|
10
nixos/doc/manual/configuration/profiles/graphical.section.md
Normal file
10
nixos/doc/manual/configuration/profiles/graphical.section.md
Normal file
@ -0,0 +1,10 @@
|
||||
# Graphical {#sec-profile-graphical}
|
||||
|
||||
Defines a NixOS configuration with the Plasma 5 desktop. It's used by the
|
||||
graphical installation CD.
|
||||
|
||||
It sets [](#opt-services.xserver.enable),
|
||||
[](#opt-services.xserver.displayManager.sddm.enable),
|
||||
[](#opt-services.xserver.desktopManager.plasma5.enable),
|
||||
and [](#opt-services.xserver.libinput.enable) to true. It also
|
||||
includes glxinfo and firefox in the system packages list.
|
@ -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="sec-profile-graphical">
|
||||
<title>Graphical</title>
|
||||
|
||||
<para>
|
||||
Defines a NixOS configuration with the Plasma 5 desktop. It's used by the
|
||||
graphical installation CD.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It sets <xref linkend="opt-services.xserver.enable"/>,
|
||||
<xref linkend="opt-services.xserver.displayManager.sddm.enable"/>,
|
||||
<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/>, and
|
||||
<xref linkend="opt-services.xserver.libinput.enable"/> to true. It also
|
||||
includes glxinfo and firefox in the system packages list.
|
||||
</para>
|
||||
</section>
|
20
nixos/doc/manual/configuration/profiles/hardened.section.md
Normal file
20
nixos/doc/manual/configuration/profiles/hardened.section.md
Normal file
@ -0,0 +1,20 @@
|
||||
# Hardened {#sec-profile-hardened}
|
||||
|
||||
A profile with most (vanilla) hardening options enabled by default,
|
||||
potentially at the cost of stability, features and performance.
|
||||
|
||||
This includes a hardened kernel, and limiting the system information
|
||||
available to processes through the `/sys` and
|
||||
`/proc` filesystems. It also disables the User Namespaces
|
||||
feature of the kernel, which stops Nix from being able to build anything
|
||||
(this particular setting can be overriden via
|
||||
[](#opt-security.allowUserNamespaces)). See the
|
||||
[profile source](https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix)
|
||||
for further detail on which settings are altered.
|
||||
|
||||
::: {.warning}
|
||||
This profile enables options that are known to affect system
|
||||
stability. If you experience any stability issues when using the
|
||||
profile, try disabling it. If you report an issue and use this
|
||||
profile, always mention that you do.
|
||||
:::
|
@ -1,32 +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-profile-hardened">
|
||||
<title>Hardened</title>
|
||||
|
||||
<para>
|
||||
A profile with most (vanilla) hardening options enabled by default,
|
||||
potentially at the cost of stability, features and performance.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This includes a hardened kernel, and limiting the system information
|
||||
available to processes through the <filename>/sys</filename> and
|
||||
<filename>/proc</filename> filesystems. It also disables the User Namespaces
|
||||
feature of the kernel, which stops Nix from being able to build anything
|
||||
(this particular setting can be overriden via
|
||||
<xref linkend="opt-security.allowUserNamespaces"/>). See the
|
||||
<literal
|
||||
xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix">
|
||||
profile source</literal> for further detail on which settings are altered.
|
||||
</para>
|
||||
<warning>
|
||||
<para>
|
||||
This profile enables options that are known to affect system
|
||||
stability. If you experience any stability issues when using the
|
||||
profile, try disabling it. If you report an issue and use this
|
||||
profile, always mention that you do.
|
||||
</para>
|
||||
</warning>
|
||||
</section>
|
@ -0,0 +1,9 @@
|
||||
# Headless {#sec-profile-headless}
|
||||
|
||||
Common configuration for headless machines (e.g., Amazon EC2 instances).
|
||||
|
||||
Disables [sound](#opt-sound.enable),
|
||||
[vesa](#opt-boot.vesa), serial consoles,
|
||||
[emergency mode](#opt-systemd.enableEmergencyMode),
|
||||
[grub splash images](#opt-boot.loader.grub.splashImage)
|
||||
and configures the kernel to reboot automatically on panic.
|
@ -1,19 +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-profile-headless">
|
||||
<title>Headless</title>
|
||||
|
||||
<para>
|
||||
Common configuration for headless machines (e.g., Amazon EC2 instances).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Disables <link linkend="opt-sound.enable">sound</link>,
|
||||
<link linkend="opt-boot.vesa">vesa</link>, serial consoles,
|
||||
<link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>,
|
||||
<link linkend="opt-boot.loader.grub.splashImage">grub splash images</link>
|
||||
and configures the kernel to reboot automatically on panic.
|
||||
</para>
|
||||
</section>
|
@ -0,0 +1,24 @@
|
||||
# Installation Device {#sec-profile-installation-device}
|
||||
|
||||
Provides a basic configuration for installation devices like CDs.
|
||||
This enables redistributable firmware, includes the
|
||||
[Clone Config profile](#sec-profile-clone-config)
|
||||
and a copy of the Nixpkgs channel, so `nixos-install`
|
||||
works out of the box.
|
||||
|
||||
Documentation for [Nixpkgs](#opt-documentation.enable)
|
||||
and [NixOS](#opt-documentation.nixos.enable) are
|
||||
forcefully enabled (to override the
|
||||
[Minimal profile](#sec-profile-minimal) preference); the
|
||||
NixOS manual is shown automatically on TTY 8, udisks is disabled.
|
||||
Autologin is enabled as `nixos` user, while passwordless
|
||||
login as both `root` and `nixos` is possible.
|
||||
Passwordless `sudo` is enabled too.
|
||||
[wpa_supplicant](#opt-networking.wireless.enable) is
|
||||
enabled, but configured to not autostart.
|
||||
|
||||
It is explained how to login, start the ssh server, and if available,
|
||||
how to start the display manager.
|
||||
|
||||
Several settings are tweaked so that the installer has a better chance of
|
||||
succeeding under low-memory environments.
|
@ -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-profile-installation-device">
|
||||
<title>Installation Device</title>
|
||||
|
||||
<para>
|
||||
Provides a basic configuration for installation devices like CDs.
|
||||
This enables redistributable firmware, includes the
|
||||
<link linkend="sec-profile-clone-config">Clone Config profile</link>
|
||||
and a copy of the Nixpkgs channel, so <command>nixos-install</command>
|
||||
works out of the box.
|
||||
</para>
|
||||
<para>
|
||||
Documentation for <link linkend="opt-documentation.enable">Nixpkgs</link>
|
||||
and <link linkend="opt-documentation.nixos.enable">NixOS</link> are
|
||||
forcefully enabled (to override the
|
||||
<link linkend="sec-profile-minimal">Minimal profile</link> preference); the
|
||||
NixOS manual is shown automatically on TTY 8, udisks is disabled.
|
||||
Autologin is enabled as <literal>nixos</literal> user, while passwordless
|
||||
login as both <literal>root</literal> and <literal>nixos</literal> is possible.
|
||||
Passwordless <command>sudo</command> is enabled too.
|
||||
<link linkend="opt-networking.wireless.enable">wpa_supplicant</link> is
|
||||
enabled, but configured to not autostart.
|
||||
</para>
|
||||
<para>
|
||||
It is explained how to login, start the ssh server, and if available,
|
||||
how to start the display manager.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Several settings are tweaked so that the installer has a better chance of
|
||||
succeeding under low-memory environments.
|
||||
</para>
|
||||
</section>
|
@ -0,0 +1,9 @@
|
||||
# Minimal {#sec-profile-minimal}
|
||||
|
||||
This profile defines a small NixOS configuration. It does not contain any
|
||||
graphical stuff. It's a very short file that enables
|
||||
[noXlibs](#opt-environment.noXlibs), sets
|
||||
[](#opt-i18n.supportedLocales) to
|
||||
only support the user-selected locale,
|
||||
[disables packages' documentation](#opt-documentation.enable),
|
||||
and [disables sound](#opt-sound.enable).
|
@ -1,17 +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-profile-minimal">
|
||||
<title>Minimal</title>
|
||||
|
||||
<para>
|
||||
This profile defines a small NixOS configuration. It does not contain any
|
||||
graphical stuff. It's a very short file that enables
|
||||
<link linkend="opt-environment.noXlibs">noXlibs</link>, sets
|
||||
<link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> to
|
||||
only support the user-selected locale,
|
||||
<link linkend="opt-documentation.enable">disables packages' documentation
|
||||
</link>, and <link linkend="opt-sound.enable">disables sound</link>.
|
||||
</para>
|
||||
</section>
|
@ -0,0 +1,7 @@
|
||||
# QEMU Guest {#sec-profile-qemu-guest}
|
||||
|
||||
This profile contains common configuration for virtual machines running under
|
||||
QEMU (using virtio).
|
||||
|
||||
It makes virtio modules available on the initrd and sets the system time from
|
||||
the hardware clock to work around a bug in qemu-kvm.
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user