From 0c3279af9273873cd5e8ea36502582351277eba4 Mon Sep 17 00:00:00 2001 From: Jose Date: Wed, 24 Dec 2025 07:07:13 +0100 Subject: [PATCH] =?UTF-8?q?docs=20=F0=9F=93=9D:=20Update=20README.md=20for?= =?UTF-8?q?=20improved=20interface=20detection=20and=20troubleshooting=20g?= =?UTF-8?q?uidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 43 ++++++++++++++++---------- tasks/main.yml | 84 +++++++++++++++++++++++++++++++------------------- 2 files changed, 79 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index d4ac7c6..2ca481f 100644 --- a/README.md +++ b/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 ` +- Some NICs may require specific BIOS settings or driver parameters +- Check if interfaces are properly detected: `ansible -m setup | 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 ` -- 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 diff --git a/tasks/main.yml b/tasks/main.yml index e4c2b2c..9a66d90 100644 --- a/tasks/main.yml +++ b/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 # ============================================================