diff --git a/docs/user/interactive.md b/docs/user/interactive.md index afd68af..6948bf9 100644 --- a/docs/user/interactive.md +++ b/docs/user/interactive.md @@ -129,8 +129,9 @@ 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 @@ -138,3 +139,13 @@ networks), it is a security risk. An attacker can easily send malicious response 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). diff --git a/docs/user/remote.md b/docs/user/remote.md new file mode 100644 index 0000000..a6b2c76 --- /dev/null +++ b/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 +# 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.