feat ✨: Add support for Wake-on-LAN

Enables Wake-on-LAN by setting `wol_interface` to an empty string and enables MAC address reporting.

README.md

@@ -11,12 +11,17 @@ This Ansible role enables persistent Wake-on-LAN (WOL) on a Proxmox VE server.
 | wol_verify | true | Verify WOL status |
 
 
-## Requirements
+## Notes for Proxmox admins
 
-Use the physical NIC, not vmbr0, unless your NIC supports WOL through the bridge
+Auto-detection works best when:
-Common interfaces:  eno1, enp3s0, eth0
+    The management IP uses the physical NIC
-Verify BIOS/UEFI:   Enable Wake on LAN
+    You are not routing management via vmbr0 only
-Disable ErP / Deep Sleep
+
+If your default route is on vmbr0, manual override is recommended
+
+BIOS must still have:
+    Wake on LAN enabled
+    ErP disabled
 
 ## Example Playbook
 
@@ -26,4 +31,4 @@ Disable ErP / Deep Sleep
   roles:
     - role: ansible_proxmox_WOL
       vars:
-        wol_interface: vmbr0
+        wol_interface: vmbr0    # Optional, comment for autodetection

defaults/main.yml

@@ -1,5 +1,5 @@
 # Network interface to enable Wake-on-LAN on
-wol_interface: "eno1"
+wol_interface: ""
 
 # WOL mode:
 # g = magic packet (most common)
@@ -7,3 +7,6 @@ wol_mode: "g"
 
 # Enable verification task
 wol_verify: true
+
+# Report MAC address for WOL senders
+wol_report_mac: true

tasks/main.yml

@@ -1,12 +1,57 @@
 ---
 - name: Install required packages
-  apt:
+  ansible.builtin.apt:
     name: ethtool
     state: present
     update_cache: yes
 
+- name: Gather network facts
+  ansible.builtin.setup:
+    gather_subset:
+      - network
+
+- name: Detect default route interface
+  ansible.builtin.set_fact:
+    wol_detected_interface: "{{ ansible_default_ipv4.interface }}"
+  when: wol_interface | length == 0
+
+- name: Validate detected interface is physical
+  ansible.builtin.set_fact:
+    wol_interface_final: "{{ wol_detected_interface }}"
+  when:
+    - wol_interface | length == 0
+    - wol_detected_interface is defined
+    - wol_detected_interface is not match("^vmbr")
+    - wol_detected_interface is not match("^lo")
+    - wol_detected_interface is not match("^bond")
+    - wol_detected_interface is not match("^tap")
+    - wol_detected_interface is not match("^veth")
+
+- name: Use manually defined interface if provided
+  ansible.builtin.set_fact:
+    wol_interface_final: "{{ wol_interface }}"
+  when: wol_interface | length > 0
+
+- name: Fail if no suitable NIC was found
+  ansible.builtin.fail:
+    msg: >
+      Unable to determine a suitable physical NIC for Wake-on-LAN.
+      Please set wol_interface manually.
+  when: wol_interface_final is not defined
+
+- name: Check WOL support on interface
+  ansible.builtin.command: ethtool {{ wol_interface_final }}
+  register: wol_capabilities
+  changed_when: false
+
+- name: Fail if NIC does not support Wake-on-LAN
+  ansible.builtin.fail:
+    msg: "Interface {{ wol_interface_final }} does not support Wake-on-LAN."
+  when: "'Supports Wake-on-Wake-on-LAN' in wol_capabilities.stdout or
+         'Wake-on:' not in wol_capabilities.stdout"
+
 - name: Create systemd service for Wake-on-LAN
-  template:
+  ansible.builtin.template:
     src: wol.service.j2
     dest: /etc/systemd/system/wol.service
     owner: root
@@ -17,16 +62,44 @@
     - Enable and start WOL service
 
 - name: Enable WOL immediately (without reboot)
-  command: ethtool -s {{ wol_interface }} wol {{ wol_mode }}
+  ansible.builtin.command: ethtool -s {{ wol_interface_final  }} wol {{ wol_mode }}
   changed_when: false
 
 - name: Verify Wake-on-LAN status
-  command: ethtool {{ wol_interface }}
+  ansible.builtin.command: ethtool {{ wol_interface_final  }}
   register: wol_status
   changed_when: false
   when: wol_verify
 
+- name: Get MAC address of WOL interface
+  set_fact:
+    wol_mac_address: >-
+      {{
+        ansible_facts['ansible_' + wol_interface_final]['macaddress']
+        | default('')
+      }}
+
 - name: Show WOL status
-  debug:
+  ansible.builtin.debug:
     msg: "{{ wol_status.stdout_lines }}"
   when: wol_verify
+
+- name: Fail if MAC address could not be detected
+  fail:
+    msg: "Unable to determine MAC address for interface {{ wol_interface_final }}"
+  when:
+    - wol_report_mac
+    - wol_mac_address | length == 0
+
+- name: Report Wake-on-LAN sender details
+  ansible.builtin.debug:
+    msg:
+      - "Wake-on-LAN enabled on interface: {{ wol_interface_final }}"
+      - "MAC address: {{ wol_mac_address }}"
+      - "Example WOL commands:"
+      - "  wakeonlan {{ wol_mac_address }}"
+      - "  etherwake {{ wol_mac_address }}"
+      - "Home Assistant:"
+      - "  mac: {{ wol_mac_address }}"
+  when: wol_report_mac
+

templates/wol.service.j2

@@ -1,10 +1,10 @@
 [Unit]
-Description=Enable Wake-on-LAN
+Description=Enable Wake-on-LAN on {{ wol_interface_final }}
 After=network.target
 
 [Service]
 Type=oneshot
-ExecStart=/sbin/ethtool -s {{ wol_interface }} wol {{ wol_mode }}
+ExecStart=/sbin/ethtool -s {{ wol_interface_final }} wol {{ wol_mode }}
 
 [Install]
 WantedBy=multi-user.target