a bare metal (type 1) VMM (hypervisor) with a python remote control API
C Python Assembly Other
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
client ACPI S3 support Oct 17, 2016
common dedicated setup stack program header Feb 8, 2018
include loader takes care of setup module load address against mbi modules Feb 8, 2018
loader
setup dedicated setup stack program header Feb 8, 2018
tools Intel VT-d iommu support Oct 17, 2016
vmm dynamic program header . our elf loader doesn't care about dynamic se… Feb 8, 2018
.gitignore ignore python dist Mar 11, 2016
Makefile new installation rules: - one can define an installer behavior out of… Jul 15, 2014
README.org fixed README Oct 7, 2014

README.org

What is Ramooflax ?

Ramooflax is a free and open source (GPLv2) virtualization tool.

Ramooflax aims at analyzing/debugging/controlling modern operating systems and complex software pieces as well as real life BIOS running on a physical machine.

Ramooflax provides a small hypervisor and a remote client allowing high-level access to the features implemented into the hypervisor.

On what hardware does it run ?

Ramooflax has been implemented for the PC world. That is Intel and AMD x86 32 and 64 bits.

Ramooflax relies on hardware virtualization extensions (AMD-V and Intel VT-x) that can be found in recent CPUs.

For Intel ones, Ramooflax needs EPT and Unrestricted guest features present since the Westmere microarchitecture. More details can be found on this wikipedia page.

For AMD ones, the only required feature is RVI and can be found into Phenom II CPUs. Some details are given on this wikipedia page.

Ramooflax can run under VMware workstation/fusion using the “virtualize vm-x/EPT” feature. But you still need a skilled enough CPU.

Notice that you can also run Ramooflax under Bochs 2.4.6.

How does it work ?

Ramooflax starts during the boot process of the machine. It can be seen as the first operating system started by the BIOS.

Once started, Ramooflax will automatically virtualize the running BIOS and all the to be run software pieces.

For instance, if you already have installed an operating system, it will be started as a virtual machine.

Ramooflax is an hypervisor dedicated to only one virtual machine, running in a virtualized environment which is as close as its native environment.

Ramooflax needs to be installed on a bootable storage (ie USB key with GRUB).

Documentation

All documents can be found on the Ramooflax wiki pages.

Software requirements

ramooflax has been compiled/tested using gcc-4.8. The loader is a 32 bits ELF while the setup and vmm kernels are 64 bits ELF.

Under Debian-like systems, the following packages are needed whether you run a 32 or 64 bits OS:

$ sudo apt-get install gcc-4.8 gcc-4.8-multilib make

Limitations

Intel and AMD are both supported. Notice that multi-cores feature is not supported yet, so you will only have one core while running virtualized.

It is recommended to read the documentation.

Obtaining

$ git clone git@github.com:sduverger/ramooflax.git

Configuring

First cleanup everything and call the specific configuration menu to choose your components

$ make distclean config

Under the build menu you will be able to choose from Intel or AMD manufacturer, which control device you want to use, debug device and so on.

For the time being, it is recommended to use NET as controlling device and UART as debugging one.

Building

Once configured you can run

$ make

This will build the loader, setup and vmm binaries.

Installing

$ make install

The installation rules looks for a script named installer.sh. We provide example scripts, located in tools, which update VMware and QEMU virtual disk images. You can define your own one and override the INSTOOL make variable:

make INSTOOL=tools/installer_qemu.sh install

Ramooflax needs a multiboot compliant bootloader (such as GRUB). The following GRUB 1 (legacy) entry can be defined to boot ramooflax:

title  Ramooflax
root   (hd0,0)
kernel /loader.bin
module /setup.bin
module /vmm.bin pool=1234 ip=192.168.0.2 gateway=192.168.0.1 netmask=255.255.255.0

We also provide a disk image creation tool (which needs GRUB legacy), in tools:

sudo ./tools/create_disk.sh ramooflax.img 32M ../grub/ loader/build/loader.bin setup/build/setup.bin vmm/build/vmm.bin 

[+] building disk image (32MB)
[+] create part on disk image
[+] formating disk
[+] mounting disk
[+] copy grub
[+] installing files
[+] configure grub
[+] install grub
[+] unmounting disk

Disk is ready !
- mnt it using : "mount -o loop,offset=512 ramooflax.img /mnt"
- run it using : "qemu -hda ramooflax.img"

The tool builds a GRUB bootable disk image of the given size, with ramooflax as default entry.

Using

You will need python (tested with 2.6.x) to run the client.

EHCI interface

If you use the EHCI Debug device configuration to control the hypervisor from the remote client, you will need a USB debug device on the client side.

You can either buy one or use the DBGP USB Gadget provided into the Linux kernel since the 2.6.36 version.

To be able to use such a Gadget, you need a device USB controller as found in embedded ARM development boards or smartphones.

Please read documentation to have usage examples of the client API.

Network interface

Do not forget to provide Ramooflax network settings on vmm module cmd line into the GRUB configuration entry.

As shown into Installing section, you can provide ip, netmask and gateway options to the vmm module.

Reaching the hypervisor will depend on your setup (real machine, running on a host using VMware, …) for the IP configuration part.

The VMM is listening to UDP port 1337.