New upstream version 1.48.4 upstream/1.48.4

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/internal/hostname.md b/docs/internal/hostname.md
new file mode 100644
index 00000000..89cf8078
--- /dev/null
+++ b/docs/internal/hostname.md
@@ -0,0 +1,40 @@
+Hostname management
+===================
+
+NetworkManager can update the system hostname via different
+mechanisms. The following diagram describes the workflow:
+
+![Hostname management workflow](hostname.png "Hostname management")
+
+A few notes on the diagram:
+
+ - if there is a static hostname set in `/etc/hostname`, no action is
+   taken. NetworkManager only manages the transient hostname. See the
+   systemd-hostnamed
+   [documentation](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.hostname1.html#Semantics)
+   about the distinction between static and transient hostname.
+
+ - When there is no static hostname set, NetworkManager builds a
+   sorted list of active devices that are eligible for the hostname
+   evaluation. When doing so, the `hostname` setting of the connection
+   active on each device is taken into account. Properties `from-dhcp`
+   and `from-dns-lookup` determine if the two methods must be used for
+   the device; property `only-from-default` determines whether devices
+   without a default route should be considered, and `priority` is
+   used to sort the entries. In case of a tie of the priority, a
+   device with the default route comes first.
+
+ - When evaluating a given device, first NM checks if the device
+   received an hostname via DHCP and then if the first IPv4 and IPv6
+   addresses configured on the interface can be resolved to a name via
+   DNS. The mechanism used to perform the reverse DNS lookup of a
+   specific address is described in the diagram on the right.
+
+ - In the "spawn helper" step, NM starts a separate process that
+   performs the reverse DNS lookup using the NSS services specified
+   (see `man nsswitch.conf`). Service `dns` does the lookup via a DNS
+   query, while `files` returns results from `/etc/hosts`.
+
+ - In case there is no valid result from DHCP or DNS, from any device,
+   if there a valid transient hostname set outside of NetworkManager,
+   that hostname is honored.