# 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 `: - 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 ` 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 `. If no `name:` is set, the script will display ``. --- ## 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.