{{Header}} {{hide_all_banners}} {{Title|title= {{project_name_long}} for KVM }} {{#seo: |description=Using {{project_name_short}} with KVM (Kernel Virtual Machine) |image=Kvm-new-logo.png }} {{Contributor| |status=stable |about=About this {{PAGENAME}} Page |difficulty=medium |contributor=[https://forums.whonix.org/u/hulahoop HulaHoop] |support=[[KVM/Support|Community support
only!]] }} {{kvm_logo}} {{intro| Using {{project_name_short}} with KVM (Kernel Virtual Machine) }} {{Community_Support|scope=page}} = General = == What is KVM? == For an openly developed, free and open-source software (FOSS), GPL licensed hypervisor that can run Whonix, There are also [[Download|Download other platforms]]. it is recommended to use [https://www.linux-kvm.org/page/Main_Page Kernel Virtual Machine (KVM)] that comes with the GNU/Linux OS. KVM combined with the [https://virt-manager.org/ VirtualMachineManager] front-end should provide a familiar, intuitive and easy-to-use GUI. KVM uses [https://wiki.archlinux.org/title/libvirt '''libvirt''']. For a detailed view on KVM's security merits read the [https://web.archive.org/web/20240205091840/https://www.atsec.se/uploads/articles_and_whitepapers/kvm_security_comparison.pdf audit report] issued by an independent security auditing firm. == Why Use KVM Over VirtualBox? == The VirtualBox developer team have taken the decision to switch out the BIOS in their hypervisor. However, it now comes with one that requires compilation by a toolchain that [[Dev/VirtualBox#VirtualBox_Unavailable_in_Debian_main_due_to_Licensing_Issues|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 {{project_name_short}} is based. The issues of the Open Watcom License are explained in [https://www.mail-archive.com/debian-legal@lists.debian.org/msg34687.html this thread] on the Debian Mailinglist. More references can be found [[Dev/VirtualBox#VirtualBox_Unavailable_in_Debian_stable_and_backports_due_to_Debian_Stable_Security_Maintenance_Issues|here]]. 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_nonfreedom_software|avoid non-freedom 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. [https://www.techopedia.com/definition/21985/security-through-obscurity-sto Security through obscurity] is the flawed [https://www.oracle.com/corporate/security-practices/assurance/vulnerability/disclosure.html modus operandi] at Oracle. [https://web.archive.org/web/20220128154850/http://users.softlab.ntua.gr/~taver/security/secur3.html 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.
 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 [https://en.wikipedia.org/wiki/Zero-day_(computing) 0day vulnerability] reported privately to Oracle in 2008 by an independent security researcher. Over four years later, the vulnerability [https://seclists.org/fulldisclosure/2012/Apr/343 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 [[Spectre_Meltdown#VirtualBox|non-responsiveness]] and non-progress by upstream. Users must patiently wait for VirtualBox developers to fix this bug. https://forums.virtualbox.org/viewtopic.php?f=7&t=89395 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. For the opposite viewpoint, see [[Dev/VirtualBox#Why_use_VirtualBox_over_KVM?|Why use VirtualBox over KVM?]] = First-time User? = {{Default_Passwords}} {{First_Time_User}} = KVM Setup Instructions = == Install KVM == Choose your host operating system. {{Tab |type=controller |content= {{Tab |title= === Debian === |image=[[File:Logo-debian.png|25px]] |addToClass=info-box |content= {{Sudo_Setup}} Update package lists. {{CodeSelect|code= sudo apt update }} For '''Debian {{Stable project version based on Debian codename}}+''' on Intel / AMD you need to install: {{CodeSelect|code= sudo apt install --no-install-recommends qemu-kvm qemu-system-x86 libvirt-daemon-system libvirt-clients virt-manager gir1.2-spiceclientgtk-3.0 dnsmasq-base qemu-utils iptables safe-rm xz-utils }} For '''Debian {{Stable project version based on Debian codename}}+''' on PowerPC you need to install: {{CodeSelect|code= sudo apt install --no-install-recommends qemu-system-ppc libvirt-daemon-system libvirt-clients virt-manager gir1.2-spiceclientgtk-3.0 dnsmasq-base qemu-utils iptables safe-rm xz-utils }} }} {{Tab |title= === Ubuntu === |image=[[File:Logo-ubuntusvg.png|25px]] |addToClass=info-box |content= {{CodeSelect|code= sudo apt install qemu-kvm libvirt-clients libvirt-daemon-system bridge-utils libguestfs-tools genisoimage virtinst libosinfo-bin virt-manager dnsmasq-base iptables safe-rm xz-utils }} Add your user to KVM Groups (1 of 2). {{CodeSelect|code= sudo adduser $USER libvirt }} Add your user to KVM Groups (2 of 2). {{CodeSelect|code= sudo adduser $USER libvirt-qemu }} }} {{Tab |title= === Arch Linux === |image=[[File:Archlinux_logo.png|25px]] |addToClass=info-box |content= TODO: Possible to only install dnsmasq-base without the dnsmasq systemd unit or does Arch Linux keep the systemd unit disabled by default? CRITIQUES: "safe-rm" and "xz-utils" aren't Archlinux packages. tar should install xz-utils if there's a dependency. safe-rm has limited value. {{CodeSelect|code= sudo pacman -Syu qemu libvirt virt-manager qemu-full dnsmasq bridge-utils safe-rm xz-utils }} {{CodeSelect|code= sudo systemctl enable libvirtd }} }} {{Tab |title= === Fedora === |image=[[File:Fedora-logo.png|25px]] |addToClass=info-box |content= '''Check System Requirements''' As KVM requires a CPU with virtualization extensions, check whether the system has either Intel VT or AMD-V. If the following command prints nothing, the system does not support the relevant virtualization extensions. {{CodeSelect|code= egrep -E '^flags.*(vmx{{!}}svm)' /proc/cpuinfo }} '''Install Dependencies''' To install mandatory and default packages in the virtualization group, run. {{CodeSelect|code= sudo dnf install @virtualization xz-utils }} Alternatively, to install the mandatory, default, and optional packages, run. {{CodeSelect|code= sudo dnf group install --with-optional virtualization xz-utils }} After package installation, start the libvirtd service. {{CodeSelect|code= sudo systemctl start libvirtd }} To start the service on boot, run. {{CodeSelect|code= sudo systemctl enable libvirtd }} Verify the KVM kernel modules loaded properly. If this command lists kvm_intel or kvm_amd, KVM is properly configured. lsmod {{!}} grep kvm '''Edit the libvirtd Configuration''' System administration is limited to the root user by default. To enable a regular user, run the following commands. Open the /etc/libvirt/libvirtd.conf file for editing. {{CodeSelect|code= sudo nano /etc/libvirt/libvirtd.conf }} Set the domain socket group ownership to libvirt. {{CodeSelect|code= unix_sock_group = "libvirt" }} Adjust the Unix socket permissions for the R/W socket. {{CodeSelect|code= unix_sock_rw_perms = "0770" }} Save and exit. To administer libvirt as a regular user, add the user to the libvirt group. Otherwise the sudo password is required every time virtual-manager is started. {{CodeSelect|code= sudo usermod -a -G libvirt $(whoami) }} You must log out and log in to apply the changes. }} {{Tab |title= === Other Distributions === |image=[[File:Gnu_operating_system.png|25px]] |addToClass=info-box |content= 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). tar, xz-utils is required to extract the {{project_name_short}} images. 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 {{Code|virsh define}}. {{CodeSelect|code= error: Failed to define domain from {{project_name_gateway_short}}_kvm.xml error: internal error Unknown controller type 'pci }} {{CodeSelect|code= {{project_name_gateway_short}}_kvm.xml:24: element pm: Relax-NG validity error : Element domain has extra content: pm {{project_name_gateway_short}}_kvm.xml fails to validate }} {{CodeSelect|code= Relax-NG validity error : Extra element devices in interleave {{project_name_gateway_short}}_kvm.xml:24: element devices: Relax-NG validity error : Element domain failed to validate content {{project_name_gateway_short}}_kvm.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! == Addgroup == 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 groups. * Debian (based) / Ubuntu: ** The following command will work in Debian and assumes the simple scenario whereby KVM will be utilized with the current logged in user. For older Ubuntu versions, note that the group names vary and ''libvirt'' may be called ''libvirtd'' instead. For Ubuntu 20.04, ''libvirt'' works. ** {{CodeSelect|inline=true|code= sudo adduser "$(whoami)" libvirt }} ** {{CodeSelect|inline=true|code= sudo adduser "$(whoami)" kvm }} ** By default Debian does not use sudo, so groups can be added with usermod. If your user is foo the following commands will work. {{CodeSelect|code= usermod -a -G libvirt foo }} And. {{CodeSelect|code= usermod -a -G kvm foo }} * Arch Linux: ** {{CodeSelect|inline=true|code= sudo gpasswd -a $USER libvirt }} ** {{CodeSelect|code= sudo gpasswd -a $USER kvm }} * Other Distributions: If another distribution is in use, then first refer to the distribution manual. For example, a necessary reference for Arch users is the [https://wiki.archlinux.org/title/libvirt Arch Linux libvirt wiki page]. == Restart libvirtd == Note: Restarting libvirtd is required after: * KVM is installed. * Users are added to groups. {{CodeSelect|code= sudo systemctl restart libvirtd }} It's possible that a reboot of the computer maybe required instead, on some systems. == Network Start == {{mbox | type = notice | image = [[File:Ambox_notice.png|40px|alt=Info]] | text = These steps have nothing to do with {{project_name_short}}, but are helpful when running other VMs. }} Ensure KVM's / QEMU's default networking is enabled and has started. https://forums.whonix.org/t/kvm-networking-broken/644 https://wiki.debian.org/KVM#Troubleshooting {{CodeSelect|code= sudo virsh -c qemu:///system net-autostart default }} {{CodeSelect|code= sudo virsh -c qemu:///system net-start default }} == Build from Scratch == Advanced users are encouraged to [[Dev/Build_Documentation|build]] {{project_name_short}} images for high security assurance. = Information = 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 {{project_name_short}} project instead of rolling your own Manually converting images from .ova to .qcow2 is no longer recommended, since .qcow images can be downloaded from the {{project_name_short}} project. because they contain important performance optimizations. As per [https://github.com/{{project_name_short}}/derivative-maker/blob/master/build-steps.d/4400_convert-raw-to-qcow2 build-steps.d/4400_convert-raw-to-qcow2] , these are "-o cluster_size=2M" and "-o preallocation=metadata". The only exception is if images were [[Dev/Build_Documentation|created from source]]. Because the same performance optimizations are present. If problems are encountered with free disk space, using a file system that supports [[sparse files]] is recommended. Also refer to the following [https://forums.whonix.org/t/please-reduce-kvm-image-size/160 forum discussion]. If {{project_name_short}} libvirt images already exist, then consider a [[#Cleanup|Cleanup]] first. For simplicity the {{project_name_short}} images should be downloaded and stored in the home folder ({{Code2|/home/}}) so the following commands can be copied/pasted without changes. = Download {{project_name_short}} = {{tos}} {{Tab |type=controller |addToClass=clear-float |content= {{Tab |active=true |title= == GUI == |image=[[File:Clipart-gui.svg|alt=Symbol representing GUI]] |content= {{#widget:Icon_Bullet_List |addClass=minimal margin-bottom-20 |fontSize=17px |item=fa-solid fa-info cs-blue,{{project_name_short}} with Xfce {{Gui}}. |item=fa-solid fa-info cs-blue,This version of {{project_name_short}} is designed to run inside KVM. }} {{#widget:Download_Button |text=Download {{project_name_short}} Xfce for KVM (Free!) |url=https://download.{{project_clearnet}}/libvirt/{{Version_KVM}}/{{project_name_short}}-Xfce-{{Version_KVM}}.Intel_AMD64.qcow2.libvirt.xz |os=kvm }}
Optional: Digital signature verification.
Version: {{VersionNew}} {{always_verify_signatures_reminder}} {{DownloadTableUnified |url=https://download.{{project_clearnet}} |project={{project_name_short}} |flavor=Xfce |flavor_case_sensitive=Xfce |after_slash=libvirt |extension=Intel_AMD64.qcow2.libvirt.xz |version={{Version_KVM}} |appendix= |signing= Verify images using this [[Main/Project_Signing_Key|{{project_name_short}} OpenPGP Signing Key]] {{signing_key_main}} |signify= Verify images using this [[Main/Project_Signing_Key|{{project_name_short}} signify Key]] {{signing_key_main_signify}} }} {{Anchor|Verify the {{project_name_short}} Images}} * [[Verify_the_images_using_Linux|Verify the {{project_name_short}} KVM images]]
}} {{Tab |title= == CLI == |image=[[File:Utilities-terminal.png|alt=Symbol representing CLI|50px]] |content= {{GoogleOff|nosnippet=1|content= {{#widget:Icon_Bullet_List |addClass=minimal |fontSize=17px |item=fa-solid fa-info cs-blue,{{project_name_short}} with {{cli}}. |item=fa-solid fa-info cs-blue,This version of {{project_name_short}} is designed to run inside KVM. |item=fa-solid fa-exclamation-circle cs-red,{{project_name_short}} with CLI is a version suited for advanced users -- those who want {{project_name_short}} without a {{gui}}. }} {{#widget:Download_Button |text=Download {{project_name_short}} CLI for KVM (Free!) |url=https://download.{{project_clearnet}}/libvirt/{{Version_KVM}}/{{project_name_short}}-CLI-{{Version_KVM}}.Intel_AMD64.qcow2.libvirt.xz |os=kvm }}
Optional: Digital signature verification.
Version: {{VersionNew}} {{always_verify_signatures_reminder}} {{DownloadTableUnified |url=https://download.{{project_clearnet}} |project={{project_name_short}} |flavor=Xfce |flavor_case_sensitive=Xfce |after_slash=libvirt |extension=Intel_AMD64.qcow2.libvirt.xz |version={{Version_KVM}} |appendix= |signing= Verify images using this [[Main/Project_Signing_Key|{{project_name_short}} OpenPGP Signing Key]] {{signing_key_main}} |signify= Verify images using this [[Main/Project_Signing_Key|{{project_name_short}} signify Key]] {{signing_key_main_signify}} }} {{Anchor|Verify the {{project_name_short}} Images}} * [[Verify_the_images_using_Linux|Verify the {{project_name_short}} KVM images]]
}} }} }} {{mbox |icon=fa-solid fa-exclamation cs-red |addToClass=cs-yellow-light |text= '''Note:''' Save your download to your usual ~/Downloads folder. }} = Decompress = '''1.''' Change directory. The decompression command below needs to be run from within the folder where you downloaded the archive (most likely in ~/Downloads or ~/ (home) folder). Note: Adjust the folder if you stored the archive elsewhere. {{CodeSelect|code= cd ~/Downloads }} '''2.''' Do not use unxz! Extract the images using gnu tar. '''3.''' Make sure the xz-utils package is installed on your system. https://forums.whonix.org/t/tar-child-xz-cannot-exec-no-such-file-or-directory-install-xz-utils-package/16708/7 If you followed the installation instructions above, this should already be the case. '''4.''' Decompress. {{CodeSelect|code= tar -xvf Whonix*.libvirt.xz }} '''5.''' Wait. Please be aware that the extraction process may take an exceptionally long time to complete. It is recommended to allow the terminal to run uninterrupted after executing the command to ensure successful decompression. '''6.''' Done. = License Agreement = {{License_Read}} = VM Settings Modification = {{Anchor|Optional: XML Modification}} '''Optional.''' Select Before VM Import or After VM Import. {{Tab |type=controller |content= {{Tab |title= === Before VM Import === |active=true |addToClass=info-box |content= This section describes XML modifications before importing a virtual machine. 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_File|filename= {{project_name_gateway_short}}*.xml }} {{Open_File|filename= {{project_name_workstation_short}}*.xml }} }} {{Tab |title= === After VM Import === |active=false |addToClass=info-box |content= For virtual machines that were already imported. Choose either option '''A)''' or '''B)'''. {{Tab |type=controller |content= {{Tab |title= ==== A) With an Editor ==== |active=true |addToClass=info-box |content= '''1.''' Choose your favorite editor. Optional. Eventually configure your favorite editor to make changes. The relevant software of your choice must be already installed, such as kwrite, leafpad, kate, vi, nano, vim and so on. This is done by setting the VISUAL environment variable. {{CodeSelect|code= export VISUAL=kwrite }} '''2.''' Edit. Use the virsh command to open the configuration file. {{Tab |type=controller |content= {{Tab |active=true |title= ===== {{project_name_gateway_short}} ===== |addToClass=info-box |content= {{CodeSelect|code= sudo -E virsh -c qemu:///system edit {{project_name_gateway_short}} }} }} {{Tab |title= ===== {{project_name_workstation_short}} ===== |addToClass=info-box |content= {{CodeSelect|code= sudo -E virsh -c qemu:///system edit {{project_name_workstation_short}} }} }} }} '''3.''' Save. '''4.''' Done. Editing an Imported Machine's XML Configuration has been completed. }} {{Tab |title= ==== B) Using virt-manager ==== |addToClass=info-box |content= In more recent versions of virt-manager, there is a second way available: Virtual Machine Manager -> Edit -> Preferences -> General -> Enable XML Editing Under the Details view for a VM, a new XML tab in the GUI is visible, allowing editing and saving directly from the VM viewer. }} }} }} }} == Importing {{project_name_short}} VM Templates == The first step after extracting the archive is to import the supplied XML files. They serve as a description for [https://wiki.archlinux.org/title/libvirt libvirt] and define the properties of the {{project_name_short}} VMs and the networking they should have. {{Box|text= '''1.''' Add the virtual networks. This step only needs to be done once and not with every upgrade. If the definition of a {{project_name_short}} network fails because the virtual bridge "virbrX" already exists, edit the {{project_name_short}}_external*.xml and {{project_name_short}}_internal*.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"). {{CodeSelect|code= sudo virsh -c qemu:///system net-define {{project_name_short}}_external*.xml }} {{CodeSelect|code= sudo virsh -c qemu:///system net-define {{project_name_short}}_internal*.xml }} '''2.''' Activate the virtual networks. {{CodeSelect|code= sudo virsh -c qemu:///system net-autostart {{project_name_short}}-External }} {{CodeSelect|code= sudo virsh -c qemu:///system net-start {{project_name_short}}-External }} {{CodeSelect|code= sudo virsh -c qemu:///system net-autostart {{project_name_short}}-Internal }} {{CodeSelect|code= sudo virsh -c qemu:///system net-start {{project_name_short}}-Internal }} '''3.''' Import the {{project_name_short}} Gateway and Workstation images. {{CodeSelect|code= sudo virsh -c qemu:///system define {{project_name_gateway_short}}*.xml }} {{CodeSelect|code= sudo virsh -c qemu:///system define {{project_name_workstation_short}}*.xml }} }} == Image File Installation == The XML files are configured to point to the default storage location of /var/lib/libvirt/images. The image files can be moved or copied depending on storage constraints. Notes: * Changing the default location may cause conflicts with SELinux, which will prevent the machines from booting. * Administrative rights (sudo) are required because the copying is to a privileged location in the system. The following steps move or copy the images there so the machines can boot. Either move or copy. {{Tab |type=controller |content= {{Tab |title= === Moving {{project_name_short}} Image Files === |type=section |active=true |content= Move. {{CodeSelect|code= sudo mv {{project_name_gateway_short}}*.qcow2 /var/lib/libvirt/images/{{project_name_gateway_short}}.qcow2 }} {{CodeSelect|code= sudo mv {{project_name_workstation_short}}*.qcow2 /var/lib/libvirt/images/{{project_name_workstation_short}}.qcow2 }} }} {{Tab |title= === Copying {{project_name_short}} Image Files === |content= Copy. {{Anchor|sparse files}} {{project_name_short}} disk images are {{kicksecure_wiki |wikipage=sparse files |text=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. {{CodeSelect|code= sudo cp --sparse=always {{project_name_gateway_short}}*.qcow2 /var/lib/libvirt/images/{{project_name_gateway_short}}.qcow2 }} {{CodeSelect|code= sudo cp --sparse=always {{project_name_workstation_short}}*.qcow2 /var/lib/libvirt/images/{{project_name_workstation_short}}.qcow2 }} }} }} == Manipulating QCOW2 Images == 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 [https://linux.die.net/man/1/qemu-img qemu-img manual]. == Encrypted Containers == 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: https://forums.whonix.org/t/cant-use-var-lib-libvirt-images-for-whonix-images-what-to-do-about-apparmor/7192/3 {{CodeSelect|code= sudo chmod og+xr /run/media/private/user/$container_name }} After this in KVM .xml for both the gateway and the workstation you will need to edit the xml configuration and change the source file tag to: source file="/run/media/private/user/Whonix-Gateway.qcow2". This is so that the VM can actually open and run. == Cleanup == After importing {{project_name_short}}, it is advised to delete the archives ({{Code2|.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 {{project_name_short}} is later downloaded. To delete the archives and temporary folders, run. Note: this may not work on some Linux distributions, those where safe-rm is unavailable. In that case, use trash-put (if trash-cli package is available) or rm (always available) instead. {{CodeSelect|code= safe-rm {{project_name_short}}* }} {{CodeSelect|code= safe-rm -r WHONIX* }} == Start == If Virtual Machine Manager is familiar, there is nothing special about starting {{project_name_short}} VMs compared to starting other VMs. First start {{project_name_gateway_long}}, then start {{project_name_workstation_long}}. === Using Whonix-Gateway with Xfce desktop vs CLI mode === To be able to start desktop environment, Whonix-Gateway virtual machine needs to be given at least 1 GB of RAM. Otherwise you will only be able to boot in CLI mode. To disable startup of the included Desktop Environment regardless of how much RAM is assigned to the VM, configure [[RAM_Adjusted_Desktop_Starter|RAM Adjusted Desktop Starter package settings]]. === Graphical User Interface (GUI) === Start Virtual Machine Manager. Start Menu → Applications → System → Virtual Machine Manager Start {{project_name_gateway_short}}. click on {{project_name_gateway_short}} → click open → click the play symbol Repeat the steps for {{project_name_workstation_short}}. === Command Line Interface (CLI) === The following instructions have been re-tested in September 2024. '''1.''' Open a terminal Inside the VM that should be accessed through CLI. This is required for the setup of the serial console VM settings. '''2.''' Install package. {{Install Package| package=serial-console-enable }} '''3.''' Shut down the VM. '''3.''' Open a terminal on the host. '''4.''' To start {{project_name_gateway_short}}, run. {{CodeSelect|code= sudo virsh start {{project_name_gateway_short}} }} To start {{project_name_workstation_short}}, run. {{CodeSelect|code= sudo virsh start {{project_name_workstation_short}} }} '''5.''' To interact with the {{project_name_workstation_short}} via serial console, run. {{CodeSelect|code= sudo virsh console {{project_name_workstation_short}} }} '''6.''' To exit the console session Press Ctrl + ] (Control and closing square bracket). This will take you back to your host terminal while leaving the VM running. '''7.''' Done. forum discussion: https://forums.whonix.org/t/how-do-i-enter-the-whonix-shell-from-cli/7271 == Adjust Display Resolution == Whisker Menu → display → select resolution https://forums.whonix.org/t/no-auto-resize-with-qxl-driver/7145/3 Alternatively, GUI Console → View → Scale Display → Check: Always + Auto resize VM with window. Every new session, a reboot is needed while the VM's GUI console is open and maximized to activate display resize. == After Installing == {{Post_Install_Advice}} == Uninstall ==
If you want to remove {{project_name_short}} KVM VMs, {{project_name_short}} network and {{project_name_short}} images, click on Expand on the right.
{{Box|text= '''1.''' Power off the VM you want to shut down. The command line can also be used to make sure the VM has been shut down. {{CodeSelect|code= sudo virsh -c qemu:///system destroy {{project_name_gateway_short}} }} {{CodeSelect|code= sudo virsh -c qemu:///system destroy {{project_name_workstation_short}} }} '''2.''' Remove KVM VM settings. {{CodeSelect|code= sudo virsh -c qemu:///system undefine {{project_name_gateway_short}} }} {{CodeSelect|code= sudo virsh -c qemu:///system undefine {{project_name_workstation_short}} }} '''3.''' Shut down KVM Network {{Code2|{{project_name_short}}}}. Warning: {{project_name_short}} 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. {{CodeSelect|code= sudo virsh -c qemu:///system net-destroy {{project_name_short}}-External }} {{CodeSelect|code= sudo virsh -c qemu:///system net-destroy {{project_name_short}}-Internal }} '''4.''' Remove Network {{Code2|{{project_name_short}}}}. Warning: {{project_name_short}} 14 and earlier versions used the network names "external" and "internal". This means the command must be changed accordingly. Try "sudo virsh -c qemu:///system net-list" to list them all. {{CodeSelect|code= sudo virsh -c qemu:///system net-undefine {{project_name_short}}-External }} {{CodeSelect|code= sudo virsh -c qemu:///system net-undefine {{project_name_short}}-Internal }} '''5.''' Delete the images. Note: All data will be lost unless it is first backed up. {{CodeSelect|code= sudo rm /var/lib/libvirt/images/{{project_name_gateway_short}}.qcow2 }} {{CodeSelect|code= sudo rm /var/lib/libvirt/images/{{project_name_workstation_short}}.qcow2 }} }}
= KVM Upgrade Instructions = It is strongly recommended to uninstall older {{project_name_short}} versions and always run the [[Stable Release|stable release]]. Note that {{project_name_short}} supports in-place APT upgrades too. # Move your data out of the VM via shared folders. # Perform the [[#Cleanup|Cleanup]] steps. # [[#Download_and_Extract|Install]] the new images. = Optional = == Fullscreen Mode == * To enter fullscreen mode press on: [[File:enterfullscreenkvm.png|600px]] * To exit fullscreen mode press on: (go with your mouse to the top middle of the screen) [[File:exitfullscreenkvm.png|600px]] == Multiple {{project_name_gateway_short}} == See: [[Multiple_{{project_name_gateway_short}}#KVM|Multiple {{project_name_gateway_short}}]]. == Testing Upcoming Versions == Download the test images from the latest folder listed [https://sourceforge.net/projects/whonix-kvm/files/libvirt/ here]. Apply the [[Multiple_{{project_name_gateway_short}}#KVM|Multiple {{project_name_gateway_short}} KVM steps]] for running {{project_name_short}} versions side by side with some differences: # Rename the test {{project_name_short}} images to something unique, preferably by appending the version number to the name. # Edit the XML templates and change the VM names. # Import the images by following the [[KVM#Importing_{{project_name_short}}_VM_Templates|Importing {{project_name_short}}]] installation steps. Keep in mind the full name of the new images must be used and do not import the Network templates. == Convert Libvirt Templates to QEMU Commands == # First export the VM template as a file: {{CodeSelect|code= sudo virsh dumpxml {{project_name_gateway_short}} > {{project_name_gateway_short}}.xml }} # Convert it to the QEMU command: {{CodeSelect|code= sudo virsh domxml-to-native qemu-argv {{project_name_gateway_short}}.xml > {{project_name_gateway_short}}.args }} # Repeat for the {{project_name_workstation_short}}. Replace {{project_name_gateway_short}} with {{project_name_workstation_short}} in above commands. == Magic SysRq Keys == 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. https://dustymabe.com/2012/04/21/send-magic-sysrq-to-a-kvm-guest-using-virsh/ Example command to shut down {{project_name_short}} Workstation from a host console. The ''O'' at the end of ''KEY_O'' can be substituted with any other [https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html supported letter] listed in the kernel documentation. See also [[SysRq]]. {{CodeSelect|code= sudo virsh send-key Whonix-Workstation KEY_LEFTALT KEY_SYSRQ KEY_O }} == DHCP == Libvirt provides built-in DHCP functionality via a custom install of the minimalist Dnsmasq DNS/DHCP daemon. https://forums.whonix.org/t/safer-dhcp-implementation-resolved/7499/7 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. [https://wiki.libvirt.org/page/Libvirtd_and_dnsmasq 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.
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
DNS is not explicitly enabled for guests unless it is added to a network’s configuration. https://fabianlee.org/2018/10/22/kvm-using-dnsmasq-for-libvirt-dns-resolution/ https://www.cyberciti.biz/faq/linux-kvm-libvirt-dnsmasq-dhcp-static-ip-address-configuration-for-guest-os/ 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. 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.
Trying to edit the Dnsmasq configuration files directly will fail as settings are rewritten and are enforced through Libvirt by design. https://serverfault.com/questions/840163/custom-dnsmasq-or-custom-options-with-libvrt {{Box|text= '''1.''' Edit the network configuration file. {{CodeSelect|code= sudo nano /etc/network/interfaces.d/30_non-qubes-whonix }} '''2.''' Make the following comment changes. Comment out. {{CodeSelect|code= auto eth0 iface eth0 inet static address 10.152.152.11 netmask 255.255.192.0 gateway 10.152.152.10 }} Comment in. {{CodeSelect|code= auto eth0 iface eth0 inet dhcp }} Save the file. '''3.''' Change the internal network setting. {{CodeSelect|code= sudo virsh net-edit Whonix-Internal }}
'''4.''' Restart the internal network. {{CodeSelect|code= sudo virsh net-destroy Whonix-Internal }} {{CodeSelect|code= sudo 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 [https://libvirt.org/formatnetwork.html#elementsAddress host attribute] under the dhcp element. '''7.''' Install a dhcp client on the Workstation and reboot. {{CodeSelect|code= sudo apt install isc-dhcp-client }} }} == Snapshot Migration == 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. https://serverfault.com/questions/434064/correct-way-to-move-kvm-vm/648871#648871 {{Box|text= '''1.''' List snapshot names of the VM. {{CodeSelect|code= sudo virsh snapshot-list --name $dom }} '''2.''' Dump each snapshot you want to back-up. {{CodeSelect|code= sudo virsh snapshot-dumpxml $dom $name > file.xml }} '''3.''' Restore snapshots at the destination. {{CodeSelect|code= sudo virsh snapshot-create --redefine $dom file.xml }} '''4.''' ''Optional:'' Identify which snapshot is the current one. On the source VM, run. {{CodeSelect|code= sudo virsh snapshot-current --name $dom }} On the destination, run. {{CodeSelect|code= sudo virsh snapshot-current $dom $name }} }} == Nested KVM Virtualization == 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. {{CodeSelect|code= sudo cat /sys/module/kvm_intel/parameters/nested }} For AMD systems use kvm_amd instead. {{CodeSelect|code= sudo cat /sys/module/kvm_amd/parameters/nested }} If the result is [N], run the following command and reboot the system. For Intel systems: {{CodeSelect|code= echo 'options kvm_intel nested=1' {{!}} sudo tee -a /etc/modprobe.d/qemu-system-x86.conf }} For AMD systems: {{CodeSelect|code= echo 'options kvm_amd 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 == Some users find it easier to move the sparse image files when they are compressed in a tarball. To re-compress files, run. {{CodeSelect|code= tar -Sczvf whonix.tar.gz }} == Adding vCPUs == 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 == Having video issues? See [[KVM#Videos|Videos]] instead. Enabling 3D acceleration is discouraged because it increases the attack surface. This is a general KVM issue and is [[unspecific|not specific to {{project_name_short}}]]. (Advanced users, see: [[Dev/KVM#Virgl3D|Dev/KVM#Virgl3D]]) '''1.''' Ensure that your host GPU drivers are installed and functional. If your host lacks a dedicated GPU and relies on software rendering (CPU), you should install libgl1-mesa-dri and mesa-utils on the host (if it’s Debian-based) to verify OpenGL functionality and enable software-based OpenGL rendering. {{CodeSelect|code= sudo apt install libgl1-mesa-dri mesa-utils }} '''2.''' Modify the VM settings before or after installation, as required: * [[KVM#VM_Settings_Modification|Before Installation]]. * After Installation: {{CodeSelect|code= sudo virsh edit Whonix-Workstation }} '''3.''' Locate the following section and apply the necessary changes: * {{CodeSelect|inline=true|code= }}: SPICE doesn't support TLS + OpenGL with remote connections, so it must be enabled locally. * {{CodeSelect|inline=true|code= }}: Enable OpenGL. * {{CodeSelect|inline=true|code= }}: Enable 3D acceleration. Here is a full example of the relevant sections.
'''4.''' Restart your VMs if they are running. '''5.''' Notes: * '''Spice Listen Type:''' Setting {{CodeSelect|inline=true|code= }} [https://forums.whonix.org/t/how-to-enable-3d-acceleration/16501/4 can also be used]. '''6.''' Done. == 3D Graphics Acceleration - Testing == === 3D Graphics Acceleration - Testing - drm === source: [https://wiki.archlinux.org/title/QEMU#virtio ArchLinux wiki QEMU, chapter virtio] {{CodeSelect|code= sudo dmesg {{!}} grep -i drm }} 
[drm] pci: virtio-vga detected
[drm] virgl 3d acceleration enabled
Note: DRM is referring to [https://en.wikipedia.org/wiki/Direct_Rendering_Manager Direct Rendering Manager]. Unrelated to [https://www.defectivebydesign.org/ Digital Restrictions Management] {{Anchor|3D Graphics Acceleration - Testing - Performance}} === 3D Graphics Acceleration - Functionality Test === {{Install Package|package= mesa-utils }} Run: {{CodeSelect|code= glxinfo {{!}} grep rendering }} The output should be https://wiki.debian.org/Mesa#A3D_acceleration: direct rendering: Yes == 3D Graphics Acceleration - Troubleshooting == The errors below are common when dealing with 3D acceleration, especially in environments with older hardware or improper configurations. Use these error outputs as references when troubleshooting. What if OpenGL is not found or installed on the host, especially when there is no dedicated graphics card (GPU)? 
Error starting domain: internal error: QEMU unexpectedly closed the monitor (vm='Whonix-Workstation'): 2024-09-04T04:29:19.732050Z qemu-system-x86_64: -device {"driver":"virtio-vga-gl","id":"video0","max_outputs":1,"bus":"pcie.0","addr":"0x1"}: opengl is not available

Traceback (most recent call last):
  File "/usr/share/virt-manager/virtManager/asyncjob.py", line 72, in cb_wrapper
    callback(asyncjob, *args, **kwargs)
  File "/usr/share/virt-manager/virtManager/asyncjob.py", line 108, in tmpcb
    callback(*args, **kwargs)
  File "/usr/share/virt-manager/virtManager/object/libvirtobject.py", line 57, in newfn
    ret = fn(self, *args, **kwargs)
          ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/share/virt-manager/virtManager/object/domain.py", line 1402, in startup
    self._backend.create()
  File "/usr/lib/python3/dist-packages/libvirt.py", line 1379, in create
    raise libvirtError('virDomainCreate() failed')
libvirt.libvirtError: internal error: QEMU unexpectedly closed the monitor (vm='Whonix-Workstation'): 2024-09-04T04:29:19.732050Z qemu-system-x86_64: -device {"driver":"virtio-vga-gl","id":"video0","max_outputs":1,"bus":"pcie.0","addr":"0x1"}: opengl is not available
What if the host lacks a dedicated GPU and uses an outdated CPU? 
Error starting domain: internal error: QEMU unexpectedly closed the monitor (vm='Whonix-Workstation'): qemu_gl_create_compile_shader: compile vertex error
0:1(10): error: GLSL ES 3.00 is not supported. Supported versions are: 1.10, 1.20, and 1.00 ES

qemu_gl_create_compile_shader: compile fragment error
0:1(10): error: GLSL ES 3.00 is not supported. Supported versions are: 1.10, 1.20, and 1.00 ES

qemu_gl_create_compile_shader: compile vertex error
0:1(10): error: GLSL ES 3.00 is not supported. Supported versions are: 1.10, 1.20, and 1.00 ES

qemu_gl_create_compile_shader: compile fragment error
0:1(10): error: GLSL ES 3.00 is not supported. Supported versions are: 1.10, 1.20, and 1.00 ES

Traceback (most recent call last):
  File "/usr/share/virt-manager/virtManager/asyncjob.py", line 72, in cb_wrapper
    callback(asyncjob, *args, **kwargs)
  File "/usr/share/virt-manager/virtManager/asyncjob.py", line 108, in tmpcb
    callback(*args, **kwargs)
  File "/usr/share/virt-manager/virtManager/object/libvirtobject.py", line 57, in newfn
    ret = fn(self, *args, **kwargs)
          ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/share/virt-manager/virtManager/object/domain.py", line 1402, in startup
    self._backend.create()
  File "/usr/lib/python3/dist-packages/libvirt.py", line 1379, in create
    raise libvirtError('virDomainCreate() failed')
libvirt.libvirtError: internal error: QEMU unexpectedly closed the monitor (vm='Whonix-Workstation'): qemu_gl_create_compile_shader: compile vertex error
0:1(10): error: GLSL ES 3.00 is not supported. Supported versions are: 1.10, 1.20, and 1.00 ES

qemu_gl_create_compile_shader: compile fragment error
0:1(10): error: GLSL ES 3.00 is not supported. Supported versions are: 1.10, 1.20, and 1.00 ES

qemu_gl_create_compile_shader: compile vertex error
0:1(10): error: GLSL ES 3.00 is not supported. Supported versions are: 1.10, 1.20, and 1.00 ES

qemu_gl_create_compile_shader: compile fragment error
0:1(10): error: GLSL ES 3.00 is not supported. Supported versions are: 1.10, 1.20, and 1.00 ES
What if TLS is enabled for remote SPICE along with 3D acceleration/OpenGL? 
Error starting domain: internal error: process exited while connecting to monitor: 2024-09-04T04:34:37.668627Z qemu-system-x86_64: SPICE GL support is local-only for now and incompatible with -spice port/tls-port

Traceback (most recent call last):
  File "/usr/share/virt-manager/virtManager/asyncjob.py", line 72, in cb_wrapper
    callback(asyncjob, *args, **kwargs)
  File "/usr/share/virt-manager/virtManager/asyncjob.py", line 108, in tmpcb
    callback(*args, **kwargs)
  File "/usr/share/virt-manager/virtManager/object/libvirtobject.py", line 57, in newfn
    ret = fn(self, *args, **kwargs)
          ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/share/virt-manager/virtManager/object/domain.py", line 1402, in startup
    self._backend.create()
  File "/usr/lib/python3/dist-packages/libvirt.py", line 1379, in create
    raise libvirtError('virDomainCreate() failed')
libvirt.libvirtError: internal error: process exited while connecting to monitor: 2024-09-04T04:34:37.668627Z qemu-system-x86_64: SPICE GL support is local-only for now and incompatible with -spice port/tls-port
== Mouse Smoothness == For smoother mouse movement. [[Untested]]. As per [https://libvirt.org/formatdomain.html#input-devices Domain XML format, Input devices]. '''1.''' [[KVM#VM_Settings_Modification|VM Settings Modification]] required. '''2.''' Look for {{CodeSelect|inline=true|code= }}. '''3.''' Below it, append the following. {{CodeSelect|code= }} forum discussion: https://forums.whonix.org/t/p-s2-mouse-movement-in-cutom-debian-workstation/19985 == Shared Folders == {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = '''Warning:''' Deleting files within the shared folder will move them to a hidden sub-directory called .Trash-1000. Make sure you reveal it and promptly delete it on the host to avoid data leakage across different VM sessions. }} 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. {{Box|text= '''1.''' On the host run the following command in a terminal (Start Menu → Applications → System → Terminal). Replace user name user with your actual user name. {{CodeSelect|code= mkdir /home/user/shared }} '''2.''' Adjust permissions on the host to allow read and write access to the folder with chmod. Replace user name user with your actual user name. {{CodeSelect|code= chmod 777 /home/user/shared }} '''3.''' Enable shared folders in VirtManager. VirtManager → Select VM → Edit → Virtual Machine Details → Details → Add Hardware → File System '''4.''' Choose the following settings. Replace user name user with your actual user name. * Mode: Mapped The file sharing mode {{Code2|mapped}} is just an example, using squash or passthrough is possible by selecting them from the drop down menu. Mapped is recommended for security. * Driver: Default * Source Path: /home/user/shared * Target Path: shared '''5.''' Click finish. '''6.''' Done. {{project_name_workstation_short}} should automatically find and mount the shared folder under /mnt/shared once it's created on the host and enabled in VirtManager. }} === Mandatory Access Control === 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. Replace user name user with your actual user name. {{CodeSelect|code= sudo chmod 777 -R /home/user/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. https://nts.strzibny.name/how-to-set-up-shared-folders-in-virt-manager/ https://unix.stackexchange.com/questions/60799/selinux-interfering-with-host-guest-file-sharing-using-kvm {{CodeSelect|code= sudo semanage fcontext -a -t svirt_image_t "/home/user/shared(/.*)?" }} {{CodeSelect|code= restorecon -vR /home/user/shared }} Setting execute permission on the user folder itself may be necessary for the guest to start up without a permission error. {{CodeSelect|code= sudo chmod 701 /home/user }} Or, more safely, you can set it just for virt-manager. The name libvirt-qemu can be different on your distribution. {{CodeSelect|code= sudo setfacl -m u:libvirt-qemu:x /home/user }} 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.
== USB Passthrough == {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = '''Warning:''' Only connect USB devices to {{project_name_workstation_short}} 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. }} {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = '''Warning:''' This isolation method is not fool-proof for sandboxing untrusted USB devices, 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. }} Libvirt supports passing through a computer's integrated webcam or any other USB devices. https://bugzilla.redhat.com/show_bug.cgi?id=1135488 https://askubuntu.com/questions/564708/qemu-kvm-virt-manager-passthrough-of-usb-webcam-to-windows-7-enterprise-creates Debian contributors have disabled USB auto-redirection by default to prevent the accidental passthrough of trusted USB devices to untrusted guests, https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=765016 https://salsa.debian.org/libvirt-team/virt-manager/-/commit/d81fd3c3af1abde1fa0e2bf3b79643f36836f45b so they must be reverted temporarily. Once finished, change them back to safe defaults by going through the steps in reverse order. '''Limitations:''' 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 {{project_name_workstation_short}} 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. {{Box|text= '''1.''' Edit the libvirt glib-2.0 schema. {{CodeSelect|code= 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. https://docs.gtk.org/gio/ {{CodeSelect|code= sudo glib-compile-schemas /usr/share/glib-2.0/schemas/ }} '''4.''' Close all instances of Libvirt/Virtual Machine Manager and restart them so the new settings apply. '''5.''' {{Box|text= '''1.''' In the ''Details'' pane change the ''Controller USB'' device model. Hypervisor Default → USB 2 '''2.''' While {{project_name_workstation_short}} is turned off, add four USB Redirection devices or as many as the number of USB ports the machine has to cover them all. {{project_name_workstation_short}} viewer window → View → Details → Add Hardware → USB Redirection '''3.''' Start {{project_name_workstation_short}} and select the device connected to the host that you want to passthrough. {{project_name_workstation_short}} viewer window → File → Redirect USB → Choose: 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. }} '''6.''' Boot {{project_name_workstation_short}} and connect the USB thumbdrive. The thumbdrive should be automatically seen in the guest only. }} == Enable Microphone Input == [[Hardware_Threat_Minimization#Microphones|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 -> . == Creating Multiple Internal Networks == Open the {{project_name_short}} 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 == 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 == In the hypothetical situation whereby a user is "trapped" in a [[Desktop#Virtual_Consoles|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 == 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. {{Box|text= '''1.''' Open the XML configuration. {{CodeSelect|code= sudo 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.
To.
It is also necessary to add this setting.
Under the 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: https://gymnasmata.wordpress.com/2010/12/02/setting-up-gdb-to-work-with-qemu-kvm-via-libvirt/ }} == Unsafe Features == The features below have serious security implications and should not be used. This applies to all hypervisors in general. === LVM Storage === 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. 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 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. https://github.com/fog/fog/issues/2525 https://news.ycombinator.com/item?id=6983097 This setting is disabled in cloud tenancy environments. === HugePages === THP/Hugepages aid rowhammer attacks https://arxiv.org/pdf/1507.06955v1.pdf 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 === Memory ballooning can potentially be abused by malicious guests to mount rowhammer attacks on the host. https://www.whonix.org/pipermail/whonix-devel/2016-September/000746.html === Clipboard Sharing === 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 {{project_name_short}} Workstation from pilfering sensitive info from the clipboard. If you still want to enable it, edit the VM config file and then change to 'yes', then save and restart. === KSM === 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. [https://www.ieee-security.org/TC/SP2016/papers/0824a987.pdf Dedup Est Machina: Memory Deduplication as an Advanced Exploitation Vector] It is capable of inferring what programs/pages are being visited outside the VM. https://web.archive.org/web/20130210040731/https://staff.aist.go.jp/c.artho/papers/EuroSec2011-suzaki.pdf This feature is disabled in cloud tenancy environments and can also allow attackers to modify/steal APT keys and source lists of the host. [https://www.usenix.org/system/files/conference/usenixsecurity16/sec16_paper_razavi.pdf Flip Feng Shui: Hammering a Needle in the Software Stack] https://archive.ph/aB7Kg === File-system Dedupe === Similar to KSM memory dedupe, filesystem dedupe introduces data leaks that violate hypervisor boundaries. The presence of certain files can be confirmed. These may develop into more advanced attacks on security in the future just like KSM related attacks have. ZFS and Btrfs have dedupe features but they are not enabled by default and should be avoided for high security environments. https://mjg59.dreamwidth.org/55638.html === Device Passthrough === Both USB and PCI device passthrough permit advanced attackers to flash the firmware of those devices and infect the host or other VMs. https://docs.openstack.org/security-guide/compute/hardening-the-virtualization-layers.html#physical-hardware-pci-passthrough == XML Settings == For more information on settings, please refer to the [https://libvirt.org/formatdomain.html Libvirt manual]. = Troubleshooting = == Videos == Enabling [[KVM#3D_Graphics_Acceleration|3D Graphics Acceleration]] might not be required for watching ([[YouTube]]) videos. By [[KVM#Adding_vCPUs|Adding vCPUs]] VM can plays videos without having to resort to 3D acceleration. https://forums.whonix.org/t/desktop-renders-slowly-despite-high-resource-spec/19727/18 == Request operation not valid: blkio device weight is valid only for bfq or cfq scheduler == 
Error starting domain: Request operation not valid: blkio device weight is valid only for bfq or cfq scheduler
As of March 2019, it has been reported that the blkio throttling feature appears to be missing/unsupported on some Linux distributions. Among them is the latest Arch version. This causes a failure during VM start up. 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 The VM also fails to start up on Ubuntu 20.04 with a "blkio" error. The current work around is to remove the feature for now. {{Box|text= '''1.''' Edit the configuration file. {{CodeSelect|code= sudo virsh edit {{project_name_gateway_short}} }} '''2.''' Strip out the following setting. 
 
    250
'''3.''' Save and repeat steps 1-2 for {{project_name_workstation_short}}. '''4.''' Start the VMs. }} * The pvspinlock feature is reported to not be supported and the issue was resolved when edited out of the VM config. forum discussion: [https://forums.whonix.org/t/issues-starting-vms-in-kvm-blkio-device-weight-is-valid-only-for-bfq-or-cfq-scheduler/10160 Issues starting VM's in KVM. - blkio device weight is valid only for bfq or cfq scheduler] == Arch/Ubuntu Users == See [[KVM#Request_operation_not_valid:_blkio_device_weight_is_valid_only_for_bfq_or_cfq_scheduler|Request operation not valid: blkio device weight is valid only for bfq or cfq scheduler]]. == Reboot? == * 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 == 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 [[KVM#Addgroup|added groups]] and [[KVM#Reboot|rebooted]]. == Unable to open a connection to the libvirt management daemon == 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. {{CodeSelect|code= 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 == If this error appears you might be a member of the {{Code|libvirt}} group, but lack membership of the {{Code|kvm}} group. In this case, it helps to change.
To.
== process exited while connecting to monitor: ioctl(KVM_CREATE_VM) failed == 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. == error: unsupported configuration: spice graphics are not supported with this QEMU == https://forums.whonix.org/t/error-s-when-importing-vm-templates-kvm/19464 == Permissions == {{CodeSelect|code= ls -la /var/run/libvirt/libvirt-sock }} == VT-x / SVM Errors == '''*invalid argument: could not find capabilities for domaintype=kvm''' '''*invalid argument: could not get preferred machine for /usr/bin/qemu-system-x86_64 type=kvm''' These errors arise when the host's hardware virtualization extension is not available for KVM to use. The reasons are either/and/or: * '''A)''' it is controlled by another hypervisor running on the system, * '''B)''' an anti-virus suite or * '''C)''' it is not present/enabled by the machine BIOS. To check, go to your BIOS settings. For basic instructions, see: [https://www.wikihow.com/Change-Computer-BIOS-Settings How to Change Computer BIOS Settings]. Then enable VT-x. This is sometimes also called AMD-V, virtualization, SVM mode or MIT perhaps under Advanced Core settings. == VT-x vs VT-d == * VT-x / AMD-V: Is required, see above chapter. * VT-d / IOMMU / AMD-Vi: [https://forums.whonix.org/t/help-welcome-kvm-development-staying-the-course/166/485 {{project_name_short}} KVM does not require VT-d.] == Add Version Numbers to Support Request == 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. {{CodeSelect|code= dpkg-query --show --showformat='${Package} ${Version} \n' libvirt-bin qemu-kvm virt-manager }} == Check Groups == Check the output of following command. {{CodeSelect|code= whoami }} The output of the previous command is expected to be something like user or your linux user account name. Should not be root. {{CodeSelect|code= groups }} The output of the previous command is expected to include the groups libvirt and kvm. For example, if one was to use su or sudo su (i.e. doing it as root) before running sudo addgroup "$(whoami)" libvirt and sudo addgroup "$(whoami)" kvm that would not work. That is because when executing commands under user root, $(whoami) will output root, not user. Hence not add the user to the required groups. If that is not the case, make sure you [[KVM#Addgroup|added groups]] and [[KVM#Reboot|rebooted]]. == Sound == No audio inside VM? Try unmute and increase volume. https://forums.whonix.org/t/no-audio-in-whonix-kvm/17642 == Support == {{project_name_short}} KVM maintainer availability is mostly limited to [[#User Help Forum|User Help Forum]]. Questions on telegram, matrix, IRC, reddit, incomplete list will most likely not get attention by {{project_name_short}} KVM maintainer. See also [[Support]]. == User Help Forum == [https://forums.whonix.org/c/kvm {{project_name_short}} KVM User Help Forum] == Alternative Guides == For alternative installation guides contributed by community members, see: [[KVM/Minimalized_Installation|Minimalized Installation]]. = Known Issues = == Host VPNs == * [https://forums.whonix.org/t/no-internet-connection-on-workstation-when-vpn-on-host/13763 No Internet Connection inside Whonix-Workstation KVM with NordVPN with Kill-Switch on Host] * [https://forums.whonix.org/t/failure-to-connect-when-vpn-on-host/3133 Failure to connect when VPN on host] Potential solution: -> [[#Development Help Wanted]] * https://forums.whonix.org/t/help-welcome-kvm-development-staying-the-course/166/546 * [https://lists.libvirt.org/archives/list/users@lists.libvirt.org/thread/UUMUA4X3YWTOTQYSXTMOWDZDKXZYGS7U/ KVM static internal networking without host bridge interface (virbr)] * QEMU/KVM feature request: [https://gitlab.com/qemu-project/qemu/-/issues/2494 Isolated network between VMs not visible to the host] == Intel 3rd Gen CPUs == Performance is markedly degraded on 3rd generation Intel CPUs as reported by a user on the forums and confirmed and therefore should be avoided. https://forums.whonix.org/t/poor-performance/13385/6 = Development = * [[Dev/KVM|KVM Development]] * [https://phabricator.whonix.org/tag/kvm/ KVM {{project_name_short}} Bug Tracker] * [https://github.com/{{project_name_short}}/whonix-libvirt whonix-libvirt github] = Development Help Wanted = * [https://forums.whonix.org/t/help-welcome-kvm-development-staying-the-course/166/546 Using hubport to avoid KVM network interfaces being visible on the host operating system] which would probably fix some [[Dev/VirtualBox#Why_use_VirtualBox_over_KVM.3F|{{project_name_short}} KVM issues with host operating system firewalls and VPNs]] = Footnotes = {{#widget:Expand or Collapse All}} {{reflist|close=1}} {{Footer}} [[Category:Documentation]]