A script for easy pci and usb passthrough along with disks, iso's and other useful flags for quick tinkering with less of a headache. I use it for VM gaming and other PCI/LiveCD/PXE/VM/RawImage testing given the script's accessibility.
Its been a while since the last release tag and with bridging revamped in master its time.
As usual there's been many various script handling improvements, cleanup, documentation tweaks, clarity in printed messages and additional/combined argument flags for ease of use. Below are the more noteworthy changes.
Key changes since 0.7.1:
-bridge tap0,br0,eth0
is now expressed as -bridge br0
, -tap tap0
, -hostint eth0
.-tpm
argument to spin up a software tpm (Using swtpm
)-pinvcpus
not specified) the guest now takes up only half of the host's total CPU thread count
kvm
module is ready for use.-force
to ignore the script's error reporting (Useful in some testing cases)-noBios
/-legacy/
-legacyboot` for booting without OVMF (For running MBR/BIOS VMs and P2V's)compact_memory
call for ZFS hosts running kernel 6.3.1+ to avoid https://github.com/openzfs/zfs/issues/15140
-nvme
to present the VM's disk to it using the NVMe protocol
-audiodev
for QEMU to useFor the full changelog experience with all the small bits heres the commits between 0.7.1 and 8.0 https://github.com/ipaqmaster/vfio/compare/0.7.1...0.8
A small bump for some new features.
Key changes since 0.7:
Various script subroutine cleanup to cover all use cases even when certain requirements aren't configured on a host
Further documentation cleanup as usual
Added -iommu
as an alternative IOMMU group check flag. Still keeping -iommugroups
and -iommugrouping
Added -portforward
to port-forward host ports to the guest when NOT using a bridge. This is for the User-mode guest networking default setting (NAT). Pretty useful for tests and quick start/stops.
Added Multi-GPU VFIO support without having to kill an existing X server.
fuser
to look for any processes (Or Xorg itself) using the GPU if any before unbinding.Added a new flag -killX
to tell the script that killing X is OK. This was primarily added for Single GPU Passthrough scenarios.
Fixed a niche issue with hugepage allocation in special circumstances.
Other than the usual cleanup some new flags have been aded which I found useful enough to make permanent:
Flag(s) [-avoidVirtio/-noVirtio] to use generic virtual hardware such as e1000e for guest Ethernet among other comprompises for special cases.
Flag(s) [-cputhreads / -showpairs / -showthreads / -showcpu]
Flag(s) [-ignorevtcon / -ignoreframebuffer / -leavefb / -leaveframebuffer / -leavevtcon] Optional workaround for kernel Bug 216475 on Nvidia cards.
Added -kernel, -cmdline and -initrd options for various realtime kernel hackery and testing
As for other general changes since the last tag:
Squashed vcpu pinning bug introduced in earlier commit (Had the ampersand in the wrong spot, damn)
-m
can now also be used instead of -memory
Script no longer relies on brctl, bash now traverses /sys/class/net itself.
Hugepage arguments now also get calculated in the dry run
Script automatically increments its spice port if already in use
Script has been stable to a point where it's worth tagging a new checkpoint given how long it's been since the last one.
Some noteworthy things since 0.6a which was quite a while ago:
-hostaudio
argument added to start a pulseaudio server on the host if possible and not already running while attaching a ich9-intel-hda sound device to the guest.-quiet
flag added with some printing changes to make the script as quiet as possible unless a fault occurs. Something I found more useful after a few hundred runs.-bridge tap5,br1,eth0
), VM can now be started with only a tap adapter and no bridge for host-only networkingSome taggable changes since 0.6:
Each virtual disk passed through using the -image
argument gets an iothread each.
guest vcpu threads of qemu get pinned to each specified core using -pinvcpus
(replaces -taskset
) then chrt is used to set all vcpu qemu threads to use the FIFO scheduler. Script waits dynamically for vcpu threads to spin up as startup time varies host to host and depends on what's being passed through.
-nodefaults added to qemu arguments by default. VM networking and display managed solely by script.
logic for hugepages improved with support for specifying a custom mountpoint.
Network bridging cleaned up with better sanity checking and custom guest mac addressing to prevent conflicts (Say if more than one VM is running with this script).
Automatic color toggling, useful for piping/grepping output without having to manually include -nocolor
.
Various other small bug fixes and script tidy-up.
Enough changes since 0.5b with stability on two machines to tag a release for it.
Fluff: Fired up previous desktop (Sabertooth x79, 3930K GTX660 [host] GTX780[Guest] to test some dual GPU support scenarios. Not the most responsive environment however useful for testing the script.
Some changes in 0.6 since 0.5b:
"Script cleanup" as usual this time featuring better echoing, some improved function return logic, catches for driver unbind hangs and other redundancies to exit early if it thinks something went wrong.
Better detection for a GPU device and the script will only attempt to kill a display-manager service if the GPU device is found currently bound to anything other than vfio-pci, rather than always. The kill is only kept in the script to try and avoid a possible deadlock during gpu unbinding.
Added a -lookingglass
/-looking-glass
/-lg
flag to support the Looking Glass project in this script. Adds some shared memory and spice devices to qemu when specified.
Added a -romfile
/-vbios
added which will be shoehorned into the qemu pci argument for any GPU device on detection
-hugepages
/-huge
improved to detect the system's hugePageSize better and support optional custom mountpoints when specified after the argument. Otherwise falls back to default /dev/hugepages
, but will no longer automount it (though, it should be automounted on modern distros anyway). On top of all this, if it detects hugepages are already allocated AND there's enough for how much memory the VM wants, it will use the existing free pages instead of allocating freshly. Otherwise, it will drop caches, compact memory and allocate its own as usual.
Made this change to support 1GB hugepages which may not always be mounted at /dev/hugepages and may have its own mount options modifying the page size, which the script should detect dynamically.
With this I was able to add hugepagesz=1G hugepages=16
to my kernel boot parameters to sactifice 16GB at system startup to hugepages, and mount those pages with mount -t hugetlbfs hugetlbfs -o rw,relatime,pagesize=1G /dev/1gb_hugepages
and start my VM with -hugepages /dev/1gb_hugepages
included to use the pages which are already present. Even if not preallocated the script would be capable of allocating 1GB hugepages instead of 2MB sized ones on the fly worst case.
Has been stable in my day to day usage, might as well tag it as there's some changes worth having if someone downloads a release instead of pulling master.
Overall since 0.5a:
Mostly clean up of readability and some functions such as hugepage allocation, display-manger management and other minor places.
Switched to using tee with sudo instead of shell redirection to deal with the script possibly running as non-root.
-hyperv flag added to add some of the most common hyperv enlightenments
Permissions management function added to take ownership of hugepages, disks, virtual disks, vfio groups, the bridge tap interface and otherwise before qemu starts when the script isn't running as root, then return them during cleanup. This were added as the script has been changed to not expect root privileges instead running everything as my user but opening gates where required with sudo before qemu gets started. Modern qemu versions can drop permissions after starting so I may look into that later.
Minor script changes which might as well be tagged.
-nocolor
or -nocolour
(optional s
on the end)Worth tagging a new one as there's been a few changes to the script since 0.4c and not everybody likes to pull master and pray.
Mostly quality-of-life changes, bugfixes with a few actual features. Noteworthy changes since 0.4c as below:
Cleaned up the script a little. More consistency in key parts and reuse of common logic checks.
Colorized most of the scripts own output so you'll see juicy orange and red coloring if it has something important to share, otherwise green or just default. (Also comes with -colortest
if someone wants to check it works)
Added -hugepages
to support allocating hugepages before starting qemu, and giving it a relevant memory argument. One will still need to customize their hugepagesize manually (default seems to be 2MB) but this call will read to make sure it allocates only as many as required if a non-default value.
Network bridging now supports attaching to an existing bridge and cleaning up only the tap adapter when finished
Made the -image flag optional, allowing liveCD usage without any trouble.
Added -imageformat
to specify the format of the image separately (Or not at all, qemu will complain though)
Added -nonet
for when you don't want any virtual networking adapter to be passed to the VM. Useful if you're about to use -PCI
to hand it a network card of its own.
The enumeratePCI function now only kills the display-manager and unbinds the EFI console driver if it detects a specified GPU is hooked by a driver. But everything else is free game. This has been useful for passing things to a VM without bothering the X session such as USB Controllers, Network/Sound cards, or maybe a *different GPU who's is already unbound? (dual-gpu setup yet to be tested)
Added -iommugroups
to print IOMMU grouping of PCI devices in a list if possible, then exit.
Fixed up the consoleDrivers function to prevent MMAP issues when starting a VM with a GPU passed through along with the fixes mentioned in pre-release 0.4b.
Tested working on the Aorus Pro x570