Manual:KVM

Applies to RouterOS: v4.3+ on x86

Overview

Kernel-based Virtual Machine provides virtualization on x86 RouterOS. It provides full virtualization to allow run multiple operating systems as guests on RouterOS host.

Requirements

KVM requires CPU virtualization support in form of Intel VT-x or AMD-V list of supported CPU, for more detailed information look on vendor page. To run guest it requires at least 16 MB of RAM and sufficient storage space on image file. Image file cannot be expanded after created and its size will be equal to one you entered in creation process of image.

Packages needed to be installed for KVM

• system
• kvm

Configuration

All KVM related configuration is done in /kvm menu. Available menus for KVM guest configuration are:

• /kvm - main KVM configuration menu
• /kvm interface - KVM interface configuration menu
• /interface virtual-ethernet - KVM interface "hook-up" with host.

KVM commands

Sub-menu: /kvm

Sub-menu allows to manage KVM guests on RouterOS host.

Command	Desciption
add	Create new KVM guest entry
comment	Set comment for KVM guest entry
console	to connect to KVM guest console display
continue	resume KVM guest if it was paused
disable	change global state of KVM guest. If enabled KVM guest will be started when RouterOS boots. KVM guest cannot change
edit	edit selected value of KVM guest entry
enable	change KVM guest global state to enable operation of KVM guest. If guest where disabled before - KVM guest is automatically started.
export	Print or save an export script that can be used to restore configuration of current sub-menu, KVM guest configuration, image files will not be saved
find	Find items by value
get	Gets value of item's property
make-routeros-image	creates RouterOS image from current installation installed on the router with no configuration. It is advised to create Image file larger than minimal, so you are able to upload new package files and upgrade/update RouterOS installation. Also, all the additional files created in KVM guest will be stored in file image. This image file is not connected to host RouterOS and user is able to run different RouterOS versions on host and guest. This command will create RAW image file containing RouterOS installation. parameters: file-name - name of ROS image file; file-size - image size in Meba Bytes; configuration-script - file name where configuration script is located;
pause	suspend operation of KVM guest
print	Print values of item properties
reboot	issue ACPI shut-down command to KVM guest, if guest does not support ACPI, command have no effect. After KVM guest is shut-downed it will be automatically started by host when shut down is complete.
reconfigure-routeros-image	sets up default configuration for RouterOS image. Parameters: file-name - name of ROS image to be reconfigured; configuraton-script - file name where configuration script is located; configuration-string - string containing ROS commands to be configured on ROS image.
remove	Remove item
set	Change item properties
shut-down	issue ACPI shut-down command to KVM guest, if guest does not support ACPI, command have no effect.
start	to start KVM guest

Create KVM guest

Expansion of command: /kvm add

To add new KVM guest you will have to issue command add under /kvm menu with attributes as follows:

Property	Desciption
comment (text, default: ')	to add simple text description of the KVM guest
cpu-count (1 .. 32, default: 1)	available count of processing cores for guest. Allowed values are [1..32]
disabled (yes | no, default: no)	to set guest state after creation, values: yes or no
disk-images ( list of images used in guest)	list of image assignment to drives for guest OS. If type will be set to cdrom then guest will automatically boot from that, instead of any other drive configured in this field. It can be single drive specified disk-images=hda:ros.img or it can be comma seperated list: disk-images=hda:system.img,hdb:swap.img
initrd (path)	path to initrd file, can be left empty if running RouterOS as guest
kernel (path)	path to kernel image file, if using RouterOS image created on host this field can be left empty
kernel-cmdline (text)	parameters that are passed to kernel, it is space separated string.
memory (integer default:32)	to set up amount of memory that is available to KVM guest
name (text)	name of KVM guest that it will be accessible though the system
snapshot (yes | no)	will try to run virtual machine with image file in read-only mode.
vnc-server (IP address:number)	if it is allowed to connect to this virtual machine using vnc client. Field value is <listen IP address>:<display number> where listen IP address - is ip address where vnc can connect to, by default 0.0.0.0 - listening on all interfaces, display number - independent positive integer value, if this number is set to 0 vnc is connections are not enabled for virtual machine. any value other than 0 will enable vnc connections to this virtual machine. If enabled, then VNC connection port will be 5900 + <display number>. For example, if <display number> = 5 then connection port will be port #5905 if port is busy starting of guest will fail.
copy-from (number)	use configuration from already existing KVM guest

If kernel and initrd fields are left empty, KVM will use hosts kernel and initrd. This is dangerous if you are going to run different RouterOS version on host and guest and can break your system. Guests other than RouterOS can break if you leave these values empty.

Example #1:

 /kvm add comment="example kvm guest" cpu-count=2 disabled=no disk-images=hda:ros.img initrd=/boot/initrd.rgz \ 
 kernel=/boot/vmlinuz kernel-cmdline="console=ttyS0" memory=128MiB name=ROS1

Example #2:

 /kvm add comment="example kvm guest" cpu-count=2 disabled=no disk-images=hda:ros.img initrd="" \ 
 kernel="" kernel-cmdline="console=ttyS0" memory=128MiB name=ROS1

Difference is, in example #1 guest will be loaded with kernel that does not support SMP while in example #2 it will look for kernel in ros.img, extract SMP kernel from there and load it. As result, guest created by exmaple #1 will show 1 cpu in /system resources while example #2 will show 2.

KVM guest interfaces

Menu: /kvm interface

Property	Desciption
comment (text)	description of interface
disabled (yes|no, default: no)	state of interface after creation
host-mac-address (MAC Address, default: generated)	MAC address of virtual interface that host will use
model (virto | e1000 | pcnet, default: virtio)	mode of virtual interface. Available options are: virtio - default value. Fastest available option, should be chosen if no other problems are encountered e1000 - emulates card that uses e1000 driver. This option where added for compatibility with some guest operating systems that where not able to communicate with host RouterOS if virtio interface model where used. pcnet - emulates card that uses pcnet driver. This option where added for compatibility with some guest operating systems that where not able to communicate with host RouterOS if virtio interface model where used.
vm-mac-address (MAC Address, default: generated)	MAC address of virtual interface that guest will use
copy-from (number)	use configuration from existing virtual interface
dynamic-bridge (interface name, default: none)	if set, dynamic interface will be automatically added as port to bridge interface
interface	is set for static interface, to assign it to already created virtual-ethernet interface
type (dynamic | static, default: static)	to set if interface is either static or dynamic. dynamic interface will add virtual-ethernet automatically when virtual machine starts. static interface have to have created virtual-ethernet interface at the time of creation of the entry.
virtual-machine (KVM machine name, must be set)	name of virtual machine this interface will be assigned to

If static interface is added and no mac address is set, it is automatically generated and set. For static interface this address will not change during use of guest. MAC address of dynamic interface will change every time dynamic interface is created. Automatically generate MAC addresses will be in form of 02:XX:XX:XX:XX:XX

Add and remove interfaces only when KVM guest is shut-down, stopped or disabled. Making changes to running guest may lead to host system crash.

States of KVM guest

This field is read-only and is set by RouterOS. These are possible values that can be set:

• stopped - KVM guest is not running, either successful shut-down or disabled.
• stopping - KVM guest is shutting down
• starting - KVM guest is starting
• running - KVM guest has started successfully and is executing guest operating system
• restarting - KVM guest is reloading its guest operating system
• failed - KVM guest has encountered an error and is not operational.
• image-busy - image file set in configuration is already in use by other KVM guest entry
• no-kernel-or-initrd - initrd or kernel was not found in files set in configuration, mentioned files could not be found or no values in those fields where set
• no-disk-image - either disk image was not found or disk image was not set in configuration.
• kernel-extract-failed - when in guest configuration field kernel is left empty and and KVM cannot extract kernel from image file supplied

See also

• Wikipedia about virtualization support on x86 CPUs
• Virtual Ethernet
• MetaROUTER