208 lines
5.6 KiB
Markdown
208 lines
5.6 KiB
Markdown
# Proxmox-WOL-Server
|
||
|
||
Helper scripts to integrate **Wake-on-LAN** with **Proxmox VE VMs** and to manage / inspect VM MAC addresses from the host.
|
||
|
||
This repository currently provides:
|
||
|
||
- `pve-list-mac-addresses.sh` — list all VM NICs and MAC addresses on a PVE node
|
||
- (optional) `pve-wol-server.sh` — listen for WOL packets on a bridge and start matching VMs automatically
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
Typical use case:
|
||
|
||
- You want to **wake a specific Proxmox VM** from a client (e.g. Moonlight, another PC, NAS, etc.).
|
||
- The client sends a **WOL magic packet** to your Proxmox bridge/VLAN.
|
||
- Proxmox host runs a small script (`pve-wol-server.sh`) that:
|
||
- listens for these packets on an interface (e.g. `vmbr0`, `vmbr1`, `ovs`, etc.),
|
||
- extracts the **target MAC**,
|
||
- finds a matching VM,
|
||
- and **starts** the corresponding VM.
|
||
|
||
`pve-list-mac-addresses.sh` helps with the annoying part: **figuring out which VM has which MAC on which interface/bridge** directly from PVE’s configs.
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
- Proxmox VE node (Debian-based host with `qm` available)
|
||
- `bash`
|
||
- `awk`, `printf`, standard coreutils
|
||
- Root or sufficient privileges to run `qm list` / `qm config`
|
||
|
||
For `wol_hack.sh` (if used):
|
||
|
||
- `tcpdump` (or similar packet capture tool)
|
||
- Access to the relevant bridge/interface that receives WOL/magic packets
|
||
|
||
---
|
||
|
||
## Scripts
|
||
|
||
### `list-pve-vm-macs.sh`
|
||
|
||
Lists all **QEMU VMs** on the node and prints:
|
||
|
||
- VMID
|
||
- VM name
|
||
- NIC (`net0`, `net1`, …)
|
||
- MAC address
|
||
- Attached bridge (e.g. `vmbr0`, `vmbr1`, `ovs`, …)
|
||
|
||
#### Installation
|
||
|
||
On the Proxmox node:
|
||
|
||
```bash
|
||
cd /root/PVE-VM-WOL # or any directory you prefer
|
||
nano pve-list-mac-addresses.sh # paste the script content
|
||
chmod +x pve-list-mac-addresses.sh
|
||
```
|
||
|
||
#### Usage
|
||
|
||
Basic usage:
|
||
|
||
```bash
|
||
./pve-list-mac-addresses.sh
|
||
```
|
||
|
||
Example output:
|
||
|
||
```text
|
||
ID NAME IF MAC BRIDGE
|
||
---------------------------------------------------------------------
|
||
100 datacenter-vm net0 DE:AD:BE:EF:01:02 vmbr0
|
||
101 jellyfin net0 DE:AD:BE:EF:01:03 vmbr1
|
||
102 vaultwarden net0 DE:AD:BE:EF:01:04 ovs
|
||
```
|
||
|
||
Only MAC addresses (e.g. for mapping files, WOL tools, etc.):
|
||
|
||
```bash
|
||
./pve-list-mac-addresses.sh | awk 'NR>2 {print $4}'
|
||
```
|
||
|
||
Export to CSV:
|
||
|
||
```bash
|
||
./pve-list-mac-addresses.sh | awk 'NR>2 {print $1","$2","$3","$4","$5}' > vm-macs.csv
|
||
```
|
||
|
||
#### How it works (short version)
|
||
|
||
- Uses `qm list` to obtain VMIDs.
|
||
- For each VMID, queries `qm config <vmid>`:
|
||
- reads `name:` for the VM name,
|
||
- parses all `netX:` lines,
|
||
- splits the NIC options into `key=value` pairs,
|
||
- identifies the MAC by pattern (`aa:bb:cc:dd:ee:ff`),
|
||
- extracts the `bridge=` field.
|
||
|
||
The script intentionally uses **very basic `awk` features** so that it works on older Proxmox/Debian versions without GNU-specific extensions.
|
||
|
||
---
|
||
|
||
### `pve-wol-server.sh` (optional listener)
|
||
|
||
This script is typically used to:
|
||
|
||
1. Listen on a given interface/bridge (e.g. `vmbr1`) for:
|
||
- WOL packets (`ether proto 0x0842`) or
|
||
- UDP port 9 (traditional WOL port).
|
||
2. Extract the MAC address from the packet.
|
||
3. Find a VM with that MAC in its `netX:` config.
|
||
4. `qm start <vmid>` for the matching VM.
|
||
|
||
Typical setup:
|
||
|
||
```bash
|
||
cd /root/PVE-VM-WOL
|
||
nano pve-wol-server.sh
|
||
chmod +x pve-wol-server.sh
|
||
```
|
||
|
||
Then either run it manually:
|
||
|
||
```bash
|
||
./pve-wol-server.sh
|
||
```
|
||
|
||
Or create a systemd service to run it in the background on boot.
|
||
|
||
> **Warning:**
|
||
> If misused or flooded with packets, this script can lead to a lot of VM start attempts.
|
||
> You should add:
|
||
> - rate limiting (e.g. sleep between loops),
|
||
> - basic logging,
|
||
> - and maybe IP/MAC allow-lists.
|
||
|
||
Use `pve-list-mac-addresses.sh` to verify the VM MACs that `pve-wol-server.sh` should respond to.
|
||
|
||
---
|
||
|
||
## Extending the Toolkit
|
||
|
||
Planned / possible additions:
|
||
|
||
- **LXC support:**
|
||
Parse `/etc/pve/lxc/*.conf` for `hwaddr=XX:XX:XX:XX:XX:XX` and print them in the same table format.
|
||
|
||
- **Static mapping file generator:**
|
||
Export VMID → MAC mapping into a flat file, JSON, or key-value format for other tools.
|
||
|
||
- **Systemd units:**
|
||
Ready-made `systemd` service files for:
|
||
- WOL listener (`pve-wakeonlan.service`),
|
||
- Periodic MAC export (`list-pve-vm-macs.timer` → writes CSV to a shared location).
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
- **No output / empty table**
|
||
|
||
- Check that VMs exist:
|
||
```bash
|
||
qm list
|
||
```
|
||
- Ensure you run the script **on the Proxmox host**, not inside a guest.
|
||
|
||
- **Script errors for `qm` or `awk`**
|
||
|
||
- Make sure `qm` is in `$PATH` (it should be on PVE hosts).
|
||
- On non-PVE Debian/Ubuntu, `qm` is not available → this script is Proxmox-specific.
|
||
|
||
- **Wrong or missing names**
|
||
|
||
- Names are read from `name:` in `qm config <vmid>`.
|
||
If no `name:` is set, the script will display `<no-name>`.
|
||
|
||
---
|
||
|
||
## Security Notes
|
||
|
||
- The MAC listing script itself is read-only (only reads VM configs).
|
||
- The WOL listener script potentially **starts VMs based on external packets**:
|
||
- Use firewalling/VLANs to limit who can send WOL packets.
|
||
- Consider rate limiting and logging.
|
||
- Be careful exposing the listening interface directly to untrusted networks.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
```text
|
||
SPDX-License-Identifier: MIT
|
||
```
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
- `pve-list-mac-addresses.sh` gives you a clean, script-friendly view of **all VM NICs and MACs** directly from Proxmox configs.
|
||
- `pve-wol-server.sh` (or a similar listener) can then use this information to **start VMs via WOL** packets hitting your PVE bridges.
|
||
|
||
Drop these into `/root/PVE-VM-WOL` on your node, wire it into systemd, and your Proxmox starts behaving a lot more like a physical machine with proper Wake-on-LAN support.
|