diff options
| -rw-r--r-- | docs/automation/vyos-api.md | 3 | ||||
| -rw-r--r-- | docs/cli.md | 14 | ||||
| -rw-r--r-- | docs/configexamples/inter-vrf-routing-vrf-lite.md | 1 | ||||
| -rw-r--r-- | docs/configexamples/zone-policy.md | 1 | ||||
| -rw-r--r-- | docs/configuration/interfaces/ethernet.md | 135 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireless.md | 2 | ||||
| -rw-r--r-- | docs/contributing/testing.md | 6 | ||||
| -rw-r--r-- | docs/troubleshooting/interfaces.md | 49 |
8 files changed, 159 insertions, 52 deletions
diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index 224107f5..a2bd81ee 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -172,12 +172,10 @@ response (shortened) "eth0": { "address": "dhcp", "duplex": "auto", - "hw-id": "50:00:00:01:00:00", "speed": "auto" }, "eth1": { "duplex": "auto", - "hw-id": "50:00:00:01:00:01", "speed": "auto" ... }, @@ -416,7 +414,6 @@ response (shortened): { "success": true, "data": "set interfaces ethernet eth0 address 'dhcp'\n - set interfaces ethernet eth0 hw-id '50:00:00:01:00:00'\n set system host-name 'vyos'\n ...", "error": null 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 diff --git a/docs/configexamples/inter-vrf-routing-vrf-lite.md b/docs/configexamples/inter-vrf-routing-vrf-lite.md index cd726c34..23371445 100644 --- a/docs/configexamples/inter-vrf-routing-vrf-lite.md +++ b/docs/configexamples/inter-vrf-routing-vrf-lite.md @@ -672,7 +672,6 @@ set protocols static route6 ::/0 next-hop 2001:db8::1 ```none set interfaces dummy dum0 address '172.16.0.1/24' set interfaces dummy dum0 address '2001:db8:0:2::1/64' -set interfaces ethernet eth0 hw-id '50:00:00:03:00:00' set interfaces ethernet eth1 address '172.16.2.2/30' set interfaces ethernet eth1 address '2001:db8::3/127' set protocols static route 0.0.0.0/0 next-hop 172.16.2.1 diff --git a/docs/configexamples/zone-policy.md b/docs/configexamples/zone-policy.md index 2cd773a9..3f899927 100644 --- a/docs/configexamples/zone-policy.md +++ b/docs/configexamples/zone-policy.md @@ -54,7 +54,6 @@ It will look something like this: interfaces { ethernet eth0 { duplex auto - hw-id 00:53:ed:6e:2a:92 smp_affinity auto speed auto vif 10 { diff --git a/docs/configuration/interfaces/ethernet.md b/docs/configuration/interfaces/ethernet.md index eac0b443..6ca5dc6c 100644 --- a/docs/configuration/interfaces/ethernet.md +++ b/docs/configuration/interfaces/ethernet.md @@ -369,6 +369,141 @@ Uplink/core tracking. :var2: eth3 ``` +(interface-naming)= + +## Interface naming + +VyOS owns the `ethN` and `wlanN` namespace: the kernel command line carries +`net.ifnames=0`, which turns off the naming policy systemd would otherwise +apply. Which physical port gets which name is therefore decided by VyOS, and +that decision has to survive a reboot. + +### How names are assigned + +A name is bound to the **slot** the hardware sits in, not to its MAC address. +The bindings live in `/config/interface-mapping.json`: + +```{code-block} none +{ + "version": 1, + "interfaces": { + "eth0": "ID_NET_NAME_SLOT=ens18", + "eth1": "ID_PATH=pci-0000:00:13.0" + } +} +``` + +Each value is a single udev property. The most stable one the device can +offer is used, in this order: + +1. `ID_NET_NAME_ONBOARD` +2. `ID_NET_NAME_SLOT` +3. `ID_NET_NAME_PATH` +4. `ID_PATH` +5. `ID_NET_NAME_MAC` + +A firmware slot index survives PCI renumbering, a bus path does not — adding a +card can shift `pci-0000:00:13.0` but not the slot the firmware reports. The +last entry is a fallback for paravirtual buses which offer no usable topology. + +The store is rendered into one file per interface under +`/etc/systemd/network/`, named `10-vyos-<interface>.link`, so udev applies the +name as the device appears and nothing ever observes a probe-order name. + +:::{note} +The `.link` files are generated from the mapping file. Do not edit them, +they are regenerated on every boot. +::: + +A name stays reserved while its hardware is absent, so a NIC which appears +later can never inherit the name — and with it the addresses — of an +interface which is merely unplugged. Hardware the system has not seen before +is named at boot in canonical hardware order and then recorded. + +What a boot decided can be inspected in `/run/vyos-net-name-resolve.json`. + +### Replacing a network card + +Nothing needs to be done. The slot is the identity, so a replacement card in +the same slot is the same interface and keeps its configuration. This is the +case which used to require updating a `hw-id` value by hand. + +### Adding a network card + +A card which the system has not seen before is given the next free name, and +that name is appended after the ones already in use. Where the card sits has +no say in it: a card in a slot between two existing ones does **not** take a +name in the middle and push the others along, because every name already +recorded is reserved. Renumbering would move interfaces onto cables they were +never configured for. + +So on a system with `eth0` to `eth7`, a card added in any free slot becomes +`eth8`, and keeps that name once it is recorded. + +This applies to a card plugged into a running system as well. It is named as +soon as it appears, and a configuration node for it is added on the next +boot, after which it can be configured like any other interface. + +### Renaming an interface + +Renaming an interface means changing both the configuration and the mapping +file. Changing only one of them leaves the old name's settings orphaned and +the new name unconfigured. + +To rename `eth1` to `eth23`: + +```{code-block} none +vyos@vyos:~$ configure +vyos@vyos# rename interfaces ethernet eth1 to interfaces ethernet eth23 +vyos@vyos# commit +vyos@vyos# save +vyos@vyos# exit +``` + +Then change the key in the mapping file, leaving its value untouched: + +```{code-block} none +vyos@vyos:~$ sudo vi /config/interface-mapping.json +``` + +```{code-block} none +{ + "version": 1, + "interfaces": { + "eth0": "ID_NET_NAME_SLOT=ens18", + "eth23": "ID_PATH=pci-0000:00:13.0" + } +} +``` + +The new name is applied on the next boot: + +```{code-block} none +vyos@vyos:~$ reboot +``` + +:::{note} +The mapping file belongs to the `vyattacfg` group and is edited with +`sudo`. It lives on the config volume and therefore survives an image +upgrade. +::: + +### Migrating from hw-id + +`interfaces ethernet <interface> hw-id` and +`interfaces wireless <interface> hw-id` no longer exist. A name is a property +of the hardware, not of the configuration. + +Upgrading converts the existing bindings automatically: every `hw-id` is +matched against the permanent address of the hardware actually present and +the slot that card sits in is recorded. No interface changes its name across +the upgrade, including systems whose names never followed slot order. A +`hw-id` whose hardware is absent is skipped, as the configuration may well +originate from another machine. + +Setting a MAC address is unrelated to naming and is still done with +`set interfaces ethernet <interface> mac <address>`. + ## Operation ```{opcmd} show interfaces ethernet diff --git a/docs/configuration/interfaces/wireless.md b/docs/configuration/interfaces/wireless.md index 9e6b7c99..057ff9e1 100644 --- a/docs/configuration/interfaces/wireless.md +++ b/docs/configuration/interfaces/wireless.md @@ -803,7 +803,6 @@ interfaces { } channel 11 description "802.11ax 2.4GHz" - hw-id [...] mode ax physical-device phy0 security { @@ -884,7 +883,6 @@ interfaces { channel 5 description "802.11ax 6GHz" enable-bf-protection - hw-id [...] mgmt-frame-protection required mode ax physical-device phy0 diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md index b68cad1b..46e6a881 100644 --- a/docs/contributing/testing.md +++ b/docs/contributing/testing.md @@ -178,16 +178,10 @@ Loading configuration from '/usr/libexec/vyos/tests/config/ospf-small' Load complete. Use 'commit' to make changes effective. [edit] vyos@vyos# compare -[edit interfaces ethernet eth0] --hw-id 00:50:56:bf:c5:6d [edit interfaces ethernet eth1] +duplex auto --hw-id 00:50:56:b3:38:c5 +speed auto [edit interfaces] --ethernet eth2 { -- hw-id 00:50:56:b3:9c:1d --} -vti vti1 { - address 192.0.2.1/30 -} diff --git a/docs/troubleshooting/interfaces.md b/docs/troubleshooting/interfaces.md index 553cbf90..5881842e 100644 --- a/docs/troubleshooting/interfaces.md +++ b/docs/troubleshooting/interfaces.md @@ -1,36 +1,29 @@ # Interface Names -If you find the names of your interfaces have changed, this could be because -your MAC addresses have changed. +Interface names no longer follow the MAC address of a network card. A name is +bound to the slot the hardware sits in, so the situations which used to rename +interfaces do not any more: -- For example, you have a VyOS VM with 4 Ethernet interfaces named - eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different - host and find your interfaces now are eth4, eth5, eth6 and eth7. +- Migrating a VM to a different host, where the hypervisor hands out new MAC + addresses, keeps the interface names. +- Cloning a VM, for example in GNS3, keeps the interface names. +- Replacing a failed network card with a new one in the same slot keeps the + name and the configuration of that interface. - One way to fix this issue **taking control of the MAC addresses** is: +An interface whose card is removed keeps its name reserved, so a card added +later can never take over the name — and with it the addresses — of the +interface which went away. - Log into VyOS and run this command to display your interface settings. +See {ref}`interface-naming` for how names are assigned, and for the procedure +to rename an interface. - ```none - show interfaces detail - ``` +If an interface really is missing after a reboot, check which names were +resolved for this boot: - Take note of MAC addresses. +```none +cat /run/vyos-net-name-resolve.json +``` - Now, in order to update a MAC address in the configuration, run this command - specifying the interface name and MAC address you want. - - ```none - set interfaces ethernet eth0 hw-id 00:0c:29:da:a4:fe - ``` - - If it is a VM, go into the settings of the host and set the MAC address to - the settings found in the config.boot file. You can also set the MAC to - static if the host allows so. - -- Another example could be when cloning VyOS VMs in GNS3 and you get into the - same issue: interface names have changed. - - And **a more generic way to fix it** is just deleting every MAC address at - the configuration file of the cloned machine. They will be correctly - regenerated automatically. +An interface listed under `missing` has a name reserved in the mapping file, +but its hardware did not appear. That points at the card, its driver or the +slot it is plugged into, rather than at the naming. |