-
-
Notifications
You must be signed in to change notification settings - Fork 443
05 Advanced quickemu configuration
Here are the command line arguments for quickemu
.
Usage
quickemu --vm ubuntu.conf <arguments>
Arguments
--access : Enable remote spice access support. 'local' (default), 'remote', 'clientipaddress'
--braille : Enable braille support. Requires SDL.
--delete-disk : Delete the disk image and EFI variables
--delete-vm : Delete the entire VM and it's configuration
--display : Select display backend. 'sdl' (default), 'gtk', 'none', 'spice' or 'spice-app'
--fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit)
--ignore-msrs-always : Configure KVM to always ignore unhandled machine-specific registers
--shortcut : Create a desktop shortcut
--snapshot apply <tag> : Apply/restore a snapshot.
--snapshot create <tag> : Create a snapshot.
--snapshot delete <tag> : Delete a snapshot.
--snapshot info : Show disk/snapshot info.
--status-quo : Do not commit any changes to disk/snapshot.
--viewer <viewer> : Choose an alternative viewer. @Options: 'spicy' (default), 'remote-viewer', 'none'
--width <width> : Set VM screen width. Does nothing without --height
--height <height> : Set VM screen height. Does nothing without --width
--ssh-port <port> : Set ssh-port manually
--spice-port <port> : Set spice-port manually
--public-dir <path> : Expose share directory. @Options: '' (default: xdg-user-dir PUBLICSHARE), '<directory>', 'none'
--monitor <type> : Set monitor connection type. @Options: 'socket' (default), 'telnet', 'none'
--monitor-telnet-host <ip/host> : Set telnet host for monitor. (default: 'localhost')
--monitor-telnet-port <port> : Set telnet port for monitor. (default: '4440')
--monitor-cmd <cmd> : Send command to monitor if available. (Example: system_powerdown)
--serial <type> : Set serial connection type. @Options: 'socket' (default), 'telnet', 'none'
--serial-telnet-host <ip/host> : Set telnet host for serial. (default: 'localhost')
--serial-telnet-port <port> : Set telnet port for serial. (default: '6660')
--keyboard <type> : Set keyboard. @Options: 'usb' (default), 'ps2', 'virtio'
--keyboard_layout <layout> : Set keyboard layout.
--mouse <type> : Set mouse. @Options: 'tablet' (default), 'ps2', 'usb', 'virtio'
--usb-controller <type> : Set usb-controller. @Options: 'ehci' (default), 'xhci', 'none'
--sound-card <type> : Set sound card. @Options: 'intel-hda' (default), 'ac97', 'es1370', 'sb16', 'none'
--extra_args <arguments> : Pass additional arguments to qemu
--version : Print version
The following features are available while using the SPICE protocol:
- Copy/paste between the guest and host
- Host file sharing with the guest
- USB device redirection
To use SPICE add --display spice
to the Quickemu invocation, this requires that the spicy
client is installed, available from the spice-client-gtk
package in Debian/Ubuntu.
quickemu --vm ubuntu-22.04.conf --display spice
To enable copy/paste with a Windows guest, install SPICE Windows guest tools in the guest VM.
To start a VM with SPICE enabled, but no display attached use --display none
.
This requires that the spicy
client is installed, available from the spice-client-gtk
package in Debian/Ubuntu to connect to the running VM
quickemu --vm ubuntu-22.04.conf --display none
You can also use the .ports
file in the VM directory to lookup what SSH and SPICE ports the VM is connected to.
cat ubuntu-22.04/ubuntu-22.04.ports
If, for example, the SSH port is set to 22220, and assuming your VM has a started SSH service (details vary by OS), you can typically SSH into it from the host as follows:
ssh -p 22220 your_vm_user@localhost
Qemu provides support for using BrlAPI to display braille output on a real or fake device.
quickemu --vm ubuntu-22.04.conf --braille --display sdl
Since Quickemu 2.1.0 efi
is the default boot option. If you want to override this behaviour then add the following line to the VM
configuration to enable legacy BIOS.
boot="legacy"
By default, Quickemu will calculate the number of CPUs cores and RAM to allocate to a VM based on the specifications of your host computer. You can override this default behaviour and tune the VM configuration to your liking.
Add additional lines to your virtual machine configuration:
-
cpu_cores="4"
- Specify the number of CPU cores allocated to the VM -
ram="4G"
- Specify the amount of RAM to allocate to the VM -
disk_size="16G"
- Specify the size of the virtual disk allocated to the VM
Preallocation mode (allowed values: off
(default), metadata
, falloc
, full
). An image with preallocated metadata is initially larger but can improve performance when the image needs to grow.
Specify what disk preallocation should be used, if any, when creating the system disk image by adding a line like this to your VM configuration.
preallocation="metadata"
CD-ROM disks
If you want to expose an ISO image from the host to guest add the following line to the VM configuration:
fixed_iso="/path/to/image.iso"
Floppy disks
If you're like Alan Pope you'll probably want to mount a floppy disk image in the guest. To do so add the following line to the VM configuration:
floppy="/path/to/floppy.img"
qemu
will always default to the primary monitor to display the VM's window.
The default resolution that quickemu
will request for virtual machines is 1280 x 800.
This can be overridden by setting width
and height
in the VM configuration files or passing --width
and --height
as command line arguments, for example:
quickemu --vm ubuntu-22.04-desktop.conf --width 1920 --height 1080
To set the display resolution on macOS, you will also need to install a 3rd party resolution manager in the macOS VM to get the best results. We recommended using one of the following:
- Resolutionator
- SwitchResX
- BetterDisplay (requires macOS 12.4 or newer)
All File Sharing options will only expose ~/Public
(or localised variations) for the current user to the guest VMs.
Supported on Linux, macOS and Windows guests. If smbd
is available on the host, Quickemu will automatically enable the built-in QEMU support for exposing a Samba share from the host to
the guest.
You can install the minimal Samba components on Ubuntu using:
sudo apt-get install --no-install-recommends samba
If everything is set up correctly, the smbd
address will be printed when the virtual machine is started. For example:
- smbd: On guest: smb://10.0.2.4/qemu
If using a Windows guest, right-click on "This PC", click "Add a network location", and paste this address, removing smb:
and replacing forward slashes with backslashes (in this example \\10.0.2.4\qemu
).
Supported on Linux and Windows guests.
- TBD
VirtIO-9P
Supported on Linux and macOS guests
- TBD
Quickemu sets up User Networking, which provides a full TCP/IP stack within QEMU to implement a virtual NAT'd network, which is (10.0.2.0/24) by default.
From inside the guest, connecting to a port on the "gateway" IP address of 10.0.2.2 will connect to that port on the host; so for instance ssh 10.0.2.2
will SSH from the guest to the host.
To completely disable all network interfaces in a guest VM add this additional line to your virtual machine configuration:
network="none"
Since Quickemu 4.9.5 you can also use the command line argument --offline
to completely override any networking configuration and disable networking for the given VM.
You can isolate the guest from the host (and broader network) using the restrict option, which will restrict networking to just the guest and any virtual devices.
This can be used to prevent software running inside the guest from phoning home while still providing a network inside the guest. Add this additional line to your virtual machine configuration:
network="restrict"
To connect your virtual machine to a preconfigured network bridge, add an additional line to your virtual machine configuration:
network="br0"
If you want to have a persistent MAC address for your bridged network interface in the guest VM you can add macaddr
to the virtual machine
configuration. QEMU requires that the MAC address is in the range: 52:54:00:AB:00:00 - 52:54:00:AB:FF:FF
So you can specify a MAC address with something like this in the VM configuration:
macaddr="52:54:00:AB:51:AE"
Add an additional line to the virtual machine configuration. For example:
port_forwards=("8123:8123" "8888:80")
In the example above:
- Port 8123 on the host is forwarded to port 8123 on the guest.
- Port 8888 on the host is forwarded to port 80 on the guest.
To share the clipboard between the host computer and the guest VM you need to use the SPICE viewer on the host and have the SPICE vdagent installed on the guest.
Start the VM with --display spice
, for example:
quickemu --vm nixos-23.11-gnome.conf --display spice
A growing number of Linux distributions including the SPICE vdagent in their live images. The SPICE vdagent needs to be installed and running on the guest in order to share the clipboard.
On Debian and Ubuntu this can be installed as follows:
sudo apt-get install spice-vdagent
If you run NixOS you will need to enable the SPICE vdagent daemon, by adding the following to your configuration:
services.spice-vdagentd.enable = true;
If you created your Windows 10 or Windows 11 virtual machine with quickget
, the required drivers were automatically installed.
Quickemu supports USB redirection via SPICE pass-through and host pass-through.
NOTE! When a USB device is redirected from the host, it will not be usable by host operating system until the guest redirection is stopped. Therefore, do not redirect the input devices, such as the keyboard and mouse, as it will be difficult (or impossible) to revert the situation.
Using SPICE for USB pass-through is easiest as it doesn't require any elevated permission:
Both spicy
from spice-gtk (Input -> Select USB Devices for redirection) and remote-viewer
from virt-viewer (File -> USB device selection) support this feature.
- Start Quickemu with
--display spice
and then - **
spicy
(default)- **Select
Input
->Select USB Device for redirection
from the menu to choose which device(s) you want to attach to the guest.
- **Select
- **
remote-viewer
- **Select
File
->USB device selection
from the menu to choose which device(s) you want to attach to the guest.
- **Select
To ensure that this functionality works as expected, make sure that you have installed the necessary SPICE Guest Tools on the virtual machine.
If you encounter this error when using NixOS as the host:
Error setting facl: Operation not permitted
You need to enable SPICE USB Redirection, by adding the following to your configuration:
virtualisation.spiceUSBRedirection.enable = true;
USB host redirection is not recommended; it is provided purely for backward compatibility with older versions of Quickemu. Using SPICE is preferred; see above.
Add an additional line to your virtual machine configuration. For example:
usb_devices=("046d:082d" "046d:085e")
In the example above:
- The USB device with vendor_id
046d
and product_id082d
will be exposed to the guest. - The USB device with vendor_id
046d
and product_id085e
will be exposed to the guest.
If the USB devices are not writable, quickemu
will display the appropriate commands to modify the USB device(s) access permissions,
like this:
- USB: Host pass-through requested:
- Sennheiser Communications EPOS GTW 270 on bus 001 device 005 needs permission changes:
sudo chown -v root:user /dev/bus/usb/001/005
ERROR! USB permission changes are required 👆
Since Quickemu 2.2.0 a software emulated TPM device can be added to guest virtual machines.
Just add tpm="on"
to your VM configuration; quickget
will automatically add this line to Windows 11 virtual machines.
Desktop shortcuts can be created for a VM, the shortcuts are saved in ~/.local/share/applications
. Here is an example of how to create a
shortcut.
quickemu --vm ubuntu-22.04-desktop.conf --shortcut