Re: [PATCH docs/manager 0/7] interface-pinning: add rename subcommand and man(1) page

[Stefan Hanreich <s.hanreich@proxmox.com>]

Thanks for trying to tackle this! Found some issues while testing :(



Renaming an existing NIC twice generates multiple link files:

> $ ls -alh /usr/local/lib/systemd/network/*test*
> -rw-r--r-- 1 root root 67 Jul 15 17:38 /usr/local/lib/systemd/network/50-pmx-test1.link
> -rw-r--r-- 1 root root 67 Jul 15 17:38 /usr/local/lib/systemd/network/50-pmx-test2.link


$ pve-network-interface-pinning rename ens20 test1
This will rename the existing pin 'ens20' to 'test1' - continue (y/N)?
y
Name for link 'ens20' (enp0s20, enxaaaaaa5bed07) will change to 'test1'
Generating link files
Successfully generated .link files in '/usr/local/lib/systemd/network/'
Updating /etc/pve/nodes/fw-testi/host.fw.new
Updating /etc/network/interfaces.new
Updating /etc/pve/sdn/controllers.cfg
Updating /etc/pve/sdn/fabrics.cfg
Removed old .link file for 'ens20'.
Successfully updated Proxmox VE configuration files.

Please reboot to apply the changes to your configuration.

$ pve-network-interface-pinning rename ens20 test2
This will rename the existing pin 'ens20' to 'test2' - continue (y/N)?
y
Name for link 'ens20' (enp0s20, enxaaaaaa5bed07) will change to 'test2'
Generating link files
Successfully generated .link files in '/usr/local/lib/systemd/network/'
Updating /etc/pve/nodes/fw-testi/host.fw.new
Updating /etc/network/interfaces.new
Updating /etc/pve/sdn/controllers.cfg
Updating /etc/pve/sdn/fabrics.cfg
Removed old .link file for 'ens20'.
Successfully updated Proxmox VE configuration files.

Please reboot to apply the changes to your configuration.

This should detect that ens20 has already been renamed to test1 and
abort early?



If ens20 was member of a bond, subsequent renames (even of different
interfaces!) fail with the following error:

bond 'bond0' - wrong interface type on slave 'test1' ('unknown' != 'eth
or bond')

We should skip this check if the referenced interface is a pending pin?
Makes me think if we shouldn't be more careful / rollback configuration
changes on such errors. Can get quite messy quite quickly in the case of
errors. This will probably be exacerbated with the 'rename' functionality.



Renaming a completely unrelated NIC (which fails) also recreates the pin
file for ens20:

> $ pve-network-interface-pinning rename ens19 test3
> This will rename the existing pin 'ens19' to 'test3' - continue (y/N)?
> y
> Name for link 'ens19' (enp0s19, enxaaaaaac69c73) will change to 'test3'
> Generating link files
> Successfully generated .link files in '/usr/local/lib/systemd/network/'
> Updating /etc/pve/nodes/fw-testi/host.fw.new
> Updating /etc/network/interfaces.new
> bond 'bond0' - wrong interface type on slave 'test1' ('unknown' != 'eth or bond')
> $ ls -alh /usr/local/lib/systemd/network/
> total 28K
> drwxr-xr-x 2 root root 4.0K Jul 15 17:47 .
> drwxr-xr-x 3 root root 4.0K Feb  2 18:38 ..
> -rw-r--r-- 1 root root   67 Jul 15 17:43 50-pmx-ens19.link
> -rw-r--r-- 1 root root   67 Jul 15 17:47 50-pmx-ens20.link
> -rw-r--r-- 1 root root   66 Jul 15 17:47 50-pmx-nic0.link
> -rw-r--r-- 1 root root   67 Jul 15 17:38 50-pmx-test1.link
> -rw-r--r-- 1 root root   67 Jul 15 17:47 50-pmx-test3.link



On 6/23/26 11:44 AM, Christoph Heiss wrote:
> It came up a few times in the forum already to be able to rename
> already-pinned interfaces, which is sensible.
> 
> While at it, also add a full man(1) page for
> pve-network-interface-pinning. Currently, it's just a hardcoded stub
> without any actual help text.
> 
> pve-docs:
> 
> Christoph Heiss (4):
>   network: fix typo occurences -> occurrences
>   pve-doc-generator: handle CLI tools/services with dashes in their name
>   pve-network-interface-pinning: init man(1) page
>   network: pinning: mention how to rename an interface
> 
>  ...-network-interface-pinning.1-synopsis.adoc | 50 ++++++++++++++++
>  pve-admin-guide.adoc                          |  8 +++
>  pve-doc-generator.mk.in                       | 12 ++--
>  pve-network-interface-pinning.adoc            | 60 +++++++++++++++++++
>  pve-network.adoc                              |  8 ++-
>  5 files changed, 131 insertions(+), 7 deletions(-)
>  create mode 100644 generated/pve-network-interface-pinning.1-synopsis.adoc
>  create mode 100644 pve-network-interface-pinning.adoc
> 
> pve-manager:
> 
> Christoph Heiss (3):
>   network-interface-pinning: avoid warning if `bond-primary` is unset
>   network-interface-pinning: add method for renaming existing pins
>   network-interface-pinning: generate proper manpage from docs
> 
>  PVE/CLI/pve_network_interface_pinning.pm | 156 +++++++++++++++++------
>  bin/Makefile                             |  19 ---
>  2 files changed, 119 insertions(+), 56 deletions(-)