From Whonix



What is KVM?[edit]

For an openly developed, free and open-source software (FOSS), GPL licensed hypervisor that can run Whonix, [1] it is recommended to use Kernel Virtual Machine (KVM) that comes with the GNU/Linux OS. KVM combined with the VirtualMachineManager front-end should provide a familiar, intuitive and easy-to-use GUI.

For a detailed view on KVM's security merits read the audit report issued by an independent security auditing firm.

Why Use KVM Over VirtualBox?[edit]

The VirtualBox developer team have recently taken the decision to switch out the BIOS in their hypervisor with one that requires compilation by a toolchain that does not meet the definition of Free Software as per the guidelines of the Free Software Foundation. This move is considered problematic for free and open source software projects like Debian, on which Whonix ™ is based.

The issues of the Open Watcom License are explained in this thread on the Debian Mailinglist. In summary, there are issues surrounding the contradictory language of the license, the assertion of patents against software that rely upon it, and the placing of certain restrictions on software uses. For these reasons, those who care about running FOSS and appreciate its ethical views are recommended to avoid running VirtualBox; also see avoid non free software.

Besides this licensing issue, a more tangible reason to avoid VirtualBox is the security practices of Oracle who produce the software. Events and news in recent years (like the Snowden leaks) demonstrate there is an urgent need for increased transparency and verifiable trust in the digital world. Oracle is infamous for their lack of transparency in disclosing the details of security bugs, as well as discouraging full and public disclosure by third parties. Security through obscurity is the flawed modus operandi at Oracle. [2]

Not going public with the details of vulnerabilities only leads to laziness and complacency on behalf of the company that fields the affected products. One example is this historical 0day vulnerability reported privately to Oracle in 2008 by an independent security researcher. Over four years later, the vulnerability remained unfixed, exhibiting Oracle has a history of failing to provide timely patches to customers so they can protect themselves.

On the VirtualBox bugtracker, ticket VirtualBox 5.2.18 is vulnerable to spectre/meltdown despite microcode being installed indicates non-responsiveness and non-progress by upstream. Users must patiently wait for VirtualBox developers to fix this bug.[3]

VirtualBox also contains significant functionality that is only available as a proprietary extension, such as USB / PCI passthrough and RDP connectivity. Based on Oracle's unfriendly track record with the FOSS community in the past -- examples include OpenSolaris and OpenOffice -- it would be unsurprising if users were charged for these restricted features in the future, or if the project was abandoned due to insufficient monetization.

First time user?[edit]

Whonix default admin password is: changeme Whonix default username: user
Whonix default password: changeme

Whonix first time users warning Warning:

  • If you do not know what metadata or a man-in-the-middle attack is.
  • If you think nobody can eavesdrop on your communications because you are using Tor.
  • If you have no idea how Whonix works.

Then read the Design and Goals, Whonix ™ and Tor Limitations and Tips on Remaining Anonymous pages to decide whether Whonix is the right tool for you based on its limitations.

KVM Setup Instructions[edit]

Before installing[edit]

Read and apply the Pre-Installation Security Advice.

Install KVM[edit]


If you are using Debian stable (currently: Stretch), click on expand on the right.

Setup sudoers. Add the operating system user name to sudoers.

Optional! First consider whether this change is desirable. [4]

Become root.


Add the user account to the sudoer's group. Replace user with the actual operating system user name.

sudo adduser user sudo

Reboot so group changes take effect.


Update package lists.

sudo apt-get update

For Debian Stretch+ you need to install:.

sudo apt-get install qemu-kvm libvirt-daemon-system libvirt-clients virt-manager


Unless manually enabled, Apparmor is not activated in a default Debian install for sVirt to take advantage of.


sudo apt-get install apparmor

Change the following line in grub settings to activate it on start-up:

sudo nano /etc/default/grub

GRUB_CMDLINE_LINUX_DEFAULT="quiet"GRUB_CMDLINE_LINUX_DEFAULT="quiet apparmor=1 security=apparmor"

Update the grub configuration and reboot for it to take effect:

sudo update-grub
sudo reboot

Arch Linux[edit]

If you are using Arch Linux, click on expand on the right.

Update package lists and install.

sudo pacman -Syu qemu libvirt virt-manager

Other Distributions[edit]

If you are using a Linux distribution, that is not documented above, click on expand on the right.

You need to have qemu-kvm and libvirt-bin. If you want to use a graphical user interface, which you most likely want, you also need virt-manager. Likely the required software can be installed using your usual distribution's package manager.

If you get one of the following errors while later using virsh define.

error: Failed to define domain from Whonix-Gateway_kvm-
error: internal error Unknown controller type 'pci

Whonix-Gateway_kvm- element pm: Relax-NG validity error : Element domain has extra content: pm
Whonix-Gateway_kvm- fails to validate

Relax-NG validity error : Extra element devices in interleave
Whonix-Gateway_kvm- element devices: Relax-NG validity error : Element domain failed to validate content
Whonix-Gateway_kvm- fails to validate

Then you most likely need a more recent version of libvirt and kvm.

Please feel free to share detailed instructions for other distributions!


Arch Users

It's been reported that the blkio throttling feature seems to be missing/unsupported on the latest Arch version as of March 2019. This causes VM start up to fail.[5] To work around this the feature must be removed for now:

sudo virsh edit Whonix-Gateway

then same for ‘Whonix-Workstation’

Strip out this setting:


Then save and start the VMs.


In order to be able to manage virtual machines as regular (non-root) user, you need to add that user to the libvirt and the kvm group. Assuming the simple use case, that you wish to use KVM with the user you are currently logged in, and assuming you are using Debian, simply use the following command. (On Ubuntu the group names vary and is called libvirtd instead).

sudo addgroup "$(whoami)" libvirt

sudo addgroup "$(whoami)" kvm


Other distributions[edit]

If you are using other distributions, have a look at your distribution's manual. (Such as Arch Linux's libvirt wiki page.)


After installation of KVM, reboot is required! After adding users to groups, reboot is required!

sudo reboot

Network Start[edit]

Although it has nothing to do with Whonix ™ since 14+, it's helpful when running other VMs.

Make sure KVM's / QEMU's default networking is enabled and started.[7] [8]

virsh -c qemu:///system net-autostart default

virsh -c qemu:///system net-start default

Build from Scratch[edit]

Advanced users are encouraged to build Whonix ™ images for high security assurance.

Download and Extract[edit]


It is highly recommended you read and apply the steps outlined here. By applying a known and tested configuration, you will be better off in convenience and security.

Make sure you use the qcow2 images that are provided by the Whonix ™ project instead of rolling your own. [9] They contain important performance optimizations. [10] (Unless you created them from source. [11])

If you have issues with free disk space, using a file system supporting sparse files is recommended, also see forum discussion.

Already have existing Whonix ™ libvirt images? Consider #Cleanup first.

For simplicity, so you can copy and paste the following commands without changes, download and store Whonix ™ images in your home folder (/home/<your user name>).

Download Whonix ™[edit]

Download FREE

Ambox warning pn.svg.png By downloading, you acknowledge that you have read, understood and agreed to our Terms of Service and License Agreement.

Info This release introduces unified ova downloads. Rather than separate Whonix-Gateway ™ and Whonix-Workstation ™ ova downloads, there is now only a single Whonix ova which includes both Whonix virtual machines (VMs), Whonix-Gateway ™ and Whonix-Workstation ™. [12] [13] [14]


Anonymous Download
Possible [15]
Download Security
without Verification
Download Security
with Verification
Https long.png


Yes [15] Medium High [16]
Button sig.png

OpenPGP Signature ( sha512 , sig )

Yes [15] - -
Crypto key.png Verify images using this Signing Key Yes [15] -

Verify the Whonix ™ images[edit]

Download HulaHoop's OpenPGP key from the keyserver.

gpg --keyserver --recv 04EF2F666D36C354058B9DD450C78B6F9FF2EC85

The output should confirm the key was imported.

gpg: key 0x50C78B6F9FF2EC85: public key "HulaHoop" imported
gpg: Total number processed: 1
gpg:               imported: 1

If the Whonix ™ signing key was already imported in the past, the output should confirm the key is unchanged.

gpg: key 0x50C78B6F9FF2EC85: "HulaHoop" not changed
gpg: Total number processed: 1
gpg:              unchanged: 1

You may also verify that the key was signed by Patrick for extra assurance.

gpg --check-sigs "04EF 2F66 6D36 C354 058B 9DD4 50C7 8B6F 9FF2 EC85"
Should show:

pub   rsa4096/0x50C78B6F9FF2EC85 2018-11-26 [SCEA]
uid                   [ unknown] HulaHoop
sig!         0x8D66066A2EEACCDA 2018-12-14  Patrick Schleizer <>
sig!3        0x50C78B6F9FF2EC85 2018-11-26  HulaHoop
sub   rsa4096/0xEB27D2F8CEE41ACC 2018-11-26 [SEA]
sig!         0x50C78B6F9FF2EC85 2018-11-26  HulaHoop

gpg: 3 good signatures

If the following message appears at the end of the output.

gpg: no ultimately trusted keys found

Analyze the other messages as usual. This extra message does not relate to the Whonix ™ signing key itself, but instead usually means the user has not created an OpenPGP key yet, which is of no importance when verifying virtual machine images.

Verify archive:


You should see output that includes:

gpg: Good signature from "HulaHoop"


Use tar to decompress the archive.

tar -xvf Whonix*.libvirt.xz

Do not use unxz! Extract the images using tar.

License Agreement[edit]

Read Whonix binary license agreement. Either by:

  • reading it online at this link, or
  • open it with a text editor of your choice, or
  • or use more.


Press enter to scroll down.

Indicate either A) acceptance, or B) refusal.

A) In case of acceptance:


B) In case of denial.

In case of acceptance:


You are welcome to attempt to negotiate any element these terms by contacting us.

Ambox warning pn.svg.png By proceeding installation, you acknowledge that you have read, understood and agreed to our Terms of Service and License Agreement. Ambox warning pn.svg.png

XML Modification (OPTIONAL)[edit]

This chapter describes XML modifications before importing a virtual machine. For already imported virtual machines, see #Editing an imported Machine's XML Configuration.

Modifying a machine's XML file gives more fine grained control over its settings than what is exposed through the virt-manager GUI. Unless you know what you are doing, editing configuration defaults is neither recommended nor necessary.

Open Whonix-Gateway*.xml in an editor.

If you are using a graphical environment, run.

kwrite Whonix-Gateway*.xml

If you are using a terminal (Konsole), run.

nano Whonix-Gateway*.xml

Open Whonix-Workstation*.xml in an editor.

If you are using a graphical environment, run.

kwrite Whonix-Workstation*.xml

If you are using a terminal (Konsole), run.

nano Whonix-Workstation*.xml

You could always edit the XML files later too, if needed as explained in the #Editing an imported Machine's XML Configuration chapter.

Importing Whonix ™ VM Templates[edit]

The supplied XML files serve as a description for libvirt, that tell it what properties a Whonix ™ machine and networking it should have.

1. Add and activate the virtual networks (settings files also in the same folder as Whonix ™ Gateway). If the definition of the Whonix ™ internal network fails because the virtual bridge "virbr2" already exists, edit the internal_network*.xml file and change the name to one that doesn't exist, e.g. "virbr3" (you can list all existing bridge adapters with "sudo brctl show"):

virsh -c qemu:///system net-define Whonix-External.xml

virsh -c qemu:///system net-define Whonix-Internal.xml

  • The names are located inside the Whonix-External.xml and Whonix-Internal.xml files.

virsh -c qemu:///system net-autostart Whonix-External

virsh -c qemu:///system net-start Whonix-External

virsh -c qemu:///system net-autostart Whonix-Internal

virsh -c qemu:///system net-start Whonix-Internal

2. Followed by importing the Whonix ™ Gateway and Workstation images:

virsh -c qemu:///system define Whonix-Gateway*.xml

virsh -c qemu:///system define Whonix-Workstation*.xml

Manipulating QCOW2 Images[edit]

To interact with KVM disk images use qemu-img. It can resize, convert virtual disks to other formats and more. Its not necessary nor recommended to change the official images so proceed only if you know what you are doing.

See the manual for more commands [17]

Moving Whonix ™ Image Files[edit]

The XML files are configured to point to the default storage location of /var/lib/libvirt/images. These steps will show how to move the images there in order for the machines to boot.

Note: Changing the default location may conflict with SELinux, which will prevent the machines from booting.

It is recommended to move the image files instead of copying them:

sudo mv Whonix-Gateway*.qcow2 /var/lib/libvirt/images/Whonix-Gateway.qcow2

sudo mv Whonix-Workstation*.qcow2 /var/lib/libvirt/images/Whonix-Workstation.qcow2

Whonix ™ disk images are sparse files, meaning they expand when filled rather than allocating their entire size, 100GB outright. These are known as sparse files and need special commands when copying them to ensure they don't lose this property, leading them to occupy all the actual space. We are copying to a privileged location in the system, so we have run with higher privileges (sudo):

sudo cp --sparse=always Whonix-Gateway*.qcow2 /var/lib/libvirt/images/Whonix-Gateway.qcow2

sudo cp --sparse=always Whonix-Workstation*.qcow2 /var/lib/libvirt/images/Whonix-Workstation.qcow2

It is possible to run image files from encrypted containers. sVirt protections are confirmed to be in effect for image files at alternative locations.

Change the permissions on the container mount point directory so virtual machine manager can access the image. In Zulucrypt containers are mounted under /run/media/private/user:[18]

sudo chmod og+xr /run/media/private/user/$container_name


After importing Whonix ™, you are advised to delete the archives (.libvirt.xz files) and the temporarily extracted folders or to move them into a custom location. This is useful to avoid conflicts and confusion should you later download a new version of Whonix ™.

To delete them.

rm Whonix*
rm -r WHONIX*


If you know Virtual Machine Manager, there is nothing special about starting Whonix ™ VMs compared to starting other VMs. First start Whonix-Gateway ™, then start Whonix-Workstation ™.

Graphical User Interface (GUI)[edit]

Start Virtual Machine Manager.

Start MenuApplicationsSystemVirtual Machine Manager

Start Whonix-Gateway ™.

click on Whonix-Gatewayclick openclick the play symbol

Repeat the same for Whonix-Workstation ™.

Command Line Interface (CLI)[edit]


sudo virsh start Whonix-Gateway

To start Whonix-Gateway ™. Respectively

sudo virsh start Whonix-Workstation

To start workstation

To interact via console:

sudo virsh console Whonix-Workstation

Adjust Display Resolution[edit]

Whisker Menudisplayselect resolution[19]

Save then take snapshot.


Instructions kept here in case it may work again in the future. This feature in virt-manager will cause the guest screen to be unresponsive. This is caused by a reported upstream bug that has not been resolved.

With the QXL driver (installed by default) you can seamlessly adjust the display resolution to adjust to your Host screen size.[20]

Virt-Manager Whonix-Workstation ™ window &rarr; View &rarr; Scale Display &rarr; Always

After installing[edit]

Read and apply the Post Installation Security Advice.


If you want to remove Whonix ™ KVM VMs, Whonix ™ network and Whonix ™ images, click on Expand on the right.

1. Make sure you powered off the VM you want to shut down. You can also make sure you have shut down the VM using command line.

virsh -c qemu:///system destroy Whonix-Gateway

virsh -c qemu:///system destroy Whonix-Workstation

2. Remove KVM VM settings.

virsh -c qemu:///system undefine Whonix-Gateway

virsh -c qemu:///system undefine Whonix-Workstation

3. Shut down KVM Network Whonix.

Warning: Whonix Version < 15 did use the network names "external" and "internal". The command line need to be changed accordingly. Try "virsh -c qemu:///system net-list " to list them all.

virsh -c qemu:///system net-destroy Whonix-External
virsh -c qemu:///system net-destroy Whonix-Internal

4. Remove Network Whonix.

Warning: Whonix Version < 15 did use the network names "external" and "internal". The command line need to be changed accordingly. Try "virsh -c qemu:///system net-list " to list them all.

virsh -c qemu:///system net-undefine Whonix-External
virsh -c qemu:///system net-undefine Whonix-Internal

5. Delete the images. (All data will be lost unless you made a backup of your valued data.)

sudo rm /var/lib/libvirt/images/Whonix-Gateway.qcow2

sudo rm /var/lib/libvirt/images/Whonix-Workstation.qcow2

KVM Upgrade Instructions[edit]

Its highly recommended that you uninstall older Whonix ™ versions and always run the newer one. Note that Whonix ™ supports in-place apt-get upgrades too.

First, move your data out of the VM via shared folders and perform the cleanup steps followed by installation of the new images.


Multiple Whonix-Gateway ™[edit]

See: Multiple Whonix-Gateway ™

Testing Upcoming Versions[edit]

Download the test images from latest folder listed here. Apply the Multiple_Whonix-Gateway#KVM for running Whonix ™ versions side by side with some differences:

1. Rename the test Whonix ™ images to something unique, preferably by appending the version number to the name.

2. Edit the XML templates and change the VM names.

3. Import the images by following the installation steps #Importing_Whonix_VM_Templates but keep in mind you must use the full name of the new images. Do not import the Network templates.

Snapshot Migration[edit]

If the VM has snapshots that you want to preserve, you should dump the snapshot xml-files of the source VM with:[21]

List snapshot names of the VM:

virsh snapshot-list --name $dom

Dump each snapshot you want to back-up:

virsh snapshot-dumpxml $dom $name > file.xml

Then for restoring snapshots at the destination use:

virsh snapshot-create --redefine $dom file.xml

If you also care about which snapshot is the current one, then additionally do on the source VM:

virsh snapshot-current --name $dom

and on the destination:

virsh snapshot-current $dom $name

Nested KVM Virtualization[edit]

It's possible to create nested KVM VMs on KVM hosts.

Check the current setting on the host. If the result is [Y], it's OK. For AMD systems use kvm_amd instead:

# cat /sys/module/kvm_intel/parameters/nested

If the result is [N], change like follows and reboot the system:

# echo 'options kvm_intel nested=1' >> /etc/modprobe.d/qemu-system-x86.conf

Host CPU instructions that include the svm and vmx extensions are passed through to the Workstation by default.

Compressing Disk Images[edit]

You may find it easier to move the sparse image files when they are compressed in a tarball.

To re-compress files use:

tar -Sczvf whonix.tar.gz <multiple file names separated by spaces>

Adding vCPUs[edit]

The pinning parameter cpuset='1' must be removed in the vcpu tag in the XML settings to allow adding more cores to a VM, otherwise performance issues and lockups will happen. CPU pinning is done to safeguard processes in other VMs that run cryptographic operations from side-channel attacks in case of a vulnerability in a crypto library.

To add more vcpus increase the number in between the opening and closing vcpu tags. Or use the hardware 'Details' pane in virtual Machine Manager.

If preserving cpu pinning while increasing core count is desired, pin the vcpus to different numbered ones than of other sensitive VMs. Map them in a 1:1 ratio to avoid over committing cores which will lead to performance problems.

3D Graphics Acceleration[edit]

By Debian Buster freeze the software requirements should be met. Other distros may be different so refer to the needed library versions here.

Change your Workstation VM's XML settings as below:

<graphics type='spice'>
  <listen type='none'/>
  <gl enable='yes'/>
  <model type='virtio'/>

Shared Folders[edit]

Ambox warning pn.svg.png Warning: Do not delete files from the shared folder from within the Workstation VM because they will reappear in the recycle bin across all snapshots with the same directory attached, causing a data leak across security levels. Use the file browser on the host to do cleanup instead.

To move data between the guest and host follow these steps. It is recommended to create/assign a unique directory per snapshot to keep shared content belonging to different security domains separate.

On the host run the following command in terminal (Start Menu → Applications → System → Terminal).

sudo mkdir /home/yourusername/shared

You must adjust permissions on the host to allow read and write access to the folder with chmod:

sudo chmod 777 /home/yourusername/shared

Enable shared folders in VirtManager:

VirtManagerSelect VMEditVirtual Machine DetailsDetailsAdd HardwareFile System


Mode: Mapped [22]

Driver: Default

Source Path: /home/yourusername/shared

Target Path: shared

Click finish. Done.

Whonix-Workstation should automatically find and mount the shared directory once its created and enabled on the Host.

Note: If your system is configured to use a Mandatory Access Control framework you may need to configure exceptions to allow the confined guests to communicate with the shared folder on the host.

Tests with Apparmor has shown it to operate transparently with shared folders without needing any manual exception configuration by the user.

On the host chmod must be applied to the shared folder's contents to access the files:

sudo chmod 777 -R  /home/yourusername/shared

If you don’t have SELinux enabled everything should work now. If you do, you will need to add a policy for files under your shared folder on your host. SELinux won’t allow you to share this folder until it’s labeled svirt_image_t. Here is how to add this policy on your host using semanage. Note that you will need to re-apply these steps everytime you transfer something:[23][24]

root@host# semanage fcontext -a -t svirt_image_t “/home/yourusername/shared(/.*)?”
root@host# restorecon -vR /home/yourusername/shared

If you are using commandline instead of virt-manager to edit your vm's device settings, add this next section to the xml.

<filesystem type='mount' accessmode='mapped'>
    <source dir='/home/yourusername/shared'/>
    <target dir='shared'/>

USB Passthrough[edit]

Libvirt supports passing through a computer's integrated webcam or any other USB devices.[25][26]

Ambox warning pn.svg.png Warning: You should only connect USB devices to Whonix-Workstation ™ when it is in a clean, trusted state. The only safe and recommended way to move files out of a VM is through Shared Folders.

Then in the Details pane change the Controller USB device model:

Hypervisor DefaultUSB 2

While Whonix-Workstation ™ is turned off, add four USB Redirection devices or as many as the number of USB ports the machine has to cover them all:

Whonix-Workstation ™ viewer window &rarr; View &rarr; Details &rarr; Add Hardware &rarr; USB Redirection

Start Whonix-Workstation ™ and select the device connected to the host you want to passthrough:

Whonix-Workstation ™ viewer window &rarr; File &rarr; Redirect USB &rarr; Choose: Webcam (or another USB Device)

Note that the last step needs to be done on demand as the device passed through is not set permanently across reboots. This prevents mistakes like USB passthrough when the VM is in an untrusted state.

Sandboxing Untrusted USB Drives[edit]

Apply these steps before the instructions above to auto-sandbox untrusted USB flash drives. USB auto-redirection is disabled by default by Debian maintainers to prevent accidental passthrough of trusted USB devices to untrusted guests.[27][28] so they must be reverted temporarily. Once you are done, change them back to safe defaults by going through the steps in reverse order.


These steps apply to USB storage devices only. Portable devices such as phones and tablets are problematic and may not be successfully auto-redirected.

The USB drive will only be isolated as long as the Whonix-Workstation ™ is running. Do not close VM GUI window or the device will be reassigned to the host. The VM window must be in focus (either mouse grabbed or in fullscreen mode just to be safe) when initially plugging in the device. You can minimize the VM window after its detected in the guest. You don't have to wait for the VM to completely boot too.

This isolation method is not fool-proof as a sophisticated attacker can tweak their BadUSB payload to crash the guest and cause the host to take control of the device and parse its malicious code.

Edit the libvirt glib-2.0 schema:

sudo nano /usr/share/glib-2.0/schemas/10_virt-manager.gschema.override

Change default contents:




Recompile for them to take effect[29] Close all instances of Libvirt/Virtual Machine Manager and restart them for the new settings to apply:

sudo glib-compile-schemas /usr/share/glib-2.0/schemas/

Add the USB Redirection devices as specified in previous instructions then boot Whonix-Workstation ™ and connect the USB thumbdrive. It should be automatically seen in the guest only.

Editing an imported Machine's XML Configuration[edit]

Eventually configure your faviorite editor to make changes. Set visual to your favorite editor (must be installed, examples are kwrite, leafpad, kate, vi, nano, vim, etc.).

export VISUAL=kwrite


virsh -c qemu:///system edit Whonix-Gateway

Disable Microphone Input[edit]

Microphone input to guests, while a nice feature for VoIP, is dangerous to have on by default. It is good practice to disable the microphone on your host system through sound settings if you are not actively using it.

It is not currently possible to ship a configuration file with the guest microphone input muted. If you need to have the host microphone turned on while denying access to the guest, mute the "virt-manager: record" device that shows up in the host's audio task-bar menu.

Creating Multiple Internal Networks[edit]

Open Whonix ™ network XML file and change the name attribute to something different than the internal network you are currently running, for example 'Whonix-Internal2' 'Whonix-Internal3' and so on. The default name used is 'Whonix-Internal'.

Alternative Configurations[edit]

Libvirt can support a variety of containment mechanisms. Currently supported ones are KVM on the x86_64 platform and QEMU. More configurations could be added at a later date. If you have hardware virtualization extensions, always use the KVM one.

To use another configuration, import its XML file with virsh.

How to leave KVM when no X is running[edit]

Situation... User is in terminal in a VM... No X is running ("sudo service kdm stop"). User wants to switch back to the host... How to do this?

The emulated tablet device handles this by not allowing the mouse to be captured by the guest. Its still possible though:

press Ctrl_L & Alt_L

Setting up gdb to work with qemu-kvm via libvirt[edit]

If you want to be able to debug a Linux kernel that’s running as a KVM guest, you need to specify the ‘-s’ parameter for the command line of qemu-kvm. The problem is, there’s no (easy) way to do this when you’re using libvirt and virt-manager to manager your virtual machines, instead of using KVM directly. What you need to do is change the XML configuration of the virtual machine so that the ‘-s’ parameter is passed on to qemu-kvm

virsh edit $guestvm

Here, $guestvm is the name of the VM that is managed via virt-manager. This will bring up the XML configuration of the VM in your editor. The first line of the XML file should be:

<domain type='kvm'>

This has to be changed to

<domain type='kvm' xmlns:qemu=''>

and you also need to add:

<qemu:arg value='-s'/>

under the <domain> level of the XML. After you save and quit the editor, the new configuration will come into effect. When you start the virtual machine, there will be a local TCP port (1234 by default) that can be used as a remote debugging port from gdb. You can connect to this port by using the command

target remote localhost:1234

from gdb running on the host machine.

Source: [30]

Unsafe Features[edit]

The features below have serious security implications and should not be used. This applies to all hypervisors in general.

LVM Storage[edit]

QCOW2 virtual disk images are the recommended and default storage format for KVM.

LVM or any other storage mechanism must be avoided for security and privacy.

LVM misconfiguration has serious security consequences and exposes the host filesystem to the processes running on the guest. [31]

Because a virtual disk is no longer used, where the low-level view of the storage can be controlled, data created by VMs can easily be recovered and exfiltrated by malicious forensics tools run in a VM at a later time. This is extremely dangerous and can expose all kinds of information originally created in a VM of higher trust level. This leads to deanonymization, past session linking and theft of sensitive information and keys.[32][33] Disabled in cloud tenancy environments.


THP/Hugepages aid rowhammer attacks[34] and memory de-duplication attacks (see KSM below) and so must be disabled for the guest and on the host. As far is what we know Debian hosts do not enable this feature. Disabled in cloud tenancy environments.

Memory Ballooning[edit]

Memory ballooning can potentially be abused by malicious guests to mount rowhammer attacks on the host.[35]

Clipboard Sharing[edit]

SPICE allows accelerated graphics and clipboard sharing. The clipboard is disabled by default for security reasons to prevent accidentally copying a link to a website you visited anonymously to your non-anonymous host browser or vice versa and to stop malware in Whonix ™ Workstation from pilfering sensitive info from your clipboard.

If you still want to enable it, edit the VM config file, then change <clipboard copypaste='no'/> to 'yes' then save and restart.


KSM is a memory de-deuplication feature that conserves memory by combining identical pages across VM RAM. It is not enabled by default. Enabling this feature is dangerous because it allows cross-VM snooping by a malicious process.[36] It can infer what programs and what pages are being visited outside the VM. [37] Disabled in cloud tenancy environments. This feature can also allow attackers to modify/steal APT keys and source lists of the host. [38][39]

Device Passthrough[edit]

Both USB and PCI device passthrough would allow advanced attackers to flash the firmware of those devcies and infect the host or other VMs.[40]

XML Settings[edit]

For more info on settings please refer to the Libvirt manual



Did you reboot after installing KVM?

Did you reboot after adding users to groups?

Add this information should you make a support request.

Unable to connect to libvirt.[edit]

If you are getting the following error.

Unable to connect to libvirt.

Verify that the 'libvirtd' daemon is running.

Libvirt URI is: qemu:///system

Make sure you added groups and rebooted.

Unable to open a connection to the libvirt management daemon.[edit]

If you are getting the following error.

Unable to open a connection to the libvirt management daemon.

Libvirt URI is: qemu:///system

Verify that:
- The 'libvirtd' daemon has been started

Check your KVM installation:

sudo service qemu-system-x86 restart ; echo $? ; sudo service libvirt-bin restart ; echo $? ; sudo service libvirt-guests restart ; echo $?

Should show.

[ ok ] Restarting libvirt management daemon: /usr/sbin/libvirtd.

Running guests on default URI: no running guests.

If you see that, it could be a permissions problem.

hda-duplex not supported in this QEMU binary[edit]

Maybe you are a member of the libvirt group, but not have the lkvm group?

Maybe changing

    <sound model='ich6'>


    <sound model='ac97'>

will help.

process exited while connecting to monitor: ioctl(KVM_CREATE_VM) failed[edit]

If you get the following error.

Error starting domain: internal error: process exited while connecting to monitor: ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy
failed to initialize KVM: Device or resource busy

Maybe you have other non-KVM VMs, such as VirtualBox VMs already running? This is not possible. Running two hypervisors at the same time is not supported by KVM / VirtualBox.


ls -la /var/run/libvirt/libvirt-sock

Add Version Numbers to Support Request[edit]

Having issues, make sure you add what versions of libvirt-bin, qemu-kvm and virt-manager you are using. If you are using Debian, you can use the following command to determine them.

dpkg-query --show --showformat='${Package} ${Version} \n' libvirt-bin qemu-kvm virt-manager

User Help Forum[edit]

Whonix ™ KVM User Help Forum

Alternative Guides[edit]

For alternative installation guides contributed by community members please check:
KVM/Installation Screenshots



  1. There are also other platforms.
  2. What is "security through obscurity":

    The basis of STO has always been to run your system on a "need to know" basis. If a person doesn't know how to do something which could impact system security, then s/he isn't dangerous. ... Nowadays there is also a greater need for the ordinary user to know details of how your system works than ever before, and STO falls down a as a result. Many users today have advanced knowledge of how their operating system works, and because of their experience will be able to guess at the bits of knowledge that they didn't "need to know". This bypasses the whole basis of STO, and makes your security useless.

  4. If this action is taken, sudo can be used as outlined below and elsewhere. Otherwise, it is necessary to manually switch to root and/or use su as per About#Based_on_Debian.
  5. achine-slice-machine-qemu/6999/5
  6. By default Debian doesn't use sudo so you can add the groups with usermod. If your user is "foo" you would do:
    usermod -a -G libvirt foo
    usermod -a -G kvm foo
  9. As in, manually converting them from .ova to .qcow2 is no longer recommended, since you can download .qcow images from the Whonix ™ project.
  10. As per build-steps.d/2400_convert-img-to-qcow2, these are "-o cluster_size=2M" and "-o preallocation=metadata".
  11. Because then you have the same performance optimizations.
  14. This change reduces the number of steps users are required to apply (one download instead of two). No functionality was lost. This improves usability, makes Whonix downloads more standardized compared to other software, and simplifies Whonix infrastructure maintenance work. The Whonix split VM design (separate Whonix-Gateway ™ and Whonix-Workstation ™) remains unmodified.
  15. 15.0 15.1 15.2 15.3 By using the Tor Browser Bundle (TBB). For an introduction, see Tor Browser. See also Hide Tor and Whonix from your ISP.
  16. It does not matter if the bulk download is done over an insecure channel if OpenPGP verification is used at the end.
  22. The file sharing mode mapped is just an example, using squash or passthrough is possible by selecting them from the drop down menu. Mapped is recommended for security.
  36. Dedup Est Machina: Memory Deduplication as an Advanced Exploitation Vector
  38. Flip Feng Shui: Hammering a Needle in the Software Stack

No comments for now due to spam. Use Whonix forums instead.

Random News:

We are looking for maintainers and developers.

https | (forcing) onion

Share: Twitter | Facebook

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation.

Copyright (C) 2012 - 2019 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

Whonix ™ is a derivative of and not affiliated with Debian. Debian is a registered trademark owned by Software in the Public Interest, Inc.

Whonix ™ is produced independently from the Tor® anonymity software and carries no guarantee from The Tor Project about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint.