ansible_proxmox_WOL

An Ansible role that configures persistent Wake‑on‑LAN (WOL) on Proxmox VE hosts.
It discovers all physical Ethernet interfaces, validates WOL support, and then enables or disables WOL on the interfaces that back the bridges you specify.
Unlike many WOL setups that rely on udev rules, this role uses a lightweight systemd template unit (wol@.service) so the setting is applied automatically each time an interface comes up, and it survives reboots without any extra steps.

---

Table of Contents

• Features
• Prerequisites
• Role Variables
• How It Works
• Usage
• Common Proxmox Scenarios
• Troubleshooting
• License
• Author

---

Features

Feature	Description
✅ Fully idempotent	Only touches an interface if the desired WOL mode differs from what ethtool currently reports.
✅ Multiple bridge support	Pass a single string or a list of bridge names to wol_bridges.
✅ Bond0 detection	If a bridge is built on a bond (e.g., bond0), all slaves receive the same WOL configuration.
✅ Facts‑driven	Uses Ansible facts (ansible_interfaces) to filter out virtual and non‑Ethernet devices.
✅ Persistent via systemd	WOL is enforced by a wol@.service template that is started for each enabled interface.
✅ Comprehensive validation	Each interface is queried with ethtool to confirm real WOL support before making any changes.
✅ Detailed reporting	The role prints a summary of every interface it touched, including the MAC addresses of WOL‑capable senders when wol_report_mac is true.

---

Prerequisites

Requirement	How the role satisfies it
Proxmox VE host	Target host runs Debian‑based Proxmox (the role uses Debian/Proxmox defaults).
Ansible ≥ 2.9	The role only uses built‑in modules (setup, package, command, template, systemd).
ethtool	The role installs the ethtool package if it is not already present.
Root / sudo access	All tasks modify network configuration; become: true is required.
BIOS/WMI WOL	WOL must be enabled in the host BIOS and the NIC driver must expose the Wake‑On‑LAN flag.

---

Role Variables

# defaults/main.yml
wol_bridges: vmbr0          # string or list – bridges that should have WOL enabled
wol_mode: "g"               # "g"=magic packet (recommended), "d"=disable, "p"/"u"/"m"/"b" for other modes
wol_verify: true            # Verify the interface state after changes
wol_report_mac: true        # Include MAC addresses of WOL‑capable senders in the report

Variable	Default	Type	Description
wol_bridges	vmbr0	string/list	Bridge(s) to configure. If you pass a string, the role treats it as a single‑item list.
wol_mode	"g"	string	Desired WOL mode. See the variable table above for valid options.
wol_verify	true	bool	Whether to run ethtool again after the changes and include the result in the final report.
wol_report_mac	true	bool	Whether to list the MAC address of each NIC that will send WOL packets.

---

How It Works

1. Package Install – Ensures the ethtool binary is present.
2. Interface Discovery – Uses ansible_facts.ansible_interfaces to collect all interfaces, then filters out virtual ones (veth*, tap*, docker*, etc.).
3. WOL Validation – For each remaining physical NIC, ethtool <iface> | grep 'Wake-on' is used to confirm that the NIC supports WOL.
4. Bridge Mapping – The role resolves each bridge name in wol_bridges to the underlying physical interface(s). If a bridge is built on a bond (e.g., bond0), every slave is treated as a candidate.
5. Idempotency Check – The current WOL state (wol_enabled) is compared to wol_mode.
6. Apply WOL –
   • If wol_mode ≠ 'd' and the current mode differs, ethtool -s <iface> wol <mode> is run.
   • If wol_mode is 'd', the role ensures WOL is disabled.
7. Deploy systemd template – Copies templates/wol@.service.j2 to /etc/systemd/system/wol@.service. The template contains ExecStart=/usr/sbin/ethtool -s %I wol {{ wol_mode }}.
8. Enable service per interface – For every affected interface, the role starts the unit wol@<iface>.service and enables it to run on boot.
9. Report – A final summary is printed, optionally listing MAC addresses if wol_report_mac is true.

---

Usage

Basic Playbook

- hosts: proxmox
  become: true
  roles:
    - ansible_proxmox_WOL

Result – WOL is automatically enabled on the physical NIC that backs the default vmbr0 bridge.

Multiple Bridges

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

Result – All three bridges are processed; the physical NICs that belong to each bridge receive the configured WOL mode.

Disable WOL

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

Result – WOL is disabled on every physical NIC that the role discovered, regardless of bridge.

Turn Off Verification

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

Result – WOL is set on vmbr1’s backing NIC(s) but the role does not perform a post‑change check.

---

Common Proxmox Scenarios

Scenario	Bridge / NIC Layout	What the role does
Standard vmbr0	eno1 → vmbr0	Enables WOL on eno1.
Bonded NICs	eno1, eno2 → bond0 → vmbr0	Detects bond0 and sets WOL on both slaves.
Multiple Bridges	eno1 → vmbr0 eno2 → vmbr1 eno3, eno4 → bond0 → vmbr2	One role run configures all three bridges automatically.

---

Troubleshooting

Problem	Likely Cause	Fix
No interfaces found that support WOL	BIOS WOL disabled, NIC driver doesn’t expose the feature, or interface isn’t a physical NIC.	Enable WOL in BIOS, run ethtool <iface> manually, verify `ansible -m setup
Unable to detect bridge backing NIC(s)	Bridge doesn’t exist or the NIC isn’t a member of it.	Verify with bridge link show / brctl show.
WOL not persisting after reboot	wol@.service isn’t enabled, or ethtool isn’t installed.	Ensure the role ran successfully, check /etc/systemd/system/wol@.service and systemctl status wol@<iface>.service.
Bond0 not detected	Bond configuration file missing or wrong.	Check /proc/net/bonding/bond0.
WOL mode unsupported	NIC driver only supports a subset of modes.	Try a different wol_mode value (e.g., p, u, m, b).

---

License

MIT

---

Author

Ansible Proxmox WOL Contributors