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 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
✅ 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

Role Variables

Variable	Default	Type	Description
wol_bridges	vmbr0	string/list	Bridge interface(s) to enable WOL on. Can be a single bridge as string or multiple bridges as a list.
wol_mode	g	string	WOL mode: g (magic packet - recommended), d (disable), p (physical activity), u (unicast), m (multicast), b (broadcast)
wol_verify	true	boolean	Verify WOL status after configuration and display results
wol_report_mac	true	boolean	Include MAC addresses in configuration report

How It Works

1. Package Installation: Ensures ethtool is installed for WOL management
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

Basic Single Bridge (Auto-Detection)

- hosts: proxmox
  become: true
  roles:
    - ansible_proxmox_WOL

Automatically configures WOL for the default vmbr0 bridge.

Multiple Bridges

- hosts: proxmox
  become: true
  roles:
    - role: ansible_proxmox_WOL
      vars:
        wol_bridges:
          - vmbr0
          - vmbr1
          - vmbr2

Configures WOL for multiple bridge interfaces simultaneously.

Custom Bridge with Verification Disabled

- hosts: proxmox
  become: true
  roles:
    - role: ansible_proxmox_WOL
      vars:
        wol_bridges: vmbr1
        wol_verify: false

Disable WOL

- hosts: proxmox
  become: true
  roles:
    - role: ansible_proxmox_WOL
      vars:
        wol_mode: d

Bond0 Support

The role automatically detects if configured bridges are backed by bonded interfaces (bond0). When bond0 is detected:

• The underlying physical slave interfaces are identified
• All slaves are configured with the same WOL settings
• The configuration is displayed in the summary report

Example output when bond0 is detected:

Bond0 Detected: Yes
Bond0 Slaves: eth0, eth1
Physical Interfaces: bond0

Common Proxmox Scenarios

Scenario 1: Standard vmbr0 Setup

Physical NIC (eno1) → vmbr0 bridge

The role automatically configures eno1 with WOL settings.

Scenario 2: Bonded Interface

Physical NICs (eno1, eno2) → bond0 → vmbr0 bridge

The role detects bond0 and applies WOL to bonded slaves.

Scenario 3: Multiple Bridges

eno1 → vmbr0
eno2 → vmbr1
bond0 (eno3, eno4) → vmbr2

Configure all bridges with one role application:

wol_bridges:
  - vmbr0
  - vmbr1
  - vmbr2

Prerequisites

• Proxmox VE host with bridge interfaces configured
• Ansible 2.9+
• ethtool package (installed automatically by role)
• Root/sudo access on target host (required for udev and ethtool)
• BIOS Configuration:
  • Wake-on-LAN enabled in BIOS
  • ErP (Energy-Related Products) disabled in BIOS

Idempotency

This role is fully idempotent. Running it multiple times has the same effect as running it once:

• ✅ Only enables WOL on interfaces that don't already have it enabled
• ✅ Skips udev rule reload if rules haven't changed
• ✅ Uses changed_when conditions to accurately report actual changes
• ✅ Safe to include in recurring Ansible playbooks and AWX workflows

Safety

• Non-Destructive: Never disables interfaces or changes bridge configuration
• Validation: Verifies NIC WOL capability before making changes
• Error Handling: Fails gracefully with clear error messages if:
  • Bridges cannot be detected
  • Physical NICs cannot be found
  • NICs don't support Wake-on-LAN
• Check Mode Support: Fully compatible with --check mode for safe preview

Implementation Details

Persistence Method

WOL settings are persisted using udev rules at /etc/udev/rules.d/90-wol.rules. This is the most reliable method for Debian/Proxmox systems and survives:

• System reboots
• Network service restarts
• Interface state changes

Example generated udev rule:

ACTION=="add", SUBSYSTEM=="net", KERNEL=="eno1", RUN+="/sbin/ethtool -s eno1 wol g"

Detection Logic

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 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 support WOL individually

Notes for Proxmox Admins

• Default Bridge: Proxmox typically uses vmbr0 as the default management bridge
• No DHCP Changes: This role only configures WOL; it doesn't modify IP configuration
• Performance Impact: WOL has negligible performance impact
• Network Redundancy: If using bonds or multiple bridges, all configured interfaces will be enabled for WOL

License

MIT

Author

Ansible Proxmox WOL Contributors