diff --git a/docs/internal/hostname.drawio b/docs/internal/hostname.drawio new file mode 100644 index 0000000000..e24a3eed65 --- /dev/null +++ b/docs/internal/hostname.drawio @@ -0,0 +1,252 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/internal/hostname.md b/docs/internal/hostname.md new file mode 100644 index 0000000000..89cf8078b5 --- /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. diff --git a/docs/internal/hostname.png b/docs/internal/hostname.png new file mode 100644 index 0000000000..e9d1b2d680 Binary files /dev/null and b/docs/internal/hostname.png differ