From 2d55f3b9fa0c60a77dd72516674bf5c28444fe0d Mon Sep 17 00:00:00 2001 From: Nikolay Edigaryev Date: Mon, 20 Jan 2025 19:26:08 +0400 Subject: [PATCH] docs(FAQ): document unsupported DHCP client identifiers (#1009) * docs(FAQ): document unsupported DHCP client identifiers * New section "Resolving the VMs IP with bridged networking" And a more clearer explanation of what "tart ip" does. * Remove extraneous space in ` --resolver=arp` * Better section name * Add a note about Linux talkativeness * Explain "talkativeness" a bit better --- docs/faq.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/faq.md b/docs/faq.md index 8c5d616..b502d79 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -77,6 +77,57 @@ sudo rm /var/db/dhcpd_leases And no worries, this file will be re-created on the next `tart run`. +## Unsupported DHCP client identifiers + +Due to the limitations of the macOS built-in DHCP server, `tart ip` is unable to correctly report the IP addresses for VMs using DHCP client identifiers that are not based on VMs link-layer addresses (MAC addresses). + +By default, when [no `--resolver=arp` is specified](#resolving-the-vms-ip-when-using-bridged-networking), `tart ip` reads the `/var/db/dhcpd_leases` file and tries to find the freshest entry that matches the VM's MAC address (based on the `hw_address` field). + +However, things starts to break when the VM uses a [DUID-EN](https://metebalci.com/blog/a-note-on-dhcpv6-duid-and-prefix-delegation#duid-types) identifier, for example. One of the notorious examples of this being Ubuntu, using this type of identifier by default on latest versions. This results in the `/var/db/dhcpd_leases` entry for Ubuntu appearing as follows: + +```ini +{ + name=ubuntu + ip_address=192.168.64.3 + hw_address=ff,f1:f5:dd:7f:0:2:0:0:ab:11:cb:fb:30:b0:97:b6:3a:67 + identifier=ff,f1:f5:dd:7f:0:2:0:0:ab:11:cb:fb:30:b0:97:b6:3a:67 + lease=0x678e2ce7 +} +``` + +Because the macOS built-in DHCP server overwrites the `hw_address` with the `identifier`, it leaves no information about the VM's MAC address to the `tart ip`. + +To avoid this issue, make sure that your VM only sends a DHCP client identifier (option 61) with link-layer address (MAC address) or that it doesn't send this option at all. + +For the aforementioned Ubuntu, the solution is outlined in the section [How to integrate with Windows DHCP Server](https://netplan.readthedocs.io/en/stable/examples/#how-to-integrate-with-windows-dhcp-server) of Canonical Netplan's documentation: + +```yaml +network: + version: 2 + ethernets: + enp3s0: + dhcp4: yes + dhcp-identifier: mac +``` + +## Resolving the VM's IP when using bridged networking + +When running `tart run` with `--net-bridged`, you need to invoke `tart ip` differently, because the macOS built-in DHCP server won't have any information about the VM's IP-address: + +```shell +tart ip --resolver=arp +``` + +This causes the `tart ip` to consult the host's ARP table instead of the `/var/db/dhcpd_leases` file. + +Note that this method of resolving the IP heavily relies on the level of VM's activity on the network, namely, exchanging ARP requests between the guest and the host. + +This is normally not an issue for macOS VMs, but on Linux VMs you might need to install Samba, which includes a [NetBIOS name server](https://www.samba.org/samba/docs/current/man-html/nmbd.8.html) and exhibits the same behavior as macOS, resulting in the population of the ARP table of the host OS: + +```shell +sudo apt-get install samba +``` + ## Running login/clone/pull/push commands over SSH When invoking the Tart in an SSH session, you might get error like this: