Proxmox-WOL-Server/README.md

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:

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:

./pve-list-mac-addresses.sh

Example output:

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.):

./pve-list-mac-addresses.sh | awk 'NR>2 {print $4}'

Export to CSV:

./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:

cd /root/PVE-VM-WOL
nano pve-wol-server.sh
chmod +x pve-wol-server.sh

Then either run it manually:

./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:

    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

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.