doc: add a "Remote access" section about mDNS

docs/user/interactive.md

@@ -129,12 +129,23 @@ might want to access remotely to the installer. If you know the IP address of th
 need to point your browser to `https://$IP`.
 
 For the case you do not know the address, or just for convenience, the Live ISO is configured to use
-mDNS (sometimes called Avahi, Zeroconf, Bonjour) for hostname resolution. Therefore, connecting to
-`https://agama.local` should do the trick.
+[Multicast DNS](https://en.wikipedia.org/wiki/Multicast_DNS) (sometimes called mDNS, Avahi,
+Zeroconf, Bonjour) for hostname resolution. Therefore, connecting to `https://agama.local` should do
+the trick.
 
 :::warning Beware of the `.local` hostname
 Do not use the `.local` hostnames in untrusted networks (like public WiFi networks, shared
 networks), it is a security risk. An attacker can easily send malicious responses for the `.local`
 hostname resolutions and point you to a wrong Agama instance which could for example steal your root
 password!
 :::
+
+The mDNS resolution also works for other services like ping or SSH. So you can use commands like:
+
+```shell
+ping agama.local
+ssh root@agama.local
+```
+
+If you want to know more about the mDNS support, please check the [remote access
+documentation](./remote.md).

docs/user/remote.md

@@ -0,0 +1,84 @@
+# Remote access
+
+Agama's Live ISO is configured to use [Multicast DNS](https://en.wikipedia.org/wiki/Multicast_DNS)
+(sometimes called mDNS, Avahi, Zeroconf, Bonjour) for hostname resolution. This protocol makes it
+easier to connect to an Agama instance using a predefined hostname.
+
+This document explains how this feature works and offers a few hints for fix potential problems.
+
+:::warning
+Do not use the `.local` hostnames in untrusted networks (like public WiFi networks, shared
+networks), it is a security risk. An attacker can easily send malicious responses for the `.local`
+hostname resolutions and point you to a wrong Agama instance which could for example steal your root
+password!
+:::
+
+## Firewall Configuration
+
+If you cannot connect to a server using the `.local` domain then maybe the
+firewall is blocking the traffic. Then you need to enable the mDNS traffic using
+these commands:
+
+```shell
+# enable the mDNS traffic in the current run
+firewall-cmd --zone=public --add-service=mdns
+# make the change permanent
+firewall-cmd --permanent --zone=public --add-service=mdns
+```
+
+## Using mDNS
+
+The Live ISO by default uses the `agama.local` hostname. To connect to the running instance simply
+type `https://agama.local` in your browser. In most browsers the HTTPS is the default protocol so
+usually it is enough to just type `agama.local`.
+
+If you run multiple Agama instances, each one will have a different name. The server appends a
+number to make it unique. So the second Agama instance gets the `agama-2.local` hostname.
+
+If you are not sure whether there are multiple Agama instances running you scan the network, see the
+[service advertising](#service-advertising) below.
+
+Alternatively you can set a different hostname for each instance manually. Use the `hostname=` boot
+option to set a different hostname. For example set `hostname=foo`, `hostname=bar` and then use
+`https://foo.local`, `https://bar.local` URLs in the web browser to connect to the respective
+instance.
+
+It is possible to change the hostname later if needed:
+
+```shell
+# set the new hostname
+hostnamectl hostname <hostname>
+# restart the avahi daemon server
+systemctl restart avahi-daemon
+```
+
+The mDNS resolution also works for other services like ping or SSH. So you can use commands like:
+
+```shell
+ping agama.local
+ssh root@agama.local
+```
+
+## Fallback
+
+The mDNS approach is just an addition, one more possibility how to connect to the machine. If it
+does not work for you then you can always use the old good classic IP address approach.
+
+## Service Advertising
+
+The Agama Live ISO also uses Avahi service advertising. With this you can easily search for all
+running Agama instances in the local network:
+
+```shell
+avahi-browse -t -r _agama._sub._https._tcp
+```
+
+The command will print the found servers and their hostnames and IP addresses.
+
+## Notes
+
+- mDNS works only in the same local network, it does not work over internet or separate network
+  segments.
+- mDNS might not be supported in all systems or it might be blocked by firewall.
+- On mobile phones with Android OS mDNS is supported since Android version 12. But this might depend
+  on the vendor.