New upstream version 1.27.90 upstream/1.27.90

1 files changed, 62 insertions, 13 deletions

diff --git a/docs/api/html/NetworkManager.html b/docs/api/html/NetworkManager.html
index f25c6299..47cc602d 100644
--- a/docs/api/html/NetworkManager.html
+++ b/docs/api/html/NetworkManager.html
@@ -508,29 +508,78 @@
 <div class="refsect1">
 <a name="id-1.2.2.10"></a><h2>Debugging</h2>
 <p>
-      The following environment variables are supported to help
-      debugging.  When used in conjunction with the
-      <code class="option">--no-daemon</code> option (thus echoing PPP and DHCP
-      helper output to stdout) these can quickly help pinpoint the
-      source of connection issues.  Also see the
-      <code class="option">--log-level</code> and <code class="option">--log-domains</code>
-      to enable debug logging inside NetworkManager itself.
+      NetworkManager only configures your system. So when your networking setup doesn't
+      work as expected, the first step is to look at your system to understand what is actually
+      configured, and whether that is correct. The second step is to find out how to tell
+      NetworkManager to do the right thing.
     </p>
 <p>
-      <code class="option">NM_PPP_DEBUG</code>: When set to anything, causes
-      NetworkManager to turn on PPP debugging in pppd, which logs
-      all PPP and PPTP frames and client/server exchanges.
+      You can for example try to <span class="command"><strong>ping</strong></span> hosts (by
+      IP address or DNS name), look at <span class="command"><strong>ip link show</strong></span>, <span class="command"><strong>ip address show</strong></span> and <span class="command"><strong>ip route show</strong></span>,
+      and look at <code class="filename">/etc/resolv.conf</code> for name resolution issues.
+      Also look at the connection profiles that you have configured in NetworkManager (<span class="command"><strong>nmcli connection</strong></span>
+      and <span class="command"><strong>nmcli connection show "$PROFILE"</strong></span>)
+      and the configured interfaces (<span class="command"><strong>nmcli device</strong></span>).
+    </p>
+<p>
+      If that does not suffice, look at the logfiles of NetworkManager. NetworkManager
+      logs to syslog, so depending on your system configuration you can call <span class="command"><strong>journalctl</strong></span>
+      to get the logs.
+      By default, NetworkManager logs are not verbose and thus not very helpful for investigating
+      a problem in detail. You can change the logging level at runtime with <span class="command"><strong>nmcli general logging level TRACE domains ALL</strong></span>.
+      But usually a better way is to collect full logs from the start, by configuring
+      <code class="literal">level=TRACE</code> in NetworkManager.conf. See
+      <a class="link" href="NetworkManager.conf.html" title="NetworkManager.conf"><span class="citerefentry"><span class="refentrytitle">NetworkManager.conf</span>(5)</span></a>
+      manual. Note that trace logs of NetworkManager are verbose and systemd-journald might rate limit
+      some lines. Possibly disable rate limiting first with the <code class="literal">RateLimitIntervalSec</code> and
+      <code class="literal">RateLimitBurst</code> options of journald (see
+      <span class="citerefentry"><span class="refentrytitle">journald.conf</span>(5)</span> manual).
+    </p>
+</div>
+<div class="refsect1">
+<a name="id-1.2.2.11"></a><h2>/var/lib/NetworkManager/secret_key and /etc/machine-id</h2>
+<p>
+      The identity of a machine is important as various settings depend on it. For example,
+      <code class="literal">ipv6.addr-gen-mode=stable</code> and <code class="literal">ethernet.cloned-mac-address=stable</code>
+      generate identifiers by hashing the machine's identity. See also the
+      <code class="literal">connection.stable-id</code> connection property which is a per-profile seed
+      that gets hashed with the machine identity for generating such addresses and identifiers.
+    </p>
+<p>
+      If you backup and restore a machine, the identity of the machine probably should be preserved.
+      In that case, preserve the files <code class="filename">/var/lib/NetworkManager/secret_key</code> and
+      <code class="literal">/etc/machine-id</code>. On the other hand, if you clone a virtual machine, you
+      probably want that the clone has a different identity. There is already existing tooling on Linux for
+      handling <code class="literal">/etc/machine-id</code> (see
+      <span class="citerefentry"><span class="refentrytitle">machine-id</span>(5)</span>).
+    </p>
+<p>
+      The identity of the machine is determined by the <code class="filename">/var/lib/NetworkManager/secret_key</code>.
+      If such a file does not exist, NetworkManager will create a file with random content. To generate
+      a new identity just delete the file and after restart a new file will be created.
+      The file should be read-only to root and contain at least 16 bytes that will be used to seed the various places
+      where a stable identifier is used.
+    </p>
+<p>
+      Since 1.16.0, NetworkManager supports a version 2 of secret-keys. For such keys
+      <code class="filename">/var/lib/NetworkManager/secret_key</code> starts with ASCII <code class="literal">"nm-v2:"</code>
+      followed by at least 32 bytes of random data.
+      Also, recent versions of NetworkManager always create such kinds of secret-keys, when
+      the file does not yet exist.
+      With version 2 of the secret-key, <code class="literal">/etc/machine-id</code> is also hashed as part
+      of the generation for addresses and identifiers. The advantage is that you can keep <code class="filename">/var/lib/NetworkManager/secret_key</code>
+      stable, and only regenerate <code class="literal">/etc/machine-id</code> when cloning a VM.
     </p>
 </div>
 <div class="refsect1">
-<a name="id-1.2.2.11"></a><h2>Bugs</h2>
+<a name="id-1.2.2.12"></a><h2>Bugs</h2>
 <p>
       Please report any bugs you find in NetworkManager at the
-      <a class="ulink" href="https://bugzilla.gnome.org/enter_bug.cgi?product=NetworkManager" target="_top">NetworkManager bug tracker</a>.
+      <a class="ulink" href="https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues" target="_top">NetworkManager issue tracker</a>.
     </p>
 </div>
 <div class="refsect1">
-<a name="id-1.2.2.12"></a><h2>See Also</h2>
+<a name="id-1.2.2.13"></a><h2>See Also</h2>
 <p>
       <a class="ulink" href="https://wiki.gnome.org/Projects/NetworkManager" target="_top">NetworkManager home page</a>,
       <a class="link" href="NetworkManager.conf.html" title="NetworkManager.conf"><span class="citerefentry"><span class="refentrytitle">NetworkManager.conf</span>(5)</span></a>,