docs 📝: Refactor README.md with detailed features, role variables, and usage examples.
Updated the README to provide comprehensive information on the Ansible Proxmox WOL role's features, variables, and usage examples.
This commit is contained in:
208
README.md
208
README.md
@@ -1,34 +1,208 @@
|
||||
# ansible_proxmox_WOL
|
||||
|
||||
This Ansible role enables persistent Wake-on-LAN (WOL) on a Proxmox VE server.
|
||||
A robust, idempotent Ansible role for enabling persistent Wake-on-LAN (WOL) on Proxmox VE servers. This role automatically detects physical network interfaces backing bridge interfaces (including bonded interfaces) and persistently enables WOL via udev rules.
|
||||
|
||||
## Variables
|
||||
## Features
|
||||
|
||||
| Variable | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| wol_interface | eno1 | Network interface |
|
||||
| wol_mode | g | WOL mode (magic packet) |
|
||||
| wol_verify | true | Verify WOL status |
|
||||
✅ **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
|
||||
✅ **Auto-Detection**: Intelligently detects physical NICs backing Proxmox bridges
|
||||
✅ **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
|
||||
|
||||
## Notes for Proxmox admins
|
||||
| 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 |
|
||||
|
||||
Auto-detection works best when:
|
||||
The management IP uses the physical NIC
|
||||
You are not routing management via vmbr0 only
|
||||
## How It Works
|
||||
|
||||
If your default route is on vmbr0, manual override is recommended
|
||||
1. **Package Installation**: Ensures `ethtool` is installed for WOL management
|
||||
2. **Bridge Discovery**: Reads bridge configuration and maps to physical NICs
|
||||
3. **Bond0 Detection**: Detects if interfaces are bonded and extracts slave information
|
||||
4. **Validation**: Verifies all detected NICs support Wake-on-LAN
|
||||
5. **Idempotency Check**: Reads current WOL status to avoid redundant changes
|
||||
6. **Enable WOL**: Applies WOL settings only to interfaces that need it
|
||||
7. **Persist Settings**: Creates/updates udev rules for persistence across reboots
|
||||
8. **Reload Udev**: Reloads udev rules and triggers network interface refresh
|
||||
9. **Verification & Reporting**: Displays WOL configuration status and MAC addresses
|
||||
|
||||
BIOS must still have:
|
||||
Wake on LAN enabled
|
||||
ErP disabled
|
||||
## Usage Examples
|
||||
|
||||
## Example Playbook
|
||||
### 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_interface: vmbr0 # Optional, comment for autodetection
|
||||
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. Reads `bridge link show` output
|
||||
2. Filters out virtual interfaces (veth, tap, fw*)
|
||||
3. Selects first physical NIC per bridge
|
||||
4. For bond0: extracts slave interfaces from `/proc/net/bonding/bond0`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "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
|
||||
|
||||
### "Does not support Wake-on-LAN"
|
||||
- Check NIC capabilities: `ethtool <interface>`
|
||||
- Verify BIOS has WOL enabled
|
||||
- Some NICs have disabled WOL by default (check driver documentation)
|
||||
|
||||
### 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`
|
||||
|
||||
### Bond0 not detected
|
||||
- Check bond status: `cat /proc/net/bonding/bond0`
|
||||
- Verify bond is backing the configured bridge
|
||||
- Check bond slave interfaces
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user