summary refs log tree commit diff
path: root/nixos/doc/manual/from_md/release-notes/rl-2003.section.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/from_md/release-notes/rl-2003.section.xml')
-rw-r--r--nixos/doc/manual/from_md/release-notes/rl-2003.section.xml1497
1 files changed, 1497 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/release-notes/rl-2003.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2003.section.xml
new file mode 100644
index 00000000000..53e6e1329a9
--- /dev/null
+++ b/nixos/doc/manual/from_md/release-notes/rl-2003.section.xml
@@ -0,0 +1,1497 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-release-20.03">
+  <title>Release 20.03 (<quote>Markhor</quote>, 2020.04/20)</title>
+  <section xml:id="sec-release-20.03-highlights">
+    <title>Highlights</title>
+    <para>
+      In addition to numerous new and upgraded packages, this release
+      has the following highlights:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          Support is planned until the end of October 2020, handing over
+          to 20.09.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Core version changes:
+        </para>
+        <para>
+          gcc: 8.3.0 -&gt; 9.2.0
+        </para>
+        <para>
+          glibc: 2.27 -&gt; 2.30
+        </para>
+        <para>
+          linux: 4.19 -&gt; 5.4
+        </para>
+        <para>
+          mesa: 19.1.5 -&gt; 19.3.3
+        </para>
+        <para>
+          openssl: 1.0.2u -&gt; 1.1.1d
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Desktop version changes:
+        </para>
+        <para>
+          plasma5: 5.16.5 -&gt; 5.17.5
+        </para>
+        <para>
+          kdeApplications: 19.08.2 -&gt; 19.12.3
+        </para>
+        <para>
+          gnome3: 3.32 -&gt; 3.34
+        </para>
+        <para>
+          pantheon: 5.0 -&gt; 5.1.3
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Linux kernel is updated to branch 5.4 by default (from 4.19).
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Grub is updated to 2.04, adding support for booting from F2FS
+          filesystems and Btrfs volumes using zstd compression. Note
+          that some users have been unable to boot after upgrading to
+          2.04 - for more information, please see
+          <link xlink:href="https://github.com/NixOS/nixpkgs/issues/61718#issuecomment-617618503">this
+          discussion</link>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Postgresql for NixOS service now defaults to v11.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The graphical installer image starts the graphical session
+          automatically. Before you'd be greeted by a tty and asked to
+          enter <literal>systemctl start display-manager</literal>. It
+          is now possible to disable the display-manager from running by
+          selecting the <literal>Disable display-manager</literal> quirk
+          in the boot menu.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GNOME 3 has been upgraded to 3.34. Please take a look at their
+          <link xlink:href="https://help.gnome.org/misc/release-notes/3.34">Release
+          Notes</link> for details.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          If you enable the Pantheon Desktop Manager via
+          <link xlink:href="options.html#opt-services.xserver.desktopManager.pantheon.enable">services.xserver.desktopManager.pantheon.enable</link>,
+          we now default to also use
+          <link xlink:href="https://blog.elementary.io/say-hello-to-the-new-greeter/">
+          Pantheon's newly designed greeter </link>. Contrary to NixOS's
+          usual update policy, Pantheon will receive updates during the
+          cycle of NixOS 20.03 when backwards compatible.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          By default zfs pools will now be trimmed on a weekly basis.
+          Trimming is only done on supported devices (i.e. NVME or SSDs)
+          and should improve throughput and lifetime of these devices.
+          It is controlled by the
+          <literal>services.zfs.trim.enable</literal> varname. The zfs
+          scrub service
+          (<literal>services.zfs.autoScrub.enable</literal>) and the zfs
+          autosnapshot service
+          (<literal>services.zfs.autoSnapshot.enable</literal>) are now
+          only enabled if zfs is set in
+          <literal>config.boot.initrd.supportedFilesystems</literal> or
+          <literal>config.boot.supportedFilesystems</literal>. These
+          lists will automatically contain zfs as soon as any zfs
+          mountpoint is configured in <literal>fileSystems</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>nixos-option</literal> has been rewritten in C++,
+          speeding it up, improving correctness, and adding a
+          <literal>-r</literal> option which prints all options and
+          their values recursively.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>services.xserver.desktopManager.default</literal> and
+          <literal>services.xserver.windowManager.default</literal>
+          options were replaced by a single
+          <link xlink:href="options.html#opt-services.xserver.displayManager.defaultSession">services.xserver.displayManager.defaultSession</link>
+          option to improve support for upstream session files. If you
+          used something like:
+        </para>
+        <programlisting language="bash">
+{
+  services.xserver.desktopManager.default = &quot;xfce&quot;;
+  services.xserver.windowManager.default = &quot;icewm&quot;;
+}
+</programlisting>
+        <para>
+          you should change it to:
+        </para>
+        <programlisting language="bash">
+{
+  services.xserver.displayManager.defaultSession = &quot;xfce+icewm&quot;;
+}
+</programlisting>
+      </listitem>
+      <listitem>
+        <para>
+          The testing driver implementation in NixOS is now in Python
+          <literal>make-test-python.nix</literal>. This was done by
+          Jacek Galowicz
+          (<link xlink:href="https://github.com/tfc">@tfc</link>), and
+          with the collaboration of Julian Stecklina
+          (<link xlink:href="https://github.com/blitz">@blitz</link>)
+          and Jana Traue
+          (<link xlink:href="https://github.com/jtraue">@jtraue</link>).
+          All documentation has been updated to use this testing driver,
+          and a vast majority of the 286 tests in NixOS were ported to
+          python driver. In 20.09 the Perl driver implementation,
+          <literal>make-test.nix</literal>, is slated for removal. This
+          should give users of the NixOS integration framework a
+          transitory period to rewrite their tests to use the Python
+          implementation. Users of the Perl driver will see this warning
+          everytime they use it:
+        </para>
+        <programlisting>
+$ warning: Perl VM tests are deprecated and will be removed for 20.09.
+Please update your tests to use the python test driver.
+See https://github.com/NixOS/nixpkgs/pull/71684 for details.
+</programlisting>
+        <para>
+          API compatibility is planned to be kept for at least the next
+          release with the perl driver.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+  <section xml:id="sec-release-20.03-new-services">
+    <title>New Services</title>
+    <para>
+      The following new services were added since the last release:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          The kubernetes kube-proxy now supports a new hostname
+          configuration
+          <literal>services.kubernetes.proxy.hostname</literal> which
+          has to be set if the hostname of the node should be non
+          default.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          UPower's configuration is now managed by NixOS and can be
+          customized via <literal>services.upower</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          To use Geary you should enable
+          <link xlink:href="options.html#opt-programs.geary.enable">programs.geary.enable</link>
+          instead of just adding it to
+          <link xlink:href="options.html#opt-environment.systemPackages">environment.systemPackages</link>.
+          It was created so Geary could function properly outside of
+          GNOME.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./config/console.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./hardware/brillo.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./hardware/tuxedo-keyboard.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./programs/bandwhich.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./programs/bash-my-aws.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./programs/liboping.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./programs/traceroute.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/backup/sanoid.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/backup/syncoid.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/backup/zfs-replication.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/continuous-integration/buildkite-agents.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/databases/victoriametrics.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/desktops/gnome3/gnome-initial-setup.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/desktops/neard.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/games/openarena.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/hardware/fancontrol.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/mail/sympa.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/misc/freeswitch.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/misc/mame.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/monitoring/do-agent.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/monitoring/prometheus/xmpp-alerts.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/network-filesystems/orangefs/server.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/network-filesystems/orangefs/client.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/3proxy.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/corerad.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/go-shadowsocks2.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/ntp/openntpd.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/shorewall.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/shorewall6.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/spacecookie.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/trickster.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/v2ray.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/xandikos.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/networking/yggdrasil.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-apps/dokuwiki.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-apps/gotify-server.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-apps/grocy.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-apps/ihatemoney</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-apps/moinmoin.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-apps/trac.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-apps/trilium.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-apps/shiori.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/web-servers/ttyd.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/x11/picom.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/x11/hardware/digimend.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./services/x11/imwheel.nix</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>./virtualisation/cri-o.nix</literal>
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+  <section xml:id="sec-release-20.03-incompatibilities">
+    <title>Backward Incompatibilities</title>
+    <para>
+      When upgrading from a previous release, please be aware of the
+      following incompatible changes:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          The dhcpcd package
+          <link xlink:href="https://roy.marples.name/archives/dhcpcd-discuss/0002621.html">
+          does not request IPv4 addresses for tap and bridge interfaces
+          anymore by default</link>. In order to still get an address on
+          a bridge interface, one has to disable
+          <literal>networking.useDHCP</literal> and explicitly enable
+          <literal>networking.interfaces.&lt;name&gt;.useDHCP</literal>
+          on every interface, that should get an address via DHCP. This
+          way, dhcpcd is configured in an explicit way about which
+          interface to run on.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GnuPG is now built without support for a graphical passphrase
+          entry by default. Please enable the
+          <literal>gpg-agent</literal> user service via the NixOS option
+          <literal>programs.gnupg.agent.enable</literal>. Note that
+          upstream recommends using <literal>gpg-agent</literal> and
+          will spawn a <literal>gpg-agent</literal> on the first
+          invocation of GnuPG anyway.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>dynamicHosts</literal> option has been removed
+          from the
+          <link xlink:href="options.html#opt-networking.networkmanager.enable">NetworkManager</link>
+          module. Allowing (multiple) regular users to override host
+          entries affecting the whole system opens up a huge attack
+          vector. There seem to be very rare cases where this might be
+          useful. Consider setting system-wide host entries using
+          <link xlink:href="options.html#opt-networking.hosts">networking.hosts</link>,
+          provide them via the DNS server in your network, or use
+          <link xlink:href="options.html#opt-environment.etc">environment.etc</link>
+          to add a file into
+          <literal>/etc/NetworkManager/dnsmasq.d</literal> reconfiguring
+          <literal>hostsdir</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>99-main.network</literal> file was removed.
+          Matching all network interfaces caused many breakages, see
+          <link xlink:href="https://github.com/NixOS/nixpkgs/pull/18962">#18962</link>
+          and
+          <link xlink:href="https://github.com/NixOS/nixpkgs/pull/71106">#71106</link>.
+        </para>
+        <para>
+          We already don't support the global
+          <link xlink:href="options.html#opt-networking.useDHCP">networking.useDHCP</link>,
+          <link xlink:href="options.html#opt-networking.defaultGateway">networking.defaultGateway</link>
+          and
+          <link xlink:href="options.html#opt-networking.defaultGateway6">networking.defaultGateway6</link>
+          options if
+          <link xlink:href="options.html#opt-networking.useNetworkd">networking.useNetworkd</link>
+          is enabled, but direct users to configure the per-device
+          <link xlink:href="options.html#opt-networking.interfaces">networking.interfaces.&lt;name&gt;….</link>
+          options.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The stdenv now runs all bash with <literal>set -u</literal>,
+          to catch the use of undefined variables. Before, it itself
+          used <literal>set -u</literal> but was careful to unset it so
+          other packages' code ran as before. Now, all bash code is held
+          to the same high standard, and the rather complex stateful
+          manipulation of the options can be discarded.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The SLIM Display Manager has been removed, as it has been
+          unmaintained since 2013. Consider migrating to a different
+          display manager such as LightDM (current default in NixOS),
+          SDDM, GDM, or using the startx module which uses Xinitrc.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The Way Cooler wayland compositor has been removed, as the
+          project has been officially canceled. There are no more
+          <literal>way-cooler</literal> attribute and
+          <literal>programs.way-cooler</literal> options.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The BEAM package set has been deleted. You will only find
+          there the different interpreters. You should now use the
+          different build tools coming with the languages with sandbox
+          mode disabled.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There is now only one Xfce package-set and module. This means
+          that attributes <literal>xfce4-14</literal> and
+          <literal>xfceUnstable</literal> all now point to the latest
+          Xfce 4.14 packages. And in the future NixOS releases will be
+          the latest released version of Xfce available at the time of
+          the release's development (if viable).
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The
+          <link xlink:href="options.html#opt-services.phpfpm.pools">phpfpm</link>
+          module now sets <literal>PrivateTmp=true</literal> in its
+          systemd units for better process isolation. If you rely on
+          <literal>/tmp</literal> being shared with other services,
+          explicitly override this by setting
+          <literal>serviceConfig.PrivateTmp</literal> to
+          <literal>false</literal> for each phpfpm unit.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          KDE’s old multimedia framework Phonon no longer supports Qt 4.
+          For that reason, Plasma desktop also does not have
+          <literal>enableQt4Support</literal> option any more.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The BeeGFS module has been removed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The osquery module has been removed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Going forward, <literal>~/bin</literal> in the users home
+          directory will no longer be in <literal>PATH</literal> by
+          default. If you depend on this you should set the option
+          <literal>environment.homeBinInPath</literal> to
+          <literal>true</literal>. The aforementioned option was added
+          this release.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>buildRustCrate</literal> infrastructure now
+          produces <literal>lib</literal> outputs in addition to the
+          <literal>out</literal> output. This has led to drastically
+          reduced closure sizes for some rust crates since development
+          dependencies are now in the <literal>lib</literal> output.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Pango was upgraded to 1.44, which no longer uses freetype for
+          font loading. This means that type1 and bitmap fonts are no
+          longer supported in applications relying on Pango for font
+          rendering (notably, GTK application). See
+          <link xlink:href="https://gitlab.gnome.org/GNOME/pango/issues/386">
+          upstream issue</link> for more information.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>roundcube</literal> module has been hardened.
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              The password of the database is not written world readable
+              in the store any more. If <literal>database.host</literal>
+              is set to <literal>localhost</literal>, then a unix user
+              of the same name as the database will be created and
+              PostreSQL peer authentication will be used, removing the
+              need for a password. Otherwise, a password is still needed
+              and can be provided with the new option
+              <literal>database.passwordFile</literal>, which should be
+              set to the path of a file containing the password and
+              readable by the user <literal>nginx</literal> only. The
+              <literal>database.password</literal> option is insecure
+              and deprecated. Usage of this option will print a warning.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              A random <literal>des_key</literal> is set by default in
+              the configuration of roundcube, instead of using the
+              hardcoded and insecure default. To ensure a clean
+              migration, all users will be logged out when you upgrade
+              to this release.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          The packages <literal>openobex</literal> and
+          <literal>obexftp</literal> are no longer installed when
+          enabling Bluetooth via
+          <literal>hardware.bluetooth.enable</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>dump1090</literal> derivation has been changed to
+          use FlightAware's dump1090 as its upstream. However, this
+          version does not have an internal webserver anymore. The
+          assets in the <literal>share/dump1090</literal> directory of
+          the derivation can be used in conjunction with an external
+          webserver to replace this functionality.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The fourStore and fourStoreEndpoint modules have been removed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Polkit no longer has the user of uid 0 (root) as an admin
+          identity. We now follow the upstream default of only having
+          every member of the wheel group admin privileged. Before it
+          was root and members of wheel. The positive outcome of this is
+          pkexec GUI popups or terminal prompts will no longer require
+          the user to choose between two essentially equivalent choices
+          (whether to perform the action as themselves with wheel
+          permissions, or as the root user).
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          NixOS containers no longer build NixOS manual by default. This
+          saves evaluation time, especially if there are many
+          declarative containers defined. Note that this is already done
+          when
+          <literal>&lt;nixos/modules/profiles/minimal.nix&gt;</literal>
+          module is included in container config.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>kresd</literal> services deprecates the
+          <literal>interfaces</literal> option in favor of the
+          <literal>listenPlain</literal> option which requires full
+          <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.socket.html#ListenStream=">systemd.socket
+          compatible</link> declaration which always include a port.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Virtual console options have been reorganized and can be found
+          under a single top-level attribute:
+          <literal>console</literal>. The full set of changes is as
+          follows:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>i18n.consoleFont</literal> renamed to
+              <link xlink:href="options.html#opt-console.font">console.font</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>i18n.consoleKeyMap</literal> renamed to
+              <link xlink:href="options.html#opt-console.keyMap">console.keyMap</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>i18n.consoleColors</literal> renamed to
+              <link xlink:href="options.html#opt-console.colors">console.colors</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>i18n.consolePackages</literal> renamed to
+              <link xlink:href="options.html#opt-console.packages">console.packages</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>i18n.consoleUseXkbConfig</literal> renamed to
+              <link xlink:href="options.html#opt-console.useXkbConfig">console.useXkbConfig</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>boot.earlyVconsoleSetup</literal> renamed to
+              <link xlink:href="options.html#opt-console.earlySetup">console.earlySetup</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>boot.extraTTYs</literal> renamed to
+              <literal>console.extraTTYs</literal>.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          The
+          <link xlink:href="options.html#opt-services.awstats.enable">awstats</link>
+          module has been rewritten to serve stats via static html
+          pages, updated on a timer, over
+          <link xlink:href="options.html#opt-services.nginx.virtualHosts">nginx</link>,
+          instead of dynamic cgi pages over
+          <link xlink:href="options.html#opt-services.httpd.enable">apache</link>.
+        </para>
+        <para>
+          Minor changes will be required to migrate existing
+          configurations. Details of the required changes can seen by
+          looking through the
+          <link xlink:href="options.html#opt-services.awstats.enable">awstats</link>
+          module.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The httpd module no longer provides options to support serving
+          web content without defining a virtual host. As a result of
+          this the
+          <link xlink:href="options.html#opt-services.httpd.logPerVirtualHost">services.httpd.logPerVirtualHost</link>
+          option now defaults to <literal>true</literal> instead of
+          <literal>false</literal>. Please update your configuration to
+          make use of
+          <link xlink:href="options.html#opt-services.httpd.virtualHosts">services.httpd.virtualHosts</link>.
+        </para>
+        <para>
+          The
+          <link xlink:href="options.html#opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;</link>
+          option has changed type from a list of submodules to an
+          attribute set of submodules, better matching
+          <link xlink:href="options.html#opt-services.nginx.virtualHosts">services.nginx.virtualHosts.&lt;name&gt;</link>.
+        </para>
+        <para>
+          This change comes with the addition of the following options
+          which mimic the functionality of their
+          <literal>nginx</literal> counterparts:
+          <link xlink:href="options.html#opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.addSSL</link>,
+          <link xlink:href="options.html#opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.forceSSL</link>,
+          <link xlink:href="options.html#opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.onlySSL</link>,
+          <link xlink:href="options.html#opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.enableACME</link>,
+          <link xlink:href="options.html#opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.acmeRoot</link>,
+          and
+          <link xlink:href="options.html#opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.useACMEHost</link>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          For NixOS configuration options, the <literal>loaOf</literal>
+          type has been deprecated and will be removed in a future
+          release. In nixpkgs, options of this type will be changed to
+          <literal>attrsOf</literal> instead. If you were using one of
+          these in your configuration, you will see a warning suggesting
+          what changes will be required.
+        </para>
+        <para>
+          For example,
+          <link xlink:href="options.html#opt-users.users">users.users</link>
+          is a <literal>loaOf</literal> option that is commonly used as
+          follows:
+        </para>
+        <programlisting language="bash">
+{
+  users.users =
+    [ { name = &quot;me&quot;;
+        description = &quot;My personal user.&quot;;
+        isNormalUser = true;
+      }
+    ];
+}
+</programlisting>
+        <para>
+          This should be rewritten by removing the list and using the
+          value of <literal>name</literal> as the name of the attribute
+          set:
+        </para>
+        <programlisting language="bash">
+{
+  users.users.me =
+    { description = &quot;My personal user.&quot;;
+      isNormalUser = true;
+    };
+}
+</programlisting>
+        <para>
+          For more information on this change have look at these links:
+          <link xlink:href="https://github.com/NixOS/nixpkgs/issues/1800">issue
+          #1800</link>,
+          <link xlink:href="https://github.com/NixOS/nixpkgs/pull/63103">PR
+          #63103</link>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          For NixOS modules, the types
+          <literal>types.submodule</literal> and
+          <literal>types.submoduleWith</literal> now support paths as
+          allowed values, similar to how <literal>imports</literal>
+          supports paths. Because of this, if you have a module that
+          defines an option of type
+          <literal>either (submodule ...) path</literal>, it will break
+          since a path is now treated as the first type instead of the
+          second. To fix this, change the type to
+          <literal>either path (submodule ...)</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The
+          <link xlink:href="options.html#opt-services.buildkite-agents">Buildkite
+          Agent</link> module and corresponding packages have been
+          updated to 3.x, and to support multiple instances of the agent
+          running at the same time. This means you will have to rename
+          <literal>services.buildkite-agent</literal> to
+          <literal>services.buildkite-agents.&lt;name&gt;</literal>.
+          Furthermore, the following options have been changed:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>services.buildkite-agent.meta-data</literal> has
+              been renamed to
+              <link xlink:href="options.html#opt-services.buildkite-agents">services.buildkite-agents.&lt;name&gt;.tags</link>,
+              to match upstreams naming for 3.x. Its type has also
+              changed - it now accepts an attrset of strings.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              The<literal>services.buildkite-agent.openssh.publicKeyPath</literal>
+              option has been removed, as it's not necessary to deploy
+              public keys to clone private repositories.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>services.buildkite-agent.openssh.privateKeyPath</literal>
+              has been renamed to
+              <link xlink:href="options.html#opt-services.buildkite-agents">buildkite-agents.&lt;name&gt;.privateSshKeyPath</link>,
+              as the whole <literal>openssh</literal> now only contained
+              that single option.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <link xlink:href="options.html#opt-services.buildkite-agents">services.buildkite-agents.&lt;name&gt;.shell</link>
+              has been introduced, allowing to specify a custom shell to
+              be used.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>citrix_workspace_19_3_0</literal> package has
+          been removed as it will be EOLed within the lifespan of 20.03.
+          For further information, please refer to the
+          <link xlink:href="https://www.citrix.com/de-de/support/product-lifecycle/milestones/receiver.html">support
+          and maintenance information</link> from upstream.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>gcc5</literal> and <literal>gfortran5</literal>
+          packages have been removed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>services.xserver.displayManager.auto</literal>
+          module has been removed. It was only intended for use in
+          internal NixOS tests, and gave the false impression of it
+          being a special display manager when it's actually LightDM.
+          Please use the
+          <literal>services.xserver.displayManager.lightdm.autoLogin</literal>
+          options instead, or any other display manager in NixOS as they
+          all support auto-login. If you used this module specifically
+          because it permitted root auto-login you can override the
+          lightdm-autologin pam module like:
+        </para>
+        <programlisting language="bash">
+{
+  security.pam.services.lightdm-autologin.text = lib.mkForce ''
+      auth     requisite pam_nologin.so
+      auth     required  pam_succeed_if.so quiet
+      auth     required  pam_permit.so
+
+      account  include   lightdm
+
+      password include   lightdm
+
+      session  include   lightdm
+  '';
+}
+</programlisting>
+        <para>
+          The difference is the:
+        </para>
+        <programlisting>
+auth required pam_succeed_if.so quiet
+</programlisting>
+        <para>
+          line, where default it's:
+        </para>
+        <programlisting>
+ auth required pam_succeed_if.so uid &gt;= 1000 quiet
+</programlisting>
+        <para>
+          not permitting users with uid's below 1000 (like root). All
+          other display managers in NixOS are configured like this.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There have been lots of improvements to the Mailman module. As
+          a result,
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              The <literal>services.mailman.hyperkittyBaseUrl</literal>
+              option has been renamed to
+              <link xlink:href="options.html#opt-services.mailman.hyperkitty.baseUrl">services.mailman.hyperkitty.baseUrl</link>.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              The <literal>services.mailman.hyperkittyApiKey</literal>
+              option has been removed. This is because having an option
+              for the Hyperkitty API key meant that the API key would be
+              stored in the world-readable Nix store, which was a
+              security vulnerability. A new Hyperkitty API key will be
+              generated the first time the new Hyperkitty service is
+              run, and it will then be persisted outside of the Nix
+              store. To continue using Hyperkitty, you must set
+              <link xlink:href="options.html#opt-services.mailman.hyperkitty.enable">services.mailman.hyperkitty.enable</link>
+              to <literal>true</literal>.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              Additionally, some Postfix configuration must now be set
+              manually instead of automatically by the Mailman module:
+            </para>
+            <programlisting language="bash">
+{
+  services.postfix.relayDomains = [ &quot;hash:/var/lib/mailman/data/postfix_domains&quot; ];
+  services.postfix.config.transport_maps = [ &quot;hash:/var/lib/mailman/data/postfix_lmtp&quot; ];
+  services.postfix.config.local_recipient_maps = [ &quot;hash:/var/lib/mailman/data/postfix_lmtp&quot; ];
+}
+</programlisting>
+            <para>
+              This is because some users may want to include other
+              values in these lists as well, and this was not possible
+              if they were set automatically by the Mailman module. It
+              would not have been possible to just concatenate values
+              from multiple modules each setting the values they needed,
+              because the order of elements in the list is significant.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          The LLVM versions 3.5, 3.9 and 4 (including the corresponding
+          CLang versions) have been dropped.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The
+          <literal>networking.interfaces.*.preferTempAddress</literal>
+          option has been replaced by
+          <literal>networking.interfaces.*.tempAddress</literal>. The
+          new option allows better control of the IPv6 temporary
+          addresses, including completely disabling them for interfaces
+          where they are not needed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Rspamd was updated to version 2.2. Read
+          <link xlink:href="https://rspamd.com/doc/migration.html#migration-to-rspamd-20">
+          the upstream migration notes</link> carefully. Please be
+          especially aware that some modules were removed and the
+          default Bayes backend is now Redis.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>*psu</literal> versions of oraclejdk8 have been
+          removed as they aren't provided by upstream anymore.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>services.dnscrypt-proxy</literal> module has been
+          removed as it used the deprecated version of dnscrypt-proxy.
+          We've added
+          <link xlink:href="options.html#opt-services.dnscrypt-proxy2.enable">services.dnscrypt-proxy2.enable</link>
+          to use the supported version. This module supports
+          configuration via the Nix attribute set
+          <link xlink:href="options.html#opt-services.dnscrypt-proxy2.settings">services.dnscrypt-proxy2.settings</link>,
+          or by passing a TOML configuration file via
+          <link xlink:href="options.html#opt-services.dnscrypt-proxy2.configFile">services.dnscrypt-proxy2.configFile</link>.
+        </para>
+        <programlisting language="bash">
+{
+  # Example configuration:
+  services.dnscrypt-proxy2.enable = true;
+  services.dnscrypt-proxy2.settings = {
+    listen_addresses = [ &quot;127.0.0.1:43&quot; ];
+    sources.public-resolvers = {
+      urls = [ &quot;https://download.dnscrypt.info/resolvers-list/v2/public-resolvers.md&quot; ];
+      cache_file = &quot;public-resolvers.md&quot;;
+      minisign_key = &quot;RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3&quot;;
+      refresh_delay = 72;
+    };
+  };
+
+  services.dnsmasq.enable = true;
+  services.dnsmasq.servers = [ &quot;127.0.0.1#43&quot; ];
+}
+</programlisting>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>qesteidutil</literal> has been deprecated in favor of
+          <literal>qdigidoc</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          sqldeveloper_18 has been removed as it's not maintained
+          anymore, sqldeveloper has been updated to version
+          <literal>19.4</literal>. Please note that this means that this
+          means that the oraclejdk is now required. For further
+          information please read the
+          <link xlink:href="https://www.oracle.com/technetwork/developer-tools/sql-developer/downloads/sqldev-relnotes-194-5908846.html">release
+          notes</link>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Haskell <literal>env</literal> and <literal>shellFor</literal>
+          dev shell environments now organize dependencies the same way
+          as regular builds. In particular, rather than receiving all
+          the different lists of dependencies mashed together as one big
+          list, and then partitioning into Haskell and non-Hakell
+          dependencies, they work from the original many different
+          dependency parameters and don't need to algorithmically
+          partition anything.
+        </para>
+        <para>
+          This means that if you incorrectly categorize a dependency,
+          e.g. non-Haskell library dependency as a
+          <literal>buildDepends</literal> or run-time Haskell dependency
+          as a <literal>setupDepends</literal>, whereas things would
+          have worked before they may not work now.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The gcc-snapshot-package has been removed. It's marked as
+          broken for &gt;2 years and used to point to a fairly old
+          snapshot from the gcc7-branch.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The nixos-build-vms8 -script now uses the python test-driver.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The riot-web package now accepts configuration overrides as an
+          attribute set instead of a string. A formerly used JSON
+          configuration can be converted to an attribute set with
+          <literal>builtins.fromJSON</literal>.
+        </para>
+        <para>
+          The new default configuration also disables automatic guest
+          account registration and analytics to improve privacy. The
+          previous behavior can be restored by setting
+          <literal>config.riot-web.conf = { disable_guests = false; piwik = true; }</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Stand-alone usage of <literal>Upower</literal> now requires
+          <literal>services.upower.enable</literal> instead of just
+          installing into
+          <link xlink:href="options.html#opt-environment.systemPackages">environment.systemPackages</link>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          nextcloud has been updated to <literal>v18.0.2</literal>. This
+          means that users from NixOS 19.09 can't upgrade directly since
+          you can only move one version forward and 19.09 uses
+          <literal>v16.0.8</literal>.
+        </para>
+        <para>
+          To provide a safe upgrade-path and to circumvent similar
+          issues in the future, the following measures were taken:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              The pkgs.nextcloud-attribute has been removed and replaced
+              with versioned attributes (currently pkgs.nextcloud17 and
+              pkgs.nextcloud18). With this change major-releases can be
+              backported without breaking stuff and to make
+              upgrade-paths easier.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              Existing setups will be detected using
+              <link xlink:href="options.html#opt-system.stateVersion">system.stateVersion</link>:
+              by default, nextcloud17 will be used, but will raise a
+              warning which notes that after that deploy it's
+              recommended to update to the latest stable version
+              (nextcloud18) by declaring the newly introduced setting
+              <link xlink:href="options.html#opt-services.nextcloud.package">services.nextcloud.package</link>.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              Users with an overlay (e.g. to use nextcloud at version
+              <literal>v18</literal> on <literal>19.09</literal>) will
+              get an evaluation error by default. This is done to ensure
+              that our
+              <link xlink:href="options.html#opt-services.nextcloud.package">package</link>-option
+              doesn't select an older version by accident. It's
+              recommended to use pkgs.nextcloud18 or to set
+              <link xlink:href="options.html#opt-services.nextcloud.package">package</link>
+              to pkgs.nextcloud explicitly.
+            </para>
+          </listitem>
+        </itemizedlist>
+        <warning>
+          <para>
+            Please note that if you're coming from
+            <literal>19.03</literal> or older, you have to manually
+            upgrade to <literal>19.09</literal> first to upgrade your
+            server to Nextcloud v16.
+          </para>
+        </warning>
+      </listitem>
+      <listitem>
+        <para>
+          Hydra has gained a massive performance improvement due to
+          <link xlink:href="https://github.com/NixOS/hydra/pull/710">some
+          database schema changes</link> by adding several IDs and
+          better indexing. However, it's necessary to upgrade Hydra in
+          multiple steps:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              At first, an older version of Hydra needs to be deployed
+              which adds those (nullable) columns. When having set
+              <link xlink:href="options.html#opt-system.stateVersion">stateVersion
+              </link> to a value older than <literal>20.03</literal>,
+              this package will be selected by default from the module
+              when upgrading. Otherwise, the package can be deployed
+              using the following config:
+            </para>
+            <programlisting language="bash">
+{ pkgs, ... }: {
+  services.hydra.package = pkgs.hydra-migration;
+}
+</programlisting>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          Automatically fill the newly added ID columns on the server by
+          running the following command:
+        </para>
+        <programlisting>
+$ hydra-backfill-ids
+</programlisting>
+        <warning>
+          <para>
+            Please note that this process can take a while depending on
+            your database-size!
+          </para>
+        </warning>
+      </listitem>
+      <listitem>
+        <para>
+          Deploy a newer version of Hydra to activate the DB
+          optimizations. This can be done by using hydra-unstable. This
+          package already includes
+          <link xlink:href="https://github.com/nixos/rfcs/pull/49">flake-support</link>
+          and is therefore compiled against pkgs.nixFlakes.
+        </para>
+        <warning>
+          <para>
+            If your
+            <link xlink:href="options.html#opt-system.stateVersion">stateVersion</link>
+            is set to <literal>20.03</literal> or greater,
+            hydra-unstable will be used automatically! This will break
+            your setup if you didn't run the migration.
+          </para>
+        </warning>
+        <para>
+          Please note that Hydra is currently not available with
+          nixStable as this doesn't compile anymore.
+        </para>
+        <warning>
+          <para>
+            pkgs.hydra has been removed to ensure a graceful
+            database-migration using the dedicated package-attributes.
+            If you still have pkgs.hydra defined in e.g. an overlay, an
+            assertion error will be thrown. To circumvent this, you need
+            to set
+            <link xlink:href="options.html#opt-services.hydra.package">services.hydra.package</link>
+            to pkgs.hydra explicitly and make sure you know what you're
+            doing!
+          </para>
+        </warning>
+      </listitem>
+      <listitem>
+        <para>
+          The TokuDB storage engine will be disabled in mariadb 10.5. It
+          is recommended to switch to RocksDB. See also
+          <link xlink:href="https://mariadb.com/kb/en/tokudb/">TokuDB</link>.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+  <section xml:id="sec-release-20.03-notable-changes">
+    <title>Other Notable Changes</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          SD images are now compressed by default using
+          <literal>bzip2</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The nginx web server previously started its master process as
+          root privileged, then ran worker processes as a less
+          privileged identity user (the <literal>nginx</literal> user).
+          This was changed to start all of nginx as a less privileged
+          user (defined by <literal>services.nginx.user</literal> and
+          <literal>services.nginx.group</literal>). As a consequence,
+          all files that are needed for nginx to run (included
+          configuration fragments, SSL certificates and keys, etc.) must
+          now be readable by this less privileged user/group.
+        </para>
+        <para>
+          To continue to use the old approach, you can configure:
+        </para>
+        <programlisting language="bash">
+{
+  services.nginx.appendConfig = let cfg = config.services.nginx; in ''user ${cfg.user} ${cfg.group};'';
+  systemd.services.nginx.serviceConfig.User = lib.mkForce &quot;root&quot;;
+}
+</programlisting>
+      </listitem>
+      <listitem>
+        <para>
+          OpenSSH has been upgraded from 7.9 to 8.1, improving security
+          and adding features but with potential incompatibilities.
+          Consult the
+          <link xlink:href="https://www.openssh.com/txt/release-8.1">
+          release announcement</link> for more information.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>PRETTY_NAME</literal> in
+          <literal>/etc/os-release</literal> now uses the short rather
+          than full version string.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The ACME module has switched from simp-le to
+          <link xlink:href="https://github.com/go-acme/lego">lego</link>
+          which allows us to support DNS-01 challenges and wildcard
+          certificates. The following options have been added:
+          <link xlink:href="options.html#opt-security.acme.acceptTerms">security.acme.acceptTerms</link>,
+          <link xlink:href="options.html#opt-security.acme.certs">security.acme.certs.&lt;name&gt;.dnsProvider</link>,
+          <link xlink:href="options.html#opt-security.acme.certs">security.acme.certs.&lt;name&gt;.credentialsFile</link>,
+          <link xlink:href="options.html#opt-security.acme.certs">security.acme.certs.&lt;name&gt;.dnsPropagationCheck</link>.
+          As well as this, the options
+          <literal>security.acme.acceptTerms</literal> and either
+          <literal>security.acme.email</literal> or
+          <literal>security.acme.certs.&lt;name&gt;.email</literal> must
+          be set in order to use the ACME module. Certificates will be
+          regenerated on activation, no account or certificate will be
+          migrated from simp-le. In particular private keys will not be
+          preserved. However, the credentials for simp-le are preserved
+          and thus it is possible to roll back to previous versions
+          without breaking certificate generation. Note also that in
+          contrary to simp-le a new private key is recreated at each
+          renewal by default, which can have consequences if you embed
+          your public key in apps.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          It is now possible to unlock LUKS-Encrypted file systems using
+          a FIDO2 token via
+          <literal>boot.initrd.luks.fido2Support</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Predictably named network interfaces get renamed in stage-1.
+          This means that it is possible to use the proper interface
+          name for e.g. Dropbear setups.
+        </para>
+        <para>
+          For further reference, please read
+          <link xlink:href="https://github.com/NixOS/nixpkgs/pull/68953">#68953</link>
+          or the corresponding
+          <link xlink:href="https://discourse.nixos.org/t/predictable-network-interface-names-in-initrd/4055">discourse
+          thread</link>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The matrix-synapse-package has been updated to
+          <link xlink:href="https://github.com/matrix-org/synapse/releases/tag/v1.11.1">v1.11.1</link>.
+          Due to
+          <link xlink:href="https://github.com/matrix-org/synapse/releases/tag/v1.10.0rc1">stricter
+          requirements</link> for database configuration when using
+          postgresql, the automated database setup of the module has
+          been removed to avoid any further edge-cases.
+        </para>
+        <para>
+          matrix-synapse expects <literal>postgresql</literal>-databases
+          to have the options <literal>LC_COLLATE</literal> and
+          <literal>LC_CTYPE</literal> set to
+          <link xlink:href="https://www.postgresql.org/docs/12/locale.html"><literal>'C'</literal></link>
+          which basically instructs <literal>postgresql</literal> to
+          ignore any locale-based preferences.
+        </para>
+        <para>
+          Depending on your setup, you need to incorporate one of the
+          following changes in your setup to upgrade to 20.03:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              If you use <literal>sqlite3</literal> you don't need to do
+              anything.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              If you use <literal>postgresql</literal> on a different
+              server, you don't need to change anything as well since
+              this module was never designed to configure remote
+              databases.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              If you use <literal>postgresql</literal> and configured
+              your synapse initially on <literal>19.09</literal> or
+              older, you simply need to enable postgresql-support
+              explicitly:
+            </para>
+            <programlisting language="bash">
+{ ... }: {
+  services.matrix-synapse = {
+    enable = true;
+    /* and all the other config you've defined here */
+  };
+  services.postgresql.enable = true;
+}
+</programlisting>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          If you deploy a fresh matrix-synapse, you need to configure
+          the database yourself (e.g. by using the
+          <link xlink:href="options.html#opt-services.postgresql.initialScript">services.postgresql.initialScript</link>
+          option). An example for this can be found in the
+          <link linkend="module-services-matrix">documentation of the
+          Matrix module</link>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          If you initially deployed your matrix-synapse on
+          <literal>nixos-unstable</literal> <emphasis>after</emphasis>
+          the <literal>19.09</literal>-release, your database is
+          misconfigured due to a regression in NixOS. For now,
+          matrix-synapse will startup with a warning, but it's
+          recommended to reconfigure the database to set the values
+          <literal>LC_COLLATE</literal> and <literal>LC_CTYPE</literal>
+          to
+          <link xlink:href="https://www.postgresql.org/docs/12/locale.html"><literal>'C'</literal></link>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The
+          <link xlink:href="options.html#opt-systemd.network.links">systemd.network.links</link>
+          option is now respected even when
+          <link xlink:href="options.html#opt-systemd.network.enable">systemd-networkd</link>
+          is disabled. This mirrors the behaviour of systemd - It's udev
+          that parses <literal>.link</literal> files, not
+          <literal>systemd-networkd</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          mongodb has been updated to version <literal>3.4.24</literal>.
+        </para>
+        <warning>
+          <para>
+            Please note that mongodb has been relicensed under their own
+            <link xlink:href="https://www.mongodb.com/licensing/server-side-public-license/faq"><literal> sspl</literal></link>-license.
+            Since it's not entirely free and not OSI-approved, it's
+            listed as non-free. This means that Hydra doesn't provide
+            prebuilt mongodb-packages and needs to be built locally.
+          </para>
+        </warning>
+      </listitem>
+    </itemizedlist>
+  </section>
+</section>