Skip to content

Commit

Permalink
Merge pull request #786 from kernelkit/update-discovery-md
Browse files Browse the repository at this point in the history 
Update discovery.md on mDNS Information

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
  • Loading branch information
@troglobit
troglobit authored Nov 7, 2024
2 parents 6a9f9fd + d277f5a commit 7a9f1c1
Show file tree
Hide file tree
Showing 3 changed files with 145 additions and 28 deletions.
3 changes: 3 additions & 0 deletions doc/ChangeLog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
170 changes: 142 additions & 28 deletions doc/discovery.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Binary file added doc/img/network-local.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 7a9f1c1

Please sign in to comment.