nixos: nixos/doc/configuration/profiles/*.xml to CommonMark

23 files changed, 130 insertions, 239 deletions

diff --git a/nixos/doc/manual/configuration/profiles.xml b/nixos/doc/manual/configuration/profiles.xml
index 9d08f7f7bed..6994c7e3170 100644
--- a/nixos/doc/manual/configuration/profiles.xml
+++ b/nixos/doc/manual/configuration/profiles.xml
@@ -25,15 +25,15 @@
   What follows is a brief explanation on the purpose and use-case for each
   profile. Detailing each option configured by each one is out of scope.
  </para>
- <xi:include href="profiles/all-hardware.xml" />
- <xi:include href="profiles/base.xml" />
- <xi:include href="profiles/clone-config.xml" />
- <xi:include href="profiles/demo.xml" />
- <xi:include href="profiles/docker-container.xml" />
- <xi:include href="profiles/graphical.xml" />
- <xi:include href="profiles/hardened.xml" />
- <xi:include href="profiles/headless.xml" />
- <xi:include href="profiles/installation-device.xml" />
- <xi:include href="profiles/minimal.xml" />
- <xi:include href="profiles/qemu-guest.xml" />
+ <xi:include href="../from_md/configuration/profiles/all-hardware.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/base.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/clone-config.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/demo.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/docker-container.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/graphical.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/hardened.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/headless.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/installation-device.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/minimal.section.xml" />
+ <xi:include href="../from_md/configuration/profiles/qemu-guest.section.xml" />
 </chapter>
diff --git a/nixos/doc/manual/configuration/profiles/all-hardware.section.md b/nixos/doc/manual/configuration/profiles/all-hardware.section.md
new file mode 100644
index 00000000000..0344b32c52f
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/all-hardware.section.md
@@ -0,0 +1,11 @@
+# All Hardware {#sec-profile-all-hardware}
+
+Enables all hardware supported by NixOS: i.e., all firmware is included, and
+all devices from which one may boot are enabled in the initrd. Its primary
+use is in the NixOS installation CDs.
+
+The enabled kernel modules include support for SATA and PATA, SCSI
+(partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and
+Hyper-V. Additionally, [`hardware.enableAllFirmware`](options.html#opt-hardware.enableAllFirmware) is
+enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically
+installed.
diff --git a/nixos/doc/manual/configuration/profiles/all-hardware.xml b/nixos/doc/manual/configuration/profiles/all-hardware.xml
deleted file mode 100644
index 2936f71069d..00000000000
--- a/nixos/doc/manual/configuration/profiles/all-hardware.xml
+++ /dev/null
@@ -1,21 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-all-hardware">
- <title>All Hardware</title>
-
- <para>
-  Enables all hardware supported by NixOS: i.e., all firmware is included, and
-  all devices from which one may boot are enabled in the initrd. Its primary
-  use is in the NixOS installation CDs.
- </para>
-
- <para>
-  The enabled kernel modules include support for SATA and PATA, SCSI
-  (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and
-  Hyper-V. Additionally, <xref linkend="opt-hardware.enableAllFirmware"/> is
-  enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically
-  installed.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/base.section.md b/nixos/doc/manual/configuration/profiles/base.section.md
new file mode 100644
index 00000000000..59b3068fda3
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/base.section.md
@@ -0,0 +1,7 @@
+# Base {#sec-profile-base}
+
+Defines the software packages included in the "minimal" installation CD. It
+installs several utilities useful in a simple recovery or install media, such
+as a text-mode web browser, and tools for manipulating block devices,
+networking, hardware diagnostics, and filesystems (with their respective
+kernel modules).
diff --git a/nixos/doc/manual/configuration/profiles/base.xml b/nixos/doc/manual/configuration/profiles/base.xml
deleted file mode 100644
index b75f6ba25b4..00000000000
--- a/nixos/doc/manual/configuration/profiles/base.xml
+++ /dev/null
@@ -1,15 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-base">
- <title>Base</title>
-
- <para>
-  Defines the software packages included in the "minimal" installation CD. It
-  installs several utilities useful in a simple recovery or install media, such
-  as a text-mode web browser, and tools for manipulating block devices,
-  networking, hardware diagnostics, and filesystems (with their respective
-  kernel modules).
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/clone-config.section.md b/nixos/doc/manual/configuration/profiles/clone-config.section.md
new file mode 100644
index 00000000000..e2583715e51
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/clone-config.section.md
@@ -0,0 +1,11 @@
+# Clone Config {#sec-profile-clone-config}
+
+This profile is used in installer images. It provides an editable
+configuration.nix that imports all the modules that were also used when
+creating the image in the first place. As a result it allows users to edit
+and rebuild the live-system.
+
+On images where the installation media also becomes an installation target,
+copying over `configuration.nix` should be disabled by
+setting `installer.cloneConfig` to `false`.
+For example, this is done in `sd-image-aarch64-installer.nix`.
diff --git a/nixos/doc/manual/configuration/profiles/clone-config.xml b/nixos/doc/manual/configuration/profiles/clone-config.xml
deleted file mode 100644
index 9c70cf35204..00000000000
--- a/nixos/doc/manual/configuration/profiles/clone-config.xml
+++ /dev/null
@@ -1,21 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-clone-config">
- <title>Clone Config</title>
-
- <para>
-  This profile is used in installer images. It provides an editable
-  configuration.nix that imports all the modules that were also used when
-  creating the image in the first place. As a result it allows users to edit
-  and rebuild the live-system.
- </para>
-
- <para>
-  On images where the installation media also becomes an installation target,
-  copying over <literal>configuration.nix</literal> should be disabled by
-  setting <literal>installer.cloneConfig</literal> to <literal>false</literal>.
-  For example, this is done in <literal>sd-image-aarch64-installer.nix</literal>.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/demo.section.md b/nixos/doc/manual/configuration/profiles/demo.section.md
new file mode 100644
index 00000000000..a50f5a00ada
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/demo.section.md
@@ -0,0 +1,4 @@
+# Demo {#sec-profile-demo}
+
+This profile just enables a `demo` user, with password `demo`, uid `1000`, `wheel` group and
+[autologin in the SDDM display manager](options.html#opt-services.xserver.displayManager.autoLogin).
diff --git a/nixos/doc/manual/configuration/profiles/demo.xml b/nixos/doc/manual/configuration/profiles/demo.xml
deleted file mode 100644
index bc801bb3dc5..00000000000
--- a/nixos/doc/manual/configuration/profiles/demo.xml
+++ /dev/null
@@ -1,14 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-demo">
- <title>Demo</title>
-
- <para>
-  This profile just enables a <systemitem class="username">demo</systemitem>
-  user, with password <literal>demo</literal>, uid <literal>1000</literal>,
-  <systemitem class="groupname">wheel</systemitem> group and
-  <link linkend="opt-services.xserver.displayManager.autoLogin">autologin in the SDDM display manager</link>.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/docker-container.section.md b/nixos/doc/manual/configuration/profiles/docker-container.section.md
new file mode 100644
index 00000000000..59954112c30
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/docker-container.section.md
@@ -0,0 +1,7 @@
+# Docker Container {#sec-profile-docker-container}
+
+This is the profile from which the Docker images are generated. It prepares a
+working system by importing the [Minimal](#sec-profile-minimal) and
+[Clone Config](#sec-profile-clone-config) profiles, and
+setting appropriate configuration options that are useful inside a container
+context, like [`boot.isContainer`](options.html#opt-boot.isContainer).
diff --git a/nixos/doc/manual/configuration/profiles/docker-container.xml b/nixos/doc/manual/configuration/profiles/docker-container.xml
deleted file mode 100644
index efa7b8f24c4..00000000000
--- a/nixos/doc/manual/configuration/profiles/docker-container.xml
+++ /dev/null
@@ -1,16 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-docker-container">
- <title>Docker Container</title>
-
- <para>
-  This is the profile from which the Docker images are generated. It prepares a
-  working system by importing the
-  <link linkend="sec-profile-minimal">Minimal</link> and
-  <link linkend="sec-profile-clone-config">Clone Config</link> profiles, and
-  setting appropriate configuration options that are useful inside a container
-  context, like <xref linkend="opt-boot.isContainer"/>.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/graphical.section.md b/nixos/doc/manual/configuration/profiles/graphical.section.md
new file mode 100644
index 00000000000..767cde9b79e
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/graphical.section.md
@@ -0,0 +1,10 @@
+# Graphical {#sec-profile-graphical}
+
+Defines a NixOS configuration with the Plasma 5 desktop. It's used by the
+graphical installation CD.
+
+It sets [`services.xserver.enable`](options.html#opt-services.xserver.enable),
+[`services.xserver.displayManager.sddm.enable`](options.html#opt-services.xserver.displayManager.sddm.enable),
+[`services.xserver.desktopManager.plasma5.enable`](options.html#opt-services.xserver.desktopManager.plasma5.enable),
+and [`services.xserver.libinput.enable`](options.html#opt-services.xserver.libinput.enable) to true. It also
+includes glxinfo and firefox in the system packages list.
diff --git a/nixos/doc/manual/configuration/profiles/graphical.xml b/nixos/doc/manual/configuration/profiles/graphical.xml
deleted file mode 100644
index cc6d0825d24..00000000000
--- a/nixos/doc/manual/configuration/profiles/graphical.xml
+++ /dev/null
@@ -1,20 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-graphical">
- <title>Graphical</title>
-
- <para>
-  Defines a NixOS configuration with the Plasma 5 desktop. It's used by the
-  graphical installation CD.
- </para>
-
- <para>
-  It sets <xref linkend="opt-services.xserver.enable"/>,
-  <xref linkend="opt-services.xserver.displayManager.sddm.enable"/>,
-  <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/>, and
-  <xref linkend="opt-services.xserver.libinput.enable"/> to true. It also
-  includes glxinfo and firefox in the system packages list.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/hardened.section.md b/nixos/doc/manual/configuration/profiles/hardened.section.md
new file mode 100644
index 00000000000..958da94d261
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/hardened.section.md
@@ -0,0 +1,20 @@
+# Hardened {#sec-profile-hardened}
+
+A profile with most (vanilla) hardening options enabled by default,
+potentially at the cost of stability, features and performance.
+
+This includes a hardened kernel, and limiting the system information
+available to processes through the `/sys` and
+`/proc` filesystems. It also disables the User Namespaces
+feature of the kernel, which stops Nix from being able to build anything
+(this particular setting can be overriden via
+[`security.allowUserNamespaces`](options.html#opt-security.allowUserNamespaces)). See the
+[profile source](https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix)
+for further detail on which settings are altered.
+
+::: {.warning}
+This profile enables options that are known to affect system
+stability. If you experience any stability issues when using the
+profile, try disabling it. If you report an issue and use this
+profile, always mention that you do.
+:::
diff --git a/nixos/doc/manual/configuration/profiles/hardened.xml b/nixos/doc/manual/configuration/profiles/hardened.xml
deleted file mode 100644
index 4a51754cc7a..00000000000
--- a/nixos/doc/manual/configuration/profiles/hardened.xml
+++ /dev/null
@@ -1,32 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-hardened">
- <title>Hardened</title>
-
- <para>
-  A profile with most (vanilla) hardening options enabled by default,
-  potentially at the cost of stability, features and performance.
- </para>
-
- <para>
-  This includes a hardened kernel, and limiting the system information
-  available to processes through the <filename>/sys</filename> and
-  <filename>/proc</filename> filesystems. It also disables the User Namespaces
-  feature of the kernel, which stops Nix from being able to build anything
-  (this particular setting can be overriden via
-  <xref linkend="opt-security.allowUserNamespaces"/>). See the
-  <literal
-   xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix">
-  profile source</literal> for further detail on which settings are altered.
- </para>
- <warning>
-   <para>
-     This profile enables options that are known to affect system
-     stability. If you experience any stability issues when using the
-     profile, try disabling it. If you report an issue and use this
-     profile, always mention that you do.
-   </para>
- </warning>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/headless.section.md b/nixos/doc/manual/configuration/profiles/headless.section.md
new file mode 100644
index 00000000000..1db4a82a4de
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/headless.section.md
@@ -0,0 +1,9 @@
+# Headless {#sec-profile-headless}
+
+Common configuration for headless machines (e.g., Amazon EC2 instances).
+
+Disables [sound](options.html#opt-sound.enable),
+[vesa](options.html#opt-boot.vesa), serial consoles,
+[emergency mode](options.html#opt-systemd.enableEmergencyMode),
+[grub splash images](options.html#opt-boot.loader.grub.splashImage)
+and configures the kernel to reboot automatically on panic.
diff --git a/nixos/doc/manual/configuration/profiles/headless.xml b/nixos/doc/manual/configuration/profiles/headless.xml
deleted file mode 100644
index 1b64497ebf7..00000000000
--- a/nixos/doc/manual/configuration/profiles/headless.xml
+++ /dev/null
@@ -1,19 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-headless">
- <title>Headless</title>
-
- <para>
-  Common configuration for headless machines (e.g., Amazon EC2 instances).
- </para>
-
- <para>
-  Disables <link linkend="opt-sound.enable">sound</link>,
-  <link linkend="opt-boot.vesa">vesa</link>, serial consoles,
-  <link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>,
-  <link linkend="opt-boot.loader.grub.splashImage">grub splash images</link>
-  and configures the kernel to reboot automatically on panic.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/installation-device.section.md b/nixos/doc/manual/configuration/profiles/installation-device.section.md
new file mode 100644
index 00000000000..aa5678c031a
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/installation-device.section.md
@@ -0,0 +1,24 @@
+# Installation Device {#sec-profile-installation-device}
+
+Provides a basic configuration for installation devices like CDs.
+This enables redistributable firmware, includes the
+[Clone Config profile](#sec-profile-clone-config)
+and a copy of the Nixpkgs channel, so `nixos-install`
+works out of the box.
+
+Documentation for [Nixpkgs](options.html#opt-documentation.enable)
+and [NixOS](options.html#opt-documentation.nixos.enable) are
+forcefully enabled (to override the
+[Minimal profile](#sec-profile-minimal) preference); the
+NixOS manual is shown automatically on TTY 8, udisks is disabled.
+Autologin is enabled as `nixos` user, while passwordless
+login as both `root` and `nixos` is possible.
+Passwordless `sudo` is enabled too.
+[wpa_supplicant](options.html#opt-networking.wireless.enable) is
+enabled, but configured to not autostart.
+
+It is explained how to login, start the ssh server, and if available,
+how to start the display manager.
+
+Several settings are tweaked so that the installer has a better chance of
+succeeding under low-memory environments.
diff --git a/nixos/doc/manual/configuration/profiles/installation-device.xml b/nixos/doc/manual/configuration/profiles/installation-device.xml
deleted file mode 100644
index 192ae955b68..00000000000
--- a/nixos/doc/manual/configuration/profiles/installation-device.xml
+++ /dev/null
@@ -1,36 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-installation-device">
- <title>Installation Device</title>
-
- <para>
-  Provides a basic configuration for installation devices like CDs.
-  This enables redistributable firmware, includes the
-  <link linkend="sec-profile-clone-config">Clone Config profile</link>
-  and a copy of the Nixpkgs channel, so <command>nixos-install</command>
-  works out of the box.
- </para>
- <para>
-  Documentation for <link linkend="opt-documentation.enable">Nixpkgs</link>
-  and <link linkend="opt-documentation.nixos.enable">NixOS</link> are
-  forcefully enabled (to override the
-  <link linkend="sec-profile-minimal">Minimal profile</link> preference); the
-  NixOS manual is shown automatically on TTY 8, udisks is disabled.
-  Autologin is enabled as <literal>nixos</literal> user, while passwordless
-  login as both <literal>root</literal> and <literal>nixos</literal> is possible.
-  Passwordless <command>sudo</command> is enabled too.
-  <link linkend="opt-networking.wireless.enable">wpa_supplicant</link> is
-  enabled, but configured to not autostart.
- </para>
- <para>
-  It is explained how to login, start the ssh server, and if available,
-  how to start the display manager.
- </para>
-
- <para>
-  Several settings are tweaked so that the installer has a better chance of
-  succeeding under low-memory environments.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/minimal.section.md b/nixos/doc/manual/configuration/profiles/minimal.section.md
new file mode 100644
index 00000000000..d5a569d6620
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/minimal.section.md
@@ -0,0 +1,9 @@
+# Minimal {#sec-profile-minimal}
+
+This profile defines a small NixOS configuration. It does not contain any
+graphical stuff. It's a very short file that enables
+[noXlibs](options.html#opt-environment.noXlibs), sets
+[`i18n.supportedLocales`](options.html#opt-i18n.supportedLocales) to
+only support the user-selected locale,
+[disables packages' documentation](options.html#opt-documentation.enable),
+and [disables sound](options.html#opt-sound.enable).
diff --git a/nixos/doc/manual/configuration/profiles/minimal.xml b/nixos/doc/manual/configuration/profiles/minimal.xml
deleted file mode 100644
index 179f2d0be64..00000000000
--- a/nixos/doc/manual/configuration/profiles/minimal.xml
+++ /dev/null
@@ -1,17 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-minimal">
- <title>Minimal</title>
-
- <para>
-  This profile defines a small NixOS configuration. It does not contain any
-  graphical stuff. It's a very short file that enables
-  <link linkend="opt-environment.noXlibs">noXlibs</link>, sets
-  <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> to
-  only support the user-selected locale,
-  <link linkend="opt-documentation.enable">disables packages' documentation
-  </link>, and <link linkend="opt-sound.enable">disables sound</link>.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/profiles/qemu-guest.section.md b/nixos/doc/manual/configuration/profiles/qemu-guest.section.md
new file mode 100644
index 00000000000..d7e3cae9cb0
--- /dev/null
+++ b/nixos/doc/manual/configuration/profiles/qemu-guest.section.md
@@ -0,0 +1,7 @@
+# QEMU Guest {#sec-profile-qemu-guest}
+
+This profile contains common configuration for virtual machines running under
+QEMU (using virtio).
+
+It makes virtio modules available on the initrd and sets the system time from
+the hardware clock to work around a bug in qemu-kvm.
diff --git a/nixos/doc/manual/configuration/profiles/qemu-guest.xml b/nixos/doc/manual/configuration/profiles/qemu-guest.xml
deleted file mode 100644
index 3ed97b94b51..00000000000
--- a/nixos/doc/manual/configuration/profiles/qemu-guest.xml
+++ /dev/null
@@ -1,17 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-profile-qemu-guest">
- <title>QEMU Guest</title>
-
- <para>
-  This profile contains common configuration for virtual machines running under
-  QEMU (using virtio).
- </para>
-
- <para>
-  It makes virtio modules available on the initrd and sets the system time from
-  the hardware clock to work around a bug in qemu-kvm.
- </para>
-</section>