doc: update discovery document

Signed-off-by: Joachim Wiberg <[email protected]>

Author: troglobit

doc/discovery.md

@@ -39,6 +39,7 @@ admin@fe80::ff:fec0:ffed%tap0's password: admin
 admin@infix-c0-ff-ee:~$ 
 ```
 
+
 ## Discovery mechanisms available in Infix
 
 Infix advertises its presence via the [mDNS](#mdns) and [LLDP](#lldp)
@@ -47,9 +48,10 @@ discovery protocols.
 
 ### LLDP
 
-Infix supports LLDP (IEEE 802.1AB). For a unit with factory default
-settings, the PC can readout the link-local IPv6 address from the
+Infix supports LLDP (IEEE 802.1AB).  For a unit with factory default
+settings, the PC can read out the link-local IPv6 address from the
 Management Address TLV using *tcpdump* or other sniffing tools[^1].
+
 ```
 linux-pc:# tcpdump -i tap0 -Qin -v ether proto 0x88cc
 tcpdump: listening on tap0, link-type EN10MB (Ethernet), snapshot length 262144 bytes
@@ -86,8 +88,9 @@ linux-pc:#
 If the unit has an IPv4 address assigned, it is shown in an additional
 Management Address TLV.
 
-> **Note** The Management Addresses shown by LLDP are not
-> necessarily associated with the port transmitting the LLDP message. 
+> [!NOTE]
+> The Management Addresses shown by LLDP are not necessarily associated
+> with the port transmitting the LLDP message.
 
 In the example below, the IPv4 address (10.0.1.1) happens to be
 assigned to *eth0*, while the IPv6 address (2001:db8::1) is not.
@@ -130,10 +133,6 @@ tcpdump: listening on tap0, link-type EN10MB (Ethernet), snapshot length 262144
 linux-pc:#
 ```
 
-[^1]: [lldpd: implementation of IEEE 802.1ab
-    (LLDP)](https://github.com/lldp/lldpd) includes *lldpcli*, which
-    is handy to sniff and display LLDP packets.
-
 The LLDP service can be disabled using the following commands.
 
 ```
@@ -143,13 +142,39 @@ admin@infix-c0-ff-ee:/config/> leave
 admin@infix-c0-ff-ee:/> 
 ```
 
-### mDNS
 
-DNS-SD/mDNS can be used to discover Infix units and services. Infix
-units present their IP addresses, services and hostname within the
-.local domain. This method has good client support in Apple and Linux
-systems. On Linux, tools such as *avahi-browse* or *mdns-scan*[^2] can
-be used to search for devices advertising their services via mDNS.
+### mDNS-SD
+
+DNS-SD/mDNS-SD can be used to discover Infix devices and services.  By
+default, Infix use the `.local` domain for advertising services.  Some
+networks use `.lan` instead, so this configurable:
+
+```
+admin@infix-c0-ff-ee:/> configure
+admin@infix-c0-ff-ee:/config/> edit mdns
+admin@infix-c0-ff-ee:/config/mdns/> set domain lan
+```
+
+Other available settings include limiting the interfaces mDNS responder
+acts on:
+
+```
+admin@infix-c0-ff-ee:/config/> set interfaces allow e1
+```
+
+or
+
+```
+admin@infix-c0-ff-ee:/config/> set interfaces deny wan
+```
+
+The `allow` and `deny` settings are complementary, `deny` always wins.
+
+----
+
+mDNS-SD has good client support in Windows, macOS and on Linux systems.
+In the latter, tools such as *avahi-browse* or *mdns-scan*[^2] can be
+used to search for devices advertising their services via mDNS.
 
 ```
 linux-pc:# avahi-browse -ar
@@ -181,9 +206,15 @@ linux-pc:# avahi-browse -ar
 linux-pc:#
 ```
 
+> [!TIP]
+> The `-t` option is also very useful, it stops browsing automatically
+> when a "more or less complete list" has been printed.  However, some
+> devices on the LAN may be in deep sleep so run the command again if
+> you cannot find the device you are looking for.
+
 Additionally, *avahi-resolve-host-name* can be used to verify domain
-name mappings for IP addresses. By default, it translates from IPv4
-addresses. This function allows users to confirm that addresses are
+name mappings for IP addresses.  By default, it translates from IPv4
+addresses.  This function allows users to confirm that addresses are
 mapped correctly.
 
 ```
@@ -219,6 +250,7 @@ linux-pc:#
 ```
 
 To disable mDNS/mDNS-SD, type the commands:
+
 ```
 admin@infix-c0-ff-ee:/> configure 
 admin@infix-c0-ff-ee:/config/> no mdns
@@ -227,12 +259,12 @@ admin@infix-c0-ff-ee:/config/> leave
 
 #### Human-Friendly Hostname Alias
 
-Each Infix unit will advertise itself as *infix.local*, in addition to
-its full hostname (e.g., *infix-c0-ff-ee.local* or *foo.local*).  This
-alias works seamlessly on a network with a single Infix device, and
-makes it easy to connect when the exact hostname is not known in
-advance. The examples below show how the alias can be used for
-actions such as pinging or establishing an SSH connection:
+Each Infix deviuce advertise itself as *infix.local*, in addition to its
+full hostname (e.g., *infix-c0-ff-ee.local* or *foo.local*).  This alias
+works seamlessly on a network with a single Infix device, and makes it
+easy to connect when the exact hostname is not known in advance.  The
+examples below show how the alias can be used for actions such as
+pinging or establishing an SSH connection:
 
 ```
 linux-pc:# ping infix.local -c 3
@@ -254,37 +286,42 @@ linux-pc:# ssh [email protected]
 
 Run the command 'cli' for interactive OAM
 
-linux-pc:#
+admin@infix-c0-ff-ee:~$
 ```
 
 When multiple Infix devices are present on the LAN the alias will not
 uniquely identify a device; *infix.local* will refer to any of the
 Infix devices, likely the one that first appeared.
 
-> When multiple Infix units are present, use the full hostname (e.g.,
-> *infix-c0-ff-ee.local* or *foo.local*) rather than the alias
-> infix.local to deterministically connect to a unit.
+> [!NOTE]
+> When multiple Infix devices are present on the LAN, use the full name,
+> e.g., *infix-c0-ff-ee.local* or *foo.local* rather than the alias
+> *infix.local* to deterministically connect to the device.
 
 
-#### Netbrowse service to find all your devices
+#### Netbrowse using *network.local*
 
-Another mDNS alias that all Infix devices can advertise is
-*network.local*. This is a web service which basically runs avahi-browse
-and displays a table of other Infix devices and their services. 
+Another mDNS alias that all Infix devices advertise is *network.local*.
+This is a web service which basically runs `avahi-browse` and displays a
+table of other Infix devices and their services.
 
 ![Netbrowse Service - network.local](img/network-local.png)
 
-With multiple Infix devices on the LAN, one will be your portal to
-access all others, if it goes down another will take its place.
+With multiple Infix devices on the LAN, one will take the role of your
+portal to access all others, if it goes down another takes its place.
+
+To disable the netbrowse service, and the *network.local* alias, the
+following commands can be used:
 
-To disable the netbrowse service, the following commands can be used:
 ```
 admin@infix-c0-ff-ee:/> configure 
 admin@infix-c0-ff-ee:/config/> edit web
 admin@infix-c0-ff-ee:/config/web/> no netbrowse
 admin@infix-c0-ff-ee:/config/web/> leave
 ```
 
+
+[^1]: E.g., [lldpd](https://github.com/lldp/lldpd) which includes the
+    *lldpcli* too, handy to sniff and display LLDP packets.
 [^2]: [mdns-scan](http://0pointer.de/lennart/projects/mdns-scan/): a
-    tool for scanning for mDNS/DNS-SD published services on the local
-    network
+    tool for scanning for mDNS/DNS-SD services on the local network.