Install Kvmapp

Kvmapp is designed to be simple to setup and use. The only dependencies are Qemu packages and some network tools which the installer sets up automatically on supported distributions. Currently supported distributions are listed below.

  • Ubuntu Xenial
  • Ubuntu Bionic
  • Debian Jessie
  • Debian Stretch
  • Centos 7
  • Alpine Linux 3.8+

Download the installer from the downloads page and extract it.

tar -xpzf kvmapp-0.1.tar.gz

cd into the kvmapp folder and run install.sh as the user who will be running VMs. Kvmapp runs VM as the user you install as. You do not need to be root to install and the installer will request sudo privileges to install dependencies and setup configuration. On Alpine Linux please ensure bash is installed before running the installer.

./install.sh

This will automatically detect the OS and install Kvmapp and required packages.

Once installed you can run the help command to get a summary of available commands

kvmapp help

Running a subcommand provides usage information for the command

kvmapp addvm

Basics

You can create and start a VM by supplying 3 arguments with the addvm command. There are 2 ways to create a VM, using a prexisting VM image or using an ISO.

Most cloud providers provide VM images. Kvmapp also has a VM image hub which provides ready to use VM images of various OSs.

Once you have a VM image file you can proceed to creating a VM

Creating VMs with VM images

kvmapp addvm [name] [vm image file] [bridge]

Here name is the user specififed name of the VM, the vm image file is the location of the vm image and bridge is the network bridge to use for the VM.

On install Kvmapp creates a default network bridge for use with VMs. This bridge is called fx0.

kvmapp addvm xenial-test /var/lib/vimages/xenial-test.img fx0

This will create a new VM called xenial-test with the specified xenial-test.img file as the disk image and connect the VM to the fx0 network bridge.

This takes seconds. Once a VM is created you can start it with the start command

kvmapp start xenial-test

You can view the status and get more information of all running VMs with the ps command.

kvmapp ps

You can also use the ls command to get details on all VMs on the host.

kvmapp ls

This will list all VMs on the host. Use the info command to get details on individual VMs.

kvmapp info xenial-test

Creating VMs with ISO files

You can also create a new VM with an ISO file.

First you need to create a diskimage. Use the addimage command to create a new disk image by specifying a name and size.

kvmapp addimage /var/lib/vimages/xenial-test.img 5G

This will create a brand new 5G disk image xenial-test.img.

You can now create a new VM.

kvmapp addvm xenial-test /var/lib/vimages/xenial-test.img fx0

This will create a brand new 'xenial-test' VM. You can now add an iso with the addiso command.

kvmapp addiso xenial-test /var/lib/vimages/xenial.iso

Once you start the VM it will boot the ISO. Whenever an ISO is attached to a VM it will automatically be booted first.

Once the ISO installation is complete you can remove the ISO with the deliso command.

kvmapp deliso xenial-test

This will remove the ISO file from the VM.

The addvm command also has a few options when creating a VM. In this case we added the ISO file after creating the VM. But you can specify an ISO file with the -i flag when creating the VM. More on that later.

flockport addvm xenial-test /var/lib/vimages/xenial-test fx0 -i /var/lib/vimages/xenial.iso

You can define cpu count and memory with the addvm command when creating VMs or the setvm command. The default is 1 cpu and 512M ram. More on that in the limits section below.

Disks

You can use the adddisk command to add disks to your VM.

kvmapp adddisk xenial-test /var/lib/vimages/xenialdisk2.img

This will attach the xenialdisk2.img to the xenial-test VM. These will show up as /dev/vdX inside the VM.

Now you when you run the listdisks command you should see the new disk in the VM.

kvmapp listdisks xenial-test

We already covered how to create empty disk images for use in VMs. You can attach multiple disk images to a VM. They will show up as multiple disks inside the VM. You can create disk images with the addimage command.

kvmapp addimage /var/lib/vimages/xenialdisk2.img 10G

This will create a empty xenialdisk2.img disk image with a size of 10G. /var/lib/vimages is the default directory Kvmapp creates on installation for VM disk images storage.

The listimages command lists all VM images on your host.

kvmapp listimages

This will list all disk images in the default VM storage folder /var/lib/vimages with size and usage information.

Most cloud providers provide VM disk images. You can download and use these when creating VMs or use the Kvmapp image hub to download ready to use VM images of various OSs.

These get attached to the VM when you create a VM and specifiy the disk image to use for it.

You can list all disks attached to a VM with the info or the listdisks command

kvmapp info xenial-test

This will provide detailed information on the xenial-test VM including attached disks

kvmapp listdisks xenial-test

This will list all disks attached to the xenial-test VM with information on size and usage.

You can remove disks from VMs with the deldisk command. Note this will remove the disk image from the VM not remove it from the system.

kvmapp deldisk xenial-test xenialdisk2.img

This will remove the xenialdisk2.img from the xenial-test VM.

When you remove VM with the delvm command any attached disks are deleted. So if you want to save a disk image for later use remove it from the VM with the deldisk command before deleting the VM.

Snapshots and Clones

You can make quick snapshots and clones of VMs with the snap and clone commands.

kvmapp snap xenial-test xenial-snap

This makes a snapshot of xenial-test named xenial-snap

You can make multiple snapshots and 'commit' them to a brand new VM.

kvmapp commit xenial-snap xenial-commit

This creates a new VM xenial-commit from the xenial-snap snapshot VM.

Please note when you make a snapshot Kvmapp will prevent you from running the original VM. To run the original VM commit a snapshot to a new VM and delete the snapshot.

You can also use the run command to directly start a snapshot of an existing VM.

kvmapp run xenial-test

This will create a snapshot of the xenial-test VM and start it. The snapshot name will be automatically generated and can be specified on the command line.

You can also create clones of VMs with the clone command.

kvmapp clone xenial-test xenial-clone

This will create a clone of the xenial-test VM called xenial-clone. Unlike snapshots clones are not linked and can be run independently. When you run clone the disk image is cloned and a new VM is created.

Networking

On installation Kvmapp creates a default fx0 bridge. When creating VMs you need to specify a default network and you can use the fx0 bridge.

You can use the info or listnetwork command to get detailed information on a VMs network.

kvmapp info xenial-test

This will show the xenial-test VM's networks and connected bridges. You can also use the listnetwork command

kvmapp listnetworks xenial-test

You can add and remove networks to VMs with the addnetwork and delnetwork commands.

kvmapp addnetwork xenial-test br0

This adds a second network interface to the xenial-test VM connected to the br0 bridge. A bridge corresponds to a network interface in the VM.

When you run listnetwork command now you should see two network interfaces for the VM.

You can remove a network with the delnetwork command.

kvmapp delnetwork xenial-test br0

This will remove the br0 network from the VM.

You can also create a new bridge with Kvmapp for use with your VMs with the addbr command

kvmapp addbr br0 10.0.10.0/24

This will create a new br0 bridge with the 10.0.10.0/2 subnet and enable it for use by Kvmapp and your VMs.

Setting VM CPU and Memory Limits

When creating a VM by default the cpu and memory is set to 1 cpu core and 512M memory. You can change this by using the '-c' and '-m' flags when creating a VM.

kvmapp addvm xenial-test /var/lib/vimages/xenial-test.img fx0 -c 2 -m 2014M

This sets 2 cpu cores and 2014M memory for the xenial-test VM. You can also set this after creating a VM with the setvm command.

kvmapp setvm xenial-test -c 2 -m 2048M

This sets 2 cpu cores and 2048M Memory for the xenial-test VM.

Port Forwarding

The default fx0 bridge is a nat bridge, this means its a private network and can't be accessed from outside the host. To reach any VMs on the host you need to use port forwarding. There are other options but more on that below.

You can quickly forward ports with the pub command.

kvmapp pub xenial-test 80:80

This will forward host port 80 to xenial-test port 80 so any application on port 80 will now be available on the host port 80.

You can forward any combination of ports for instance

kvmapp pub xenial-test 80:8080

This will forward host port 80 to xenial-test port 8080.

If you want to forward the same port you can simplify the command to:

kvmapp pub xenial-test 80

This forwards host port 80 to VM port 80.

An alternative to port forwarding is to use a host bridge as opposed to standalone nat bridge. A host bridge is connected to a physical interface on the host. For instance if you create a bridge and add one of your host's network interfaces to it then any VMs connecting to this bridge will be on the same network as the host. In this case port forwarding is not required.

Enabling VNC or Spice

You can enable VNC or Spice to access VM GUIs or access remote VMs. By default VNC or Spice are not enabled.

To enable VNC for a VM use the setvm command.

kvmapp setvm xenial-test -v vnc -p 5901

This enables VNC for the xenial-test VM and makes it available on localhost port 5901. You can access the VM with any VNC client on localhost:5901

For Spice

kvmapp setvm xenial-test -v spice -p 5909

This enables the Spice server and make it available on localhost 5909. You can now access the xenial-test VM with any Spice client.

You can also specify an IP when using the '-p' flag by using a colon seperator eg '127.0.0.1:5900' to access VMs remotely. But please note since both VNC and Spice are not secure protocols this is not secure. It's best to use this on trusted or private networks.

When enabling VNC or Spice you can also experiment with the graphics and display options for better performance with the '-g' and '-d' flags.

kvmapp setvm xenial-test -g qxl

This sets the graphics driver for the xenial-test VM to 'qxl'. By default the graphics and display are set to standard. Using the 'qxl' driver for graphics for instance usually provides better performance on VNC and Spice sessions.

There are a number of ways for more security if you are running remote VMs and would like to access them with VNC or Spice, for instance ssh port forwarding.

Shared Folders

You can share VM folders with host folders with the share command.

kvmapp share xenial-test:/var/shared /var/shared ubuntu

This shared the xenial-test VMs /var/shared folder with the host /var/shared. You need to specify the VM user so Kvmapp can enable the share. The share feature uses sshfs. You can login to the VM and see all data in the /var/shared is replicated in the VM.

The info command lists any shared folders with the VM

kvmapp info xenial-test

noVNC support

This is actually designed as part of the Flockport UI and is included in Kvmapp as a preview. noVNC is a browser based VNC client. You can point noVNC to a VNC address and port and access the VNC session in the browser.

For instance if you have a VNC session on 192.168.52.100 port 5900 you can point noVNC to this port and address and access it in your browser on the noVNC address.

kvmapp startnovnc 7000 192.168.52.100:5900

This will start noVNC on localhost port 7000 targetting the vnc session on 192.168.52.100:5900. When you access https://localhost:7000 on your browser you should be able to access the VNC session. By default we generate a self signed certificate for noVNC so you access it over https. Depending on your browser you may need to clear any alerts raised by the browser for a self signed certificate.

You can monitor and list all started noVNC instances with the getvncstatus command.

kvmapp getvncstatus

You can stop any started noVNC sessions by using the stopnovnc command with the port it was started on.

kvmapp stopnovnc 7000

This will stop the noVNC instance started on port 7000.

Upcoming features

Kvmapp will shortly have the functionality to build VMs like containers. This will leverage the same build functionality used by Flockport to build containers to provision and build VMs. So you will be able to use Flockport recipes to build VMs.

A rest API and UI are also being worked on and will be previewed shortly.

We are looking at Firecracker, the VM project by AWS, which uses KVM like Kvmapp does but with a more stripped down model. Kvmapp will have the ability to run Firecracker as an alternative VM engine. Kvmapp already is very lightweight and performant as most users will discover and KVM and QEMU combination is extremely efficient. But its always good to have options.