Skip to content

About

Systemd daemon for live USB hot-attach to running Proxmox VMs via resource mappings

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

proxmox-usb-hotplug

Hot-plug USB devices into running Proxmox VMs. Plug a device in and it shows up in the VM a few seconds later; unplug it and it's gone. No reboots, no GUI clicks, no udev rules.

Proxmox only passes USB through at boot or by hand. This daemon watches lsusb against your Proxmox USB resource mappings and runs qm set as devices come and go.

Setup

Create mappings in Datacenter → Resource Mappings → USB, named by where they should go:

Name Goes to
vm110-keyboard VM 110
shared-mouse whichever VM currently has the GPU
disabled-whatever nowhere
git clone https://github.com/codemonkeying/proxmox-usb-hotplug
cd proxmox-usb-hotplug
sudo ./install.sh
journalctl -u usb-hotplug -f

Usage

usb-mapping-daemon.sh --status      # what's attached where
usb-mapping-daemon.sh --test        # dry run
usb-mapping-helper.sh protect 100   # never touch VM 100

Extras

  • Pools (/etc/usb-hotplug/pools.conf): identical devices with the same VID:PID and no serial, e.g. two controller dongles. Attached by port, up to a max per VM.
    # name  vid:pid  vmid|shared  max  [usb3]
    pads    1038:1430  shared  2  usb3
    
  • Clusters: mappings pinned to another node are skipped.
  • PCI exclusivity: a running VM's hostpci mapping is removed from other VMs' live configs so two can't claim the same GPU.
  • Event relay (/etc/usb-hotplug/event-relays.conf): forwards host events like the laptop lid into the GPU VM via the guest agent. Example guest handler in guest-handlers/.

Uninstall

sudo systemctl disable --now usb-hotplug event-relay
sudo rm /etc/systemd/system/usb-hotplug.service /etc/systemd/system/event-relay.service
sudo rm /usr/local/bin/usb-mapping-*.sh /usr/local/bin/event-relay-daemon.sh
sudo systemctl daemon-reload
sudo rm -rf /etc/usb-hotplug /etc/usb-hotplug-protected-vms.conf

License

Copyright (c) 2026 codemonkeying. All rights reserved.

About

Systemd daemon for live USB hot-attach to running Proxmox VMs via resource mappings

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages