kvmrun

README

Kvmrun

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

Features

• create, edit, start and stop VMs via CLI
• 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
• 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 via custom ifup/ifdown scripts

Concept & idea

Kvmrun interacts very closely with the runit supervisor. Each virtual machine is formed as a separate service. Runit is responsible for starting and for correct completion of virtual machine by sending the approriate ACPI signal to the guest system kernel.

Kvmrun runs each virtual machine in a separate chroot environment on behalf of an unprivileged user.

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

Future plans

• qcow2 images support
• incremental backup of block devices

Installation

Only Debian/Ubuntu distributions are currently supported.

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

Quick start

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

1. Install package using instructions from the prevoious step. QEMU-KVM and Runit will be installed by dependency.

2. 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:stretch-slim. See here for more information.

   $ mk-debian-image -t stretch-slim
   

3. Wrap the resulting image file in a loop device:

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

4. Create your first virtual machine:

   $ kvmhelper create-conf --mem 2048 --cpu 2-4 alice
   $ kvmhelper attach-disk alice /dev/loop0
   

5. Run it:

   $ sv u alice
   

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

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

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

$ kvmhelper set-vncpass alice 
Password: ecb8cffac56426bf57a70cb9abbbbd16
Display/Port: 1025/6925
Websocket port: 11725

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.