* [pve-devel] [PATCH docs 1/3] fix #4847: network: extend section on interface naming scheme
2023-07-27 10:37 [pve-devel] [PATCH+RFC docs/common 0/3] fix #4847: network: custom naming for network devices Friedrich Weber
@ 2023-07-27 10:37 ` Friedrich Weber
2023-11-17 9:18 ` [pve-devel] applied: " Thomas Lamprecht
2023-07-27 10:37 ` [pve-devel] [RFC docs 2/3] network: describe and recommend `c*` names for custom interface Friedrich Weber
2023-07-27 10:37 ` [pve-devel] [RFC common 3/3] network: recognize interfaces matching `c*` as physical NICs Friedrich Weber
2 siblings, 1 reply; 5+ messages in thread
From: Friedrich Weber @ 2023-07-27 10:37 UTC (permalink / raw)
To: pve-devel
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
^ permalink raw reply [flat|nested] 5+ messages in thread* [pve-devel] [RFC docs 2/3] network: describe and recommend `c*` names for custom interface
2023-07-27 10:37 [pve-devel] [PATCH+RFC docs/common 0/3] fix #4847: network: custom naming for network devices Friedrich Weber
2023-07-27 10:37 ` [pve-devel] [PATCH docs 1/3] fix #4847: network: extend section on interface naming scheme Friedrich Weber
@ 2023-07-27 10:37 ` Friedrich Weber
2023-07-27 10:37 ` [pve-devel] [RFC common 3/3] network: recognize interfaces matching `c*` as physical NICs Friedrich Weber
2 siblings, 0 replies; 5+ messages in thread
From: Friedrich Weber @ 2023-07-27 10:37 UTC (permalink / raw)
To: pve-devel
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
^ permalink raw reply [flat|nested] 5+ messages in thread