depot/third_party/nixpkgs/nixos/doc/manual/release-notes/rl-2009.xml

<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-release-20.09">
 <title>Release 20.09 (“Nightingale”, 2020.09/??)</title>

 <section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-release-20.09-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 April 2021, handing over to 21.03.
    </para>
   </listitem>
   <listitem>
    <para>GNOME desktop environment was upgraded to 3.36, see its <link xlink:href="https://help.gnome.org/misc/release-notes/3.36/">release notes</link>.</para>
   </listitem>
   <listitem>
    <para>
     We now distribute a GNOME ISO.
    </para>
   </listitem>
   <listitem>
    <para>
     PHP now defaults to PHP 7.4, updated from 7.3.
    </para>
   </listitem>
   <listitem>
    <para>
     Two new options, <link linkend="opt-services.openssh.authorizedKeysCommand">authorizedKeysCommand</link>
     and <link linkend="opt-services.openssh.authorizedKeysCommandUser">authorizedKeysCommandUser</link>, have
     been added to the <literal>openssh</literal> module. If you have <literal>AuthorizedKeysCommand</literal>
     in your <link linkend="opt-services.openssh.extraConfig">services.openssh.extraConfig</link> you should
     make use of these new options instead.
    </para>
   </listitem>
   <listitem>
    <para>
     There is a new module for Podman(<varname>virtualisation.podman</varname>), a drop-in replacement for the Docker command line.
    </para>
   </listitem>
   <listitem>
    <para>
     The new <varname>virtualisation.containers</varname> module manages configuration shared by the CRI-O and Podman modules.
    </para>
   </listitem>
   <listitem>
    <para>
      Declarative Docker containers are renamed from <varname>docker-containers</varname> to <varname>virtualisation.oci-containers.containers</varname>.
      This is to make it possible to use <literal>podman</literal> instead of <literal>docker</literal>.
    </para>
   </listitem>
   <listitem>
    <para>
      MariaDB has been updated to 10.4, MariaDB Galera to 26.4.
      Before you upgrade, it would be best to take a backup of your database.
      For MariaDB Galera Cluster, see <link xlink:href="https://mariadb.com/kb/en/upgrading-from-mariadb-103-to-mariadb-104-with-galera-cluster/">Upgrading
      from MariaDB 10.3 to MariaDB 10.4 with Galera Cluster</link> instead.
      Before doing the upgrade read <link xlink:href="https://mariadb.com/kb/en/upgrading-from-mariadb-103-to-mariadb-104/#incompatible-changes-between-103-and-104">Incompatible
      Changes Between 10.3 and 10.4</link>.
      After the upgrade you will need to run <literal>mysql_upgrade</literal>.
      MariaDB 10.4 introduces a number of changes to the authentication process, intended to make things easier and more
      intuitive. See <link xlink:href="https://mariadb.com/kb/en/authentication-from-mariadb-104/">Authentication from MariaDB 10.4</link>.
      unix_socket auth plugin does not use a password, and uses the connecting user's UID instead. When a new MariaDB data directory is initialized, two MariaDB users are
      created and can be used with new unix_socket auth plugin, as well as traditional mysql_native_password plugin: root@localhost and mysql@localhost. To actually use
      the traditional mysql_native_password plugin method, one must run the following:
<programlisting>
services.mysql.initialScript = pkgs.writeText "mariadb-init.sql" ''
  ALTER USER root@localhost IDENTIFIED VIA mysql_native_password USING PASSWORD("verysecret");
'';
</programlisting>
      When MariaDB data directory is just upgraded (not initialized), the users are not created or modified.
    </para>
   </listitem>
  </itemizedlist>
 </section>

 <section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-release-20.09-new-services">
  <title>New Services</title>

  <para>
   The following new services were added since the last release:
  </para>

  <itemizedlist>
   <listitem>
    <para>
      There is a new <xref linkend="opt-security.doas.enable"/> module that provides <command>doas</command>, a lighter alternative to <command>sudo</command> with many of the same features.
    </para>
   </listitem>
  </itemizedlist>

 </section>

 <section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-release-20.09-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 go-modules builder now uses vendorSha256 instead of modSha256 to pin
     fetched version data. This is currently a warning, but will be removed in the next release.
    </para>
   </listitem>
   <listitem>
    <para>
     Grafana is now built without support for phantomjs by default. Phantomjs support has been
     <link xlink:href="https://grafana.com/docs/grafana/latest/guides/whats-new-in-v6-4/">deprecated in Grafana</link>
     and the <package>phantomjs</package> project is
     <link xlink:href="https://github.com/ariya/phantomjs/issues/15344#issue-302015362">currently unmaintained</link>.
     It can still be enabled by providing <literal>phantomJsSupport = true</literal> to the package instanciation:
<programlisting>{
  services.grafana.package = pkgs.grafana.overrideAttrs (oldAttrs: rec {
    phantomJsSupport = false;
  });
}</programlisting>
    </para>
   </listitem>
   <listitem>
    <para>
      The <link linkend="opt-services.supybot.enable">supybot</link> module now uses <literal>/var/lib/supybot</literal>
      as its default <link linkend="opt-services.supybot.stateDir">stateDir</link> path if <literal>stateVersion</literal>
      is 20.09 or higher. It also enables number of
      <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing">systemd sandboxing options</link>
      which may possibly interfere with some plugins. If this is the case you can disable the options through attributes in
      <option>systemd.services.supybot.serviceConfig</option>.
    </para>
   </listitem>
   <listitem>
    <para>
      The <literal>security.duosec.skey</literal> option, which stored a secret in the
      nix store, has been replaced by a new
      <link linkend="opt-security.duosec.secretKeyFile">security.duosec.secretKeyFile</link>
      option for better security.
    </para>
    <para>
      <literal>security.duosec.ikey</literal> has been renamed to
      <link linkend="opt-security.duosec.integrationKey">security.duosec.integrationKey</link>.
    </para>
   </listitem>
   <listitem>
    <para>
     The initrd SSH support now uses OpenSSH rather than Dropbear to
     allow the use of Ed25519 keys and other OpenSSH-specific
     functionality. Host keys must now be in the OpenSSH format, and at
     least one pre-generated key must be specified.
    </para>
    <para>
     If you used the <option>boot.initrd.network.ssh.host*Key</option>
     options, you'll get an error explaining how to convert your host
     keys and migrate to the new
     <option>boot.initrd.network.ssh.hostKeys</option> option.
     Otherwise, if you don't have any host keys set, you'll need to
     generate some; see the <option>hostKeys</option> option
     documentation for instructions.
    </para>
   </listitem>
   <listitem>
     <para>
       Since this release there's an easy way to customize your PHP
       install to get a much smaller base PHP with only wanted
       extensions enabled. See the following snippet installing a
       smaller PHP with the extensions <literal>imagick</literal>,
       <literal>opcache</literal>, <literal>pdo</literal> and
       <literal>pdo_mysql</literal> loaded:

       <programlisting>
environment.systemPackages = [
  (pkgs.php.withExtensions
    ({ all, ... }: with all; [
      imagick
      opcache
      pdo
      pdo_mysql
    ])
  )
];</programlisting>

       The default <literal>php</literal> attribute hasn't lost any
       extensions. The <literal>opcache</literal> extension has been
       added.

       All upstream PHP extensions are available under <package><![CDATA[php.extensions.<name?>]]></package>.
     </para>
     <para>
       All PHP <literal>config</literal> flags have been removed for
       the following reasons:

       <itemizedlist>
         <listitem>
           <para>
             The updated <literal>php</literal> attribute is now easily
             customizable to your liking by using
             <literal>php.withExtensions</literal> or
             <literal>php.buildEnv</literal> instead of writing config files
             or changing configure flags.
           </para>
         </listitem>
         <listitem>
           <para>
             The remaining configuration flags can now be set directly on
             the <literal>php</literal> attribute. For example, instead of

             <programlisting>
php.override {
  config.php.embed = true;
  config.php.apxs2 = false;
}
             </programlisting>

             you should now write

             <programlisting>
php.override {
  embedSupport = true;
  apxs2Support = false;
}
             </programlisting>
           </para>
         </listitem>
       </itemizedlist>

     </para>
   </listitem>
   <listitem>
     <para>
      Gollum received a major update to version 5.x and you may have to change
      some links in your wiki when migrating from gollum 4.x. More information
      can be found
      <link xlink:href="https://github.com/gollum/gollum/wiki/5.0-release-notes#migrating-your-wiki">here</link>.
     </para>
   </listitem>
   <listitem>
     <para>
       Deluge 2.x was added and is used as default for new NixOS
       installations where stateVersion is >= 20.09. If you are upgrading from a previous
       NixOS version, you can set <literal>service.deluge.package = pkgs.deluge-2_x</literal>
       to upgrade to Deluge 2.x and migrate the state to the new format.
       Be aware that backwards state migrations are not supported by Deluge.
     </para>
   </listitem>
   <listitem>
     <para>
       Add option <literal>services.nginx.enableSandbox</literal> to starting Nginx web server with additional sandbox/hardening options.
       By default, write access to <literal>services.nginx.stateDir</literal> is allowed. To allow writing to other folders,
       use <literal>systemd.services.nginx.serviceConfig.ReadWritePaths</literal>
       <programlisting>
systemd.services.nginx.serviceConfig.ReadWritePaths = [ "/var/www" ];
       </programlisting>
     </para>
   </listitem>
   <listitem>
    <para>
      The NixOS options <literal>nesting.clone</literal> and
      <literal>nesting.children</literal> have been deleted, and
      replaced with named <xref linkend="opt-specialisation"/>
      configurations.
    </para>

    <para>
      Replace a <literal>nesting.clone</literal> entry with:

<programlisting>{
<link xlink:href="#opt-specialisation">specialisation.example-sub-configuration</link> = {
  <link xlink:href="#opt-specialisation._name_.configuration">configuration</link> = {
    ...
  };
};</programlisting>

    </para>
    <para>
      Replace a <literal>nesting.children</literal> entry with:

<programlisting>{
<link xlink:href="#opt-specialisation">specialisation.example-sub-configuration</link> = {
  <link xlink:href="#opt-specialisation._name_.inheritParentConfig">inheritParentConfig</link> = false;
  <link xlink:href="#opt-specialisation._name_.configuration">configuration</link> = {
    ...
  };
};</programlisting>
    </para>

    <para>
     To switch to a specialised configuration at runtime you need to
     run:
<programlisting>
# sudo /run/current-system/specialisation/example-sub-configuration/bin/switch-to-configuration test
</programlisting>
     Before you would have used:
<programlisting>
# sudo /run/current-system/fine-tune/child-1/bin/switch-to-configuration test
</programlisting>
    </para>
   </listitem>
   <listitem>
    <para>
      The Nginx log directory has been moved to <literal>/var/log/nginx</literal>, the cache directory
      to <literal>/var/cache/nginx</literal>. The option <literal>services.nginx.stateDir</literal> has
      been removed.
    </para>
   </listitem>
   <listitem>
    <para>
     The httpd web server previously started its main process as root
     privileged, then ran worker processes as a less privileged identity user.
     This was changed to start all of httpd as a less privileged user (defined by
     <xref linkend="opt-services.httpd.user"/> and
     <xref linkend="opt-services.httpd.group"/>). As a consequence, all files that
     are needed for httpd to run (included configuration fragments, SSL
     certificates and keys, etc.) must now be readable by this less privileged
     user/group.
    </para>
    <para>
     The default value for <xref linkend="opt-services.httpd.mpm"/>
     has been changed from <literal>prefork</literal> to <literal>event</literal>. Along with
     this change the default value for
     <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.http2</link>
     has been set to <literal>true</literal>.
    </para>
   </listitem>
   <listitem>
    <para>
      The <literal>systemd-networkd</literal> option
      <literal>systemd.network.networks.&lt;name&gt;.dhcp.CriticalConnection</literal>
      has been removed following upstream systemd's deprecation of the same. It is recommended to use
      <literal>systemd.network.networks.&lt;name&gt;.networkConfig.KeepConfiguration</literal> instead.
      See <citerefentry><refentrytitle>systemd.network</refentrytitle>
      <manvolnum>5</manvolnum></citerefentry> for details.
    </para>
   </listitem>
   <listitem>
    <para>
     The <literal>systemd-networkd</literal> option
     <literal>systemd.network.networks._name_.dhcpConfig</literal>
     has been renamed to
     <xref linkend="opt-systemd.network.networks._name_.dhcpV4Config"/>
     following upstream systemd's documentation change.
     See <citerefentry><refentrytitle>systemd.network</refentrytitle>
     <manvolnum>5</manvolnum></citerefentry> for details.
    </para>
   </listitem>
   <listitem>
    <para>
      In the <literal>picom</literal> module, several options that accepted
      floating point numbers encoded as strings (for example
      <xref linkend="opt-services.picom.activeOpacity"/>) have been changed
      to the (relatively) new native <literal>float</literal> type. To migrate
      your configuration simply remove the quotes around the numbers.
    </para>
   </listitem>
   <listitem>
    <para>
      When using <literal>buildBazelPackage</literal> from Nixpkgs,
      <literal>flat</literal> hash mode is now used for dependencies
      instead of <literal>recursive</literal>. This is to better allow
      using hashed mirrors where needed. As a result, these hashes
      will have changed.
    </para>
   </listitem>
  </itemizedlist>
 </section>

 <section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-release-20.09-notable-changes">
  <title>Other Notable Changes</title>

  <itemizedlist>
   <listitem>
    <para>
     <option>services.journald.rateLimitBurst</option> was updated from
     <literal>1000</literal> to <literal>10000</literal> to follow the new
     upstream systemd default.
    </para>
   </listitem>
   <listitem>
    <para>
     The <package>notmuch</package> package move its emacs-related binaries and
     emacs lisp files to a separate output. They're not part
     of the default <literal>out</literal> output anymore - if you relied on the
     <literal>notmuch-emacs-mua</literal> binary or the emacs lisp files, access them via
     the <literal>notmuch.emacs</literal> output.
    </para>
   </listitem>
   <listitem>
   <para>
     The default output of <literal>buildGoPackage</literal> is now <literal>$out</literal> instead of <literal>$bin</literal>.
   </para>
   </listitem>
  </itemizedlist>
 </section>
</section>