feat(nmcli): support the fail_over_mac parameter

[cnfrancis]

SUMMARY

Missing fail_over_mac parameter in the module ncmli, this PR is to make this parameter available.
Fixes #9570

ISSUE TYPE

• Feature Pull Request

COMPONENT NAME

nmcli

ADDITIONAL INFORMATION

Before

# ansible.cfg
#collections_paths = ./local
[defaults]
keep_remote_files = True
private_key_file = home/REDACTED/.ssh/id_ed25519
host_key_checking = False
pipelining = True
control_path = /tmp/ansible-ssh-%%h-%%p-%%r

# inv.yml
all:
  children:
    blue:
  hosts:
    r1.incus

# test.yml
---
- name: Test nmcli bond configuration with fail_over_mac parameter
  hosts: all
  become: true
  gather_facts: true
  tasks:
    - name: Configure bond0 interface with fail_over_mac parameter
      community.general.nmcli:
        type: bond
        conn_name: bond0
        ifname: bond0
        ip4: 192.168.1.10/24
        gw4: 192.168.1.1
        mode: active-backup
        miimon: 100
        fail_over_mac: 1
        state: present

$ ANSIBLE_FORCE_COLOR=False ansible-playbook test.yml -i inv.yml -u root

PLAY [Test nmcli bond configuration with fail_over_mac parameter] *****************************************************************************************************************************************

TASK [Gathering Facts] ************************************************************************************************************************************************************************************
ok: [r1.incus]

TASK [Configure bond0 interface with fail_over_mac parameter] *********************************************************************************************************************************************
fatal: [r1.incus]: FAILED! => {"changed": false, "msg": "Unsupported parameters for (community.general.nmcli) module: fail_over_mac. Supported parameters include: addr_gen_mode6, ageingtime, arp_interval, arp_ip_target, autoconnect, conn_name, conn_reload, dhcp_client_id, dns4, dns4_ignore_auto, dns4_options, dns4_search, dns6, dns6_ignore_auto, dns6_options, dns6_search, downdelay, egress, flags, forwarddelay, gsm, gw4, gw4_ignore_auto, gw6, gw6_ignore_auto, hairpin, hellotime, ifname, ignore_unsupported_suboptions, ingress, ip4, ip6, ip_privacy6, ip_tunnel_dev, ip_tunnel_input_key, ip_tunnel_local, ip_tunnel_output_key, ip_tunnel_remote, mac, macvlan, master, maxage, may_fail4, method4, method6, miimon, mode, mtu, never_default4, path_cost, primary, priority, route_metric4, route_metric6, routes4, routes4_extended, routes6, routes6_extended, routing_rules4, runner, runner_fast_rate, runner_hwaddr_policy, slave_type, slavepriority, sriov, ssid, state, stp, transport_mode, type, updelay, vlandev, vlanid, vpn, vxlan_id, vxlan_local, vxlan_remote, wifi, wifi_sec, wireguard, xmit_hash_policy, zone."}

PLAY RECAP ************************************************************************************************************************************************************************************************
r1.incus                   : ok=1    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0  

After

# ansible.cfg
[defaults]
collections_paths = ./local
keep_remote_files = True
private_key_file = home/REDACTED/.ssh/id_ed25519
host_key_checking = False
pipelining = True
control_path = /tmp/ansible-ssh-%%h-%%p-%%r

$ ANSIBLE_FORCE_COLOR=False ansible-playbook -vvv test.yml -i inv.yml -u root
ansible-playbook [core 2.16.12]
  config file = /REDACTED//Open-Source/community.general/ansible.cfg
  configured module search path = ['/home/REDACTED/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.13/site-packages/ansible
  ansible collection location = /REDACTED//Open-Source/community.general/local
  executable location = /usr/bin/ansible-playbook
  python version = 3.13.1 (main, Dec  9 2024, 00:00:00) [GCC 14.2.1 20240912 (Red Hat 14.2.1-3)] (/usr/bin/python3)
  jinja version = 3.1.4
  libyaml = True
Using /REDACTED//Open-Source/community.general/ansible.cfg as config file
[DEPRECATION WARNING]: [defaults]collections_paths option, does not fit var naming standard, use the singular form collections_path instead. This feature will be removed from ansible-core in version 
2.19. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
host_list declined parsing /REDACTED//Open-Source/community.general/inv.yml as it did not pass its verify_file() method
script declined parsing /REDACTED//Open-Source/community.general/inv.yml as it did not pass its verify_file() method
Parsed /REDACTED//Open-Source/community.general/inv.yml inventory source with yaml plugin
Skipping callback 'default', as we already have a stdout callback.
Skipping callback 'minimal', as we already have a stdout callback.
Skipping callback 'oneline', as we already have a stdout callback.

PLAYBOOK: test.yml ****************************************************************************************************************************************************************************************
1 plays in test.yml

PLAY [Test nmcli bond configuration with fail_over_mac parameter] *****************************************************************************************************************************************

TASK [Gathering Facts] ************************************************************************************************************************************************************************************
task path: /REDACTED//Open-Source/community.general/test.yml:2
<r1.incus> ESTABLISH SSH CONNECTION FOR USER: root
...
Using module file /usr/lib/python3.13/site-packages/ansible/modules/setup.py
...
<r1.incus> ESTABLISH SSH CONNECTION FOR USER: root
...
<r1.incus> SSH: EXEC ssh -C -o ControlMaster=auto -o ControlPersist=60s -o StrictHostKeyChecking=no -o 'IdentityFile="/REDACTED//Open-Source/community.general/home/REDACTED/.ssh/REDACTED"' -o KbdInteractiveAuthentication=no -o PreferredAuthentications=gssapi-with-mic,gssapi-keyex,hostbased,publickey -o PasswordAuthentication=no -o 'User="root"' -o ConnectTimeout=10 -o 'ControlPath="/home/REDACTED/.ansible/cp/97fe4e88a9"' -tt r1.incus '/bin/sh -c '"'"'/usr/bin/python3 /root/.ansible/tmp/ansible-tmp-1736801956.6801987-107447-259572370427240/AnsiballZ_setup.py && sleep 0'"'"''
ok: [r1.incus]

TASK [Configure bond0 interface with fail_over_mac parameter] *********************************************************************************************************************************************
task path: /REDACTED//Open-Source/community.general/test.yml:7
...
Using module file /REDACTED//Open-Source/community.general/local/ansible_collections/community/general/plugins/modules/nmcli.py
...
<r1.incus> (0, b'\r\n{"conn_name": "bond0", "state": "present", "Connection": "Connection bond0 of Type bond is being added", "changed": true, "stdout": "Connection \'bond0\' (632fd952-a7b2-48d5-8294-f48c491abad6) successfully added.\\n", "invocation": {"module_args": {"type": "bond", "conn_name": "bond0", "ifname": "bond0", "ip4": ["192.168.1.10/24"], "gw4": "192.168.1.1", "mode": "active-backup", "miimon": 100, "fail_over_mac": 1, "state": "present", "ignore_unsupported_suboptions": false, "autoconnect": true, "conn_reload": false, "gw4_ignore_auto": false, "never_default4": false, "dns4_ignore_auto": false, "may_fail4": true, "gw6_ignore_auto": false, "dns6_ignore_auto": false, "stp": true, "priority": 128, "slavepriority": 32, "forwarddelay": 15, "hellotime": 2, "maxage": 20, "ageingtime": 300, "hairpin": false, "path_cost": 100, "runner": "roundrobin", "master": null, "slave_type": null, "routes4": null, "routes4_extended": null, "route_metric4": null, "routing_rules4": null, "dns4": null, "dns4_search": null, "dns4_options": null, "method4": null, "dhcp_client_id": null, "ip6": null, "gw6": null, "dns6": null, "dns6_search": null, "dns6_options": null, "routes6": null, "routes6_extended": null, "route_metric6": null, "method6": null, "ip_privacy6": null, "addr_gen_mode6": null, "downdelay": null, "updelay": null, "xmit_hash_policy": null, "arp_interval": null, "arp_ip_target": null, "primary": null, "mtu": null, "mac": null, "zone": null, "runner_hwaddr_policy": null, "runner_fast_rate": null, "vlanid": null, "vlandev": null, "flags": null, "ingress": null, "egress": null, "vxlan_id": null, "vxlan_local": null, "vxlan_remote": null, "ip_tunnel_dev": null, "ip_tunnel_local": null, "ip_tunnel_remote": null, "ip_tunnel_input_key": null, "ip_tunnel_output_key": null, "ssid": null, "wifi": null, "wifi_sec": null, "gsm": null, "macvlan": null, "wireguard": null, "vpn": null, "transport_mode": null, "sriov": null}}}\r\n', b'Shared connection to r1.incus closed.\r\n')
changed: [r1.incus] => {
    "Connection": "Connection bond0 of Type bond is being added",
    "changed": true,
    "conn_name": "bond0",
    "invocation": {
        "module_args": {
            "addr_gen_mode6": null,
            "ageingtime": 300,
            "arp_interval": null,
            "arp_ip_target": null,
            "autoconnect": true,
            "conn_name": "bond0",
            "conn_reload": false,
            "dhcp_client_id": null,
            "dns4": null,
            "dns4_ignore_auto": false,
            "dns4_options": null,
            "dns4_search": null,
            "dns6": null,
            "dns6_ignore_auto": false,
            "dns6_options": null,
            "dns6_search": null,
            "downdelay": null,
            "egress": null,
            "fail_over_mac": 1,
            "flags": null,
            "forwarddelay": 15,
            "gsm": null,
            "gw4": "192.168.1.1",
            "gw4_ignore_auto": false,
            "gw6": null,
            "gw6_ignore_auto": false,
            "hairpin": false,
            "hellotime": 2,
            "ifname": "bond0",
            "ignore_unsupported_suboptions": false,
            "ingress": null,
            "ip4": [
                "192.168.1.10/24"
            ],
            "ip6": null,
            "ip_privacy6": null,
            "ip_tunnel_dev": null,
            "ip_tunnel_input_key": null,
            "ip_tunnel_local": null,
            "ip_tunnel_output_key": null,
            "ip_tunnel_remote": null,
            "mac": null,
            "macvlan": null,
            "master": null,
            "maxage": 20,
            "may_fail4": true,
            "method4": null,
            "method6": null,
            "miimon": 100,
            "mode": "active-backup",
            "mtu": null,
            "never_default4": false,
            "path_cost": 100,
            "primary": null,
            "priority": 128,
            "route_metric4": null,
            "route_metric6": null,
            "routes4": null,
            "routes4_extended": null,
            "routes6": null,
            "routes6_extended": null,
            "routing_rules4": null,
            "runner": "roundrobin",
            "runner_fast_rate": null,
            "runner_hwaddr_policy": null,
            "slave_type": null,
            "slavepriority": 32,
            "sriov": null,
            "ssid": null,
            "state": "present",
            "stp": true,
            "transport_mode": null,
            "type": "bond",
            "updelay": null,
            "vlandev": null,
            "vlanid": null,
            "vpn": null,
            "vxlan_id": null,
            "vxlan_local": null,
            "vxlan_remote": null,
            "wifi": null,
            "wifi_sec": null,
            "wireguard": null,
            "xmit_hash_policy": null,
            "zone": null
        }
    },
    "state": "present",
    "stdout": "Connection 'bond0' (632fd952-a7b2-48d5-8294-f48c491abad6) successfully added.\n",
    "stdout_lines": [
        "Connection 'bond0' (632fd952-a7b2-48d5-8294-f48c491abad6) successfully added."
    ]
}

PLAY RECAP ************************************************************************************************************************************************************************************************
r1.incus                   : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

[root@r1 ~]# cat /sys/class/net/bond0/bonding/fail_over_mac 
active 1

[ansibullbot]

cc @alcamie101
click here for bot help

[felixfontein]

Thanks for your contribution! I've added some first comments.

[russoz]

LGTM

[patchback]

Backport to stable-10: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-10/d6863eaec3470607e39aab9ac70b312243e9eed9/pr-9571

Backported as #9594

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

[felixfontein]

@cnfrancis thanks for your contribution!
@russoz thanks for reviewing!