<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>
