Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



KVM (for Kernel-based Virtual Machine) is a full virtualization solution for Linux on x86 or x86_64 (AKA amd64) hardware containing virtualization extensions (Intel VT or AMD-V). It consists of a loadable kernel module, kvm.ko, that provides the core virtualization infrastructure and a processor specific module, kvm-intel.ko or kvm-amd.ko which together provide for all that is needed to get virtualized CPU support.

KVM also requires a modified QEMU to provide for the remaining virtualized hardware (a virtual machine) including network, disk, and video adapters as well as block devices like hard drives, cdrom or floppies.

Be aware that not all Intel or AMD CPUs have virtualization extensions and some might need to have also a BIOS setting enabled in order to be able to use it. Refer to the KVM FAQ for more information.

Also be aware that KVM supports virtualization features in other CPUs like PowerPC, IA64 and s390 but there is no support to them in this ebuild yet which is mainly focused into "Intel Compatible" processors.


After the release of Gentoo 2008.0 (around Jul 10, 2008) KVM was added to the portage tree and is now officially part of Gentoo and no longer waiting for a maintainer.

That means that you can just emerge it like you would do with any other Gentoo package and any problems found should be reported through bugzilla.

Until a version is stabilized, you will need to unmask it as described below if you are using "stable" or move to "unstable" and help stabilizing it.

If you were using the sajinet overlay that used to be referenced here this is probably a good time to remove it to avoid conflicts, but if you are feeling nostalgic you can always browse its now obsoleted packages/patches list by going to :

Configuring your USE flags

The ebuild has several configurable options that can be used to adjust it to your environment better. For more information about how to set the USE flags refer to HOWTO Use Portage Correctly, but to configure the recommended defaults in a non invasive way execute as root :

Code: Adding the recommended USE flags to portage for this package
 # echo "app-emulation/kvm ncurses sdl" >> /etc/portage/package.use


Adds support for media-libs/alsa-lib (Advanced Linux Sound Architecture).

This used to be enabled by default for "<app-emulation/kvm-47" but was turned off because the same functionality is available by using alsa through SDL instead.


Adds support for media-sound/esound (The Enlightened Sound Daemon).


Adds support for net-libs/gnutls.

Since >=app-emulation/kvm-45, the VNC server option available from the userspace application with the -vnc option is able to use TLS to encrypt the session established with the vnc client, this flag enables support for that functionality. If disabled vnc sessions are still possible but only using unencrypted channels.


Tells ebuild to skip all checks for the kernel version or configuration.

If enabled, it could be used to provide your own kernel module through a yet non existent package or to use modules you compiled and installed by hand; if disabled will use whatever kernel module comes with your kernel.

the kernel module is included with linux since version 2.6.20, but the first 2 versions of it up to kernel 2.6.21 didn't have an stable ABI and are therefore tied to specific versions of the kvm package as shown in :

the kernel module included with kernel 2.6.22 (kvm api version 12) or newer will be able to talk to recent versions of the userspace application but not be able to use all the provided functionality.

most recent kernels include newer versions of the kvm module, including some that have support for "preempt notifiers" which will improve the performance of your guests and that can't be enabled if using an external module.

depending on your environment needs and the features you are interested, you could use this flag to trade functionality for performance, but it is important to stress that you are not using the kvm kernel module from this package and so the version of the kvm module you are using will be different than the version of this package and that any kernel related issues should be instead filed as bugs for the kernel.


for >=app-emulation/kvm-73 support to build and install the kernel module from this package was re-added (similar to old USE="kvm").

if enabled you will be able to use the version of the external module included with this package and that could include more features than the one from your kernel and that contains a patch to support Solaris 10 guests.

since the modules are installed in a "kvm" subdirectory from your kernel modules you'll need to select individually the two that are required by your hardware and load them manually by using insmod as shown by :

Code: Installing module in an Intel based system
 # cd /lib/modules/`uname -r`/kvm
 # insmod kvm.ko
 # insmod kvm-intel.ko


for >=app-emulation/kvm-63 support was added to create a curses console as an option to using SDL and an X server.

If enabled (recommended), will allow you to create an interactive text console in the same terminal were kvm is running if kvm was called with the -curses flag.


Adds support for Simple Direct Layer (media library)

If enabled (recommended), will use SDL to emulate a console, so you can interact with your virtual machine through an X session.

If you don't need to have anything but a text console (ideal if running virtual machines through ssh), use the ncurses USE flag instead as an alternative.

If you are only interested on using kvm to run "headless" virtual machines then be sure to start them with either an emulated serial console going into a file (or /dev/null) or a vnc server console and disable this flag.


If you are planning to use KVM with WinXP or other "graphical" installation, you should enable sdl flag, or you'll get no output.


Code: Using emerge to install the package and its dependencies
 # emerge -Dvu kvm

Getting Started

Loading the kernel modules

If you have kernel support compiled into your kernel then you are ready to go, but if you are using kernel modules instead you are going to need to load them first.

There are 2 modules to load and 3 to choose from. You will need the generic one that enables KVM support (kvm.ko) and a CPU specific one (kvm-intel.ko or kvm-amd.ko) that depends on the generic one and that should match the type of CPU that you have.

You can use modprobe to resolve dependencies and load the module for you

Code: Using modprobe to load the module for a Core2 system
 # modprobe kvm-intel

Adding access to /dev/kvm to your user

The /dev/kvm device is owned by root but with read/write priviledges for the kvm group, so in order to be able to access it you have to add your user to it (using a user named "carenas" below as an example)

Code: Adding the "carenas" user to the kvm group
 # gpasswd -a carenas kvm

Create a virtual disk image

Code: Using kvm-img to create a RAW 10G disk image
 # kvm-img create gentoo-i386.img 10G

Installing the guest OS to your image

Gentoo example

Code: Installing gentoo into the disk image using an livecd ISO
 # kvm -hda gentoo-i386.img -cdrom livecd-i686-installer-2007.0.iso -boot d

Windows example

This is how i started my Windows installation using the kvm python script which is not distributed with the last versions of the package. I still have to fix my tap/tunnel support so i use --no-tap for now. (which means no networking!)

Code: Installing windows into the disk image using an real Windows CD-ROM
 # kvm --no-tap windows.img --install --cdrom /dev/cdrom


Because of ACPI problems you need to press F5 while starting the installer for the first time. Here you should choose "Standard PC", as showing in the screenshot.

Read for more info.


Booting your system

Code: Booting your virtual machine
 # kvm gentoo-i386.img


My x86 Gentoo Guest dies with a kernel panic

KVM doesn't emulate the MMR registers needed for performance metrics and therefore it will generate a General Protection Fault if they were used. A workaround was added to the Linux kernel and therefore upgrading the kernel in your guest will fix this problem. If you can't upgrade your kernel try using the "nolapic" or "nmi_watchdog=0" boot parameters instead.

But I can't boot my guest anymore

KVM images are also compatible with qemu so you could use qemu + kqemu instead to try to fix any problems with the guest that affected kvm, if that doesn't work try using kvm -no-kvm or qemu -no-kqemu as a last resort.

Certain keys (arrow key, for example) don't work in the guest os

If you are using evdev as a driver for the host's xorg.conf, or possibly in other cases, a different set of keycodes than standard are sent to programs. By default, qemu doesn't interpret these correctly. Add "-k en-us" to the end of your kvm commandline. Details:

My VM runs really slow

The default memory allocation of KVM is 128Mb of RAM which can be a little tight for more heavyweight setups. If you have RAM to spare it will really boost performance.

External References

Retrieved from ""

Last modified: Sun, 14 Sep 2008 03:11:00 +0000 Hits: 23,710