ansible_proxmox_WOL/README.md

# 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)
```yaml
- hosts: proxmox
  become: true
  roles:
    - ansible_proxmox_WOL
```
Automatically configures WOL for the default `vmbr0` bridge.

### Multiple Bridges
```yaml
- 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
```yaml
- hosts: proxmox
  become: true
  roles:
    - role: ansible_proxmox_WOL
      vars:
        wol_bridges: vmbr1
        wol_verify: false
```

### Disable WOL
```yaml
- 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:
```yaml
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