Hotplugger: Real USB Port Passthrough for VFIO/QEMU!

Related tags

Hardwarehotplugger
Overview

Hotplugger: Real USB Port Passthrough for VFIO/QEMU!

Welcome to Hotplugger! This app, as the name might tell you, is a combination of some scripts (python, yaml, udev rules and some QEMU args) to allow you to pass through an actual USB port into a VM. Instead of passing the USB root hub (which could have the side effect of passing all the ports, including the ones you didn't want to) or another PCIe hub or something, you can just pass a specific USB port to a VM and have the others free for anything else. Plus, it saves you from using the vfio-pci driver for the USB root hub, so you can keep using it for evdev or other things on the VM host.

Requirements

  • monitor.py and hotplugger.py require Python 3
  • Only tested with QEMU 5.0.0. Untested with older or newer versions.

Quick start (Ubuntu 20.10)

  1. git clone https://github.com/darkguy2008/hotplugger.git

  2. (Optional) run python3 monitor.py and follow the prompts. Basically once you hit Enter you have to plug and unplug an USB device (a thumbdrive or audio device preferred) into the USB ports that you want to know their DEVPATH route from. This will help you identify them so you can write them into config.yaml in the ports array. This array only accepts DEVPATH routes that UDEV generates.

  3. Edit config.yaml. It must stay in the same folder as monitor.py and hotplugger.py. Look at the current example: It's set for a Windows VM (the name doesn't matter, as long as it's unique within the entries of the same file). Make sure the socket property matches the file path of the QEMU chardev device pointing to an Unix domain socket file and in the ports array put the list of the udev DEVPATH of the USB ports you want to pass through to that VM:

    virtual_machines:
    
      windows:
        socket: /home/dragon/vm/test/qmp-sock
        ports:
          - /devices/pci0000:00/0000:00:14.0/usb3/3-1
          - /devices/pci0000:00/0000:00:14.0/usb3/3-2
          - /devices/pci0000:00/0000:00:14.0/usb4/4-1
          - /devices/pci0000:00/0000:00:14.0/usb4/4-2
    
  4. Create an /etc/udev/rules.d/99-zzz-local.rules file with the following content:

    SUBSYSTEM=="usb", ACTION=="add", RUN+="/bin/bash -c 'python3 /path-to-hotplugger/hotplugger.py >> /tmp/hotplugger.log' 2>&1"
    SUBSYSTEM=="usb", ACTION=="remove", RUN+="/bin/bash -c 'python3 /path-to-hotplugger/hotplugger.py >> /tmp/hotplugger.log' 2>&1"
    

    Make sure to change path-to-hotplugger with the path where you cloned the repo to, or installed the package. It can be simplified, but this one is useful in case you want to debug and see what's going on. Otherwise, proceed with a simpler file:

    SUBSYSTEM=="usb", ACTION=="add", RUN+="/bin/bash -c 'python3 /path-to-hotplugger/hotplugger.py'"
    SUBSYSTEM=="usb", ACTION=="remove", RUN+="/bin/bash -c 'python3 /path-to-hotplugger/hotplugger.py'"
    
  5. Create the QMP monitor Unix domain socket if you haven't already in your QEMU args. I use this:

    -chardev socket,id=mon1,server,nowait,path=./qmp-sock
    -mon chardev=mon1,mode=control,pretty=on
    
  6. Have a coffee!

Libvirt setup

This is a work in progress, but here's some steps to get you started:

  1. Edit your VM's XML config like this:

    1. <domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
        <name>QEMUGuest1name>
        <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809uuid>
        ...
        <qemu:commandline>
          <qemu:arg value='-chardev'/>
          <qemu:arg value='socket,id=mon1,server,nowait,path=/tmp/my-vm-sock'/>
          <qemu:arg value='-mon'/>
          <qemu:arg value='chardev=mon1,mode=control,pretty=on'/>
        qemu:commandline>
      domain>

      Add the xmlns attribute and the QEMU commandline arguments like that. The /tmp/my-vm-sock is the name of an unix domain socket. You can use any, just make sure to also put the same path in the config.yaml file.

  2. If you get a permissions issue, edit /etc/libvirt/qemu.conf and add security_driver = "none"to it to fix apparmor being annoying about it.

How it works

  1. The udev rule launches the script on every USB event. For each USB add/remove action there's around 3 to 5+ events. This allows the app to act at any step in the action lifecycle.
  2. In the first step it gets the kernel environment variables from udev and stores them in a temp file. In those variables, the DEVPATH, the DEVNUM (host address in QEMU, it seems to change and is sequential...) and the BUSNUM (bus address in QEMU) are captured. For the subsequent events, the following steps are run:
    1. It requests QEMU through the Unix socket and the info usbhost QMP command the USB info from the host. This gives it an extra field: The host port where the device is also connected to. Since I got the host and bus addresses in the first event, I can use that to parse through the info usbhost command's output and find the port connected to the device.
    2. If the port is found, using the device_add command, a new usb-host device is added using the USB bus and port we got in the previous step, and assigns it a predictable ID that it can use to unplug the device afterwards. To add this of course, the VM should have a usb-xhci device I think. Not sure if it's required or not, but I prefer to add it as I have USB 3.0 ports and devices.
    3. The temp file is cleared once the device_add command has run successfully.

Steps 2.1, 2.2 and 2.3 are run on every udev event. For instance, for an audio device it gets 3 or 4 events: One for the HID device, and two or so for the audio devices. My audio device (Corsair Void Elite Wireless) has both stereo audio and a communications device (mono audio, for mic) so for a single dongle like that I get those many events. Since these steps are ran on all the events, there's multiple chances to do the hotplug action. When one of them succeeds, the others will silently fail as QEMU will say that the same device ID is being used, so all is good.

Troubleshooting

If for some reason the app doesn't seem to work, try these methods:

  • Remove the /tmp folder where hotplugger.py is located
  • Reboot the computer
  • Reboot udev: sudo udevadm control --reload-rules && sudo udevadm trigger
  • View udev's logfile: sudo service udev restart && sudo udevadm control --log-priority=debug && journalctl -f | grep -i hotplugger
  • If you want to see what will be run when you plug a device, try with this command to simulate an udev event: udevadm test $(udevadm info -a --path=/devices/pci0000:00/0000:00:14.0/usb3/3-1/3-1:1.0) --action=add replacing --path with the path of the USB port down to the device itself (in this case, I had a device connected to the usb3/3-1 port, identified as 3-1:1.0.

Thank you!

A lot of work and sleepless nights were involved in this procedure, so if this app helps you in any way or another, please consider sending a small donation, it helps a lot in these tough times!

Changelog

(2020-02-05)

  • Initial changelog writing
  • App was refactored a bit with improved python mad skillz. It also seems to be a bit more stable and robust, it doesn't hang much anymore and USB detection seems to work better. This is due to the fact that I added a stupid 1-second delay after all the USB UDEV events have gone through. Since there's no way to know when UDEV has "finished" sending all the events (and there could be a lot more) the commands being sent to QEMU to add the device will have to wait 1 second now. While it's not ideal, it should be enough to avoid a VM hanging up and I can live with that.
Owner
DARKGuy (Alemar)
DARKGuy (Alemar)
KIRI - Keyboard Interception, Remapping, and Injection using Raspberry Pi as an HID Proxy.

KIRI - Keyboard Interception, Remapping and Injection using Raspberry Pi as a HID Proxy. Near limitless abilities for a keyboard warrior. Features Sim

Viggo Falster 10 Dec 23, 2022
Authentication provider using Synology DSM users for Home Assistant

Authentication provider using Synology DSM users for Home Assistant The Synology authentication provider lets you authenticate using the users in your

Sam Debruyn 5 Oct 06, 2022
Open source home automation that puts local control and privacy first.

Home Assistant Open source home automation that puts local control and privacy first. Powered by a worldwide community of tinkerers and DIY enthusiast

Home Assistant 57k Jan 01, 2023
A LiteX project which builds a SoC with DRAM / HDIM output via the GPDI SYZYGY addon.

ButterStick GPDI LiteX demo A LiteX project which builds a SoC with DRAM / HDIM output via the GPDI SYZYGY addon. Getting started Connect GPDI board t

4 Nov 21, 2021
Blender Camera Switcher

Blender Camera Switcher A simple camera switcher addon for blender. Useful when use reference image for camera. This addon will automatically fix the

Corgice 1 Jan 31, 2022
A simple program to make MSI Modern 15 speaker and microphone mute led work.

MSI Modern 15 sound led fixup for linux A simple program to fix the MSI Modern 15 speaker and microphone mute LEDs. Installation Requirements pulsectl

Seyed Danial Movahed 4 Oct 18, 2022
LedFx is a network based LED effect controller with support for advanced real-time audio effects

Welcome to LedFx ✨ -Making music come alive! LedFx website: https://ledfx.app/ What is LedFx? What LedFx offers is the ability to take audio input, an

786 Jan 02, 2023
Python module for controlling Broadlink RM2/3 (Pro) remote controls, A1 sensor platforms and SP2/3 smartplugs

Python module for controlling Broadlink RM2/3 (Pro) remote controls, A1 sensor platforms and SP2/3 smartplugs

Matthew Garrett 1.2k Jan 04, 2023
This OctoPrint plugin will make the initial connection to 3D Hub a breeze

3D Hub Connector This OctoPrint plugin will make the initial connection to 3D Hub a breeze. In future it will help in setting up a tunnel connection a

3D Hub 2 Aug 03, 2022
DNP3 Stalker is a project to analyze and interact with DNP3 devices

DNP3 Stalker Purpose DNP3 Stalker is a project to analyze and interact with DNP3

Cutaway Security, LLC. 2 Feb 10, 2022
Python Keylogger for Linux

A keylogger is a program that records your keystrokes, this program saves them in a .txt file on your local computer and, after 30 seconds (or as long as you want), it will close the .txt file and se

Darío Mazzitelli 4 Jul 31, 2021
This repository hosts the code for Stanford Pupper and Stanford Woofer, Raspberry Pi-based quadruped robots that can trot, walk, and jump.

This repository hosts the code for Stanford Pupper and Stanford Woofer, Raspberry Pi-based quadruped robots that can trot, walk, and jump.

Stanford Student Robotics 1.2k Dec 25, 2022
Code and build instructions for Snap, a simple Raspberry Pi and LED machine to show you how expensive the electricyty is at the moment

Code and build instructions for Snap, a simple Raspberry Pi and LED machine to show you how expensive the electricyty is at the moment. On row of LEDs shows the cost of the hour, the other row the co

Johan Jonk Stenström 3 Sep 08, 2022
Hotplugger: Real USB Port Passthrough for VFIO/QEMU!

Hotplugger: Real USB Port Passthrough for VFIO/QEMU! Welcome to Hotplugger! This app, as the name might tell you, is a combination of some scripts (py

DARKGuy (Alemar) 66 Nov 24, 2022
This Home Assistant custom component adds support for controlling Midea dehumidiferes on local network.

This is a custom component for Home assistant that adds support for Midea dehumidifier appliances via the local area network. midea-dehumidifier-lan H

Nenad Bogojevic 97 Jan 08, 2023
Home Assistant custom integration for e-distribución

e-Distribución is an energy distribution company that covers most of South Spain area. If you live in this area, you probably are able to register into their website to get some information about you

VMG 17 Sep 07, 2022
Doughskript interpreter for converting simple command sequences into executable Arduino C++ code.

Doughskript interpreter for converting simple command sequences into executable Arduino C++ code.

Svjatoslav 2 Jan 11, 2022
MicroPython driver for 74HC595 shift registers

MicroPython 74HC595 A MicroPython library for 74HC595 8-bit shift registers. There's both an SPI version and a bit-bang version, each with a slightly

Mike Causer 17 Nov 29, 2022
HACS gives you a powerful UI to handle downloads of all your custom needs.

HACS (Home Assistant Community Store) Manage (Install, track, upgrade) and discover custom elements for Home Assistant directly from the UI. What? HAC

HACS 3.2k Jan 04, 2023
Home assiatant Custom component: Camera Archiver

Camera archiver Archive your ftp camera meadia files on other ftp with files renaming and event creation. Event can be used for send information to el

1 Jan 06, 2022