[pve-devel] [PATCH+RFC docs/common 0/3] fix #4847: network: custom naming for network devices

[pve-devel] [PATCH+RFC docs/common 0/3] fix #4847: network: custom naming for network devices

[Friedrich Weber]

Patch #1 expands the documentation on custom network interface names,
including the usage of systemd.link files to assign custom names to network
interfaces. Patch #2 and #3 are optional and marked as RFC, with the following
reasoning.

Working on patch #1, I noticed that PVE only recognizes interfaces with
certain names (ethN/en*/ib*) as physical NICs which can be configured in the
GUI. This means that users who want to assign custom names and also use the
GUI have to choose names that match these patterns. This seems inconvenient.

Aaron had the idea of adding a pattern `c*` specifically for "custom" names.
So to maybe start a discussion on this idea, this series comes with two
additional RFC patches: Patch #2 changes the documentation from patch #1
accordingly, and patch #3 adds the `c*` pattern.



docs:

Friedrich Weber (2):
  fix #4847: network: extend section on interface naming scheme
  network: describe and recommend `c*` names for custom interface

 pve-network.adoc | 120 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 105 insertions(+), 15 deletions(-)


common:

Friedrich Weber (1):
  network: recognize interfaces matching `c*` as physical NICs

 src/PVE/Network.pm | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)


Summary over all repositories:
  2 files changed, 106 insertions(+), 16 deletions(-)

-- 
murpp v0.4.0

[pve-devel] [PATCH docs 1/3] fix #4847: network: extend section on interface naming scheme

[Friedrich Weber]

Expand the existing section on systemd network interface names with a
link to the systemd.net-naming-scheme(7) manpage and some information
about naming scheme versions. Also mention the possibility of
interface naming changes due to a new naming scheme version, or
kernel/driver updates. This happens for quite some users during the
upgrade from PVE 7 to 8.

Further, describe how to pin a specific naming scheme version and how
to override interface names using systemd.link files.

Also, make some formatting fixes to the existing text.

Signed-off-by: Friedrich Weber <f.weber@proxmox.com>
---
 pve-network.adoc | 122 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 107 insertions(+), 15 deletions(-)

diff --git a/pve-network.adoc b/pve-network.adoc
index 4567ed4..b2202cc 100644
--- a/pve-network.adoc
+++ b/pve-network.adoc
@@ -68,16 +68,16 @@ Naming Conventions
 
 We currently use the following naming conventions for device names:
 
-* Ethernet devices: en*, systemd network interface names. This naming scheme is
+* Ethernet devices: `en*`, systemd network interface names. This naming scheme is
  used for new {pve} installations since version 5.0.
 
-* Ethernet devices: eth[N], where 0 ≤ N (`eth0`, `eth1`, ...) This naming
+* Ethernet devices: `eth[N]`, where 0 ≤ N (`eth0`, `eth1`, ...) This naming
 scheme is used for {pve} hosts which were installed before the 5.0
 release. When upgrading to 5.0, the names are kept as-is.
 
-* Bridge names: vmbr[N], where 0 ≤ N ≤ 4094 (`vmbr0` - `vmbr4094`)
+* Bridge names: `vmbr[N]`, where 0 ≤ N ≤ 4094 (`vmbr0` - `vmbr4094`)
 
-* Bonds: bond[N], where 0 ≤ N (`bond0`, `bond1`, ...)
+* Bonds: `bond[N]`, where 0 ≤ N (`bond0`, `bond1`, ...)
 
 * VLANs: Simply add the VLAN number to the device name,
   separated by a period (`eno1.50`, `bond1.30`)
@@ -88,25 +88,117 @@ name implies the device type.
 Systemd Network Interface Names
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Systemd uses the two character prefix 'en' for Ethernet network
-devices. The next characters depends on the device driver and the fact
-which schema matches first.
+Systemd defines a versioned naming scheme for network device names. The
+scheme uses the two-character prefix `en` for Ethernet network devices. The
+next characters depends on the device driver, device location and other
+attributes. Some possible patterns are:
 
-* o<index>[n<phys_port_name>|d<dev_port>] — devices on board
+* `o<index>[n<phys_port_name>|d<dev_port>]` — devices on board
 
-* s<slot>[f<function>][n<phys_port_name>|d<dev_port>] — device by hotplug id
+* `s<slot>[f<function>][n<phys_port_name>|d<dev_port>]` — devices by hotplug id
 
-* [P<domain>]p<bus>s<slot>[f<function>][n<phys_port_name>|d<dev_port>] — devices by bus id
+* `[P<domain>]p<bus>s<slot>[f<function>][n<phys_port_name>|d<dev_port>]` —
+devices by bus id
 
-* x<MAC> — device by MAC address
+* `x<MAC>` — devices by MAC address
 
-The most common patterns are:
+Some examples for the most common patterns are:
 
-* eno1 — is the first on board NIC
+* `eno1` — is the first on-board NIC
 
-* enp3s0f1 — is the NIC on pcibus 3 slot 0 and use the NIC function 1.
+* `enp3s0f1` — is function 1 of the NIC on PCI bus 3, slot 0
 
-For more information see https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/[Predictable Network Interface Names].
+For a full list of possible device name patterns, see the
+https://manpages.debian.org/stable/systemd/systemd.net-naming-scheme.7.en.html[
+systemd.net-naming-scheme(7) manpage].
+
+A new version of systemd may define a new version of the network device naming
+scheme, which it then uses by default. Consequently, updating to a newer
+systemd version, for example during a major {pve} upgrade, can change the names
+of network devices and require adjusting the network configuration. To avoid
+name changes due to a new version of the naming scheme, you can manually pin a
+particular naming scheme version (see
+xref:network_pin_naming_scheme_version[below]).
+
+However, even with a pinned naming scheme version, network device names can
+still change due to kernel or driver updates. In order to avoid name changes
+for a particular network device altogether, you can manually override its name
+using a link file (see xref:network_override_device_names[below]).
+
+For more information on network interface names, see
+https://systemd.io/PREDICTABLE_INTERFACE_NAMES/[Predictable Network Interface
+Names].
+
+[[network_pin_naming_scheme_version]]
+Pinning a specific naming scheme version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can pin a specific version of the naming scheme for network devices by
+adding the `net.naming-scheme=<version>` parameter to the
+xref:sysboot_edit_kernel_cmdline[kernel command line]. For a list of naming
+scheme versions, see the
+https://manpages.debian.org/stable/systemd/systemd.net-naming-scheme.7.en.html[
+systemd.net-naming-scheme(7) manpage].
+
+For example, to pin the version `v252`, which is the latest naming scheme
+version for a fresh {pve} 8.0 installation, add the following kernel
+command-line parameter:
+
+----
+net.naming-scheme=v252
+----
+
+See also xref:sysboot_edit_kernel_cmdline[this section] on editing the kernel
+command line. You need to reboot for the changes to take effect.
+
+[[network_override_device_names]]
+Overriding network device names
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can manually assign a name to a particular network device using a custom
+https://manpages.debian.org/stable/udev/systemd.link.5.en.html[systemd.link
+file]. This overrides the name that would be assigned according to the latest
+network device naming scheme. This way, you can avoid naming changes due to
+kernel updates, driver updates or newer versions of the naming scheme.
+
+Custom link files should be placed in `/etc/systemd/network/` and named
+`<n>-<id>.link`, where `n` is a priority smaller than `99` and `id` is some
+identifier. A link file has two sections: `[Match]` determines which interfaces
+the file will apply to; `[Link]` determines how these interfaces should be
+configured, including their naming.
+
+To assign a name to a particular network device, you need a way to uniquely and
+permanently identify that device in the `[Match]` section. One possibility is
+to match the device's MAC address using the `MACAddress` option, as it is
+unlikely to change. Then, you can assign a name using the `Name` option in the
+`[Link]` section.
+
+For example, to assign the name `enwan0` to the device with MAC address
+`aa:bb:cc:dd:ee:ff`, create a file `/etc/systemd/network/10-enwan0.link` with
+the following contents:
+
+----
+[Match]
+MACAddress=aa:bb:cc:dd:ee:ff
+
+[Link]
+Name=enwan0
+----
+
+Do not forget to adjust `/etc/network/interfaces` to use the new name.
+You need to reboot the node for the change to take effect.
+
+NOTE: It is recommended to assign a name starting with `en` or `eth` so that
+{pve} recognizes the interface as a physical network device which can then be
+configured via the GUI. Also, you should ensure that the name will not clash
+with other interface names in the future. One possibility is to assign a name
+that does not match any name pattern that systemd uses for network interfaces
+(xref:systemd_network_interface_names[see above]), such as `enwan0` in the
+example above.
+
+For more information on link files, see the
+https://manpages.debian.org/stable/udev/systemd.link.5.en.html[systemd.link(5)
+manpage].
 
 Choosing a network configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.39.2

[pve-devel] [RFC docs 2/3] network: describe and recommend `c*` names for custom interface

[Friedrich Weber]

Signed-off-by: Friedrich Weber <f.weber@proxmox.com>
---
 pve-network.adoc | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/pve-network.adoc b/pve-network.adoc
index b2202cc..bd6a15d 100644
--- a/pve-network.adoc
+++ b/pve-network.adoc
@@ -71,6 +71,9 @@ We currently use the following naming conventions for device names:
 * Ethernet devices: `en*`, systemd network interface names. This naming scheme is
  used for new {pve} installations since version 5.0.
 
+* Ethernet devices: `c*`, intended for user-defined **c**ustom interface names
+(see xref:network_override_device_names[below]).
+
 * Ethernet devices: `eth[N]`, where 0 ≤ N (`eth0`, `eth1`, ...) This naming
 scheme is used for {pve} hosts which were installed before the 5.0
 release. When upgrading to 5.0, the names are kept as-is.
@@ -173,28 +176,23 @@ to match the device's MAC address using the `MACAddress` option, as it is
 unlikely to change. Then, you can assign a name using the `Name` option in the
 `[Link]` section.
 
-For example, to assign the name `enwan0` to the device with MAC address
-`aa:bb:cc:dd:ee:ff`, create a file `/etc/systemd/network/10-enwan0.link` with
-the following contents:
+For example, to assign the name `cwan0` to the device with MAC address
+`aa:bb:cc:dd:ee:ff`, create a file `/etc/systemd/network/10-cwan0.link` with
 
 ----
 [Match]
 MACAddress=aa:bb:cc:dd:ee:ff
 
 [Link]
-Name=enwan0
+Name=cwan0
 ----
 
 Do not forget to adjust `/etc/network/interfaces` to use the new name.
 You need to reboot the node for the change to take effect.
 
-NOTE: It is recommended to assign a name starting with `en` or `eth` so that
-{pve} recognizes the interface as a physical network device which can then be
-configured via the GUI. Also, you should ensure that the name will not clash
-with other interface names in the future. One possibility is to assign a name
-that does not match any name pattern that systemd uses for network interfaces
-(xref:systemd_network_interface_names[see above]), such as `enwan0` in the
-example above.
+NOTE: It is recommended to assign a name starting with `c` (for **c**ustom) so
+that {pve} recognizes the interface as a physical network device which can then
+be configured via the GUI.
 
 For more information on link files, see the
 https://manpages.debian.org/stable/udev/systemd.link.5.en.html[systemd.link(5)
-- 
2.39.2

[pve-devel] [RFC common 3/3] network: recognize interfaces matching `c*` as physical NICs

[Friedrich Weber]

Users can use systemd link files to assign meaningful interface names
to physical NICs. However, so far PVE only recognizes interface names
`ethN`, `en*` and `ib*` as physical NICs. NICs not matching these
patterns cannot be configured via the GUI (their type is "Unknown").

To allow users to choose meaningful interface names and still
configure these NICs via the GUI, recognize interfaces matching `c*`
(for "custom") as physical NICs.

Suggested-by: Aaron Lauterer <a.lauterer@proxmox.com>
Signed-off-by: Friedrich Weber <f.weber@proxmox.com>
---
 src/PVE/Network.pm | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/PVE/Network.pm b/src/PVE/Network.pm
index a4f5ba9..02918a3 100644
--- a/src/PVE/Network.pm
+++ b/src/PVE/Network.pm
@@ -17,7 +17,7 @@ use Socket qw(NI_NUMERICHOST NI_NUMERICSERV);
 
 # host network related utility functions
 
-our $PHYSICAL_NIC_RE = qr/(?:eth\d+|en[^:.]+|ib[^:.]+)/;
+our $PHYSICAL_NIC_RE = qr/(?:eth\d+|en[^:.]+|ib[^:.]+|c[^:.]+)/;
 
 our $ipv4_reverse_mask = [
     '0.0.0.0',
-- 
2.39.2

[pve-devel] applied: [PATCH docs 1/3] fix #4847: network: extend section on interface naming scheme

[Thomas Lamprecht]

Am 27/07/2023 um 12:37 schrieb Friedrich Weber:
> Expand the existing section on systemd network interface names with a
> link to the systemd.net-naming-scheme(7) manpage and some information
> about naming scheme versions. Also mention the possibility of
> interface naming changes due to a new naming scheme version, or
> kernel/driver updates. This happens for quite some users during the
> upgrade from PVE 7 to 8.
> 
> Further, describe how to pin a specific naming scheme version and how
> to override interface names using systemd.link files.
> 
> Also, make some formatting fixes to the existing text.
> 
> Signed-off-by: Friedrich Weber <f.weber@proxmox.com>
> ---
>  pve-network.adoc | 122 +++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 107 insertions(+), 15 deletions(-)
> 
>

applied this one for now, thanks!