T3871: bind interface names to hardware slots instead of hw-id (#2246)mergify/bp/scutum/pr-2246

* docs: T3871: describe how interface names are assigned

Names are no longer derived from the hw-id node. They are bound to the slot
the hardware occupies and recorded in a mapping file, so document what
decides a name, what happens when a card is replaced or added, and how to
rename an interface.

The troubleshooting page said to pin a MAC with hw-id when interfaces were
renamed after a VM migration or a clone. That node no longer exists and the
situation it describes no longer arises, so replace it with a pointer to the
new section and a note on where to look when an interface really is missing.

* docs: T3871: drop hw-id from the example output

The node is gone from the CLI, so example configuration dumps which still
show it no longer match what a reader sees on their own system. Remove it
from the shown output only; no prose changes. The comparison shown on the
testing page is rewritten rather than trimmed, as deleting the lines would
have left an edit level behind with nothing under it.

(cherry picked from commit f939f4eb05f55e7e4c81e1b5dc954c3fc06d2389)

1 files changed, 3 insertions, 11 deletions

diff --git a/docs/cli.md b/docs/cli.md
index 0931c9d6..9a01bc64 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -218,7 +218,6 @@ vyos@vyos:~$ show configuration
 interfaces {
   ethernet eth0 {
         address dhcp
-        hw-id 00:53:00:00:aa:01
   }
   loopback lo {
   }
@@ -279,7 +278,6 @@ Get a collection of all the set commands required which led to the running confi
 :::{code-block} none
 vyos@vyos:~$ show configuration commands
 set interfaces ethernet eth0 address 'dhcp'
-set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f'
 set interfaces loopback 'lo'
 set service ssh port '22'
 set system config-management commit-revisions '20'
@@ -308,7 +306,7 @@ Use the `show configuration commands | strip-private` command when you want to h
 View the current active configuration in JSON format.
 
 :::{code-block} none
-{"interfaces": {"ethernet": {"eth0": {"address": ["192.0.2.11/24", "192.0.2.35/24"], "hw-id": "52:54:00:48:a0:c6"}, "eth1": {"address": ["203.0.113.1/24"], "hw-id": "52:54:00:fc:50:0b"}}, "loopback": {"lo": {}}}, "protocols": {"static": {"route": {"0.0.0.0/0": {"next-hop": {"192.0.2.254": {}}}}}}, "service": {"ssh": {"disable-host-validation": {}}}, "system": {"config-management": {"commit-revisions": "100"}, "console": {"device": {"ttyS0": {"speed": "115200"}}}, "host-name": "r11-vyos", "login": {"user": {"vyos": {"authentication": {"encrypted-password": "$6$Vt68...F0", "plaintext-password": "", "public-keys": {"vyos@vyos": {"key": "AAAAxxx=", "type": "ssh-rsa"}}}}}}, "name-server": ["203.0.113.254"], "ntp": {"server": {"time1.vyos.net": {}, "time2.vyos.net": {}, "time3.vyos.net": {}}}, "syslog": {"global": {"facility": {"all": {"level": "info"}, "protocols": {"level": "debug"}}}}, "time-zone": "America/New_York"}}
+{"interfaces": {"ethernet": {"eth0": {"address": ["192.0.2.11/24", "192.0.2.35/24"]}, "eth1": {"address": ["203.0.113.1/24"]}}, "loopback": {"lo": {}}}, "protocols": {"static": {"route": {"0.0.0.0/0": {"next-hop": {"192.0.2.254": {}}}}}}, "service": {"ssh": {"disable-host-validation": {}}}, "system": {"config-management": {"commit-revisions": "100"}, "console": {"device": {"ttyS0": {"speed": "115200"}}}, "host-name": "r11-vyos", "login": {"user": {"vyos": {"authentication": {"encrypted-password": "$6$Vt68...F0", "plaintext-password": "", "public-keys": {"vyos@vyos": {"key": "AAAAxxx=", "type": "ssh-rsa"}}}}}}, "name-server": ["203.0.113.254"], "ntp": {"server": {"time1.vyos.net": {}, "time2.vyos.net": {}, "time3.vyos.net": {}}}, "syslog": {"global": {"facility": {"all": {"level": "info"}, "protocols": {"level": "debug"}}}}, "time-zone": "America/New_York"}}
 :::
 ```
 
@@ -324,14 +322,12 @@ View the current active configuration in readable JSON format.
                 "address": [
                     "192.0.2.11/24",
                     "192.0.2.35/24"
-                ],
-                "hw-id": "52:54:00:48:a0:c6"
+                ]
             },
             "eth1": {
                 "address": [
                     "203.0.113.1/24"
-                ],
-                "hw-id": "52:54:00:fc:50:0b"
+                ]
             }
         },
         "loopback": {
@@ -461,7 +457,6 @@ vyos@vyos# show interfaces
  ethernet eth0 {
      description MY_OLD_DESCRIPTION
      disable
-     hw-id 00:53:dd:44:3b:03
  }
  loopback lo {
  }
@@ -477,7 +472,6 @@ vyos@vyos# show interfaces
 +    address dhcp
 >    description MY_NEW_DESCRIPTION
 -    disable
-     hw-id 00:53:dd:44:3b:03
  }
  loopback lo {
  }
@@ -489,7 +483,6 @@ mode using {cfgcmd}`show | commands`
 ``` none
 vyos@vyos# show interfaces ethernet eth0 | commands
 set address dhcp
-set hw-id 00:53:ad:44:3b:03
 ```
 
 These commands are also relative to the level you are inside and only relevant
@@ -499,7 +492,6 @@ configuration blocks will be displayed when entering a sub-level.
 [edit interfaces ethernet eth0]
 vyos@vyos# show
  address dhcp
- hw-id 00:53:ad:44:3b:03
 ```
 
 Exiting from the configuration mode is done via the {cfgcmd}`exit` command from