Actions

KVM

From Whonix

About this KVM Page
Support Status stable
Difficulty medium
Maintainer HulaHoop
Support Support

Contents

General[edit]

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. However, it now comes 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 / Kicksecure default admin password is: changeme default username: user
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]

Debian[edit]

If you are using Debian stable (currently: buster), 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.

su

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.

reboot

Update package lists.

sudo apt-get update

For Debian Buster+ you need to install:.

sudo apt-get install qemu-kvm libvirt-daemon-system libvirt-clients virt-manager gir1.2-spiceclientgtk-3.0

Arch Linux[edit]

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

Update the package lists and install the following packages.

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.

The qemu-kvm and libvirt-bin packages are necessary. virt-manager is also required in order to use a graphical user interface (which most users want). It is most likely this software can be installed using the usual distribution's package manager.

If any of the following errors appear while later using virsh define.

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

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

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

Then a more recent version of libvirt and kvm is likely needed.

Readers are welcome to add detailed instructions for other distributions here!

Notice[edit]

Arch Users[edit]

  • As of March 2019, it has been reported that the blkio throttling feature appears to be missing/unsupported on the latest Arch version. This causes a failure during VM start up. [5] The current work around is to remove the feature for now.

1. Edit the configuration file.

sudo virsh edit Whonix-Gateway

2. Strip out the following setting.

 <blkiotune>
    <weight>250</weight>
</blkiotune>

3. Repeat steps 1-2 in Whonix-Workstation.

4. Save and start the VMs.

  • The pvspinlock feature is reported to not be supported and the issue was resolved when edited out of the VM config.

Addgroup[edit]

In order to be able to manage virtual machines as a regular (non-root) user, that user must be added to the libvirt and the kvm group. The following command will work in Debian and assumes the simple scenario whereby KVM will be utilized with the current logged in user. Also note that in Ubuntu the group names vary and it is called libvirtd instead.

sudo addgroup "$(whoami)" libvirt

sudo addgroup "$(whoami)" kvm

[6]

Other Distributions[edit]

If another distribution is in use, then first refer to the distribution manual. For example, a necessary reference for Arch users is the Arch Linux libvirt wiki page.

Reboot[edit]

Note: A reboot is required after:

  • KVM is installed.
  • Users are added to groups.

sudo reboot

Network Start[edit]

Info These steps have nothing to do with Whonix ™ 14+, but are helpful when running other VMs.

Ensure KVM's / QEMU's default networking is enabled and has 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]

Introduction[edit]

It is strongly recommended to read and apply the steps outlined in this section. By applying a known and tested configuration, this will provide better convenience and security.

Be sure to use the qcow2 images that are provided by the Whonix ™ project instead of rolling your own [9] because they contain important performance optimizations. [10] The only exception is if images were created from source. [11]

If problems are encountered with free disk space, using a file system that supports sparse files is recommended. Also refer to the following forum discussion.

If Whonix ™ libvirt images already exist, then consider a Cleanup first.

For simplicity the Whonix ™ images should be downloaded and stored in the home folder (/home/<your user name>) so the following commands can be copied/pasted without changes.

Download Whonix ™[edit]

FREE Download


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

Version: 15.0.0.4.9

Whonix ™
Download Security
without Verification
Download Security
with Verification
Https long.png

Download

Medium High [12]
Button sig.png

OpenPGP Signature ( sha512 , sig )

- -
Crypto key.png Verify images using this Signing Key -


Verify the Whonix ™ Images[edit]

1. Download HulaHoop's OpenPGP key from the website.

curl --tlsv1.2 --proto =https https://www.whonix.org/hulahoop.asc -o hulahoop.asc

2. Check fingerprints/owners without importing anything. [13]

gpg --keyid-format long --import --import-options show-only --with-fingerprint hulahoop.asc

3. Verify the output.

The output should be identical to the following.

pub   rsa4096/50C78B6F9FF2EC85 2018-11-26 [SCEA]
      Key fingerprint = 04EF 2F66 6D36 C354 058B  9DD4 50C7 8B6F 9FF2 EC85
uid                            HulaHoop
sub   rsa4096/EB27D2F8CEE41ACC 2018-11-26 [SEA]

4. Import the key.

gpg --import hulahoop.asc

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

5. Optional: For extra assurance, verify the key was also signed by Patrick Schleizer.

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

The output should be identical to the message below.

pub   rsa4096/0x50C78B6F9FF2EC85 2018-11-26 [SCEA]
      04EF2F666D36C354058B9DD450C78B6F9FF2EC85
uid                   [ unknown] HulaHoop
sig!         0x8D66066A2EEACCDA 2018-12-14  Patrick Schleizer <adrelanos@riseup.net>
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.

6. Verify the archive with Hulahoop's key.

gpg --verify whonix*.libvirt.xz.asc whonix*.libvirt.xz

The output should include the following text.

gpg: Good signature from "HulaHoop"

Decompress[edit]

Use tar to decompress the archive.

tar -xvf Whonix*.libvirt.xz

Do not use unxz! Extract the images using tar.

License Agreement[edit]

Read the Whonix binary license agreement via one of the following resources:

  • this online link; or
  • open it with a text editor; or
  • use more.

more WHONIX_BINARY_LICENSE_AGREEMENT

Press Enter to scroll down.

Indicate either A) acceptance, or B) refusal.

A) In the case of acceptance:

touch WHONIX_BINARY_LICENSE_AGREEMENT_accepted

B) In the case of denial:

touch WHONIX_BINARY_LICENSE_AGREEMENT_denied

You are welcome to attempt negotiations regarding any element of these terms by contacting us.

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

Optional: XML Modification[edit]

This section describes XML modifications before importing a virtual machine. For virtual machines that were already imported, see: Editing an Imported Machine's XML Configuration.

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

Open Whonix-Gateway*.xml in an editor as a regular, non-root user.

If you are using a graphical environment, run.

mousepad Whonix-Gateway*.xml

If you are using a terminal, run.

nano Whonix-Gateway*.xml

Open Whonix-Workstation*.xml in an editor as a regular, non-root user.

If you are using a graphical environment, run.

mousepad Whonix-Workstation*.xml

If you are using a terminal, run.

nano Whonix-Workstation*.xml

It is possible to edit the XML files later on if this is necessary, see: Editing an Imported Machine's XML Configuration.

Importing Whonix ™ VM Templates[edit]

The supplied XML files serve as a description for libvirt and define the properties of a Whonix ™ VM and the networking it should have.

1. Add and activate the virtual networks. [14]

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 does not exist, for example "virbr3" (all existing bridge adapters can be listed 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. Import 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]

Use qemu-img to interact with KVM disk images. This software can resize virtual disks, convert virtual disks to other formats, and more. It is not necessary nor recommended to change the official images, so proceed cautiously and only if the procedure is understood.

For more commands, refer to the qemu-img manual.

Moving Whonix ™ Image Files[edit]

The XML files are configured to point to the default storage location of /var/lib/libvirt/images. The following steps move the images there so the machines can boot.

Note: Changing the default location may cause conflicts 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

Copying Whonix ™ Image Files[edit]

Whonix ™ disk images are sparse files, meaning they expand when filled rather than allocating their entire size (100GB outright). Sparse files require special commands when they are copied to ensure they do not lose this property, otherwise they will occupy all of the actual space. Higher privileges (sudo) are required because the copying is to a privileged location in the system.

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

Encrypted Containers[edit]

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

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

Cleanup[edit]

After importing Whonix ™, it is 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 if a new version of Whonix ™ is later downloaded.

To delete the archives and temporary folders, run.

rm Whonix*
rm -r WHONIX*

Start[edit]

If Virtual Machine Manager is familiar, 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 steps for Whonix-Workstation ™.

Command Line Interface (CLI)[edit]

On the host.

To start Whonix-Gateway ™, run.

sudo virsh start Whonix-Gateway

To start Whonix-Workstation ™, run.

sudo virsh start Whonix-Workstation

To interact with the Whonix-Workstation ™ via console, run.

sudo virsh console Whonix-Workstation

To disable startup of the included Desktop Environment regardless of how much RAM is assigned to the VM, configure RAM Adjusted Desktop Starter package settings.

Adjust Display Resolution[edit]

Whisker Menudisplayselect resolution [16]

Save and then take a snapshot.

Deprecated[edit]

Note: The following instructions have been kept in case they are functional again in the future. This feature in virt-manager will currently cause the guest screen to be unresponsive due to a reported upstream bug that has not yet been resolved.

With the QXL driver (installed by default) it is possible to seamlessly adjust the display resolution to adjust to the Host screen size. [17]

Virt-Manager Whonix-Workstation ™ windowViewScale DisplayAlways | Check: Auto resize VM with window

After Installing[edit]

Read and apply the Post Installation Security Advice.

Uninstall[edit]

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

1. Power off the VM you want to shut down. [18]

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 ™ 14 and earlier versions used the network names "external" and "internal". This means the command must 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 ™ 14 and earlier versions used the network names "external" and "internal". This means the command must 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.

Note: All data will be lost unless it is first backed up.

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

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

KVM Upgrade Instructions[edit]

It is strongly recommended to uninstall older Whonix ™ versions and always run the stable release. Note that Whonix ™ supports in-place apt-get upgrades too.

  1. Move your data out of the VM via shared folders.
  2. Perform the Cleanup steps.
  3. Install the new images.

Optional[edit]

Multiple Whonix-Gateway ™s[edit]

See: Multiple Whonix-Gateway ™s.

Testing Upcoming Versions[edit]

Download the test images from the latest folder listed here. Apply the Multiple Whonix-Gateway KVM steps 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 Importing Whonix installation steps. Keep in mind the full name of the new images must be used and do not import the Network templates.

Magic SysRq Keys[edit]

Magic SysRq keys are useful when the guest is unresponsive, especially in cases where VMs are running headless and a GUI console is not available for forcing them to shut off on the host.[19]

Example command to shut down Whonix Workstation from a host console. The O at the end of KEY_O can be substituted with any other supported letter listed in the kernel documentation. See also SysRq.

sudo virsh send-key Whonix-Workstation KEY_LEFTALT KEY_SYSRQ KEY_O

DHCP[edit]

Libvirt provides built-in DHCP functionality via a custom install of the minimalist Dnsmasq DNS/DHCP daemon. [20] This is useful when running multiple Workstations concurrently that are attached to the same Gateway, and for custom Workstations running Android x86.

For privacy and traffic leak purposes Dnsmasq does not resolve DNS as implemented in Libvirt. [21] [22] DNS is not explicitly enabled for guests unless it is added to a network’s configuration. [23] [24] Even when DNS is enabled, the way Libvirt uses it does not increase the host's attack surface (by using raw sockets for example) nor does DHCP because it is bound to a specific NIC in this case. [25] Trying to edit the Dnsmasq configuration files directly will fail as settings are rewritten and are enforced through Libvirt by design. [26]

1. Edit the network configuration file.

sudo nano /etc/network/interfaces.d/30_non-qubes-whonix

2. Make the following comment changes.

Comment out.

auto eth0
iface eth0 inet static

Comment in.

auto eth0
iface eth0 inet dhcp

Save the file.

3. Change the internal network setting.

sudo virsh net-edit Whonix-Internal

<ip address='10.152.152.0' netmask='255.255.192.0'>
    <dhcp>
      <range start='10.152.128.1' end='10.152.191.254'/>
    </dhcp>
</ip>

4. Restart the internal network.

sudo virsh net-destroy Whonix-Internal

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

5. Use sudo ifconfig to confirm if dynamic IP assignment is functional.

6. Optional: Construct a static IP address.

Libvirt also allows the pairing of a static IP from the DHCP server to a VM with a specific MAC address if services in the Workstation depend on predictable IPs. See the host attribute under the dhcp element.

Snapshot Migration[edit]

If the VM has snapshots that you wish to preserve, the snapshot xml-files of the source VM should be dumped with the following commands. [27]

1. List snapshot names of the VM.

virsh snapshot-list --name $dom

2. Dump each snapshot you want to back-up.

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

3. Restore snapshots at the destination.

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

4. Optional: Identify which snapshot is the current one.

On the source VM, run.

virsh snapshot-current --name $dom

On the destination, run.

virsh snapshot-current $dom $name

Nested KVM Virtualization[edit]

It is possible to create nested KVM VMs on KVM hosts. As root...

Check the current setting on the host. If the result is [Y], then it is okay.

sudo cat /sys/module/kvm_intel/parameters/nested

For AMD systems use kvm_amd instead.

sudo cat /sys/module/kvm_amd/parameters/nested

If the result is [N], run the following command and reboot the system.

echo 'options kvm_intel nested=1' | sudo tee -a /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]

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

To re-compress files, run.

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 occur. 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 cryptographic library.

To add more vcpus, increase the number in between the opening and closing vcpu tags. Alternatively, 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 compared to other sensitive VMs. Map them in a 1:1 ratio to avoid over committing cores (which leads to performance problems).

3D Graphics Acceleration[edit]

Not yet functional as of Buster but this has been fixed upstream. Future enhancements for performance and security are planned. Will revisit in Bullseye.

Shared Folders[edit]

Ambox warning pn.svg.png Warning: Do not delete files from the shared folder from within the Workstation VM! The reason is 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.

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

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

sudo mkdir /home/yourusername/shared

2. Adjust permissions on the host to allow read and write access to the folder with chmod.

sudo chmod 777 /home/yourusername/shared

3. Enable shared folders in VirtManager.

VirtManagerSelect VMEditVirtual Machine DetailsDetailsAdd HardwareFile System

4. Choose the following settings.

  • Mode: Mapped [28]
  • 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.

Mandatory Access Control[edit]

Note: If your system is configured to use a Mandatory Access Control framework then it might be necessary to configure exceptions to allow the confined guests to communicate with the shared folder on the host.

Tests with Apparmor have shown it operates transparently with shared folders, without the need for a manual exception configuration.

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 SELinux is disabled then everything should be functional. If SELinux is enabled, it is necessary to add a policy for files under the shared folder on the host. SELinux will not allow this folder to be shared until it is labeled svirt_image_t. To achieve this add the following policy on the host using semanage. Note that these steps must be re-applied every time something is transferred. [29] [30]

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

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

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

USB Passthrough[edit]

Ambox warning pn.svg.png Warning: 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.

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

1. In the Details pane change the Controller USB device model.

Hypervisor DefaultUSB 2

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 windowViewDetailsAdd HardwareUSB Redirection

3. Start Whonix-Workstation ™ and select the device connected to the host that you want to passthrough.

Whonix-Workstation ™ viewer windowFileRedirect USBChoose: Webcam (or another USB Device)

Note this last step must 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 completing the instructions above to auto-sandbox untrusted USB flash drives. Debian maintainers have disabled USB auto-redirection by default to prevent the accidental passthrough of trusted USB devices to untrusted guests, [33] [34] so they must be reverted temporarily. Once finished, change them back to safe defaults by going through the steps in reverse order.

Limitations[edit]

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 so long as the Whonix-Workstation ™ is running. Do not close the 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. The VM window can be minimized after it is detected in the guest; it is unnecessary to wait for the VM to completely boot.

This isolation method is not fool-proof because 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.

1. Edit the libvirt glib-2.0 schema.

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

2. Change the default contents.

[org.virt-manager.virt-manager.console]
auto-redirect=false

Should be changed to.

[org.virt-manager.virt-manager.console]

3. Recompile the schemas for changes to take effect. [35]

4. Close all instances of Libvirt/Virtual Machine Manager and restart them so the new settings apply.

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

5. Add the USB Redirection devices as specified in previous instructions.

6. Boot Whonix-Workstation ™ and connect the USB thumbdrive.

The thumbdrive should be automatically seen in the guest only.

Editing an Imported Machine's XML Configuration[edit]

Eventually configure your favorite editor to make changes. Set visual as your favorite editor -- the relevant software must be installed, such as kwrite, leafpad, kate, vi, nano, vim and so on.

export VISUAL=kwrite

Edit.

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

Disable Microphone Input[edit]

Microphone input to guests is a nice feature for VoIP, but it is dangerous to have on by default. It is good practice to disable the microphone on your host system through sound settings when it is not in active use.

The shipped configuration only includes a speaker by default (without a microphone) to prevent malware in the VM from eavesdropping on the user. To enable microphone input for select guests, edit the configuration and change <codec type='output'/> -> <codec type='micro'/>.

Creating Multiple Internal Networks[edit]

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

Alternative Configurations[edit]

Libvirt can support a variety of containment mechanisms. Currently supported mechanisms include KVM on the x86_64 platform and QEMU, but more configurations might be added at a later date. If hardware virtualization extensions are available, 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]

In the hypothetical situation whereby a user is "trapped" in a virtual console inside a VM without graphical desktop environment (X Window System) ("sudo service lightdm stop"), it is still possible to switch back to the host.

In other words, should the graphical desktop environment crash or be terminated, the user may be "trapped" inside a black VM window. It is possible to exit this.

The emulated tablet device handles this by not allowing the mouse to be captured by the guest, however this is still possible:

Press Ctrl_L & Alt_L

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

In order to debug a Linux kernel that is running as a KVM guest, the -s parameter must be specified for the command line of qemu-kvm. Unfortunately there is no (easy) way to do this when libvirt and virt-manager are used to manage your virtual machines (instead of using KVM directly). In this case it is necessary to change the XML configuration of the virtual machine so that the -s parameter is passed on to qemu-kvm.

1. Open the XML configuration.

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.

2. Edit the XML configuration.

Change the first line of the XML file from.

<domain type='kvm'>

To.

<domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>

It is also necessary to add this setting.

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

Under the <domain> level of the XML.

3. Save the XML configuration.

After saving and quitting the editor, the new configuration will come into effect. When the virtual machine is started, there will be a local TCP port (1234 by default) that can be used as a remote debugging port from gdb.

4. Connect to the local TCP port.

Use the following command from gdb running on the host machine.

target remote localhost:1234

Source: [36]

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

In the event 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. [38] [39] This setting is disabled in cloud tenancy environments.

HugePages[edit]

THP/Hugepages aid rowhammer attacks [40] and memory de-duplication attacks (see KSM below) and therefore must be disabled for the guest and on the host. Research suggests that Debian hosts do not enable this feature and it is also disabled in cloud tenancy environments.

Memory Ballooning[edit]

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

Clipboard Sharing[edit]

SPICE allows accelerated graphics and clipboard sharing. The clipboard is disabled by default for security reasons:

  • To prevent the accidental copying of a link to a website that was visited anonymously to the non-anonymous host browser (or vice versa).
  • To stop malware in Whonix ™ Workstation from pilfering sensitive info from the clipboard.

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

KSM[edit]

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

Device Passthrough[edit]

Both USB and PCI device passthrough permit advanced attackers to flash the firmware of those devices and infect the host or other VMs. [46]

XML Settings[edit]

For more information on settings, please refer to the Libvirt manual.

Troubleshooting[edit]

Reboot?[edit]

  • Did you reboot after installing KVM?
  • Did you reboot after adding users to groups?

Please add this information if making a support request.

Unable to connect to libvirt[edit]

If the following error appears.

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 the following error appears.

Unable to open a connection to the libvirt management daemon.

Libvirt URI is: qemu:///system

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

Check the KVM installation.

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

The output should show.

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

Running guests on default URI: no running guests.
0

In this case, it could be a permissions problem.

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

If this error appears you might be a member of the libvirt group, but lack membership of the kvm group.

In this case, it helps to change.

    <sound model='ich6'>

To.

    <sound model='ac97'>

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

If the following error appears.

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

Then it is not possible other non-KVM VMs (such as VirtualBox VMs) might already be running, since two concurrent hypervisor instances is not supported by KVM / VirtualBox.

Permissions[edit]

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

Add Version Numbers to Support Request[edit]

If problems are experienced, be sure to note what versions of libvirt-bin, qemu-kvm and virt-manager are in use as part of the support request. If you are using Debian, the following command will determine the software versions.

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, see: Installation Screenshots.

Development[edit]

Footnotes[edit]

  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.

  3. https://forums.virtualbox.org/viewtopic.php?f=7&t=89395
  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. https://forums.whonix.org/t/problem-starting-whonix-14-after-upgrade-unable-to-write-to-sys-fs-cgroup-blkio-machine-slice-machine-qemu/6999/5
  6. By default Debian does not use sudo, so groups can be added with usermod. If your user is "foo" the following commands will work.
    usermod -a -G libvirt foo
    And.
    usermod -a -G kvm foo
  7. https://forums.whonix.org/t/kvm-networking-broken/644
  8. https://wiki.debian.org/KVM#Troubleshooting
  9. Manually converting images from .ova to .qcow2 is no longer recommended, since .qcow images can be downloaded 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 the same performance optimizations are present.
  12. It does not matter if the bulk download is done over an insecure channel if OpenPGP verification is used at the end.
  13. https://forums.whonix.org/t/gpg-show-key-warning-gpg-warning-no-command-supplied-trying-to-guess-what-you-mean/7859
  14. The settings files are also in the same folder as Whonix ™ Gateway.
  15. https://forums.whonix.org/t/cant-use-var-lib-libvirt-images-for-whonix-images-what-to-do-about-apparmor/7192/3
  16. https://forums.whonix.org/t/no-auto-resize-with-qxl-driver/7145/3
  17. https://elmarco.fedorapeople.org/manual.html
  18. The command line can also be used to make sure the VM has been shut down.
  19. https://dustymabe.com/2012/04/21/send-magic-sysrq-to-a-kvm-guest-using-virsh/
  20. https://forums.whonix.org/t/safer-dhcp-implementation-resolved/7499/7
  21. https://wiki.libvirt.org/page/Libvirtd_and_dnsmasq:

    On linux host servers, libvirtd uses dnsmasq to service the virtual networks, such as the default network. A new instance of dnsmasq is started for each virtual network, only accessible to guests in that specific network.

  22. Dnsmasq is visible to a nmap scan from the Workstation but not much else. Manual test: sent a DNS request with this result:
        dig microsoft.com @10.152.152.0
    
        ; <<>> DiG 9.11.5-P4-3-Debian <<>> microsoft.com @10.152.152.0
        ;; global options: +cmd
        ;; connection timed out; no servers could be reached
    
  23. https://fabianlee.org/2018/10/22/kvm-using-dnsmasq-for-libvirt-dns-resolution/
  24. https://www.cyberciti.biz/faq/linux-kvm-libvirt-dnsmasq-dhcp-static-ip-address-configuration-for-guest-os/
  25. https://unix.stackexchange.com/questions/256061/is-libvirt-dnsmasq-exposed-to-the-network-if-i-run-fedora-without-a-firewall:

    So I can see an open TCP port. However it responds as if it’s “tcpwrapped”. That implies if you connect over a different interface from virbr0 , dnsmasq closes the connection without reading any data. So data you send to it doesn’t matter; it can’t e.g. exploit a classic buffer overflow.

  26. https://serverfault.com/questions/840163/custom-dnsmasq-or-custom-options-with-libvrt
  27. https://serverfault.com/a/648871
  28. 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.
  29. http://nts.strzibny.name/how-to-set-up-shared-folders-in-virt-manager/
  30. https://unix.stackexchange.com/questions/60799/selinux-interfering-with-host-guest-file-sharing-using-kvm
  31. https://bugzilla.redhat.com/show_bug.cgi?id=1135488
  32. https://askubuntu.com/questions/564708/qemu-kvm-virt-manager-passthrough-of-usb-webcam-to-windows-7-enterprise-creates
  33. https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=765016
  34. https://anonscm.debian.org/cgit/pkg-libvirt/virt-manager.git/commit/?id=d81fd3c3af1abde1fa0e2bf3b79643f36836f45b
  35. https://developer.gnome.org/gio/stable/glib-compile-schemas.html
  36. https://gymnasmata.wordpress.com/2010/12/02/setting-up-gdb-to-work-with-qemu-kvm-via-libvirt/
  37. 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
  38. https://github.com/fog/fog/issues/2525
  39. https://news.ycombinator.com/item?id=6983097
  40. https://arxiv.org/pdf/1507.06955v1.pdf
  41. https://www.whonix.org/pipermail/whonix-devel/2016-September/000746.html
  42. Dedup Est Machina: Memory Deduplication as an Advanced Exploitation Vector
  43. https://staff.aist.go.jp/c.artho/papers/EuroSec2011-suzaki.pdf
  44. Flip Feng Shui: Hammering a Needle in the Software Stack
  45. https://archive.is/aB7Kg
  46. https://docs.openstack.org/security-guide/compute/hardening-the-virtualization-layers.html#physical-hardware-pci-passthrough

[advertisement] Looking to Sell Your Company? Contact me.


Want to make Whonix safer and more usable? We're looking for helping hands. Check out the Open Issues and development forum.

https | (forcing) onion
Follow: Twitter.png Facebook.png 1280px-Gab text logo.svg.png Rss.png 1024px-Telegram 2019 Logo.svg.png

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.