Kvmrun

Kvmrun is a suite of tools that provides a command line and gRPC interface for creating and managing virtual machines based on QEMU-KVM.

Features

create, edit, start and stop VMs via CLI and gRPC
attach/detach one or more block/network devices without restarting VMs (hot-plug/unplug)
live migration with/without local storage or with a specified list of block devices
full and incremental block backups
access to the guest virtual console (hvc0)
run with external kernel/initrd and iso-file with modules (linux specific)
limit CPU resources via cgroups
limit IO operations via QEMU
configure network using custom ifup/ifdown scripts

Concept & idea

Kvmrun uses Systemd to run virtual machines. Each QEMU process runs in its own personal chroot environment as an unprivileged user. Systemd is responsible for starting and for properly completion of virtual machines by invoking appropriate kvmrun's utils (start/stop/cleanup).

The primary goal of Kvmrun is to simplify as much as possible the most popular actions such as hot-plug/unplug devices, hot reconfiguration, full or incremental block backup and live migration between the same type hosts. These are the most required things for hosting providers to organize cloud services.

gRPC interface

Kvmrun provides API based on gRPC services. All exposed functions are defined in .proto files under api directory.

Communication with the API server is possible using two interfaces -- secure TCP port 9393 or unsecure abstract UNIX socket @/run/kvmrund.sock.

Supported configurations

Kvmrun can work with all versions of QEMU starting from 3.1.x. Below are the tested configurations:

Debian 10 and QEMU 3.x/5.x
Debian 11 and QEMU 5.x/6.x
Ubuntu 20.04 LTS and QEMU 4.x
Ubuntu 22.04 LTS and QEMU 6.x

Installation

Currently there are packages only for Debian/Ubuntu based distributions. Otherwise build from source should be used.

From pre-built package

Install the repository using this script autogenerated by packagecloud.io.

$ curl -s https://packagecloud.io/install/repositories/0xef53/kvmrun/script.deb.sh | sudo bash

And then install the package:

$ sudo apt-get install kvmrun

From source

Install pre-requisite packages:

$ sudo apt-get install make git

Install docker-ce package using the official guide:

Clone the repository and start building the binaries:

$ git clone https://github.com/0xef53/kvmrun.git
$ cd kvmrun
$ make && make install

Generate the certificates and run the server:

$ /usr/lib/kvmrun/gencert
$ systemctl enable kvmrund.service
$ systemctl start kvmrund.service

Quick start

The following steps illustrate how to run a virtual machine with a Debian as a guest.

Install Kvmrun using instructions from the previous step. Don't forget to install QEMU in case Kvmrun was built from source.
Create a bootable image with a guest OS using scripts/mk-debian-image. This script uses the appropriate docker image as a basis. In this case -- debian:bullseye-slim. See here for more information.
```
$ /usr/share/kvmrun/mk-debian-image -t bullseye-slim
```

Wrap the resulting image file in a loop device:

$ losetup -f --show debian-bullseye-slim.img
/dev/loop0

Create your first virtual machine:

$ vmm create-conf --mem 2048 --cpu 2-4 alice
$ vmm storage attach alice /dev/loop0

Run it:
```
$ vmm start alice
```

A list of all configured virtual machines can be seen as follows:

$ vmm list
Name                 PID      Mem(MiB)     CPUs     %CPU       State         Time
alice              32531     2048/2048      2/4      ---     running          34s

Then you can activate the VNC to communicate with the running virtual machine:

$ vmm vnc activate alice
Password: ofKajev5
Display/Port: 1024/6924
Websocket port: 11724

The VNC server will listen on 127.0.0.2. It's convenient to use SSH to forward the connection to the host server with VNC. Something like this:

$ ssh -L 127.0.0.1:6925:127.0.0.2:6925 <HOST-SERVER-ADDR>

After that you can connect to the VNC server:

$ gvncviewer localhost:1025

License

This project is under the MIT License. See the LICENSE file for the full license text.