Merge pull request #129083 from bobby285271/pr12

nixos/doc: convert Chapter 49, 50, 51, 52, 53, 54 to CommonMark

14 files changed, 359 insertions, 398 deletions

diff --git a/nixos/doc/manual/administration/boot-problems.section.md b/nixos/doc/manual/administration/boot-problems.section.md
index dee83e7ec2252..bca4fdc3fb38b 100644
--- a/nixos/doc/manual/administration/boot-problems.section.md
+++ b/nixos/doc/manual/administration/boot-problems.section.md
@@ -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`
 
diff --git a/nixos/doc/manual/administration/cleaning-store.chapter.md b/nixos/doc/manual/administration/cleaning-store.chapter.md
new file mode 100644
index 0000000000000..fb2090b31d84a
--- /dev/null
+++ b/nixos/doc/manual/administration/cleaning-store.chapter.md
@@ -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.
diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml
deleted file mode 100644
index 526803e429baf..0000000000000
--- a/nixos/doc/manual/administration/cleaning-store.xml
+++ /dev/null
@@ -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>
diff --git a/nixos/doc/manual/administration/control-groups.chapter.md b/nixos/doc/manual/administration/control-groups.chapter.md
new file mode 100644
index 0000000000000..abe8dd80b5ab0
--- /dev/null
+++ b/nixos/doc/manual/administration/control-groups.chapter.md
@@ -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.
diff --git a/nixos/doc/manual/administration/control-groups.xml b/nixos/doc/manual/administration/control-groups.xml
deleted file mode 100644
index 16d03cc0d1abb..0000000000000
--- a/nixos/doc/manual/administration/control-groups.xml
+++ /dev/null
@@ -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>
diff --git a/nixos/doc/manual/administration/logging.chapter.md b/nixos/doc/manual/administration/logging.chapter.md
new file mode 100644
index 0000000000000..4ce6f5e9fa729
--- /dev/null
+++ b/nixos/doc/manual/administration/logging.chapter.md
@@ -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`.
diff --git a/nixos/doc/manual/administration/logging.xml b/nixos/doc/manual/administration/logging.xml
deleted file mode 100644
index da4877fcdf080..0000000000000
--- a/nixos/doc/manual/administration/logging.xml
+++ /dev/null
@@ -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>
diff --git a/nixos/doc/manual/administration/rebooting.chapter.md b/nixos/doc/manual/administration/rebooting.chapter.md
new file mode 100644
index 0000000000000..ec4b889b1648c
--- /dev/null
+++ b/nixos/doc/manual/administration/rebooting.chapter.md
@@ -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.
diff --git a/nixos/doc/manual/administration/rebooting.xml b/nixos/doc/manual/administration/rebooting.xml
deleted file mode 100644
index c57d885c5f3cc..0000000000000
--- a/nixos/doc/manual/administration/rebooting.xml
+++ /dev/null
@@ -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>
diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml
index 19bec1f7794d8..24fd864956ffa 100644
--- a/nixos/doc/manual/administration/running.xml
+++ b/nixos/doc/manual/administration/running.xml
@@ -10,12 +10,12 @@
    such as how to use the <command>systemd</command> service manager.
   </para>
  </partintro>
- <xi:include href="service-mgmt.xml" />
- <xi:include href="rebooting.xml" />
- <xi:include href="user-sessions.xml" />
- <xi:include href="control-groups.xml" />
- <xi:include href="logging.xml" />
- <xi:include href="cleaning-store.xml" />
+ <xi:include href="../from_md/administration/service-mgmt.chapter.xml" />
+ <xi:include href="../from_md/administration/rebooting.chapter.xml" />
+ <xi:include href="../from_md/administration/user-sessions.chapter.xml" />
+ <xi:include href="../from_md/administration/control-groups.chapter.xml" />
+ <xi:include href="../from_md/administration/logging.chapter.xml" />
+ <xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
  <xi:include href="containers.xml" />
  <xi:include href="troubleshooting.xml" />
 </part>
diff --git a/nixos/doc/manual/administration/service-mgmt.chapter.md b/nixos/doc/manual/administration/service-mgmt.chapter.md
new file mode 100644
index 0000000000000..bb0f9b62e9138
--- /dev/null
+++ b/nixos/doc/manual/administration/service-mgmt.chapter.md
@@ -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.
diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml
deleted file mode 100644
index 863b0d47f6c7b..0000000000000
--- a/nixos/doc/manual/administration/service-mgmt.xml
+++ /dev/null
@@ -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>
-
diff --git a/nixos/doc/manual/administration/user-sessions.chapter.md b/nixos/doc/manual/administration/user-sessions.chapter.md
new file mode 100644
index 0000000000000..5ff468b301220
--- /dev/null
+++ b/nixos/doc/manual/administration/user-sessions.chapter.md
@@ -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
+```
diff --git a/nixos/doc/manual/administration/user-sessions.xml b/nixos/doc/manual/administration/user-sessions.xml
deleted file mode 100644
index 9acb147ac1a68..0000000000000
--- a/nixos/doc/manual/administration/user-sessions.xml
+++ /dev/null
@@ -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>