ansible_proxmox_WOL/README.md

# 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](#features)  
- [Prerequisites](#prerequisites)  
- [Role Variables](#role-variables)  
- [How It Works](#how-it-works)  
- [Usage](#usage)  
- [Common Proxmox Scenarios](#common-proxmox-scenarios)  
- [Troubleshooting](#troubleshooting)  
- [License](#license)  
- [Author](#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

```yaml
# 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** – Resolves each bridge name in `wol_bridges` to the 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 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

```yaml
- 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

```yaml
- 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

```yaml
- 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

```yaml
- 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`  <br> `eno2` → `vmbr1` <br> `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 <host> | grep ansible_interfaces`. |
| **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