Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/airbus-seclab/ramooflax

a bare metal (type 1) VMM (hypervisor) with a python remote control API
https://github.com/airbus-seclab/ramooflax

Last synced: 10 days ago
JSON representation

a bare metal (type 1) VMM (hypervisor) with a python remote control API

Awesome Lists containing this project

README 

        
#+LANGUAGE: en

#+OPTIONS: H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t

#+OPTIONS: TeX:t LaTeX:nil skip:nil d:nil todo:t pri:nil tags:not-in-toc

#+EXPORT_EXCLUDE_TAGS: exclude

#+STARTUP: showall



* 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 [[http://en.wikipedia.org/wiki/Nehalem_(microarchitecture)][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 [[http://en.wikipedia.org/wiki/AMD-V#AMD_virtualization_.28AMD-V.29][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 [[https://github.com/sduverger/ramooflax/wiki][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 [email protected]: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:



#+BEGIN_EXAMPLE

make INSTOOL=tools/installer_qemu.sh install

#+END_EXAMPLE



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



#+BEGIN_EXAMPLE

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

#+END_EXAMPLE



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



#+BEGIN_EXAMPLE

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"

#+END_EXAMPLE



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/.