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>
    <package>maxx</package> package removed along with <varname>services.xserver.desktopManager.maxx</varname> module.
    Please migrate to <package>cdesktopenv</package> and <varname>services.xserver.desktopManager.cde</varname> module.
    </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>
     <literal>buildGoModule</literal> now internally creates a vendor directory
     in the source tree for downloaded modules instead of using go's <link
     xlink:href="https://golang.org/cmd/go/#hdr-Module_proxy_protocol">module
     proxy protocol</link>. This storage format is simpler and therefore less
     likekly to break with future versions of go. As a result
     <literal>buildGoModule</literal> switched from
     <literal>modSha256</literal> to the <literal>vendorSha256</literal>
     attribute to pin fetched version data. <literal>buildGoModule</literal>
     still accepts <literal>modSha256</literal> with a warning, but support 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>
      <literal>vmware</literal> has been removed from the <literal>services.x11.videoDrivers</literal> defaults.
      For VMWare guests set <literal>virtualisation.vmware.guest.enable</literal> to <literal>true</literal> which will include the appropriate drivers.
    </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>
   <listitem>
    <para>
      The rkt module has been removed, it was archived by upstream.
    </para>
   </listitem>
   <listitem>
    <para>
      The <link xlink:href="https://bazaar.canonical.com">Bazaar</link> VCS is
      unmaintained and, as consequence of the Python 2 EOL, the packages
      <literal>bazaar</literal> and <literal>bazaarTools</literal> were
      removed. Breezy, the backward compatible fork of Bazaar (see the
      <link xlink:href="https://www.jelmer.uk/breezy-intro.html">announcement</link>),
      was packaged as <literal>breezy</literal> and can be used instead.
    </para>
    <para>
      Regarding Nixpkgs, <literal>fetchbzr</literal>,
      <literal>nix-prefetch-bzr</literal> and Bazaar support in Hydra will
      continue to work through Breezy.
    </para>
   </listitem>
   <listitem>
     <para>
       In addition to the hostname, the fully qualified domain name (FQDN),
       which consists of <literal>${cfg.hostName}</literal> and
       <literal>${cfg.domain}</literal> is now added to
       <literal>/etc/hosts</literal>, to allow local FQDN resolution, as used by the
       <literal>hostname --fqdn</literal> command and other applications that
       try to determine the FQDN. These new entries take precedence over entries
       from the DNS which could cause regressions in some very specific setups.
       Additionally the hostname is now resolved to <literal>127.0.0.2</literal>
       instead of <literal>127.0.1.1</literal> to be consistent with what
       <literal>nss-myhostname</literal> (from systemd) returns.
       The old behaviour can e.g. be restored by using
       <literal>networking.hosts = lib.mkForce { "127.0.1.1" = [ config.networking.hostName ]; };</literal>.
     </para>
   </listitem>
   <listitem>
     <para>
       The hostname (<literal>networking.hostName</literal>) must now be a valid
       DNS label (see RFC 1035) and as such must not contain the domain part.
       This means that the hostname must start with a letter, end with a letter
       or digit, and have as interior characters only letters, digits, and
       hyphen. The maximum length is 63 characters. Additionally it is
       recommended to only use lower-case characters.
     </para>
   </listitem>
   <listitem>
    <para>
     The GRUB specific option <option>boot.loader.grub.extraInitrd</option>
     has been replaced with the generic option
     <option>boot.initrd.secrets</option>. This option creates a secondary
     initrd from the specified files, rather than using a manually created
     initrd file.

     Due to an existing bug with <option>boot.loader.grub.extraInitrd</option>,
     it is not possible to directly boot an older generation that used that
     option. It is still possible to rollback to that generation if the required
     initrd file has not been deleted.
    </para>
   </listitem>
   <listitem>
    <para>
     The <link xlink:href="https://github.com/okTurtles/dnschain">DNSChain</link>
     package and NixOS module have been removed from Nixpkgs as the software is
     unmaintained and can't be built. For more information see issue
     <link xlink:href="https://github.com/NixOS/nixpkgs/issues/89205">#89205</link>.
    </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>SD and ISO images are now compressed by default using <literal>zstd</literal>.</para>
   </listitem>
   <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>
   <listitem>
   <para>
     The cc- and binutils-wrapper's "infix salt" and <literal>_BUILD_</literal> and <literal>_TARGET_</literal> user infixes have been replaced with with a "suffix salt" and suffixes and <literal>_FOR_BUILD</literal> and <literal>_FOR_TARGET</literal>.
      This matches the autotools convention for env vars which standard for these things, making interfacing with other tools easier.
   </para>
   </listitem>
   <listitem>
   <para>
     Additional Git documentation (HTML and text files) is now available via the <literal>git-doc</literal> package.
   </para>
   </listitem>
   <listitem>
   <para>
     Default algorithm for ZRAM swap was changed to <literal>zstd</literal>.
   </para>
   </listitem>
   <listitem>
    <para>
     The scripted networking system now uses <literal>.link</literal> files in
     <literal>/etc/systemd/network</literal> to configure mac address and link MTU,
     instead of the sometimes buggy <literal>network-link-*</literal> units, which
     have been removed.
     Bringing the interface up has been moved to the beginning of the
     <literal>network-addresses-*</literal> unit.
     Note this doesn't require <command>systemd-networkd</command> - it's udev that
     parses <literal>.link</literal> files.
     Extra care needs to be taken in the presence of <link xlink:href="https://wiki.debian.org/NetworkInterfaceNames#THE_.22PERSISTENT_NAMES.22_SCHEME">legacy udev rules</link>
     to rename interfaces, as MAC Address and MTU defined in these options can only match on the original link name.
     In such cases, you most likely want to create a <literal>10-*.link</literal> file through <xref linkend="opt-systemd.network.links"/> and set both name and MAC Address / MTU there.
    </para>
   </listitem>
   <listitem>
    <para>
     Grafana received a major update to version 7.x. A plugin is now needed for
     image rendering support, and plugins must now be signed by default. More
     information can be found
     <link xlink:href="https://grafana.com/docs/grafana/latest/installation/upgrading/#upgrading-to-v7-0">in the Grafana documentation</link>.
    </para>
   </listitem>
  </itemizedlist>
 </section>
</section>