Jump to: navigation, search




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 audit report issued by an independent security auditing firm.

A supported platform that can run Whonix. There are also others.

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.

The issues of the Open Watcom License are explained in thread on the Debian Mailinglist 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. Read more about why you should avoid non free software.

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. Security through obscurity is the operandi at Oracle.

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. A 0day reported privately to Oracle in 2008 by an independent security researcher has 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 track record 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.

VirtualBox is incompatible with many important defenses provided in Grsecurity hardened kernels including KERNEXEC, UDEREF, and RANDKSTACK.[1]

First time user?[edit]

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: jessie), click on expand on the right.

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

Optional! Only if you want this. [2]

Become root.

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

sudo adduser user sudo

Reboot so group changes take effect.


Update package lists.

sudo apt-get update


sudo apt-get install qemu-kvm libvirt-bin virt-manager

For Debian Stretch+ you need to install:

qemu-kvm libvirt-daemon-system libvirt-clients virt-manager

Arch Linux[edit]

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

Update package lists and install.

sudo pacman -Sy 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!


These are workarounds to problems affecting KVM on Debian Stable (currently Jessie).

  • On the host, 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

  • The KVM qxl package: xserver-xorg-video-qxl suffers from performance bugs caused by the Xorg surfaces feature. You will notice the graphics lagging even during mundane tasks such as scrolling down a webpage. This has been reported extensively and fixed upstream in testing. Until testing becomes stable, a workaround provided by a Whonix package is available.[3][4]

In the guest install the fix:

sudo apt-get install qxl-xorg-enhance

  • Whonix 13 users: To get rid of the Whonixcheck PVClock warning, upgrade the packages in the VM. This assumes you have enabled the Whonix stable repo:
sudo apt-get update && apt-get dist-upgrade


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]

Legacy instructions: applies up to Whonix 13 only

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

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

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's images in your home folder (/home/<your user name>).

Download Whonix[edit]


Note: You need to download both Gateway and Workstation virtual machine images.

(1.7 GB)
(2.0 GB)
Anonymous Download
possible [11]
Download Security
without Verification
Download Security
with Verification
Https long.png
Download Download Yes [11] Medium High [12]
Button sig.png OpenPGP Signature

( sha512, sig)

OpenPGP Signature

( sha512, sig)

Yes [11] - -
Crypto key.png Verify the images using the Signing Key Yes [11] - -

Verify the Whonix images[edit]


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.

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.

Legacy instructions: applies up to Whonix 13

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

If the definition of the Whonix internal network fails because the network bridge "virbr1" already exists, edit the Whonix_network*.xml file and change the name to one that doesnt exist, e.g. "virbr2" (you can list all existing bridge adapters with "sudo brctl show").

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

New Settings for Whonix 14+

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 doesnt 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

virsh -c qemu:///system net-autostart external
virsh -c qemu:///system net-start external
virsh -c qemu:///system net-autostart internal
virsh -c qemu:///system net-start 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 [13]

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


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*
rm -r external_network*
rm -r internal_network*


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

Command Line Interface (CLI)[edit]


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

To start Whonix-gateway. Respectively

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

To start workstation

Adjust Display Resolution[edit]

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

Virt-Manager Whonix-Workstation window -> View -> Scale Display -> Always | Check: Auto resize VM with window

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.

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

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.

Stay tuned[edit]


Reading the latest news is important to stay on top of latest developments. Should security vulnerabilities ever be found in Whonix, any major issues (such as with the updater) happen or should an improved version be released, you should be informed.

Whonix News Blogs[edit]

For your convenience, there are multiple choices to get news. Choose at your preference.

  1. Whonix Important Blog Whonix Important Blog Rss - Most important stuff only. Security vulnerabilities and new stable versions only. For people with very limited time and interest in Whonix development and news.
  2. Whonix Feature Blog Whonix Feature Blog rss - Includes everything from Whonix Important Blog. Also testers-only and developers versions are announced. Has a relaxed posting policy. Also blog posts about updated articles, new features, future features, development, call for testing, general project thoughts and so on will be published.
  3. Other choices. [15]

It's recommended at least to read Whonix Important Blog if you are in a hurry. Have a look into Whonix Feature Blog if you are generally interested to learn about anonymity/privacy/security related things or to see what's going on with Whonix.

Operating System Updates[edit]

You should regularly check for operating system updates on your host operating system, on Whonix-Workstation and on Whonix-Gateway as highly recommended in the Security Guide.

Tor Browser[edit]

Tor Browser's built in update check mechanism also works in Whonix. Use it.

For additional information about Tor Browser updates see Tor Browser. Additionally it might also be wise to subscribe to https://blog.torproject.org for news.

Whonix Version Check and Whonix News[edit]

whonixcheck graphical user interface screnshot
Whonix Version Check (first rectangle in black) and
Whonix News
(second rectangle in green)

Furthermore you will be automatically notified about new Whonix versions and about the most important Whonix News updates [16] by Whonixcheck.

Running Whonixcheck[edit]

By default, Whonixcheck runs automatically from time to time whenever the user starts up a Whonix-Workstation (commonly called whonix-ws). When run, Whonixcheck will verify that the Whonix system is up-to-date and that everything is in proper working order.

Even though Whonixcheck should run automatically from time to time (i.e. not every time the user starts a Whonix-Workstation), you may want to manually run Whonixcheck just to make sure that everything is in order. To do that, follow the directions below

How to manually run whonixcheck[edit]

If you are using Qubes-Whonix, complete the following steps [17]:

Qubes App Launcher (blue/grey "Q") -> click on the Whonix VM you want to check -> whonixcheck / System Check

If you are using a graphical Whonix, complete the following steps:

Start Menu -> System -> whonixcheck

If you are using a terminal-only Whonix, complete the following steps:


Whonixcheck will take a few minutes to run. Assuming everything is good, you should get a print out where each heading "INFO" is in green (not red). See example printout below:

Example of Whonixcheck printout[edit]

INFO: SocksPort Test Result: Connected to Tor. IP: 
INFO: TransPort Test Result: Connected to Tor. IP: 
INFO: Stream Isolation Test Result: Functional. 
INFO: Whonix News Result:
√ Up to date: whonix-workstation-packages-dependencies 2.5-1
√ Up to date: Whonix Build Version: 
INFO: Debian Package Update Check Result: No updates found via apt-get. 
INFO: Whonix APT Repository: Enabled. When the Whonix team releases JESSIE updates, they will be AUTOMATICALLY installed (when you run apt-get dist-upgrade) along with updated packages from the Debian team. Please read https://www.whonix.org/wiki/Trust to understand the risk. If you want to change this, use: 
Start menu -> Applications -> System -> Whonix Repository 
INFO: Tor Browser Update Check Result: Up to date. 
INFO: Please consider making a small reoccurring donation. See: https://www.whonix.org/wiki/Donate

Tor Bootstrap[edit]

Tor bootstrap refers to... It's "Tor connecting xx percent...", "Tor not connected", "Tor connected". That's all. It's not about "secure", "not secure", "anonymous", "not anonymous".

Social Media Profiles[edit]

There are some Whonix Social Media Profiles, but please don't rely on them for getting Whonix News and please don't use them to contact Whonix developers. (See Contact for contact information.)

Because some people will do so even though it is not recommended, messages from the Whonix Feature Blog will be automatically mirrored to Whonix Twitter Profile, to Whonix Facebook Profile and to Whonix Google+ Profile.

If you won't get into trouble by letting others learn about Whonix, feel free to follow or like those profiles (with your anonymous account) as a little way to Contribute. You can share this page on: Twitter | Facebook | Google+.

Source Code[edit]

In case you are interested in Whonix source code updates, subscribe to code changes.

Known bugs[edit]

Non-Qubes-Whonix means all Whonix platforms except Qubes-Whonix. That includes KVM, VirtualBox and Physical Isolation.

Suspend / Hibernate Issues[edit]

Short: Better do not suspend or hilbernate your computer or Whonix VMs while Whonix is running.

Long: Network Time Syncing, Troubleshooting#Clock Fix. [18]

Mounting (CD/DVD) Devices[edit]

Device auto mounter is broken.

See if Start menu -> System Settings -> Removable Media helps.

You can use the following workaround.

sudo mkdir /mnt/cdrom
sudo mount -o ro /dev/cdrom /mnt/cdrom/

Using the ro flag will mount the CD/DVD read-only. If you are not mounting a CD/DVD, then you can drop the "-o ro" parameter.

Forum discussion:

Help fixing this bug is welcome! (ticket)

VLC / Video Player Crash[edit]

You can use this workaround.

VLC -> Tools -> Preferences -> Video -> Output -> X11 -> Save

Network Manager Systray Unmanaged Devices[edit]

Network manger question mark.png Short answer: unrelated. Forget about it.
Long answer: [19]

Proxychains Tor Browser Issue[edit]

If you want to use Tor Browser in conjunction with proxychains for the connection scheme user -> Tor -> proxy -> internet,
this currently won't work. For more information, see here.

"apt-get source package" will show "dpkg-source: warning: failed to verify signature"[edit]

This is not a security issue, but only a warning. See here for more information and read the entire thread.

You can get remove this warning message with the following workaround below.

1. Modify /etc/dpkg/origins/default

sudo unlink /etc/dpkg/origins/default
sudo ln -s /etc/dpkg/origins/debian /etc/dpkg/origins/default

2. Download the Source Package

apt-get source package

3. Undo Afterwards to Prevent Unexpected Issues

sudo unlink /etc/dpkg/origins/default
sudo ln -s /etc/dpkg/origins/whonix /etc/dpkg/origins/default


Multiple Whonix-Gateways[edit]

In this scenario Workstations will not be able to communicate. This is recommended to keep different Tor activity profiles completely separate from each other. To run multiple Whonix-Gateways you need to clone existing machines. These steps assume an existing Whonix install.

1. Create clones of the Gateway and Workstation VMs rolled back to clean snapshots:

In Virtual Machine Manager:

Highlight VM -> Open -> Virtual Machine -> Clone... -> Clone

2. Export Whonix's internal network settings:

sudo virsh net-dumpxml internal > internal2.xml

3. Edit the network configuration to make it unique. Change the name and bridge name. Delete the mac address and uuid parameters. Alternatively, replace the configuration with the example below:

  <bridge name='virbr3' stp='on' delay='0'/>

Save and exit:


Note that virbr1 is assigned to the external network (NAT NIC), and virbr2 to the internal network (Whonix NIC), therefore, the network name was changed to internal2 and the bridge name to virbr3.

4. Import and start the new network:

virsh -c qemu:///system net-define internal2.xml
virsh -c qemu:///system net-autostart internal2
virsh -c qemu:///system net-start internal2

5. Attach the Gateway and Workstation VM NICs to the new network. Its important you pay attention and match internal network interfaces to the newer ones and not switch to a NIC that connects outside. To edit the VM virtual NIC settings:

Highlight VM -> Open -> Settings -> NIC virtual hardware -> Set Network Source to: Virtual network 'internal2' : Isolated network, internal and host routing only

Note that the network is exclusively internal and does not communicate with the host in any way.

6. Its recommended that you also edit the cloned workstation's configuration and change the pinned CPU's number to a different number (3 or 4) than used by the gateway and primary workstation. Only works if you have a quadcore system.

Testing Upcoming Versions[edit]

Download the test images from latest folder listed here. Apply the #Multiple_Whonix-Gateways 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.

Snaphot Migration[edit]

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

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

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>

3D Graphics Acceleration[edit]

By Debian Stretch 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]

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 /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:

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


Mode: Mapped [21]

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 chown must be applied to the shared folder's contents to access the files:

sudo chown -R yourusername /home/yourusername/shared && sudo chmod 777 -R /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='/mnt/shared'/>
    <target dir='shared'/>

USB Passthrough[edit]

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

WARNING: You should only connect USB devices to Whonix-Workstation when its in a clean trusted state. The only safe and recommended way to move files out of a VM is through Shared Folders.

While Whonix-Workstation is shut down, add two USB redirection devices:

Whonix-Workstation viewer window -> View -> Details -> Add Hardware -> USB Redirection

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

Hypervisor Default -> USB 2

Start Whonix-Workstation and select the device connected to the host you want to pass through:

Whonix-Workstation viewer window -> File -> Redirect USB -> 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.

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.

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.

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

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

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. [25]

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.[26][27] Disabled in cloud tenancy environments.


THP/Hugepages aid rowhammer attacks[28] 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.[29]

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.


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.[30] It can infer what programs and what pages are being visited outside the VM. [31] Disabled in cloud tenancy environments. This feature can also allow attackers to modify/steal APT keys and source lists of the host. [32][33]

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.[34]

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

Alternative Guides[edit]

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



  1. https://github.com/linux-scraping/linux-grsecurity/commit/31e606aa9da683109cee72d45c9cda60992f01dc
  2. If you don't do this, you cannot use sudo as outline below and elsewhere. You then would have to manually switch to root and/or use su as per About#Based_on_Debian.
  3. https://forums.whonix.org/t/qxl-slowness-fix/1759
  4. https://phabricator.whonix.org/T511
  5. 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
  6. https://forums.whonix.org/t/kvm-networking-broken/644
  7. https://wiki.debian.org/KVM#Troubleshooting
  8. As in, manually converting them from .ova to .qcow2 is no longer recommended, since you can download .qcow images from the Whonix project.
  9. As per build-steps.d/2400_convert-img-to-qcow2, these are "-o cluster_size=2M" and "-o preallocation=metadata".
  10. Because then you have the same performance optimizations.
  11. 11.0 11.1 11.2 11.3 By using the Tor Browser Bundle (TBB). For an introduction, see Tor Browser. See also Hide Tor and Whonix from your ISP.
  12. It does not matter if you did the bulk download over an insecure channel, if you use OpenPGP verification at the end.
  13. http://linux.die.net/man/1/qemu-img
  14. https://elmarco.fedorapeople.org/manual.html
  15. Other choices.
  16. Such as when a version becomes unsupported, if manual action is required, if major features break, or if security vulnerabilities are found. The policy is to use Whonix News as rarely as possible.
  17. Qubes VM Manager -> right-click on the Whonix VM you want to check -> select "Run command in VM"

    Type the following.


    Then press.


    Type the following.


    Then press.

  18. https://github.com/QubesOS/qubes-issues/issues/1764
  19. Whonix doesn't use network manager to either manage eth0 or eth1. We do not want to port to network manager at this point, because there is no reason besides this issue. For one reason, because ifupdown works well with Whonix for a long time and is well tested. It is unclear if network manager, specifically cli, is ready for prime time yet. What network manager reports is that it does not manage these devices. It's not an error. Just an information. What we would like to do would be hiding that systray item by default. Or suppress that information. Or not starting that systray by default. Because that would cause less confusion. Network manager is installed to make it easier for users setting up VPNs using its graphical user interface.
    All attempts so far fixing it have failed. Help required for fixing it.
    Long standing known issue.
    Fix Unmanaged Devices Network Manager
  20. https://serverfault.com/a/648871
  21. 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.
  22. https://bugzilla.redhat.com/show_bug.cgi?id=1135488
  23. https://askubuntu.com/questions/564708/qemu-kvm-virt-manager-passthrough-of-usb-webcam-to-windows-7-enterprise-creates
  24. https://gymnasmata.wordpress.com/2010/12/02/setting-up-gdb-to-work-with-qemu-kvm-via-libvirt/
  25. 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
  26. https://github.com/fog/fog/issues/2525
  27. https://news.ycombinator.com/item?id=6983097
  28. http://arxiv.org/pdf/1507.06955v1.pdf
  29. https://www.whonix.org/pipermail/whonix-devel/2016-September/000746.html
  30. Dedup Est Machina: Memory Deduplication as an Advanced Exploitation Vector
  31. https://staff.aist.go.jp/c.artho/papers/EuroSec2011-suzaki.pdf
  32. Flip Feng Shui: Hammering a Needle in the Software Stack
  33. https://archive.is/aB7Kg
  34. http://docs.openstack.org/security-guide/compute/hardening-the-virtualization-layers.html#physical-hardware-pci-passthrough

Random News:

Want to help create awesome, up-to-date screenshots for the Whonix wiki? Help is most welcome!

Impressum | Datenschutz | Haftungsausschluss

https | (forcing) onion
Share: Twitter | Facebook | Google+
This is a wiki. Want to improve this page? Help is welcome and 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, the content of this page is copyrighted and licensed under the same Free (as in speech) license as Whonix itself.