···2121approach, containers are configured and updated independently from the
2222host system.
23232424-```{=docbook}
2525-<xi:include href="imperative-containers.section.xml" />
2626-<xi:include href="declarative-containers.section.xml" />
2727-<xi:include href="container-networking.section.xml" />
2424+```{=include=} sections
2525+imperative-containers.section.md
2626+declarative-containers.section.md
2727+container-networking.section.md
2828```
+14
nixos/doc/manual/administration/running.md
···11+# Administration {#ch-running}
22+33+This chapter describes various aspects of managing a running NixOS system, such as how to use the {command}`systemd` service manager.
44+55+```{=include=} chapters
66+service-mgmt.chapter.md
77+rebooting.chapter.md
88+user-sessions.chapter.md
99+control-groups.chapter.md
1010+logging.chapter.md
1111+cleaning-store.chapter.md
1212+containers.chapter.md
1313+troubleshooting.chapter.md
1414+```
-21
nixos/doc/manual/administration/running.xml
···11-<part xmlns="http://docbook.org/ns/docbook"
22- xmlns:xlink="http://www.w3.org/1999/xlink"
33- xmlns:xi="http://www.w3.org/2001/XInclude"
44- version="5.0"
55- xml:id="ch-running">
66- <title>Administration</title>
77- <partintro xml:id="ch-running-intro">
88- <para>
99- This chapter describes various aspects of managing a running NixOS system,
1010- such as how to use the <command>systemd</command> service manager.
1111- </para>
1212- </partintro>
1313- <xi:include href="../from_md/administration/service-mgmt.chapter.xml" />
1414- <xi:include href="../from_md/administration/rebooting.chapter.xml" />
1515- <xi:include href="../from_md/administration/user-sessions.chapter.xml" />
1616- <xi:include href="../from_md/administration/control-groups.chapter.xml" />
1717- <xi:include href="../from_md/administration/logging.chapter.xml" />
1818- <xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
1919- <xi:include href="../from_md/administration/containers.chapter.xml" />
2020- <xi:include href="../from_md/administration/troubleshooting.chapter.xml" />
2121-</part>
···1111here we give a short overview of the most important constructs useful in
1212NixOS configuration files.
13131414-```{=docbook}
1515-<xi:include href="config-file.section.xml" />
1616-<xi:include href="abstractions.section.xml" />
1717-<xi:include href="modularity.section.xml" />
1414+```{=include=} sections
1515+config-file.section.md
1616+abstractions.section.md
1717+modularity.section.md
1818```
+27
nixos/doc/manual/configuration/configuration.md
···11+# Configuration {#ch-configuration}
22+33+This chapter describes how to configure various aspects of a NixOS machine through the configuration file {file}`/etc/nixos/configuration.nix`. As described in [](#sec-changing-config), changes to this file only take effect after you run {command}`nixos-rebuild`.
44+55+```{=include=} chapters
66+config-syntax.chapter.md
77+package-mgmt.chapter.md
88+user-mgmt.chapter.md
99+file-systems.chapter.md
1010+x-windows.chapter.md
1111+wayland.chapter.md
1212+gpu-accel.chapter.md
1313+xfce.chapter.md
1414+networking.chapter.md
1515+linux-kernel.chapter.md
1616+subversion.chapter.md
1717+```
1818+1919+```{=include=} chapters
2020+@MODULE_CHAPTERS@
2121+```
2222+2323+```{=include=} chapters
2424+profiles.chapter.md
2525+kubernetes.chapter.md
2626+```
2727+<!-- Apache; libvirtd virtualisation -->
-31
nixos/doc/manual/configuration/configuration.xml
···11-<part xmlns="http://docbook.org/ns/docbook"
22- xmlns:xlink="http://www.w3.org/1999/xlink"
33- xmlns:xi="http://www.w3.org/2001/XInclude"
44- version="5.0"
55- xml:id="ch-configuration">
66- <title>Configuration</title>
77- <partintro xml:id="ch-configuration-intro">
88- <para>
99- This chapter describes how to configure various aspects of a NixOS machine
1010- through the configuration file
1111- <filename>/etc/nixos/configuration.nix</filename>. As described in
1212- <xref linkend="sec-changing-config" />, changes to this file only take
1313- effect after you run <command>nixos-rebuild</command>.
1414- </para>
1515- </partintro>
1616- <xi:include href="../from_md/configuration/config-syntax.chapter.xml" />
1717- <xi:include href="../from_md/configuration/package-mgmt.chapter.xml" />
1818- <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />
1919- <xi:include href="../from_md/configuration/file-systems.chapter.xml" />
2020- <xi:include href="../from_md/configuration/x-windows.chapter.xml" />
2121- <xi:include href="../from_md/configuration/wayland.chapter.xml" />
2222- <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />
2323- <xi:include href="../from_md/configuration/xfce.chapter.xml" />
2424- <xi:include href="../from_md/configuration/networking.chapter.xml" />
2525- <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
2626- <xi:include href="../from_md/configuration/subversion.chapter.xml" />
2727- <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
2828- <xi:include href="../from_md/configuration/profiles.chapter.xml" />
2929- <xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
3030-<!-- Apache; libvirtd virtualisation -->
3131-</part>
···4040To "uninstall" a package, simply remove it from
4141[](#opt-environment.systemPackages) and run `nixos-rebuild switch`.
42424343-```{=docbook}
4444-<xi:include href="customizing-packages.section.xml" />
4545-<xi:include href="adding-custom-packages.section.xml" />
4343+```{=include=} sections
4444+customizing-packages.section.md
4545+adding-custom-packages.section.md
4646```
···11+# Development {#ch-development}
22+33+This chapter describes how you can modify and extend NixOS.
44+55+```{=include=} chapters
66+sources.chapter.md
77+writing-modules.chapter.md
88+building-parts.chapter.md
99+bootspec.chapter.md
1010+what-happens-during-a-system-switch.chapter.md
1111+writing-documentation.chapter.md
1212+nixos-tests.chapter.md
1313+testing-installer.chapter.md
1414+```
···55(using Nix) by a testing framework that automatically starts one or more
66virtual machines containing the NixOS system(s) required for the test.
7788-```{=docbook}
99-<xi:include href="writing-nixos-tests.section.xml" />
1010-<xi:include href="running-nixos-tests.section.xml" />
1111-<xi:include href="running-nixos-tests-interactively.section.xml" />
1212-<xi:include href="linking-nixos-tests-to-packages.section.xml" />
88+```{=include=} sections
99+writing-nixos-tests.section.md
1010+running-nixos-tests.section.md
1111+running-nixos-tests-interactively.section.md
1212+linking-nixos-tests-to-packages.section.md
1313```
···4747with our units or the activation script. For this reason, these topics are
4848explained in the next sections.
49495050-```{=docbook}
5151-<xi:include href="unit-handling.section.xml" />
5252-<xi:include href="activation-script.section.xml" />
5050+```{=include=} sections
5151+unit-handling.section.md
5252+activation-script.section.md
5353```
···83838484## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}
85858686-Open the parent XML file and add an `xi:include` element to the list of
8686+Open the parent CommonMark file and add a line to the list of
8787chapters with the file name of the topic that you created. If you
8888created a `section`, you add the file to the `chapter` file. If you created
8989a `chapter`, you add the file to the `part` file.
···470470471471The following options can be used when writing tests.
472472473473-```{=docbook}
474474-<xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/>
473473+```{=include=} options
474474+id-prefix: test-opt-
475475+list-id: test-options-list
476476+source: @NIXOS_TEST_OPTIONS_JSON@
475477```
+11
nixos/doc/manual/installation/installation.md
···11+# Installation {#ch-installation}
22+33+This section describes how to obtain, install, and configure NixOS for first-time use.
44+55+```{=include=} chapters
66+obtaining.chapter.md
77+installing.chapter.md
88+changing-config.chapter.md
99+upgrading.chapter.md
1010+building-nixos.chapter.md
1111+```
···11-<refentry xmlns="http://docbook.org/ns/docbook"
22- xmlns:xlink="http://www.w3.org/1999/xlink"
33- xmlns:xi="http://www.w3.org/2001/XInclude">
44- <refmeta>
55- <refentrytitle><filename>configuration.nix</filename>
66- </refentrytitle><manvolnum>5</manvolnum>
77- <refmiscinfo class="source">NixOS</refmiscinfo>
88-<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
99- </refmeta>
1010- <refnamediv>
1111- <refname><filename>configuration.nix</filename></refname>
1212- <refpurpose>NixOS system configuration specification</refpurpose>
1313- </refnamediv>
1414- <refsection>
1515- <title>Description</title>
1616- <para>
1717- The file <filename>/etc/nixos/configuration.nix</filename> contains the
1818- declarative specification of your NixOS system configuration. The command
1919- <command>nixos-rebuild</command> takes this file and realises the system
2020- configuration specified therein.
2121- </para>
2222- </refsection>
2323- <refsection>
2424- <title>Options</title>
2525- <para>
2626- You can use the following options in <filename>configuration.nix</filename>.
2727- </para>
2828- <xi:include href="./generated/options-db.xml"
2929- xpointer="configuration-variable-list" />
3030- </refsection>
3131-</refentry>
+29-1
nixos/doc/manual/man-pages.xml
···1414 <copyright><year>2007-2022</year><holder>Eelco Dolstra and the Nixpkgs/NixOS contributors</holder>
1515 </copyright>
1616 </info>
1717- <xi:include href="man-configuration.xml" />
1717+ <refentry>
1818+ <refmeta>
1919+ <refentrytitle><filename>configuration.nix</filename>
2020+ </refentrytitle><manvolnum>5</manvolnum>
2121+ <refmiscinfo class="source">NixOS</refmiscinfo>
2222+ <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
2323+ </refmeta>
2424+ <refnamediv>
2525+ <refname><filename>configuration.nix</filename></refname>
2626+ <refpurpose>NixOS system configuration specification</refpurpose>
2727+ </refnamediv>
2828+ <refsection>
2929+ <title>Description</title>
3030+ <para>
3131+ The file <filename>/etc/nixos/configuration.nix</filename> contains the
3232+ declarative specification of your NixOS system configuration. The command
3333+ <command>nixos-rebuild</command> takes this file and realises the system
3434+ configuration specified therein.
3535+ </para>
3636+ </refsection>
3737+ <refsection>
3838+ <title>Options</title>
3939+ <para>
4040+ You can use the following options in <filename>configuration.nix</filename>.
4141+ </para>
4242+ <xi:include href="./generated/options-db.xml"
4343+ xpointer="configuration-variable-list" />
4444+ </refsection>
4545+ </refentry>
1846</reference>
+53
nixos/doc/manual/manual.md
···11+# NixOS Manual {#book-nixos-manual}
22+## Version @NIXOS_VERSION@
33+44+<!--
55+ this is the top-level structure file for the nixos manual.
66+77+ the manual structure extends the nixpkgs commonmark further with include
88+ blocks to allow better organization of input text. there are six types of
99+ include blocks: preface, parts, chapters, sections, appendix, and options.
1010+ each type except `options`` corresponds to the docbook elements of (roughly)
1111+ the same name, and can itself can further include blocks to denote its
1212+ substructure.
1313+1414+ non-`options`` include blocks are fenced code blocks that list a number of
1515+ files to include, in the form
1616+1717+ ```{=include=} <type>
1818+ <file-name-1>
1919+ <file-name-2>
2020+ <...>
2121+ ```
2222+2323+ `options` include blocks do not list file names but contain a list of key-value
2424+ pairs that describe the options to be included and how to convert them into
2525+ elements of the manual output type:
2626+2727+ ```{=include=} options
2828+ id-prefix: <options id prefix>
2929+ list-id: <variable list element id>
3030+ source: <path to options.json>
3131+ ```
3232+3333+-->
3434+3535+```{=include=} preface
3636+preface.md
3737+```
3838+3939+```{=include=} parts
4040+installation/installation.md
4141+configuration/configuration.md
4242+administration/running.md
4343+development/development.md
4444+```
4545+4646+```{=include=} chapters
4747+contributing-to-this-manual.chapter.md
4848+```
4949+5050+```{=include=} appendix
5151+nixos-options.md
5252+release-notes/release-notes.md
5353+```
···11+# Preface {#preface}
22+33+This manual describes how to install, use and extend NixOS, a Linux distribution based on the purely functional package management system [Nix](https://nixos.org/nix), that is composed using modules and packages defined in the [Nixpkgs](https://nixos.org/nixpkgs) project.
44+55+Additional information regarding the Nix package manager and the Nixpkgs project can be found in respectively the [Nix manual](https://nixos.org/nix/manual) and the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).
66+77+If you encounter problems, please report them on the [`Discourse`](https://discourse.nixos.org), the [Matrix room](https://matrix.to/#nix:nixos.org), or on the [`#nixos` channel on Libera.Chat](irc://irc.libera.chat/#nixos). Alternatively, consider [contributing to this manual](#chap-contributing). Bugs should be reported in [NixOS’ GitHub issue tracker](https://github.com/NixOS/nixpkgs/issues).
88+99+::: {.note}
1010+Commands prefixed with `#` have to be run as root, either requiring to login as root user or temporarily switching to it using `sudo` for example.
1111+:::
-42
nixos/doc/manual/preface.xml
···11-<preface xmlns="http://docbook.org/ns/docbook"
22- xmlns:xlink="http://www.w3.org/1999/xlink"
33- xml:id="preface">
44- <title>Preface</title>
55- <para>
66- This manual describes how to install, use and extend NixOS, a Linux
77- distribution based on the purely functional package management system
88- <link xlink:href="https://nixos.org/nix">Nix</link>, that is composed
99- using modules and packages defined in the
1010- <link xlink:href="https://nixos.org/nixpkgs">Nixpkgs</link> project.
1111- </para>
1212- <para>
1313- Additional information regarding the Nix package manager and the Nixpkgs
1414- project can be found in respectively the
1515- <link xlink:href="https://nixos.org/nix/manual">Nix manual</link> and the
1616- <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs manual</link>.
1717- </para>
1818- <para>
1919- If you encounter problems, please report them on the
2020- <literal
2121- xlink:href="https://discourse.nixos.org">Discourse</literal>,
2222- the <link
2323- xlink:href="https://matrix.to/#nix:nixos.org">Matrix room</link>,
2424- or on the <link
2525- xlink:href="irc://irc.libera.chat/#nixos">
2626- <literal>#nixos</literal> channel on Libera.Chat</link>.
2727- Alternatively, consider <link
2828- xlink:href="#chap-contributing">
2929- contributing to this manual</link>. Bugs should be
3030- reported in
3131- <link
3232- xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’
3333- GitHub issue tracker</link>.
3434- </para>
3535- <note>
3636- <para>
3737- Commands prefixed with <literal>#</literal> have to be run as root, either
3838- requiring to login as root user or temporarily switching to it using
3939- <literal>sudo</literal> for example.
4040- </para>
4141- </note>
4242-</preface>
+25
nixos/doc/manual/release-notes/release-notes.md
···11+# Release Notes {#ch-release-notes}
22+33+This section lists the release notes for each stable version of NixOS and current unstable revision.
44+55+```{=include=} sections
66+rl-2305.section.md
77+rl-2211.section.md
88+rl-2205.section.md
99+rl-2111.section.md
1010+rl-2105.section.md
1111+rl-2009.section.md
1212+rl-2003.section.md
1313+rl-1909.section.md
1414+rl-1903.section.md
1515+rl-1809.section.md
1616+rl-1803.section.md
1717+rl-1709.section.md
1818+rl-1703.section.md
1919+rl-1609.section.md
2020+rl-1603.section.md
2121+rl-1509.section.md
2222+rl-1412.section.md
2323+rl-1404.section.md
2424+rl-1310.section.md
2525+```
···11-#!/usr/bin/env ruby
22-33-# This script is written intended as a living, evolving tooling
44-# to fix oopsies within the docbook documentation.
55-#
66-# This is *not* a formatter. It, instead, handles some known cases
77-# where something bad happened, and fixing it manually is tedious.
88-#
99-# Read the code to see the different cases it handles.
1010-#
1111-# ALWAYS `make format` after fixing with this!
1212-# ALWAYS read the changes, this tool isn't yet proven to be always right.
1313-1414-require "rexml/document"
1515-include REXML
1616-1717-if ARGV.length < 1 then
1818- $stderr.puts "Needs a filename."
1919- exit 1
2020-end
2121-2222-filename = ARGV.shift
2323-doc = Document.new(File.open(filename))
2424-2525-$touched = false
2626-2727-# Fixing varnames having a sibling element without spacing.
2828-# This is to fix an initial `xmlformat` issue where `term`
2929-# would mangle as spaces.
3030-#
3131-# <varlistentry>
3232-# <term><varname>types.separatedString</varname><replaceable>sep</replaceable> <----
3333-# </term>
3434-# ...
3535-#
3636-# Generates: types.separatedStringsep
3737-# ^^^^
3838-#
3939-# <varlistentry xml:id='fun-makeWrapper'>
4040-# <term>
4141-# <function>makeWrapper</function><replaceable>executable</replaceable><replaceable>wrapperfile</replaceable><replaceable>args</replaceable> <----
4242-# </term>
4343-#
4444-# Generates: makeWrapperexecutablewrapperfileargs
4545-# ^^^^ ^^^^ ^^ ^^
4646-#
4747-# <term>
4848-# <option>--option</option><replaceable>name</replaceable><replaceable>value</replaceable> <-----
4949-# </term>
5050-#
5151-# Generates: --optionnamevalue
5252-# ^^ ^^
5353-doc.elements.each("//varlistentry/term") do |term|
5454- ["varname", "function", "option", "replaceable"].each do |prev_name|
5555- term.elements.each(prev_name) do |el|
5656- if el.next_element and
5757- el.next_element.name == "replaceable" and
5858- el.next_sibling_node.class == Element
5959- then
6060- $touched = true
6161- term.insert_after(el, Text.new(" "))
6262- end
6363- end
6464- end
6565-end
6666-6767-6868-6969-# <cmdsynopsis>
7070-# <command>nixos-option</command>
7171-# <arg>
7272-# <option>-I</option><replaceable>path</replaceable> <------
7373-# </arg>
7474-#
7575-# Generates: -Ipath
7676-# ^^
7777-doc.elements.each("//cmdsynopsis/arg") do |term|
7878- ["option", "replaceable"].each do |prev_name|
7979- term.elements.each(prev_name) do |el|
8080- if el.next_element and
8181- el.next_element.name == "replaceable" and
8282- el.next_sibling_node.class == Element
8383- then
8484- $touched = true
8585- term.insert_after(el, Text.new(" "))
8686- end
8787- end
8888- end
8989-end
9090-9191-# <cmdsynopsis>
9292-# <arg>
9393-# <group choice='req'>
9494-# <arg choice='plain'>
9595-# <option>--profile-name</option>
9696-# </arg>
9797-#
9898-# <arg choice='plain'>
9999-# <option>-p</option>
100100-# </arg>
101101-# </group><replaceable>name</replaceable> <----
102102-# </arg>
103103-#
104104-# Generates: [{--profile-name | -p }name]
105105-# ^^^^
106106-doc.elements.each("//cmdsynopsis/arg") do |term|
107107- ["group"].each do |prev_name|
108108- term.elements.each(prev_name) do |el|
109109- if el.next_element and
110110- el.next_element.name == "replaceable" and
111111- el.next_sibling_node.class == Element
112112- then
113113- $touched = true
114114- term.insert_after(el, Text.new(" "))
115115- end
116116- end
117117- end
118118-end
119119-120120-121121-if $touched then
122122- doc.context[:attribute_quote] = :quote
123123- doc.write(output: File.open(filename, "w"))
124124-end
···2020 # The websites yt-dlp deals with are a very moving target. That means that
2121 # downloads break constantly. Because of that, updates should always be backported
2222 # to the latest stable release.
2323- version = "2023.1.6";
2323+ version = "2023.2.17";
24242525 src = fetchPypi {
2626 inherit pname version;
2727- sha256 = "sha256-Ong6NnUc7RY2j0CzuoZas5swaJ7YBW8e4jRqo4OaCw8=";
2727+ sha256 = "sha256-mvkt5e/8GTvbUSFtnr8oh02WGA0gL651Kw2fKmM4Dzo=";
2828 };
29293030 propagatedBuildInputs = [ brotli certifi mutagen pycryptodomex websockets ];