Jump to: navigation, search


Random News:

Got spare bandwidth on your server? Please consider Hosting a Whonix Mirror.


What is KVM?[edit]

For an openly developed, FOSS GPL licensed hypervisor, it is recommended you use KVM [Kernel Virtual Machine] that comes with the GNU/Linux OS. KVM combined with the VirtualMachineManager front-end should provide a familiar and intuitive, easy to use GUI.

For a detailed view on its security merits read the report issued by an independent security auditing firm: http://www.atsec.com/downloads/white-papers/kvm_security_comparison.pdf

Why Use KVM Over VirtualBox?[edit]

Recently, the VirtualBox developer team have 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 has been deemed problematic for free and open source software projects like Debian, on which Whonix is based. https://www.whonix.org/wiki/Dev/Virtualization_Platform#VirtualBox_no_longer_in_Debian_mai...

The issues of the Open Watcom License are explained in this thread on the Debian Mailinglist: http://www.mail-archive.com/debian-legal@lists.debian.org/msg34687.html and can be summarized as issues surrounding the contradictory language of the license, the assertion of patents against software that relies on it and the placing of certain restrictions on uses of the software.

For those who care about running Free Software and appreciate its ethical views, it is recommended that you avoid running VirtualBox, for that reason alone if nothing else.

Besides this licensing issue which may or may not be of concern to users, a more tangible reason can be the security practices of Oracle, the corporation behind VirtualBox. Recent events and news (see Snowden leaks) have shown the urgent need for increased transparency and trust in the digital world. Oracle is infamous for their lack of transparency in disclosing security bugs details and for discouraging public full disclosure by third parties. http://www.oracle.com/us/support/assurance/vulnerability-remediation/disclosure/index.html << security through obscurity is the modus operandi at Oracle. http://www.oracle.com/us/support/assurance/vulnerability-remediation/reporting-security-vu... << Oracle calls it "responsible disclosure" which is actually security through obscurity. Not going public with a vulnerability and its details only leads to laziness and complacency on part of the company that fields the affected products. http://seclists.org/fulldisclosure/2012/Apr/343 << A 0day reported privately to Oracle in 2008 by an independent security researcher has remained unfixed as of 2012 when this post was written.

Furthermore VirtualBox contains significant functionality that is only available as a proprietary extension, such as USB and PCI passthrough and RDP connectivity. Seeing Oracle's unfriendly trackrecord with the free software community in the past; examples include OpenSolaris and OpenOffice, it would not be a stretch to imagine them charging money for the closed up features at some point in the future or simply abandoning the project if they cannot monetize it to their liking.

KVM Setup Instructions[edit]

Before installing[edit]

Read and apply the Security Advice. The instructions below assume you have verified the authenticity of the release before proceeding and that you have placed them in your home directory.

Install KVM[edit]

Debian oldstable[edit]

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

You need to enable wheezy-backports first, because we need a more recent version of kvm for security reasons. [1] This is not necessary if you are using Debian stable (currently: jessie).

Open /etc/apt/sources.list with root rights.

kdesudo kwrite /etc/apt/sources.list

Add the following line.

deb http://ftp.us.debian.org/debian/ wheezy-backports main


Update package lists.

sudo apt-get update

Install. [2]

sudo apt-get install -t wheezy-backports qemu-kvm libvirt-bin virt-manager

Alternatively, if this does not work for you, see footnote. [3]

Check version numbers[edit]

To make sure you have recent enough versions.

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

Should show.

libvirt-bin 1.2.4-1~bpo70+1 
qemu-kvm 2.0.0+dfsg-4~bpo70+1 
virt-manager 0.9.1-4

(Higher version numbers would be okay as well.)

Debian stable[edit]

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

Update package lists.

sudo apt-get update


sudo apt-get install qemu-kvm libvirt-bin 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!


If you are running Debian Stable (Jessie) you will run into a libvirt bug that conflicts with the way it works with Apparmor and the VM will refuse to start. It was fixed upstream but it will be a while until it reaches you.

To fix it run:

sudo ln -s /etc/apparmor.d/libvirt/TEMPLATE.qemu /etc/apparmor.d/libvirt/TEMPLATE.kvm


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.

sudo addgroup "$(whoami)" libvirt
sudo addgroup "$(whoami)" kvm

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]

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

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

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. [6] They contain important performance optimizations. [7] (Unless you created them from source. [8])

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

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

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

3. Make sure you verify the integrity of your download by using gpg to make sure that your downloads have not been tampered with. See here: Download#Verify_the_Whonix_images

4. Use tar to decompress the archive.

tar -xvf ~/Whonix-Gateway-*.libvirt.xz
tar -xvf ~/Whonix-Workstation-*.libvirt.xz

Do not use unxz! Extract the images using tar.

XML Modification (OPTIONAL)[edit]

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.

nano ~/Whonix-Gateway_kvm-*.xml
nano ~/Whonix-Workstation_kvm-*.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. First we will start with Whonix-Gateway:

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

2. Followed by the Whonix isolated internal network (XML also in the same folder as Whonix Gateway):

virsh -c qemu:///system net-define Whonix_network*.xml
virsh -c qemu:///system net-autostart Whonix
virsh -c qemu:///system net-start Whonix

3. Lastly the Whonix-Workstation:

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 [9]

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: It is highly recommended you use this default path for storing the images to avoid any conflicts with AppArmor or 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

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.

Its 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.


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-Gateway*.libvirt.xz
rm Whonix-Workstation*.libvirt.xz
rm -r Whonix-Gateway*
rm -r Whonix-Workstation*


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

Start Virtual Machine Manager.

Start Menu -> Applications -> System -> Virtual Machine Manager

Start Whonix-Gateway.

click on Whonix-Gateway -> click open -> click the play symbol

Repeat the same for Whonix-Workstation.


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.

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

4. Remove Network Whonix.

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

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


Shared Folders[edit]

To move data between the guest and host follow these steps.

On the host.

Run the following command in terminal (Start Menu -> Applications -> System -> Terminal).

sudo mkdir /mnt/shared

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

sudo chmod 777 /mnt/shared

Enable shared folders in VirtManager:

VirtManager -> click once on virtual machine -> Edit -> Virtual Machine Details -> Details -> Add Hardware -> File System


Mode: Mapped [10]

Driver: Default

Source Path: /mnt/shared

Target Path: shared

Click finish. Done.

In the VM.

Run the following command in terminal (Start Menu -> Applications -> System -> Terminal).

sudo mount -t 9p -o trans=virtio shared /mnt/shared -oversion=9p2000.L

To automatically mount this every time at boot, open /etc/fstab.

If you are using a graphical virtual machine.

kdesudo kwrite /etc/fstab

Or if you are using a terminal-only virtual machine.

sudo nano /etc/fstab


shared /mnt/shared    9p  trans=virtio,version=9p2000.L,rw    0   0


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.

Applying chown to the shared folder's contents is needed however to access the files:

chown -R yourusername /mnt/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='/mnt/shared'/>
    <target dir='shared'/>

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

LVM as Storage[edit]

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

LVM is not recommended because misconfiguration have serious security consequences and expose the host filesystem to the processes running on the guest. [11]

Enabling HugePages[edit]

Warning: Unless you trust the VMs it is recommended to NOT use this feature because it has been used as a cross-vm side-channel attack allowing full recovery of private keys in other VMs. This applies to all hypervisors.

Huge memory pages improve performance for some virtualized workloads such as running databases. They are not enabled by default in Linux because the amount of memory to be allocated this way depends on the different needs from one user/admin to another. [12]

On the host you need to activate the nr_hugepages setting in the proc filesystem:

echo 1054 > /proc/sys/vm/nr_hugepages

NOTE: To make the above value persistent, you'd need to set:

echo "vm.nr_hugepages=1054" > /etc/sysctl.d/50_hugepages

Then, `grep` for the HugePages_Total:

grep -i HugePages_Total /proc/meminfo 

Should show.

HugePages_Total:    1054

The total system RAM allocated as hugepages can be calculated as:

2Mb * 1054 = 2108 ≈ 2GiB

Then, boot a libvirt virtual machine with 2 GB memory with appropriate XML setting as noted in the example below:

  <memory unit='KiB'>2000896</memory>
  <currentMemory unit='KiB'>2000000</currentMemory>
      <page size='2048' unit='KiB' nodeset='0'/>
  <vcpu placement='static'>8</vcpu>

Enabling Clipboard Sharing[edit]

SPICE allows accelerated graphics and clipboard sharing. The clipboard is disabled by default for security reasons [13] but could be enabled.

When editing using xml, search for.

<clipboard copypaste='no'/>

And change to.

<clipboard copypaste='yes'/>

Creating Multiple Internal Networks[edit]

Open Whonix's network XML file and change the name attribute to something different than the internal network you are currently running, for example 'Whonix2' 'Whonix3' and so on. The default name used is 'Whonix'.

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


KSM is a kernel feature that allows de-deuplication of anonymous memory pages belonging to multiple instances of the same process. Only software that is designed to explicitly take advantage of it can use it such as KVM. It is usually not enabled by default. KSM only kicks in when a certain low memory threshold is reached on the host.

Depending on your use case, enabling KSM may have privacy implications as per this research [14].

The security assumptions about virtual environments is that each vm is a completely isolated instance that knows nothing about what's happening outside it. It posses a privacy problem for an isolated multi-workstation setup.

In a single workstation-to-gateway scenario, KSM isn't problematic because technically, nothing going on, on the gateway, even if known would endanger privacy. However should someone run multiple workstation vms, each with the intent that they are all separated - each with its own internal network for isolation for example, then with KSM all similar activities or processes running in the other vms, would register to an attacker who has compromised one of them. For example, information that the same website has been visited in another vm too. This would allow cross-vm activity correlation.

Its not really a weakness unique to KSM, but a common problem shared by using the equivalent feature on other hypervisors too (Xen's TPS - Transparent Page Sharing). [15]

Quote Memory Deduplication as a Threat to the Guest OS:

4.3 Detection of Downloaded Files

The memory disclosure attack can also be applied to find an opened file on a victim’s VM. We have tried to detect a logo file when Firefox shows a home page.

We confirmed that the Google logo file was detected if page caching is enabled on Firefox. When the page cache was set to 0, detection failed. If an attacker leads a victim to a malicious home page which includes an identifiable logo file, the attacker can detect the page view from the victim’s VM.

This disclosure attack is dangerous because it detects a page view even if the network is encrypted by TLS/SSL. Especially in a multi-tenant data center, this attack is serious, because it does not violate any SLA statements on cloud computing.

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='http://libvirt.org/schemas/domain/qemu/1.0'>

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: [16]

Wiping the storage used by a guest domain[edit]

A volume used by a domain can contain confidential data, hence it is necessary to wipe it before removal. Libvirt offers a helping hand for such cases:

virsh vol-wipe <volume>

which truncates and extends the volume to its original size. This in fact fills the file with zeroes. This ensures that data previously stored on volume is not accessible to reads anymore. After this, you can remove volume :

virsh vol-delete <volume>

Source [17]

XML Settings[edit]

TODO: Soon here xml settings will be explained here.



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



  1. The one in wheezy does not support rng device.
    Implemented in: http://fedoraproject.org/wiki/Features/Virtio_RNG
  2. Technically virt-manager gets installed from Debian oldstable (currently: wheezy), not Debian wheezy-backports. But that does not matter. Command works anyway. qemu-kvm and libvirt-bin get installed from wheezy-backports and virt-manager gets installed from stable.
  3. Try this.
    sudo apt-get install libvirt-bin=1.2.4-1~bpo70+1 qemu-kvm=2.0.0+dfsg-4~bpo70+1 virt-manager

    If it still doesn't work, try this.

    sudo apt-get install libvirt-bin=1.2.4-1~bpo70+1 qemu-kvm=2.0.0+dfsg-4~bpo70+1 virt-manager libvirt0=1.2.4-1~bpo70+1 qemu-system-x86=2.0.0+dfsg-4~bpo70+1 qemu-system-common python-libvirt=1.2.1-2~bpo70+1

    Maybe you need to update version numbers, see: https://packages.debian.org/wheezy-backports/libvirt-bin

  4. https://www.whonix.org/forum/index.php/topic,690
  5. https://wiki.debian.org/KVM#Troubleshooting
  6. As in, manually converting them from .ova to .qcow2 is no longer recommended, since you can download .qcow images from the Whonix project.
  7. As per build-steps.d/2400_convert-img-to-qcow2, these are "-o cluster_size=2M" and "-o preallocation=metadata".
  8. Because then you have the same performance optimizations.
  9. http://linux.die.net/man/1/qemu-img
  10. 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.
  11. https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Virtualization_Administration_Guide/sect-Virtualization-Adding_storage_devices_to_guests-Adding_hard_drives_and_other_block_devices_to_a_guest.html
  12. https://bugzilla.redhat.com/show_bug.cgi?id=1173218#c12
  13. So you don't accidentally copy for example a link to a website you visited anonymously to your non-anonymous host browser or vice versa.
  14. https://staff.aist.go.jp/c.artho/papers/EuroSec2011-suzaki.pdf
  15. http://docs.openstack.org/security-guide/content/hypervisor-selection.html
  16. https://gymnasmata.wordpress.com/2010/12/02/setting-up-gdb-to-work-with-qemu-kvm-via-libvirt/
  17. http://wiki.libvirt.org/page/VM_lifecycle#Wiping_the_storage_used_by_a_guest_domain

Log in | OpenID | Contact | Impressum | Datenschutz | Haftungsausschluss | Investors | Donate

https | Mirror | Mirror | Share: Twitter | Facebook | Google+

This is a wiki. Want to improve this page? Help welcome, volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation.

Whonix (g+) is a licensee of the Open Invention Network. Unless otherwise noted above, content of this page is copyrighted and licensed under the same Free (as in speech) license as Whonix itself.