docs 📝: Update README.md for improved interface detection and troubleshooting guidance

Updated the README.md file to include detailed instructions on how to improve interface detection, add Ansible facts-based validation, and enhance troubleshooting guidance.

README.md

@@ -1,13 +1,13 @@
 # ansible_proxmox_WOL
 
-A robust, idempotent Ansible role for enabling persistent Wake-on-LAN (WOL) on Proxmox VE servers. This role automatically detects physical network interfaces backing bridge interfaces (including bonded interfaces) and persistently enables WOL via udev rules.
+A robust, idempotent Ansible role for enabling persistent Wake-on-LAN (WOL) on Proxmox VE servers. This role automatically detects physical network interfaces with WOL capability using Ansible facts and persistently enables WOL via udev rules.
 
 ## Features
 
 ✅ **Fully Idempotent**: Checks current WOL status and only applies changes when needed  
 ✅ **Multiple Bridge Support**: Configure WOL on multiple bridges simultaneously  
 ✅ **Bond0 Detection**: Automatically detects and configures bonded interfaces  
-✅ **Auto-Detection**: Intelligently detects physical NICs backing Proxmox bridges  
+✅ **Ansible Facts-Based**: Uses Ansible facts to detect and validate WOL-capable interfaces  
 ✅ **Safe & Persistent**: Uses udev rules for persistence across reboots  
 ✅ **Comprehensive Validation**: Verifies WOL capability before configuration  
 ✅ **Detailed Reporting**: Shows configuration status and MAC addresses for WOL senders  
@@ -24,14 +24,15 @@ A robust, idempotent Ansible role for enabling persistent Wake-on-LAN (WOL) on P
 ## How It Works
 
 1. **Package Installation**: Ensures `ethtool` is installed for WOL management
-2. **Bridge Discovery**: Reads bridge configuration and maps to physical NICs
-3. **Bond0 Detection**: Detects if interfaces are bonded and extracts slave information
-4. **Validation**: Verifies all detected NICs support Wake-on-LAN
-5. **Idempotency Check**: Reads current WOL status to avoid redundant changes
-6. **Enable WOL**: Applies WOL settings only to interfaces that need it
-7. **Persist Settings**: Creates/updates udev rules for persistence across reboots
-8. **Reload Udev**: Reloads udev rules and triggers network interface refresh
-9. **Verification & Reporting**: Displays WOL configuration status and MAC addresses
+2. **Interface Discovery**: Uses Ansible facts to identify all physical Ethernet interfaces
+3. **WOL Validation**: Tests each interface for Wake-on-LAN capability using ethtool
+4. **Bridge Mapping**: Maps configured bridges to their backing WOL-capable physical NICs
+5. **Bond0 Detection**: Detects if interfaces are bonded and extracts slave information
+6. **Idempotency Check**: Reads current WOL status to avoid redundant changes
+7. **Enable WOL**: Applies WOL settings only to interfaces that need it
+8. **Persist Settings**: Creates/updates udev rules for persistence across reboots
+9. **Reload Udev**: Reloads udev rules and triggers network interface refresh
+10. **Verification & Reporting**: Displays WOL configuration status and MAC addresses
 
 ## Usage Examples
 
@@ -165,32 +166,42 @@ ACTION=="add", SUBSYSTEM=="net", KERNEL=="eno1", RUN+="/sbin/ethtool -s eno1 wol
 ```
 
 ### Detection Logic
-1. Reads `bridge link show` output
-2. Filters out virtual interfaces (veth, tap, fw*)
-3. Selects first physical NIC per bridge
-4. For bond0: extracts slave interfaces from `/proc/net/bonding/bond0`
+1. **Interface Discovery**: Uses Ansible facts to enumerate all network interfaces
+2. **Physical Interface Filtering**: Filters for Ethernet interfaces, excluding virtual interfaces (veth, tap, fw*, docker, br*)
+3. **WOL Capability Testing**: Tests each physical interface with ethtool to verify WOL support
+4. **Bridge Mapping**: Maps configured bridges to their backing WOL-capable physical NICs
+5. **Bond0 Detection**: Extracts slave interfaces from `/proc/net/bonding/bond0` when present
 
 ## Troubleshooting
 
+### "No network interfaces found that support Wake-on-LAN"
+- Check BIOS settings to ensure WOL is enabled
+- Verify NIC drivers support WOL: `ethtool <interface>`
+- Some NICs may require specific BIOS settings or driver parameters
+- Check if interfaces are properly detected: `ansible -m setup <host> | grep ansible_interfaces`
+
 ### "Unable to detect physical NIC backing bridge(s)"
 - Verify bridges exist: `bridge link show`
 - Check bridge configuration: `brctl show`
 - Ensure physical NIC is member of bridge
+- Confirm the backing interface supports WOL (listed in "Available WOL-capable interfaces")
 
 ### "Does not support Wake-on-LAN"
 - Check NIC capabilities: `ethtool <interface>`
-- Verify BIOS has WOL enabled
+- Verify BIOS has WOL enabled for the specific NIC
 - Some NICs have disabled WOL by default (check driver documentation)
+- Try different WOL modes: `p`, `u`, `m`, or `b`
 
 ### WOL not persisting after reboot
 - Check udev rules: `cat /etc/udev/rules.d/90-wol.rules`
 - Verify ethtool installed: `which ethtool`
 - Check system logs: `journalctl -u systemd-udevd -b`
+- Ensure udev service is running: `systemctl status systemd-udevd`
 
 ### Bond0 not detected
 - Check bond status: `cat /proc/net/bonding/bond0`
 - Verify bond is backing the configured bridge
-- Check bond slave interfaces
+- Check bond slave interfaces support WOL individually
 
 ## Notes for Proxmox Admins
 

tasks/main.yml

@@ -22,7 +22,55 @@
     fail_msg: "wol_bridges must contain at least one bridge interface"
 
 # ============================================================
-# Detect physical NICs for all bridges (including bond0)
+# Detect physical NICs with WOL support using Ansible facts
+# ============================================================
+- name: Gather network interface facts
+  ansible.builtin.setup:
+    gather_subset:
+      - network
+  when: ansible_facts.interfaces is not defined
+
+- name: Get all physical network interfaces with WOL support
+  ansible.builtin.set_fact:
+    wol_capable_interfaces: >-
+      {{
+        ansible_facts.interfaces
+        | map('extract', hostvars[inventory_hostname]['ansible_' ~ item] | default({}))
+        | selectattr('type', 'defined')
+        | selectattr('type', 'equalto', 'ether')
+        | selectattr('device', 'defined')
+        | rejectattr('device', 'search', '^(veth|tap|fw|lo|docker|br)')
+        | map(attribute='device')
+        | list
+      }}
+
+- name: Validate WOL capability using ethtool for detected interfaces
+  ansible.builtin.command: "ethtool {{ item }}"
+  register: wol_capabilities_check
+  changed_when: false
+  failed_when: false
+  loop: "{{ wol_capable_interfaces }}"
+  loop_control:
+    label: "{{ item }}"
+
+- name: Filter interfaces that actually support WOL
+  ansible.builtin.set_fact:
+    wol_supported_interfaces: >-
+      {{
+        wol_capabilities_check.results
+        | selectattr('stdout', 'search', 'Supports Wake-on:.*[gGdDpPuU]')
+        | map(attribute='item')
+        | list
+      }}
+
+- name: Fail if no interfaces support WOL
+  ansible.builtin.assert:
+    that:
+      - wol_supported_interfaces | length > 0
+    fail_msg: "No network interfaces found that support Wake-on-LAN. Check BIOS settings and NIC capabilities."
+
+# ============================================================
+# Map bridges to physical NICs using Ansible facts
 # ============================================================
 - name: Get bridge link information
   ansible.builtin.command: "bridge link show"
@@ -30,13 +78,6 @@
   changed_when: false
   check_mode: false
 
-- name: Get bond info
-  ansible.builtin.command: "cat /proc/net/bonding/bond0"
-  register: bond_info
-  changed_when: false
-  failed_when: false
-  check_mode: false
-
 - name: Initialize detected interfaces dictionary
   ansible.builtin.set_fact:
     wol_detected_interfaces: {}
@@ -52,6 +93,7 @@
             | map('regex_replace', '^\\d+: ([a-z0-9@.]+):.*$', '\\1')
             | reject('search', '^(veth|tap|fw)')
             | reject('search', '^\\d+:')
+            | select('in', wol_supported_interfaces)
             | first | default('')
           )
         })
@@ -82,9 +124,8 @@
   ansible.builtin.fail:
     msg: >
       Unable to detect physical NIC backing bridge(s): {{ unresolved_bridges | join(', ') }}.
-      Please verify bridges exist or set wol_interfaces explicitly.
-      Bridge output:
-      {{ bridge_links.stdout_lines | join('\n') }}
+      Please verify bridges exist and are backed by WOL-capable interfaces.
+      Available WOL-capable interfaces: {{ wol_supported_interfaces | join(', ') }}
   vars:
     unresolved_bridges: "{{ wol_detected_interfaces | dict2items | selectattr('value', 'equalto', '') | map(attribute='key') | list }}"
   when: unresolved_bridges | length > 0
@@ -93,27 +134,6 @@
   ansible.builtin.set_fact:
     wol_final_interfaces: "{{ wol_detected_interfaces.values() | unique | list }}"
 
-# ============================================================
-# Validate WOL capability
-# ============================================================
-- name: Check WOL capability on all detected NICs
-  ansible.builtin.command: "ethtool {{ item }}"
-  register: wol_capabilities_check
-  changed_when: false
-  failed_when: false
-  loop: "{{ wol_final_interfaces }}"
-  loop_control:
-    label: "{{ item }}"
-
-- name: Validate all NICs support WOL
-  ansible.builtin.assert:
-    that:
-      - item.stdout is search('Supports Wake-on:.*[gGdDpPuU]')
-    fail_msg: "Interface {{ item.item }} does not support Wake-on-LAN"
-  loop: "{{ wol_capabilities_check.results }}"
-  loop_control:
-    label: "{{ item.item }}"
-
 # ============================================================
 # Check current WOL status to ensure idempotency
 # ============================================================