Merge branch 'master' into feature/bump-torchvision
This commit is contained in:
commit
b9b70a1217
10
.github/CODEOWNERS
vendored
10
.github/CODEOWNERS
vendored
|
@ -19,7 +19,7 @@
|
|||
|
||||
# Libraries
|
||||
/lib @edolstra @nbp @infinisil
|
||||
/lib/systems @nbp @ericson2314 @matthewbauer
|
||||
/lib/systems @alyssais @nbp @ericson2314 @matthewbauer
|
||||
/lib/generators.nix @edolstra @nbp @Profpatsch
|
||||
/lib/cli.nix @edolstra @nbp @Profpatsch
|
||||
/lib/debug.nix @edolstra @nbp @Profpatsch
|
||||
|
@ -42,6 +42,12 @@
|
|||
# Nixpkgs build-support
|
||||
/pkgs/build-support/writers @lassulus @Profpatsch
|
||||
|
||||
# Nixpkgs documentation
|
||||
/maintainers/scripts/db-to-md.sh @jtojnar @ryantm
|
||||
/maintainers/scripts/doc @jtojnar @ryantm
|
||||
/doc/build-aux/pandoc-filters @jtojnar
|
||||
/doc/contributing/contributing-to-documentation.chapter.md @jtojnar
|
||||
|
||||
# NixOS Internals
|
||||
/nixos/default.nix @nbp @infinisil
|
||||
/nixos/lib/from-env.nix @nbp @infinisil
|
||||
|
@ -104,7 +110,7 @@
|
|||
|
||||
# Rust
|
||||
/pkgs/development/compilers/rust @Mic92 @LnL7 @zowoq
|
||||
/pkgs/build-support/rust @andir @danieldk @zowoq
|
||||
/pkgs/build-support/rust @andir @zowoq
|
||||
|
||||
# Darwin-related
|
||||
/pkgs/stdenv/darwin @NixOS/darwin-maintainers
|
||||
|
|
2
.github/workflows/basic-eval.yml
vendored
2
.github/workflows/basic-eval.yml
vendored
|
@ -15,6 +15,6 @@ jobs:
|
|||
# we don't limit this action to only NixOS repo since the checks are cheap and useful developer feedback
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- uses: cachix/install-nix-action@v13
|
||||
- uses: cachix/install-nix-action@v14
|
||||
# explicit list of supportedSystems is needed until aarch64-darwin becomes part of the trunk jobset
|
||||
- run: nix-build pkgs/top-level/release.nix -A tarball.nixpkgs-basic-release-checks --arg supportedSystems '[ "aarch64-darwin" "aarch64-linux" "x86_64-linux" "x86_64-darwin" ]'
|
||||
|
|
2
.github/workflows/editorconfig.yml
vendored
2
.github/workflows/editorconfig.yml
vendored
|
@ -28,7 +28,7 @@ jobs:
|
|||
# pull_request_target checks out the base branch by default
|
||||
ref: refs/pull/${{ github.event.pull_request.number }}/merge
|
||||
if: env.PR_DIFF
|
||||
- uses: cachix/install-nix-action@v13
|
||||
- uses: cachix/install-nix-action@v14
|
||||
if: env.PR_DIFF
|
||||
with:
|
||||
# nixpkgs commit is pinned so that it doesn't break
|
||||
|
|
2
.github/workflows/manual-nixos.yml
vendored
2
.github/workflows/manual-nixos.yml
vendored
|
@ -18,7 +18,7 @@ jobs:
|
|||
with:
|
||||
# pull_request_target checks out the base branch by default
|
||||
ref: refs/pull/${{ github.event.pull_request.number }}/merge
|
||||
- uses: cachix/install-nix-action@v13
|
||||
- uses: cachix/install-nix-action@v14
|
||||
with:
|
||||
# explicitly enable sandbox
|
||||
extra_nix_config: sandbox = true
|
||||
|
|
2
.github/workflows/manual-nixpkgs.yml
vendored
2
.github/workflows/manual-nixpkgs.yml
vendored
|
@ -18,7 +18,7 @@ jobs:
|
|||
with:
|
||||
# pull_request_target checks out the base branch by default
|
||||
ref: refs/pull/${{ github.event.pull_request.number }}/merge
|
||||
- uses: cachix/install-nix-action@v13
|
||||
- uses: cachix/install-nix-action@v14
|
||||
with:
|
||||
# explicitly enable sandbox
|
||||
extra_nix_config: sandbox = true
|
||||
|
|
2
.github/workflows/nixos-manual.yml
vendored
2
.github/workflows/nixos-manual.yml
vendored
|
@ -19,7 +19,7 @@ jobs:
|
|||
with:
|
||||
# pull_request_target checks out the base branch by default
|
||||
ref: refs/pull/${{ github.event.pull_request.number }}/merge
|
||||
- uses: cachix/install-nix-action@v12
|
||||
- uses: cachix/install-nix-action@v14
|
||||
- name: Check DocBook files generated from Markdown are consistent
|
||||
run: |
|
||||
nixos/doc/manual/md-to-db.sh
|
||||
|
|
2
.github/workflows/periodic-merge-24h.yml
vendored
2
.github/workflows/periodic-merge-24h.yml
vendored
|
@ -33,7 +33,7 @@ jobs:
|
|||
- uses: actions/checkout@v2
|
||||
|
||||
- name: ${{ matrix.pairs.from }} → ${{ matrix.pairs.into }}
|
||||
uses: devmasx/merge-branch@v1.3.1
|
||||
uses: devmasx/merge-branch@1.4.0
|
||||
with:
|
||||
type: now
|
||||
from_branch: ${{ matrix.pairs.from }}
|
||||
|
|
2
.github/workflows/periodic-merge-6h.yml
vendored
2
.github/workflows/periodic-merge-6h.yml
vendored
|
@ -39,7 +39,7 @@ jobs:
|
|||
- uses: actions/checkout@v2
|
||||
|
||||
- name: ${{ matrix.pairs.from }} → ${{ matrix.pairs.into }}
|
||||
uses: devmasx/merge-branch@v1.3.1
|
||||
uses: devmasx/merge-branch@1.4.0
|
||||
with:
|
||||
type: now
|
||||
from_branch: ${{ matrix.pairs.from }}
|
||||
|
|
1
.gitignore
vendored
1
.gitignore
vendored
|
@ -2,6 +2,7 @@
|
|||
,*
|
||||
.*.swp
|
||||
.*.swo
|
||||
.idea/
|
||||
result
|
||||
result-*
|
||||
/doc/NEWS.html
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -68,27 +68,107 @@ Erlang.mk functions similarly to Rebar3, except we use `buildErlangMk` instead o
|
|||
|
||||
`mixRelease` is used to make a release in the mix sense. Dependencies will need to be fetched with `fetchMixDeps` and passed to it.
|
||||
|
||||
#### mixRelease - Elixir Phoenix example {#mixrelease---elixir-phoenix-example}
|
||||
#### mixRelease - Elixir Phoenix example {#mix-release-elixir-phoenix-example}
|
||||
|
||||
Here is how your `default.nix` file would look.
|
||||
there are 3 steps, frontend dependencies (javascript), backend dependencies (elixir) and the final derivation that puts both of those together
|
||||
|
||||
##### mixRelease - Frontend dependencies (javascript) {#mix-release-javascript-deps}
|
||||
|
||||
for phoenix projects, inside of nixpkgs you can either use yarn2nix (mkYarnModule) or node2nix. An example with yarn2nix can be found [here](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/web-apps/plausible/default.nix#L39). An example with node2nix will follow. To package something outside of nixpkgs, you have alternatives like [npmlock2nix](https://github.com/nix-community/npmlock2nix) or [nix-npm-buildpackage](https://github.com/serokell/nix-npm-buildpackage)
|
||||
|
||||
##### mixRelease - backend dependencies (mix) {#mix-release-mix-deps}
|
||||
|
||||
There are 2 ways to package backend dependencies. With mix2nix and with a fixed-output-derivation (FOD).
|
||||
|
||||
###### mix2nix {#mix2nix}
|
||||
|
||||
mix2nix is a cli tool available in nixpkgs. it will generate a nix expression from a mix.lock file. It is quite standard in the 2nix tool series.
|
||||
|
||||
Note that currently mix2nix can't handle git dependencies inside the mix.lock file. If you have git dependencies, you can either add them manually (see [example](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/pleroma/default.nix#L20)) or use the FOD method.
|
||||
|
||||
The advantage of using mix2nix is that nix will know your whole dependency graph. On a dependency update, this won't trigger a full rebuild and download of all the dependencies, where FOD will do so.
|
||||
|
||||
practical steps:
|
||||
|
||||
- run `mix2nix > mix_deps.nix` in the upstream repo.
|
||||
- pass `mixNixDeps = with pkgs; import ./mix_deps.nix { inherit lib beamPackages; };` as an argument to mixRelease.
|
||||
|
||||
If there are git depencencies.
|
||||
|
||||
- You'll need to fix the version artificially in mix.exs and regenerate the mix.lock with fixed version (on upstream). This will enable you to run `mix2nix > mix_deps.nix`.
|
||||
- From the mix_deps.nix file, remove the dependencies that had git versions and pass them as an override to the import function.
|
||||
|
||||
```nix
|
||||
mixNixDeps = import ./mix.nix {
|
||||
inherit beamPackages lib;
|
||||
overrides = (final: prev: {
|
||||
# mix2nix does not support git dependencies yet,
|
||||
# so we need to add them manually
|
||||
prometheus_ex = beamPackages.buildMix rec {
|
||||
name = "prometheus_ex";
|
||||
version = "3.0.5";
|
||||
|
||||
# Change the argument src with the git src that you actually need
|
||||
src = fetchFromGitLab {
|
||||
domain = "git.pleroma.social";
|
||||
group = "pleroma";
|
||||
owner = "elixir-libraries";
|
||||
repo = "prometheus.ex";
|
||||
rev = "a4e9beb3c1c479d14b352fd9d6dd7b1f6d7deee5";
|
||||
sha256 = "1v0q4bi7sb253i8q016l7gwlv5562wk5zy3l2sa446csvsacnpjk";
|
||||
};
|
||||
# you can re-use the same beamDeps argument as generated
|
||||
beamDeps = with final; [ prometheus ];
|
||||
};
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
You will need to run the build process once to fix the sha256 to correspond to your new git src.
|
||||
|
||||
###### FOD {#fixed-output-derivation}
|
||||
|
||||
A fixed output derivation will download mix dependencies from the internet. To ensure reproducibility, a hash will be supplied. Note that mix is relatively reproducible. An FOD generating a different hash on each run hasn't been observed (as opposed to npm where the chances are relatively high). See [elixir_ls](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/beam-modules/elixir_ls.nix) for a usage example of FOD.
|
||||
|
||||
Practical steps
|
||||
|
||||
- start with the following argument to mixRelease
|
||||
|
||||
```nix
|
||||
mixFodDeps = fetchMixDeps {
|
||||
pname = "mix-deps-${pname}";
|
||||
inherit src version;
|
||||
sha256 = lib.fakeSha256;
|
||||
};
|
||||
```
|
||||
|
||||
The first build will complain about the sha256 value, you can replace with the suggested value after that.
|
||||
|
||||
Note that if after you've replaced the value, nix suggests another sha256, then mix is not fetching the dependencies reproducibly. An FOD will not work in that case and you will have to use mix2nix.
|
||||
|
||||
##### mixRelease - example {#mix-release-example}
|
||||
|
||||
Here is how your `default.nix` file would look for a phoenix project.
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> { };
|
||||
|
||||
let
|
||||
# beam.interpreters.erlangR23 is available if you need a particular version
|
||||
packages = beam.packagesWith beam.interpreters.erlang;
|
||||
|
||||
pname = "your_project";
|
||||
version = "0.0.1";
|
||||
|
||||
src = builtins.fetchgit {
|
||||
url = "ssh://git@github.com/your_id/your_repo";
|
||||
rev = "replace_with_your_commit";
|
||||
};
|
||||
|
||||
pname = "your_project";
|
||||
version = "0.0.1";
|
||||
mixEnv = "prod";
|
||||
|
||||
# if using mix2nix you can use the mixNixDeps attribute
|
||||
mixFodDeps = packages.fetchMixDeps {
|
||||
pname = "mix-deps-${pname}";
|
||||
inherit src mixEnv version;
|
||||
inherit src version;
|
||||
# nix will complain and tell you the right value to replace this with
|
||||
sha256 = lib.fakeSha256;
|
||||
# if you have build time environment variables add them here
|
||||
|
@ -97,45 +177,19 @@ let
|
|||
|
||||
nodeDependencies = (pkgs.callPackage ./assets/default.nix { }).shell.nodeDependencies;
|
||||
|
||||
frontEndFiles = stdenvNoCC.mkDerivation {
|
||||
pname = "frontend-${pname}";
|
||||
|
||||
nativeBuildInputs = [ nodejs ];
|
||||
|
||||
inherit version src;
|
||||
|
||||
buildPhase = ''
|
||||
cp -r ./assets $TEMPDIR
|
||||
|
||||
mkdir -p $TEMPDIR/assets/node_modules/.cache
|
||||
cp -r ${nodeDependencies}/lib/node_modules $TEMPDIR/assets
|
||||
export PATH="${nodeDependencies}/bin:$PATH"
|
||||
|
||||
cd $TEMPDIR/assets
|
||||
webpack --config ./webpack.config.js
|
||||
cd ..
|
||||
'';
|
||||
|
||||
installPhase = ''
|
||||
cp -r ./priv/static $out/
|
||||
'';
|
||||
|
||||
outputHashAlgo = "sha256";
|
||||
outputHashMode = "recursive";
|
||||
# nix will complain and tell you the right value to replace this with
|
||||
outputHash = lib.fakeSha256;
|
||||
|
||||
impureEnvVars = lib.fetchers.proxyImpureEnvVars;
|
||||
};
|
||||
|
||||
|
||||
in packages.mixRelease {
|
||||
inherit src pname version mixEnv mixFodDeps;
|
||||
inherit src pname version mixFodDeps;
|
||||
# if you have build time environment variables add them here
|
||||
MY_ENV_VAR="my_value";
|
||||
preInstall = ''
|
||||
mkdir -p ./priv/static
|
||||
cp -r ${frontEndFiles} ./priv/static
|
||||
|
||||
postBuild = ''
|
||||
ln -sf ${nodeDependencies}/lib/node_modules assets/node_modules
|
||||
npm run deploy --prefix ./assets
|
||||
|
||||
# for external task you need a workaround for the no deps check flag
|
||||
# https://github.com/phoenixframework/phoenix/issues/2690
|
||||
mix do deps.loadpaths --no-deps-check, phx.digest
|
||||
mix phx.digest --no-deps-check
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
@ -165,6 +219,8 @@ in
|
|||
systemd.services.${release_name} = {
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
after = [ "network.target" "postgresql.service" ];
|
||||
# note that if you are connecting to a postgres instance on a different host
|
||||
# postgresql.service should not be included in the requires.
|
||||
requires = [ "network-online.target" "postgresql.service" ];
|
||||
description = "my app";
|
||||
environment = {
|
||||
|
@ -201,6 +257,7 @@ in
|
|||
path = [ pkgs.bash ];
|
||||
};
|
||||
|
||||
# in case you have migration scripts or you want to use a remote shell
|
||||
environment.systemPackages = [ release ];
|
||||
}
|
||||
```
|
||||
|
@ -215,16 +272,11 @@ Usually, we need to create a `shell.nix` file and do our development inside of t
|
|||
{ pkgs ? import <nixpkgs> {} }:
|
||||
|
||||
with pkgs;
|
||||
|
||||
let
|
||||
|
||||
elixir = beam.packages.erlangR22.elixir_1_9;
|
||||
|
||||
elixir = beam.packages.erlangR24.elixir_1_12;
|
||||
in
|
||||
mkShell {
|
||||
buildInputs = [ elixir ];
|
||||
|
||||
ERL_INCLUDE_PATH="${erlang}/lib/erlang/usr/include";
|
||||
}
|
||||
```
|
||||
|
||||
|
@ -264,6 +316,7 @@ let
|
|||
# TODO: not sure how to make hex available without installing it afterwards.
|
||||
mix local.hex --if-missing
|
||||
export LANG=en_US.UTF-8
|
||||
# keep your shell history in iex
|
||||
export ERL_AFLAGS="-kernel shell_history enabled"
|
||||
|
||||
# postges related
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Introduction {#javascript-introduction}
|
||||
|
||||
This contains instructions on how to package javascript applications. For instructions on how to add a cli package from npm please consult the #node.js section
|
||||
This contains instructions on how to package javascript applications.
|
||||
|
||||
The various tools available will be listed in the [tools-overview](#javascript-tools-overview). Some general principles for packaging will follow. Finally some tool specific instructions will be given.
|
||||
|
||||
|
|
|
@ -35,6 +35,8 @@ rec {
|
|||
("generators.mkValueStringDefault: " +
|
||||
"${t} not supported: ${toPretty {} v}");
|
||||
in if isInt v then toString v
|
||||
# convert derivations to store paths
|
||||
else if lib.isDerivation v then toString v
|
||||
# we default to not quoting strings
|
||||
else if isString v then v
|
||||
# isString returns "1", which is not a good default
|
||||
|
@ -169,7 +171,7 @@ rec {
|
|||
# converts { a.b.c = 5; } to { "a.b".c = 5; } for toINI
|
||||
gitFlattenAttrs = let
|
||||
recurse = path: value:
|
||||
if isAttrs value then
|
||||
if isAttrs value && !lib.isDerivation value then
|
||||
lib.mapAttrsToList (name: value: recurse ([ name ] ++ path) value) value
|
||||
else if length path > 1 then {
|
||||
${concatStringsSep "." (lib.reverseList (tail path))}.${head path} = value;
|
||||
|
|
|
@ -89,7 +89,7 @@ rec {
|
|||
=> "usr/local/bin"
|
||||
*/
|
||||
concatStringsSep = builtins.concatStringsSep or (separator: list:
|
||||
concatStrings (intersperse separator list));
|
||||
lib.foldl' (x: y: x + y) "" (intersperse separator list));
|
||||
|
||||
/* Maps a function over a list of strings and then concatenates the
|
||||
result with the specified separator interspersed between
|
||||
|
|
|
@ -107,6 +107,7 @@ rec {
|
|||
else if final.isMips then "mips"
|
||||
else if final.isPower then "powerpc"
|
||||
else if final.isRiscV then "riscv"
|
||||
else if final.isS390 then "s390"
|
||||
else final.parsed.cpu.name;
|
||||
|
||||
qemuArch =
|
||||
|
|
|
@ -28,7 +28,7 @@ let
|
|||
"aarch64-linux" "armv5tel-linux" "armv6l-linux" "armv7a-linux"
|
||||
"armv7l-linux" "i686-linux" "m68k-linux" "mipsel-linux"
|
||||
"powerpc64-linux" "powerpc64le-linux" "riscv32-linux"
|
||||
"riscv64-linux" "s390-linux" "x86_64-linux"
|
||||
"riscv64-linux" "s390-linux" "s390x-linux" "x86_64-linux"
|
||||
|
||||
# MMIXware
|
||||
"mmix-mmixware"
|
||||
|
@ -41,7 +41,8 @@ let
|
|||
# none
|
||||
"aarch64-none" "arm-none" "armv6l-none" "avr-none" "i686-none"
|
||||
"msp430-none" "or1k-none" "m68k-none" "powerpc-none"
|
||||
"riscv32-none" "riscv64-none" "s390-none" "vc4-none" "x86_64-none"
|
||||
"riscv32-none" "riscv64-none" "s390-none" "s390x-none" "vc4-none"
|
||||
"x86_64-none"
|
||||
|
||||
# OpenBSD
|
||||
"i686-openbsd" "x86_64-openbsd"
|
||||
|
|
|
@ -152,6 +152,10 @@ rec {
|
|||
config = "s390-unknown-linux-gnu";
|
||||
};
|
||||
|
||||
s390x = {
|
||||
config = "s390x-unknown-linux-gnu";
|
||||
};
|
||||
|
||||
arm-embedded = {
|
||||
config = "arm-none-eabi";
|
||||
libc = "newlib";
|
||||
|
|
|
@ -106,6 +106,7 @@ rec {
|
|||
riscv64 = { bits = 64; significantByte = littleEndian; family = "riscv"; };
|
||||
|
||||
s390 = { bits = 32; significantByte = bigEndian; family = "s390"; };
|
||||
s390x = { bits = 64; significantByte = bigEndian; family = "s390"; };
|
||||
|
||||
sparc = { bits = 32; significantByte = bigEndian; family = "sparc"; };
|
||||
sparc64 = { bits = 64; significantByte = bigEndian; family = "sparc"; };
|
||||
|
|
|
@ -28,7 +28,7 @@ with lib.systems.doubles; lib.runTests {
|
|||
testredox = mseteq redox [ "x86_64-redox" ];
|
||||
testgnu = mseteq gnu (linux /* ++ kfreebsd ++ ... */);
|
||||
testillumos = mseteq illumos [ "x86_64-solaris" ];
|
||||
testlinux = mseteq linux [ "aarch64-linux" "armv5tel-linux" "armv6l-linux" "armv7a-linux" "armv7l-linux" "i686-linux" "mipsel-linux" "riscv32-linux" "riscv64-linux" "x86_64-linux" "powerpc64-linux" "powerpc64le-linux" "m68k-linux" "s390-linux" ];
|
||||
testlinux = mseteq linux [ "aarch64-linux" "armv5tel-linux" "armv6l-linux" "armv7a-linux" "armv7l-linux" "i686-linux" "mipsel-linux" "riscv32-linux" "riscv64-linux" "x86_64-linux" "powerpc64-linux" "powerpc64le-linux" "m68k-linux" "s390-linux" "s390x-linux" ];
|
||||
testnetbsd = mseteq netbsd [ "aarch64-netbsd" "armv6l-netbsd" "armv7a-netbsd" "armv7l-netbsd" "i686-netbsd" "m68k-netbsd" "mipsel-netbsd" "powerpc-netbsd" "riscv32-netbsd" "riscv64-netbsd" "x86_64-netbsd" ];
|
||||
testopenbsd = mseteq openbsd [ "i686-openbsd" "x86_64-openbsd" ];
|
||||
testwindows = mseteq windows [ "i686-cygwin" "x86_64-cygwin" "i686-windows" "x86_64-windows" ];
|
||||
|
|
|
@ -80,6 +80,12 @@
|
|||
githubId = 791309;
|
||||
name = "Jan Hrnko";
|
||||
};
|
||||
_1000teslas = {
|
||||
name = "Kevin Tran";
|
||||
email = "47207223+1000teslas@users.noreply.github.com";
|
||||
github = "1000teslas";
|
||||
githubId = 47207223;
|
||||
};
|
||||
_3699n = {
|
||||
email = "nicholas@nvk.pm";
|
||||
github = "3699n";
|
||||
|
@ -348,6 +354,12 @@
|
|||
githubId = 4732885;
|
||||
name = "Ivan Jager";
|
||||
};
|
||||
airwoodix = {
|
||||
email = "airwoodix@posteo.me";
|
||||
github = "airwoodix";
|
||||
githubId = 44871469;
|
||||
name = "Etienne Wodey";
|
||||
};
|
||||
ajs124 = {
|
||||
email = "nix@ajs124.de";
|
||||
github = "ajs124";
|
||||
|
@ -526,6 +538,16 @@
|
|||
fingerprint = "B422 CFB1 C9EF 73F7 E1E2 698D F53E 3233 42F7 A6D3A";
|
||||
}];
|
||||
};
|
||||
alyaeanyx = {
|
||||
email = "alexandra.hollmeier@mailbox.org";
|
||||
github = "alyaeanyx";
|
||||
githubId = 74795488;
|
||||
name = "Alexandra Hollmeier";
|
||||
keys = [{
|
||||
longkeyid = "rsa3072/0x87D1AADCD25B8DEE";
|
||||
fingerprint = "1F73 8879 5E5A 3DFC E2B3 FA32 87D1 AADC D25B 8DEE";
|
||||
}];
|
||||
};
|
||||
amanjeev = {
|
||||
email = "aj@amanjeev.com";
|
||||
github = "amanjeev";
|
||||
|
@ -1318,6 +1340,12 @@
|
|||
githubId = 7346933;
|
||||
name = "betaboon";
|
||||
};
|
||||
bew = {
|
||||
email = "benoit.dechezelles@gmail.com";
|
||||
github = "bew";
|
||||
githubId = 9730330;
|
||||
name = "Benoit de Chezelles";
|
||||
};
|
||||
bfortz = {
|
||||
email = "bernard.fortz@gmail.com";
|
||||
github = "bfortz";
|
||||
|
@ -1508,12 +1536,6 @@
|
|||
githubId = 355401;
|
||||
name = "Brian Hicks";
|
||||
};
|
||||
bricewge = {
|
||||
email = "bricewge@gmail.com";
|
||||
github = "bricewge";
|
||||
githubId = 5525646;
|
||||
name = "Brice Waegeneire";
|
||||
};
|
||||
Br1ght0ne = {
|
||||
email = "brightone@protonmail.com";
|
||||
github = "Br1ght0ne";
|
||||
|
@ -1671,6 +1693,12 @@
|
|||
githubId = 7435854;
|
||||
name = "Victor Calvert";
|
||||
};
|
||||
cameronnemo = {
|
||||
email = "cnemo@tutanota.com";
|
||||
github = "cameronnemo";
|
||||
githubId = 3212452;
|
||||
name = "Cameron Nemo";
|
||||
};
|
||||
campadrenalin = {
|
||||
email = "campadrenalin@gmail.com";
|
||||
github = "campadrenalin";
|
||||
|
@ -2257,6 +2285,12 @@
|
|||
githubId = 1382175;
|
||||
name = "Oliver Matthews";
|
||||
};
|
||||
cyounkins = {
|
||||
name = "Craig Younkins";
|
||||
email = "cyounkins@gmail.com";
|
||||
github = "cyounkins";
|
||||
githubId = 346185;
|
||||
};
|
||||
cypherpunk2140 = {
|
||||
email = "stefan.mihaila@pm.me";
|
||||
github = "stefan-mihaila";
|
||||
|
@ -3621,6 +3655,12 @@
|
|||
fingerprint = "2F93 661D AC17 EA98 A104 F780 ECC7 55EE 583C 1672";
|
||||
}];
|
||||
};
|
||||
flexagoon = {
|
||||
email = "flexagoon@pm.me";
|
||||
github = "flexagoon";
|
||||
githubId = 66178592;
|
||||
name = "Pavel Zolotarevskiy";
|
||||
};
|
||||
flexw = {
|
||||
email = "felix.weilbach@t-online.de";
|
||||
github = "FlexW";
|
||||
|
@ -5478,6 +5518,12 @@
|
|||
githubId = 66669;
|
||||
name = "Jeff Zellner";
|
||||
};
|
||||
k4leg = {
|
||||
name = "k4leg";
|
||||
email = "python.bogdan@gmail.com";
|
||||
github = "k4leg";
|
||||
githubId = 39882583;
|
||||
};
|
||||
kaction = {
|
||||
name = "Dmitry Bogatov";
|
||||
email = "KAction@disroot.org";
|
||||
|
@ -6700,6 +6746,12 @@
|
|||
githubId = 775189;
|
||||
name = "Jordi Masip";
|
||||
};
|
||||
MaskedBelgian = {
|
||||
email = "michael.colicchia@imio.be";
|
||||
github = "MaskedBelgian";
|
||||
githubId = 29855073;
|
||||
name = "Michael Colicchia";
|
||||
};
|
||||
matdsoupe = {
|
||||
github = "matdsoupe";
|
||||
githubId = 44469426;
|
||||
|
@ -7451,6 +7503,16 @@
|
|||
name = "Maxim Schuwalow";
|
||||
email = "maxim.schuwalow@gmail.com";
|
||||
};
|
||||
msfjarvis = {
|
||||
github = "msfjarvis";
|
||||
githubId = 3348378;
|
||||
name = "Harsh Shandilya";
|
||||
email = "nixos@msfjarvis.dev";
|
||||
keys = [{
|
||||
longkeyid = "rsa4096/0xB7843F823355E9B9";
|
||||
fingerprint = "8F87 050B 0F9C B841 1515 7399 B784 3F82 3355 E9B9";
|
||||
}];
|
||||
};
|
||||
msiedlarek = {
|
||||
email = "mikolaj@siedlarek.pl";
|
||||
github = "msiedlarek";
|
||||
|
@ -7655,6 +7717,12 @@
|
|||
githubId = 2590830;
|
||||
name = "Sage Raflik";
|
||||
};
|
||||
neosimsim = {
|
||||
email = "me@abn.sh";
|
||||
github = "neosimsim";
|
||||
githubId = 1771772;
|
||||
name = "Alexander Ben Nasrallah";
|
||||
};
|
||||
nequissimus = {
|
||||
email = "tim@nequissimus.com";
|
||||
github = "nequissimus";
|
||||
|
@ -8520,7 +8588,7 @@
|
|||
githubId = 1719781;
|
||||
name = "Pablo Ovelleiro Corral";
|
||||
keys = [{
|
||||
longkeyid = "sa4096/0x823A6154426408D3";
|
||||
longkeyid = "rsa4096/0x823A6154426408D3";
|
||||
fingerprint = "D03B 218C AE77 1F77 D7F9 20D9 823A 6154 4264 08D3";
|
||||
}];
|
||||
};
|
||||
|
@ -8778,6 +8846,12 @@
|
|||
githubId = 33375;
|
||||
name = "Peter Sanford";
|
||||
};
|
||||
pshirshov = {
|
||||
email = "pshirshov@eml.cc";
|
||||
github = "pshirshov";
|
||||
githubId = 295225;
|
||||
name = "Pavel Shirshov";
|
||||
};
|
||||
psibi = {
|
||||
email = "sibi@psibi.in";
|
||||
github = "psibi";
|
||||
|
@ -9532,6 +9606,12 @@
|
|||
github = "s1341";
|
||||
githubId = 5682183;
|
||||
};
|
||||
samalws = {
|
||||
email = "sam@samalws.com";
|
||||
name = "Sam Alws";
|
||||
github = "samalws";
|
||||
githubId = 20981725;
|
||||
};
|
||||
samb96 = {
|
||||
email = "samb96@gmail.com";
|
||||
github = "samb96";
|
||||
|
@ -9566,6 +9646,12 @@
|
|||
githubId = 115821;
|
||||
name = "Sam Rose";
|
||||
};
|
||||
samuela = {
|
||||
email = "skainsworth@gmail.com";
|
||||
github = "samuela";
|
||||
githubId = 226872;
|
||||
name = "Samuel Ainsworth";
|
||||
};
|
||||
samueldr = {
|
||||
email = "samuel@dionne-riel.com";
|
||||
github = "samueldr";
|
||||
|
@ -10256,6 +10342,12 @@
|
|||
githubId = 8668915;
|
||||
name = "Stephane Schitter";
|
||||
};
|
||||
staccato = {
|
||||
name = "staccato";
|
||||
email = "moveq@riseup.net";
|
||||
github = "staccato";
|
||||
githubId = 86573128;
|
||||
};
|
||||
steell = {
|
||||
email = "steve@steellworks.com";
|
||||
github = "Steell";
|
||||
|
@ -11030,6 +11122,12 @@
|
|||
githubId = 10110;
|
||||
name = "Travis B. Hartwell";
|
||||
};
|
||||
travisdavis-ops = {
|
||||
email = "travisdavismedia@gmail.com";
|
||||
github = "travisdavis-ops";
|
||||
githubId = 52011418;
|
||||
name = "Travis Davis";
|
||||
};
|
||||
TredwellGit = {
|
||||
email = "tredwell@tutanota.com";
|
||||
github = "TredwellGit";
|
||||
|
@ -11287,10 +11385,14 @@
|
|||
name = "Jos van den Oever";
|
||||
};
|
||||
vanilla = {
|
||||
email = "neko@hydev.org";
|
||||
email = "osu_vanilla@126.com";
|
||||
github = "VergeDX";
|
||||
githubId = 25173827;
|
||||
name = "Vanilla";
|
||||
keys = [{
|
||||
longkeyid = "rsa4096/0x4DFA2BDD7305E739";
|
||||
fingerprint = "5C16 5178 7DE2 EE5A AF98 3EA3 4DFA 2BDD 7305 E739";
|
||||
}];
|
||||
};
|
||||
vanschelven = {
|
||||
email = "klaas@vanschelven.com";
|
||||
|
@ -11742,6 +11844,12 @@
|
|||
githubId = 3992240;
|
||||
name = "Elijah Rum";
|
||||
};
|
||||
x3ro = {
|
||||
name = "^x3ro";
|
||||
email = "nix@x3ro.dev";
|
||||
github = "x3rAx";
|
||||
githubId = 2268851;
|
||||
};
|
||||
xaverdh = {
|
||||
email = "hoe.dom@gmx.de";
|
||||
github = "xaverdh";
|
||||
|
|
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
|
|
@ -1,89 +1,86 @@
|
|||
name,server,version,luaversion,maintainers
|
||||
alt-getopt,,,,arobyn
|
||||
ansicolors,,,,
|
||||
bit32,,5.3.0-1,lua5_1,lblasc
|
||||
argparse,,,,
|
||||
basexx,,,,
|
||||
binaryheap,,,,vcunat
|
||||
busted,,,,
|
||||
cassowary,,,,marsam alerque
|
||||
compat53,,0.7-1,,vcunat
|
||||
cosmo,,,,marsam
|
||||
coxpcall,,1.17.0-1,,
|
||||
cqueues,,,,vcunat
|
||||
cyrussasl,,,,
|
||||
digestif,,0.2-1,lua5_3,
|
||||
dkjson,,,,
|
||||
fifo,,,,
|
||||
gitsigns.nvim,,,lua5_1,
|
||||
http,,0.3-0,,vcunat
|
||||
inspect,,,,
|
||||
ldbus,http://luarocks.org/dev,,,
|
||||
ldoc,,,,
|
||||
lgi,,,,
|
||||
linenoise,,,,
|
||||
ljsyscall,,,lua5_1,lblasc
|
||||
lpeg,,,,vyp
|
||||
lpeg_patterns,,,,
|
||||
lpeglabel,,,,
|
||||
lpty,,,,
|
||||
lrexlib-gnu,,,,
|
||||
lrexlib-pcre,,,,vyp
|
||||
lrexlib-posix,,,,
|
||||
ltermbox,,,,
|
||||
lua-cjson,,,,
|
||||
lua-cmsgpack,,,,
|
||||
lua-iconv,,,,
|
||||
lua-lsp,http://luarocks.org/dev,,,
|
||||
lua-messagepack,,,,
|
||||
lua-resty-http,,,,
|
||||
lua-resty-jwt,,,,
|
||||
lua-resty-openidc,,,,
|
||||
lua-resty-openssl,,,,
|
||||
lua-resty-session,,,,
|
||||
lua-term,,,,
|
||||
lua-toml,,,,
|
||||
lua-zlib,,,,koral
|
||||
lua_cliargs,,,,
|
||||
luabitop,,,,
|
||||
luacheck,,,,
|
||||
luacov,,,,
|
||||
luadbi,,,,
|
||||
luadbi-mysql,,,,
|
||||
luadbi-postgresql,,,,
|
||||
luadbi-sqlite3,,,,
|
||||
luadoc,,,,
|
||||
luaepnf,,,,
|
||||
luaevent,,,,
|
||||
luaexpat,,1.3.0-1,,arobyn flosse
|
||||
luaffi,http://luarocks.org/dev,,,
|
||||
luafilesystem,,1.7.0-2,,flosse
|
||||
lualogging,,,,
|
||||
luaossl,,,lua5_1,
|
||||
luaposix,,34.1.1-1,,vyp lblasc
|
||||
luarepl,,,,
|
||||
luasec,,,,flosse
|
||||
luasocket,,,,
|
||||
luasql-sqlite3,,,,vyp
|
||||
luassert,,,,
|
||||
luasystem,,,,
|
||||
luautf8,,,,pstn
|
||||
luazip,,,,
|
||||
lua-yajl,,,,pstn
|
||||
luuid,,,,
|
||||
luv,,1.30.0-0,,
|
||||
lyaml,,,,lblasc
|
||||
markdown,,,,
|
||||
mediator_lua,,,,
|
||||
mpack,,,,
|
||||
moonscript,,,,arobyn
|
||||
nvim-client,,,,
|
||||
penlight,,,,
|
||||
plenary.nvim,,,lua5_1,
|
||||
rapidjson,,,,
|
||||
readline,,,,
|
||||
say,,,,
|
||||
std._debug,,,,
|
||||
std.normalize,,,,
|
||||
stdlib,,,,vyp
|
||||
vstruct,,,,
|
||||
name,src,ref,server,version,luaversion,maintainers
|
||||
alt-getopt,,,,,,arobyn
|
||||
bit32,,,,5.3.0-1,lua5_1,lblasc
|
||||
argparse,https://github.com/luarocks/argparse.git,,,,,
|
||||
basexx,https://github.com/teto/basexx.git,,,,,
|
||||
binaryheap,https://github.com/Tieske/binaryheap.lua,,,,,vcunat
|
||||
busted,,,,,,
|
||||
cassowary,,,,,,marsam alerque
|
||||
compat53,,,,0.7-1,,vcunat
|
||||
cosmo,,,,,,marsam
|
||||
coxpcall,,,,1.17.0-1,,
|
||||
cqueues,,,,,,vcunat
|
||||
cyrussasl,https://github.com/JorjBauer/lua-cyrussasl.git,,,,,
|
||||
digestif,https://github.com/astoff/digestif.git,,,0.2-1,lua5_3,
|
||||
dkjson,,,,,,
|
||||
fifo,,,,,,
|
||||
gitsigns.nvim,https://github.com/lewis6991/gitsigns.nvim.git,,,,lua5_1,
|
||||
http,,,,0.3-0,,vcunat
|
||||
inspect,,,,,,
|
||||
ldbus,,,http://luarocks.org/dev,,,
|
||||
ldoc,https://github.com/stevedonovan/LDoc.git,,,,,
|
||||
lgi,,,,,,
|
||||
linenoise,https://github.com/hoelzro/lua-linenoise.git,,,,,
|
||||
ljsyscall,,,,,lua5_1,lblasc
|
||||
lpeg,,,,,,vyp
|
||||
lpeg_patterns,,,,,,
|
||||
lpeglabel,,,,,,
|
||||
lpty,,,,,,
|
||||
lrexlib-gnu,,,,,,
|
||||
lrexlib-pcre,,,,,,vyp
|
||||
lrexlib-posix,,,,,,
|
||||
lua-cjson,,,,,,
|
||||
lua-cmsgpack,,,,,,
|
||||
lua-iconv,,,,,,
|
||||
lua-lsp,,,,,,
|
||||
lua-messagepack,,,,,,
|
||||
lua-resty-http,,,,,,
|
||||
lua-resty-jwt,,,,,,
|
||||
lua-resty-openidc,,,,,,
|
||||
lua-resty-openssl,,,,,,
|
||||
lua-resty-session,,,,,,
|
||||
lua-term,,,,,,
|
||||
lua-toml,,,,,,
|
||||
lua-zlib,,,,,,koral
|
||||
lua_cliargs,https://github.com/amireh/lua_cliargs.git,,,,,
|
||||
luabitop,https://github.com/teto/luabitop.git,,,,,
|
||||
luacheck,,,,,,
|
||||
luacov,,,,,,
|
||||
luadbi,,,,,,
|
||||
luadbi-mysql,,,,,,
|
||||
luadbi-postgresql,,,,,,
|
||||
luadbi-sqlite3,,,,,,
|
||||
luaepnf,,,,,,
|
||||
luaevent,,,,,,
|
||||
luaexpat,,,,1.3.0-1,,arobyn flosse
|
||||
luaffi,,,http://luarocks.org/dev,,,
|
||||
luafilesystem,,,,1.7.0-2,,flosse
|
||||
lualogging,,,,,,
|
||||
luaossl,,,,,lua5_1,
|
||||
luaposix,,,,34.1.1-1,,vyp lblasc
|
||||
luarepl,,,,,,
|
||||
luasec,,,,,,flosse
|
||||
luasocket,,,,,,
|
||||
luasql-sqlite3,,,,,,vyp
|
||||
luassert,,,,,,
|
||||
luasystem,,,,,,
|
||||
luautf8,,,,,,pstn
|
||||
luazip,,,,,,
|
||||
lua-yajl,,,,,,pstn
|
||||
luuid,,,,,,
|
||||
luv,,,,1.30.0-0,,
|
||||
lyaml,,,,,,lblasc
|
||||
markdown,,,,,,
|
||||
mediator_lua,,,,,,
|
||||
mpack,,,,,,
|
||||
moonscript,,,,,,arobyn
|
||||
nvim-client,https://github.com/neovim/lua-client.git,,,,,
|
||||
penlight,https://github.com/lunarmodules/Penlight.git,,,,,alerque
|
||||
plenary.nvim,https://github.com/nvim-lua/plenary.nvim.git,,,,lua5_1,
|
||||
rapidjson,https://github.com/xpol/lua-rapidjson.git,,,,,
|
||||
readline,,,,,,
|
||||
say,https://github.com/Olivine-Labs/say.git,,,,,
|
||||
std._debug,https://github.com/lua-stdlib/_debug.git,,,,,
|
||||
std.normalize,git://github.com/lua-stdlib/normalize.git,,,,,
|
||||
stdlib,,,,41.2.2,,vyp
|
||||
vstruct,https://github.com/ToxicFrog/vstruct.git,,,,,
|
||||
|
|
|
|
@ -547,7 +547,6 @@ def update_plugins(editor: Editor, args):
|
|||
|
||||
log.setLevel(LOG_LEVELS[args.debug])
|
||||
log.info("Start updating plugins")
|
||||
nixpkgs_repo = git.Repo(editor.root, search_parent_directories=True)
|
||||
update = editor.get_update(args.input_file, args.outfile, args.proc)
|
||||
|
||||
redirects = update()
|
||||
|
@ -556,6 +555,7 @@ def update_plugins(editor: Editor, args):
|
|||
autocommit = not args.no_commit
|
||||
|
||||
if autocommit:
|
||||
nixpkgs_repo = git.Repo(editor.root, search_parent_directories=True)
|
||||
commit(nixpkgs_repo, f"{editor.attr_path}: update", [args.outfile])
|
||||
|
||||
if redirects:
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
#!/usr/bin/env nix-shell
|
||||
#!nix-shell -p nix-prefetch-git luarocks-nix python3 python3Packages.GitPython nix -i python3
|
||||
#!nix-shell update-luarocks-shell.nix -i python3
|
||||
|
||||
# format:
|
||||
# $ nix run nixpkgs.python3Packages.black -c black update.py
|
||||
|
@ -19,7 +19,7 @@ import logging
|
|||
import textwrap
|
||||
from multiprocessing.dummy import Pool
|
||||
|
||||
from typing import List, Tuple
|
||||
from typing import List, Tuple, Optional
|
||||
from pathlib import Path
|
||||
|
||||
log = logging.getLogger()
|
||||
|
@ -50,10 +50,21 @@ FOOTER="""
|
|||
@dataclass
|
||||
class LuaPlugin:
|
||||
name: str
|
||||
version: str
|
||||
server: str
|
||||
luaversion: str
|
||||
maintainers: str
|
||||
'''Name of the plugin, as seen on luarocks.org'''
|
||||
src: str
|
||||
'''address to the git repository'''
|
||||
ref: Optional[str]
|
||||
'''git reference (branch name/tag)'''
|
||||
version: Optional[str]
|
||||
'''Set it to pin a package '''
|
||||
server: Optional[str]
|
||||
'''luarocks.org registers packages under different manifests.
|
||||
Its value can be 'http://luarocks.org/dev'
|
||||
'''
|
||||
luaversion: Optional[str]
|
||||
'''Attribue of the lua interpreter if a package is available only for a specific lua version'''
|
||||
maintainers: Optional[str]
|
||||
''' Optional string listing maintainers separated by spaces'''
|
||||
|
||||
@property
|
||||
def normalized_name(self) -> str:
|
||||
|
@ -149,16 +160,33 @@ def generate_pkg_nix(plug: LuaPlugin):
|
|||
Our cache key associates "p.name-p.version" to its rockspec
|
||||
'''
|
||||
log.debug("Generating nix expression for %s", plug.name)
|
||||
cmd = [ "luarocks", "nix", plug.name]
|
||||
cmd = [ "luarocks", "nix"]
|
||||
|
||||
if plug.server:
|
||||
cmd.append(f"--only-server={plug.server}")
|
||||
|
||||
if plug.maintainers:
|
||||
cmd.append(f"--maintainers={plug.maintainers}")
|
||||
|
||||
if plug.version:
|
||||
cmd.append(plug.version)
|
||||
# updates plugin directly from its repository
|
||||
print("server: [%s]" % plug.server)
|
||||
# if plug.server == "src":
|
||||
if plug.src != "":
|
||||
if plug.src is None:
|
||||
msg = "src must be set when 'version' is set to \"src\" for package %s" % plug.name
|
||||
log.error(msg)
|
||||
raise RuntimeError(msg)
|
||||
log.debug("Updating from source %s", plug.src)
|
||||
cmd.append(plug.src)
|
||||
# update the plugin from luarocks
|
||||
else:
|
||||
cmd.append(plug.name)
|
||||
if plug.version and plug.version != "src":
|
||||
|
||||
cmd.append(plug.version)
|
||||
|
||||
#
|
||||
if plug.server != "src" and plug.server:
|
||||
cmd.append(f"--only-server={plug.server}")
|
||||
|
||||
|
||||
if plug.luaversion:
|
||||
with CleanEnvironment():
|
||||
|
@ -169,7 +197,7 @@ def generate_pkg_nix(plug: LuaPlugin):
|
|||
lua_drv_path=subprocess.check_output(cmd2, text=True).strip()
|
||||
cmd.append(f"--lua-dir={lua_drv_path}/bin")
|
||||
|
||||
log.debug("running %s", cmd)
|
||||
log.debug("running %s", ' '.join(cmd))
|
||||
output = subprocess.check_output(cmd, text=True)
|
||||
return (plug, output)
|
||||
|
||||
|
@ -191,3 +219,4 @@ if __name__ == "__main__":
|
|||
|
||||
main()
|
||||
|
||||
# vim: set ft=python noet fdm=manual fenc=utf-8 ff=unix sts=0 sw=4 ts=4 :
|
||||
|
|
|
@ -1,12 +1,13 @@
|
|||
{ nixpkgs ? import ../.. { }
|
||||
}:
|
||||
with nixpkgs;
|
||||
let
|
||||
pyEnv = python3.withPackages(ps: [ ps.GitPython ]);
|
||||
in
|
||||
mkShell {
|
||||
packages = [
|
||||
bash
|
||||
pyEnv
|
||||
luarocks-nix
|
||||
nix-prefetch-scripts
|
||||
parallel
|
||||
];
|
||||
LUAROCKS_NIXPKGS_PATH = toString nixpkgs.path;
|
||||
}
|
||||
|
|
|
@ -103,7 +103,7 @@ let
|
|||
pathContent = lib.attrByPath prefix null pkgs;
|
||||
in
|
||||
if pathContent == null then
|
||||
builtins.throw "Attribute path `${path}` does not exists."
|
||||
builtins.throw "Attribute path `${path}` does not exist."
|
||||
else
|
||||
packagesWithPath prefix (path: pkg: builtins.hasAttr "updateScript" pkg)
|
||||
pathContent;
|
||||
|
@ -115,7 +115,7 @@ let
|
|||
package = lib.attrByPath (lib.splitString "." path) null pkgs;
|
||||
in
|
||||
if package == null then
|
||||
builtins.throw "Package with an attribute name `${path}` does not exists."
|
||||
builtins.throw "Package with an attribute name `${path}` does not exist."
|
||||
else if ! builtins.hasAttr "updateScript" package then
|
||||
builtins.throw "Package with an attribute name `${path}` does not have a `passthru.updateScript` attribute defined."
|
||||
else
|
||||
|
|
|
@ -178,6 +178,15 @@ with lib.maintainers; {
|
|||
scope = "Maintain the ecosystem around Matrix, a decentralized messenger.";
|
||||
};
|
||||
|
||||
openstack = {
|
||||
members = [
|
||||
angustrau
|
||||
superherointj
|
||||
SuperSandro2000
|
||||
];
|
||||
scope = "Maintain the ecosystem around OpenStack";
|
||||
};
|
||||
|
||||
pantheon = {
|
||||
members = [
|
||||
davidak
|
||||
|
|
|
@ -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
nixos/doc/manual/administration/containers.chapter.md
Normal file
28
nixos/doc/manual/administration/containers.chapter.md
Normal file
|
@ -0,0 +1,28 @@
|
|||
# Container Management {#ch-containers}
|
||||
|
||||
NixOS allows you to easily run other NixOS instances as *containers*.
|
||||
Containers are a light-weight approach to virtualisation that runs
|
||||
software in the container at the same speed as in the host system. NixOS
|
||||
containers share the Nix store of the host, making container creation
|
||||
very efficient.
|
||||
|
||||
::: {.warning}
|
||||
Currently, NixOS containers are not perfectly isolated from the host
|
||||
system. This means that a user with root access to the container can do
|
||||
things that affect the host. So you should not give container root
|
||||
access to untrusted users.
|
||||
:::
|
||||
|
||||
NixOS containers can be created in two ways: imperatively, using the
|
||||
command `nixos-container`, and declaratively, by specifying them in your
|
||||
`configuration.nix`. The declarative approach implies that containers
|
||||
get upgraded along with your host system when you run `nixos-rebuild`,
|
||||
which is often not what you want. By contrast, in the imperative
|
||||
approach, containers are configured and updated independently from the
|
||||
host system.
|
||||
|
||||
```{=docbook}
|
||||
<xi:include href="imperative-containers.section.xml" />
|
||||
<xi:include href="declarative-containers.section.xml" />
|
||||
<xi:include href="container-networking.section.xml" />
|
||||
```
|
|
@ -1,34 +0,0 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="ch-containers">
|
||||
<title>Container Management</title>
|
||||
<para>
|
||||
NixOS allows you to easily run other NixOS instances as
|
||||
<emphasis>containers</emphasis>. Containers are a light-weight approach to
|
||||
virtualisation that runs software in the container at the same speed as in
|
||||
the host system. NixOS containers share the Nix store of the host, making
|
||||
container creation very efficient.
|
||||
</para>
|
||||
<warning>
|
||||
<para>
|
||||
Currently, NixOS containers are not perfectly isolated from the host system.
|
||||
This means that a user with root access to the container can do things that
|
||||
affect the host. So you should not give container root access to untrusted
|
||||
users.
|
||||
</para>
|
||||
</warning>
|
||||
<para>
|
||||
NixOS containers can be created in two ways: imperatively, using the command
|
||||
<command>nixos-container</command>, and declaratively, by specifying them in
|
||||
your <filename>configuration.nix</filename>. The declarative approach implies
|
||||
that containers get upgraded along with your host system when you run
|
||||
<command>nixos-rebuild</command>, which is often not what you want. By
|
||||
contrast, in the imperative approach, containers are configured and updated
|
||||
independently from the host system.
|
||||
</para>
|
||||
<xi:include href="imperative-containers.xml" />
|
||||
<xi:include href="declarative-containers.xml" />
|
||||
<xi:include href="container-networking.xml" />
|
||||
</chapter>
|
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="containers.xml" />
|
||||
<xi:include href="troubleshooting.xml" />
|
||||
<xi:include href="../from_md/administration/service-mgmt.chapter.xml" />
|
||||
<xi:include href="../from_md/administration/rebooting.chapter.xml" />
|
||||
<xi:include href="../from_md/administration/user-sessions.chapter.xml" />
|
||||
<xi:include href="../from_md/administration/control-groups.chapter.xml" />
|
||||
<xi:include href="../from_md/administration/logging.chapter.xml" />
|
||||
<xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
|
||||
<xi:include href="../from_md/administration/containers.chapter.xml" />
|
||||
<xi:include href="../from_md/administration/troubleshooting.chapter.xml" />
|
||||
</part>
|
||||
|
|
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>
|
12
nixos/doc/manual/administration/troubleshooting.chapter.md
Normal file
12
nixos/doc/manual/administration/troubleshooting.chapter.md
Normal file
|
@ -0,0 +1,12 @@
|
|||
# Troubleshooting {#ch-troubleshooting}
|
||||
|
||||
This chapter describes solutions to common problems you might encounter
|
||||
when you manage your NixOS system.
|
||||
|
||||
```{=docbook}
|
||||
<xi:include href="boot-problems.section.xml" />
|
||||
<xi:include href="maintenance-mode.section.xml" />
|
||||
<xi:include href="rollback.section.xml" />
|
||||
<xi:include href="store-corruption.section.xml" />
|
||||
<xi:include href="network-problems.section.xml" />
|
||||
```
|
|
@ -1,16 +0,0 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="ch-troubleshooting">
|
||||
<title>Troubleshooting</title>
|
||||
<para>
|
||||
This chapter describes solutions to common problems you might encounter when
|
||||
you manage your NixOS system.
|
||||
</para>
|
||||
<xi:include href="../from_md/administration/boot-problems.section.xml" />
|
||||
<xi:include href="maintenance-mode.xml" />
|
||||
<xi:include href="rollback.xml" />
|
||||
<xi:include href="store-corruption.xml" />
|
||||
<xi:include href="network-problems.xml" />
|
||||
</chapter>
|
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>
|
19
nixos/doc/manual/configuration/config-syntax.chapter.md
Normal file
19
nixos/doc/manual/configuration/config-syntax.chapter.md
Normal file
|
@ -0,0 +1,19 @@
|
|||
# Configuration Syntax {#sec-configuration-syntax}
|
||||
|
||||
The NixOS configuration file `/etc/nixos/configuration.nix` is actually
|
||||
a *Nix expression*, which is the Nix package manager's purely functional
|
||||
language for describing how to build packages and configurations. This
|
||||
means you have all the expressive power of that language at your
|
||||
disposal, including the ability to abstract over common patterns, which
|
||||
is very useful when managing complex systems. The syntax and semantics
|
||||
of the Nix language are fully described in the [Nix
|
||||
manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions), but
|
||||
here we give a short overview of the most important constructs useful in
|
||||
NixOS configuration files.
|
||||
|
||||
```{=docbook}
|
||||
<xi:include href="config-file.section.xml" />
|
||||
<xi:include href="abstractions.section.xml" />
|
||||
<xi:include href="modularity.section.xml" />
|
||||
<xi:include href="summary.section.xml" />
|
||||
```
|
|
@ -1,25 +0,0 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-configuration-syntax">
|
||||
<title>Configuration Syntax</title>
|
||||
<para>
|
||||
The NixOS configuration file
|
||||
<filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix
|
||||
expression</emphasis>, which is the Nix package manager’s purely functional
|
||||
language for describing how to build packages and configurations. This means
|
||||
you have all the expressive power of that language at your disposal,
|
||||
including the ability to abstract over common patterns, which is very useful
|
||||
when managing complex systems. The syntax and semantics of the Nix language
|
||||
are fully described in the
|
||||
<link
|
||||
xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
|
||||
manual</link>, but here we give a short overview of the most important
|
||||
constructs useful in NixOS configuration files.
|
||||
</para>
|
||||
<xi:include href="config-file.xml" />
|
||||
<xi:include href="../from_md/configuration/abstractions.section.xml" />
|
||||
<xi:include href="modularity.xml" />
|
||||
<xi:include href="summary.xml" />
|
||||
</chapter>
|
|
@ -13,19 +13,19 @@
|
|||
effect after you run <command>nixos-rebuild</command>.
|
||||
</para>
|
||||
</partintro>
|
||||
<xi:include href="config-syntax.xml" />
|
||||
<xi:include href="package-mgmt.xml" />
|
||||
<xi:include href="user-mgmt.xml" />
|
||||
<xi:include href="file-systems.xml" />
|
||||
<xi:include href="x-windows.xml" />
|
||||
<xi:include href="wayland.xml" />
|
||||
<xi:include href="gpu-accel.xml" />
|
||||
<xi:include href="xfce.xml" />
|
||||
<xi:include href="networking.xml" />
|
||||
<xi:include href="linux-kernel.xml" />
|
||||
<xi:include href="subversion.xml" />
|
||||
<xi:include href="../from_md/configuration/config-syntax.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/package-mgmt.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/file-systems.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/x-windows.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/wayland.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/xfce.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/networking.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/subversion.chapter.xml" />
|
||||
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
|
||||
<xi:include href="profiles.xml" />
|
||||
<xi:include href="kubernetes.xml" />
|
||||
<xi:include href="../from_md/configuration/profiles.chapter.xml" />
|
||||
<xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
|
||||
<!-- Apache; libvirtd virtualisation -->
|
||||
</part>
|
||||
|
|
|
@ -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>
|
|
@ -0,0 +1,46 @@
|
|||
# Declarative Package Management {#sec-declarative-package-mgmt}
|
||||
|
||||
With declarative package management, you specify which packages you want
|
||||
on your system by setting the option
|
||||
[](#opt-environment.systemPackages). For instance, adding the
|
||||
following line to `configuration.nix` enables the Mozilla Thunderbird
|
||||
email application:
|
||||
|
||||
```nix
|
||||
environment.systemPackages = [ pkgs.thunderbird ];
|
||||
```
|
||||
|
||||
The effect of this specification is that the Thunderbird package from
|
||||
Nixpkgs will be built or downloaded as part of the system when you run
|
||||
`nixos-rebuild switch`.
|
||||
|
||||
::: {.note}
|
||||
Some packages require additional global configuration such as D-Bus or
|
||||
systemd service registration so adding them to
|
||||
[](#opt-environment.systemPackages) might not be sufficient. You are
|
||||
advised to check the [list of options](#ch-options) whether a NixOS
|
||||
module for the package does not exist.
|
||||
:::
|
||||
|
||||
You can get a list of the available packages as follows:
|
||||
|
||||
```ShellSession
|
||||
$ nix-env -qaP '*' --description
|
||||
nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
|
||||
...
|
||||
```
|
||||
|
||||
The first column in the output is the *attribute name*, such as
|
||||
`nixos.thunderbird`.
|
||||
|
||||
Note: the `nixos` prefix tells us that we want to get the package from
|
||||
the `nixos` channel and works only in CLI tools. In declarative
|
||||
configuration use `pkgs` prefix (variable).
|
||||
|
||||
To "uninstall" a package, simply remove it from
|
||||
[](#opt-environment.systemPackages) and run `nixos-rebuild switch`.
|
||||
|
||||
```{=docbook}
|
||||
<xi:include href="customizing-packages.section.xml" />
|
||||
<xi:include href="adding-custom-packages.section.xml" />
|
||||
```
|
|
@ -1,54 +0,0 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-declarative-package-mgmt">
|
||||
<title>Declarative Package Management</title>
|
||||
|
||||
<para>
|
||||
With declarative package management, you specify which packages you want on
|
||||
your system by setting the option
|
||||
<xref linkend="opt-environment.systemPackages"/>. For instance, adding the
|
||||
following line to <filename>configuration.nix</filename> enables the Mozilla
|
||||
Thunderbird email application:
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
|
||||
</programlisting>
|
||||
The effect of this specification is that the Thunderbird package from Nixpkgs
|
||||
will be built or downloaded as part of the system when you run
|
||||
<command>nixos-rebuild switch</command>.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Some packages require additional global configuration such as D-Bus or systemd service registration so adding them to <xref linkend="opt-environment.systemPackages"/> might not be sufficient. You are advised to check the <link xlink:href="#ch-options">list of options</link> whether a NixOS module for the package does not exist.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
You can get a list of the available packages as follows:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-env -qaP '*' --description
|
||||
nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
|
||||
<replaceable>...</replaceable>
|
||||
</screen>
|
||||
The first column in the output is the <emphasis>attribute name</emphasis>,
|
||||
such as <literal>nixos.thunderbird</literal>.
|
||||
</para>
|
||||
<para>
|
||||
Note: the <literal>nixos</literal> prefix tells us that we want to get the
|
||||
package from the <literal>nixos</literal> channel and works only in CLI tools.
|
||||
|
||||
In declarative configuration use <literal>pkgs</literal> prefix (variable).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To “uninstall” a package, simply remove it from
|
||||
<xref linkend="opt-environment.systemPackages"/> and run
|
||||
<command>nixos-rebuild switch</command>.
|
||||
</para>
|
||||
|
||||
<xi:include href="customizing-packages.xml" />
|
||||
|
||||
<xi:include href="adding-custom-packages.xml" />
|
||||
</section>
|
42
nixos/doc/manual/configuration/file-systems.chapter.md
Normal file
42
nixos/doc/manual/configuration/file-systems.chapter.md
Normal file
|
@ -0,0 +1,42 @@
|
|||
# File Systems {#ch-file-systems}
|
||||
|
||||
You can define file systems using the `fileSystems` configuration
|
||||
option. For instance, the following definition causes NixOS to mount the
|
||||
Ext4 file system on device `/dev/disk/by-label/data` onto the mount
|
||||
point `/data`:
|
||||
|
||||
```nix
|
||||
fileSystems."/data" =
|
||||
{ device = "/dev/disk/by-label/data";
|
||||
fsType = "ext4";
|
||||
};
|
||||
```
|
||||
|
||||
This will create an entry in `/etc/fstab`, which will generate a
|
||||
corresponding [systemd.mount](https://www.freedesktop.org/software/systemd/man/systemd.mount.html)
|
||||
unit via [systemd-fstab-generator](https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html).
|
||||
The filesystem will be mounted automatically unless `"noauto"` is
|
||||
present in [options](#opt-fileSystems._name_.options). `"noauto"`
|
||||
filesystems can be mounted explicitly using `systemctl` e.g.
|
||||
`systemctl start data.mount`. Mount points are created automatically if they don't
|
||||
already exist. For `device`, it's best to use the topology-independent
|
||||
device aliases in `/dev/disk/by-label` and `/dev/disk/by-uuid`, as these
|
||||
don't change if the topology changes (e.g. if a disk is moved to another
|
||||
IDE controller).
|
||||
|
||||
You can usually omit the file system type (`fsType`), since `mount` can
|
||||
usually detect the type and load the necessary kernel module
|
||||
automatically. However, if the file system is needed at early boot (in
|
||||
the initial ramdisk) and is not `ext2`, `ext3` or `ext4`, then it's best
|
||||
to specify `fsType` to ensure that the kernel module is available.
|
||||
|
||||
::: {.note}
|
||||
System startup will fail if any of the filesystems fails to mount,
|
||||
dropping you to the emergency shell. You can make a mount asynchronous
|
||||
and non-critical by adding `options = [ "nofail" ];`.
|
||||
:::
|
||||
|
||||
```{=docbook}
|
||||
<xi:include href="luks-file-systems.section.xml" />
|
||||
<xi:include href="sshfs-file-systems.section.xml" />
|
||||
```
|
|
@ -1,58 +0,0 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="ch-file-systems">
|
||||
<title>File Systems</title>
|
||||
<para>
|
||||
You can define file systems using the <option>fileSystems</option>
|
||||
configuration option. For instance, the following definition causes NixOS to
|
||||
mount the Ext4 file system on device
|
||||
<filename>/dev/disk/by-label/data</filename> onto the mount point
|
||||
<filename>/data</filename>:
|
||||
<programlisting>
|
||||
<xref linkend="opt-fileSystems"/>."/data" =
|
||||
{ device = "/dev/disk/by-label/data";
|
||||
fsType = "ext4";
|
||||
};
|
||||
</programlisting>
|
||||
This will create an entry in <filename>/etc/fstab</filename>, which will
|
||||
generate a corresponding
|
||||
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.mount.html">systemd.mount</link>
|
||||
unit via
|
||||
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html">systemd-fstab-generator</link>.
|
||||
The filesystem will be mounted automatically unless
|
||||
<literal>"noauto"</literal> is present in <link
|
||||
linkend="opt-fileSystems._name_.options">options</link>.
|
||||
<literal>"noauto"</literal> filesystems can be mounted explicitly using
|
||||
<command>systemctl</command> e.g. <command>systemctl start
|
||||
data.mount</command>.
|
||||
Mount points are created automatically if they don’t already exist. For
|
||||
<option><link linkend="opt-fileSystems._name_.device">device</link></option>,
|
||||
it’s best to use the topology-independent device aliases in
|
||||
<filename>/dev/disk/by-label</filename> and
|
||||
<filename>/dev/disk/by-uuid</filename>, as these don’t change if the
|
||||
topology changes (e.g. if a disk is moved to another IDE controller).
|
||||
</para>
|
||||
<para>
|
||||
You can usually omit the file system type
|
||||
(<option><link linkend="opt-fileSystems._name_.fsType">fsType</link></option>),
|
||||
since <command>mount</command> can usually detect the type and load the
|
||||
necessary kernel module automatically. However, if the file system is needed
|
||||
at early boot (in the initial ramdisk) and is not <literal>ext2</literal>,
|
||||
<literal>ext3</literal> or <literal>ext4</literal>, then it’s best to
|
||||
specify <option>fsType</option> to ensure that the kernel module is
|
||||
available.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
System startup will fail if any of the filesystems fails to mount, dropping
|
||||
you to the emergency shell. You can make a mount asynchronous and
|
||||
non-critical by adding
|
||||
<literal><link linkend="opt-fileSystems._name_.options">options</link> = [
|
||||
"nofail" ];</literal>.
|
||||
</para>
|
||||
</note>
|
||||
<xi:include href="luks-file-systems.xml" />
|
||||
<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>
|
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue