diff --git a/doc/ChangeLog.md b/doc/ChangeLog.md index 9981568e3..da6a596ae 100644 --- a/doc/ChangeLog.md +++ b/doc/ChangeLog.md @@ -22,6 +22,9 @@ All notable changes to the project are documented in this file. - Support for saving and restoring system clock from a disk file. This allows restoring the system clock to a sane date in case the RTC is disabled or does not have a valid time, issue #794 +- Updated Discovery documentation with information on `infix.local` + mDNS alias, `netbrowse` support to discover *all* local units, and + command examples for disabling LLDP and mDNS services, issue #786 ### Fixes - Fix #685: DSA conduit interface not always detected, randomly causing diff --git a/doc/discovery.md b/doc/discovery.md index e46a63f38..6bbba8f9c 100644 --- a/doc/discovery.md +++ b/doc/discovery.md @@ -16,14 +16,14 @@ seen in the response. In the example below, the PC is connected to Infix via interface *tap0* (*tap0* is *if1* in Figure 1) and Infix responds with address -*fe80::ff:fe00:0*. +*fe80::ff:fec0:ffed*. ``` linux-pc:# ping -6 -L -c 3 ff02::1%tap0 PING ff02::1%tap0(ff02::1%tap0) 56 data bytes -64 bytes from fe80::ff:fe00:0%tap0: icmp_seq=1 ttl=64 time=0.558 ms -64 bytes from fe80::ff:fe00:0%tap0: icmp_seq=2 ttl=64 time=0.419 ms -64 bytes from fe80::ff:fe00:0%tap0: icmp_seq=3 ttl=64 time=0.389 ms +64 bytes from fe80::ff:fec0:ffed%tap0: icmp_seq=1 ttl=64 time=0.558 ms +64 bytes from fe80::ff:fec0:ffed%tap0: icmp_seq=2 ttl=64 time=0.419 ms +64 bytes from fe80::ff:fec0:ffed%tap0: icmp_seq=3 ttl=64 time=0.389 ms --- ff02::1%tap0 ping statistics --- 3 packets transmitted, 3 received, 0% packet loss, time 2043ms @@ -34,9 +34,9 @@ linux-pc:# The PC could connect then connect to Infix, e.g., using SSH. ``` -linux-pc:# ssh admin@fe80::ff:fe00:0%tap0 -admin@fe80::ff:fe00:0%tap0's password: admin -admin@infix-00-00-00:~$ +linux-pc:# ssh admin@fe80::ff:fec0:ffed%tap0 +admin@fe80::ff:fec0:ffed%tap0's password: admin +admin@infix-c0-ff-ee:~$ ``` ## Discovery mechanisms available in Infix @@ -55,18 +55,18 @@ linux-pc:# tcpdump -i tap0 -Qin -v ether proto 0x88cc tcpdump: listening on tap0, link-type EN10MB (Ethernet), snapshot length 262144 bytes 15:51:52.061071 LLDP, length 193 Chassis ID TLV (1), length 7 - Subtype MAC address (4): 02:00:00:00:00:00 (oui Unknown) + Subtype MAC address (4): 02:00:00:c0:ff:ee (oui Unknown) Port ID TLV (2), length 7 - Subtype MAC address (3): 02:00:00:00:00:00 (oui Unknown) + Subtype MAC address (3): 02:00:00:c0:ff:ee (oui Unknown) Time to Live TLV (3), length 2: TTL 120s - System Name TLV (5), length 14: infix-00-00-00 + System Name TLV (5), length 14: infix-c0-ff-ee System Description TLV (6), length 91 Infix by KernelKit Linux 5.19.17 #1 SMP PREEMPT_DYNAMIC Wed Jun 7 08:47:23 CEST 2023 x86_64 System Capabilities TLV (7), length 4 System Capabilities [Bridge, WLAN AP, Router, Station Only] (0x009c) Enabled Capabilities [Station Only] (0x0080) Management Address TLV (8), length 24 - Management Address length 17, AFI IPv6 (2): fe80::ff:fe00:0 + Management Address length 17, AFI IPv6 (2): fe80::ff:fec0:ffed Interface Index Interface Numbering (2): 2 Port Description TLV (4), length 4: eth0 Organization specific TLV (127), length 9: OUI IEEE 802.3 Private (0x00120f) @@ -97,11 +97,11 @@ linux-pc:# sudo tcpdump -i tap0 -Qin -v ether proto 0x88cc tcpdump: listening on tap0, link-type EN10MB (Ethernet), snapshot length 262144 bytes 15:46:07.908665 LLDP, length 207 Chassis ID TLV (1), length 7 - Subtype MAC address (4): 02:00:00:00:00:00 (oui Unknown) + Subtype MAC address (4): 02:00:00:c0:ff:ee (oui Unknown) Port ID TLV (2), length 7 - Subtype MAC address (3): 02:00:00:00:00:00 (oui Unknown) + Subtype MAC address (3): 02:00:00:c0:ff:ee (oui Unknown) Time to Live TLV (3), length 2: TTL 120s - System Name TLV (5), length 14: infix-00-00-00 + System Name TLV (5), length 14: infix-c0-ff-ee System Description TLV (6), length 91 Infix by KernelKit Linux 5.19.17 #1 SMP PREEMPT_DYNAMIC Wed Jun 7 08:47:23 CEST 2023 x86_64 System Capabilities TLV (7), length 4 @@ -134,6 +134,15 @@ linux-pc:# (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. + +``` +admin@infix-c0-ff-ee:/> configure +admin@infix-c0-ff-ee:/config/> no lldp +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 @@ -144,33 +153,138 @@ be used to search for devices advertising their services via mDNS. ``` linux-pc:# avahi-browse -ar -+ tap0 IPv6 infix-00-00-00 SFTP File Transfer local -+ tap0 IPv4 infix-00-00-00 SFTP File Transfer local -+ tap0 IPv6 infix-00-00-00 SSH Remote Terminal local -+ tap0 IPv4 infix-00-00-00 SSH Remote Terminal local -= tap0 IPv4 infix-00-00-00 SFTP File Transfer local - hostname = [infix-00-00-00.local] ++ tap0 IPv6 infix-c0-ff-ee SFTP File Transfer local ++ tap0 IPv4 infix-c0-ff-ee SFTP File Transfer local ++ tap0 IPv6 infix-c0-ff-ee SSH Remote Terminal local ++ tap0 IPv4 infix-c0-ff-ee SSH Remote Terminal local += tap0 IPv4 infix-c0-ff-ee SFTP File Transfer local + hostname = [infix-c0-ff-ee.local] address = [10.0.1.1] port = [22] txt = [] -= tap0 IPv4 infix-00-00-00 SSH Remote Terminal local - hostname = [infix-00-00-00.local] += tap0 IPv4 infix-c0-ff-ee SSH Remote Terminal local + hostname = [infix-c0-ff-ee.local] address = [10.0.1.1] port = [22] txt = [] -= tap0 IPv6 infix-00-00-00 SFTP File Transfer local - hostname = [infix-00-00-00.local] - address = [fe80::ff:fe00:0] += tap0 IPv6 infix-c0-ff-ee SFTP File Transfer local + hostname = [infix-c0-ff-ee.local] + address = [fe80::ff:fec0:ffed] port = [22] txt = [] -= tap0 IPv6 infix-00-00-00 SSH Remote Terminal local - hostname = [infix-00-00-00.local] - address = [fe80::ff:fe00:0] += tap0 IPv6 infix-c0-ff-ee SSH Remote Terminal local + hostname = [infix-c0-ff-ee.local] + address = [fe80::ff:fec0:ffed] port = [22] txt = [] ^C linux-pc:# ``` + +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 +mapped correctly. + +``` +linux-pc:# avahi-resolve-host-name infix-c0-ff-ee.local +infix-c0-ff-ee.local 10.0.1.1 +linux-pc:# +``` + +Thanks to mDNS we can use the advertised name instead of the IP +address for operations like `ping` and `ssh` as shown below: + +``` +linux-pc:# ping infix-c0-ff-ee.local -c 3 +PING infix-c0-ff-ee.local (10.0.1.1) 56(84) bytes of data. +64 bytes from 10.0.1.1: icmp_seq=1 ttl=64 time=0.852 ms +64 bytes from 10.0.1.1: icmp_seq=2 ttl=64 time=1.12 ms +64 bytes from 10.0.1.1: icmp_seq=3 ttl=64 time=1.35 ms + +--- infix-c0-ff-ee.local ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 0.852/1.105/1.348/0.202 ms + +linux-pc:# ssh admin@infix-c0-ff-ee.local +(admin@infix-c0-ff-ee.local) Password: +.-------. +| . . | Infix -- a Network Operating System +|-. v .-| https://kernelkit.org +'-'---'- + +Run the command 'cli' for interactive OAM + +linux-pc:# +``` + +To disable mDNS/mDNS-SD, type the commands: +``` +admin@infix-c0-ff-ee:/> configure +admin@infix-c0-ff-ee:/config/> no mdns +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: + +``` +linux-pc:# ping infix.local -c 3 +PING infix.local (10.0.1.1) 56(84) bytes of data. +64 bytes from 10.0.1.1: icmp_seq=1 ttl=64 time=0.751 ms +64 bytes from 10.0.1.1: icmp_seq=2 ttl=64 time=2.28 ms +64 bytes from 10.0.1.1: icmp_seq=3 ttl=64 time=1.42 ms + +--- infix.local ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 0.751/1.482/2.281/0.626 ms + +linux-pc:# ssh admin@infix.local +(admin@infix.local) Password: +.-------. +| . . | Infix -- a Network Operating System +|-. v .-| https://kernelkit.org +'-'---'- + +Run the command 'cli' for interactive OAM + +linux-pc:# +``` + +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. + + +#### Netbrowse service to find all your devices + +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. + +![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. + +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 +``` + [^2]: [mdns-scan](http://0pointer.de/lennart/projects/mdns-scan/): a tool for scanning for mDNS/DNS-SD published services on the local network diff --git a/doc/img/network-local.png b/doc/img/network-local.png new file mode 100644 index 000000000..112ea5d6f Binary files /dev/null and b/doc/img/network-local.png differ