GETTING STARTED WITH PALACIOS ----------------------------- * Note, the example shell commands in this document use "$" and "#" to indicate either standard-user ("$") or root-user ("#") shells. * In addition, a simple set of config files and an initial ramdisk that can be used for running palacios in QEMU is available from the Palacios website. The instructions in that tarfile along with those described below are a good way to get started with Palacios. 1. Packages needed for building Palacios and creating virtual machines - GCC and binutils - GNU make - ncurses or qt needed for configuring palacios 2. System requirements For the host OS, a 2.6/3.x kernel is required and this kernel must be configured with the memory hot-remove feature, which is not enabled by default in most kernels. This feature is located under: Processor type and features | +---> Allow for memory hot-add | +---> Allow for memory hot-remove Without this feature, Palacios will be unable to allocate large chunks of memory for a VM. - For example, on a Debian system check the config file in "/boot", $ cat /boot/config-$(uname -r) | grep HOTREMOVE CONFIG_MEMORY_HOTREMOVE=y CONFIG_ARCH_ENABLE_MEMORY_HOTREMOVE=y 3. Get source code using the git repository - Install git * If you are using Ubuntu or Debian system, run: $sudo apt-get install git * If you are using RedHat or Fedora system, run: $sudo yum install git - Configure your personal identification after installing git successfully. To do this, run: $git config --global user.name "Your_Name" $git config --global user.email "Your_Email" - Clone our repository. * To checkout the head of the master branch into the subdirectory palacios Run: $git clone http://v3vee.org/palacios/palacios.web/palacios.git * After checking out the head of the master branch, you may want to switch to the devel branch or one of the release branches. (NOTE: The newest version is "Release-1.3".) o Option-A: To switch to the devel branch, run $cd palacios $git checkout --track -b devel origin/devel o Option-B: To switch to the version 1.3 release branch, run $cd palacios $git checkout --track -b Release-1.3 origin/Release-1.3 o Information regarding other releases and branches is available on the website (http://v3vee.org/palacios/) 4. Build Palacios - Configuration. Before compiling Palacios, you will need to do some manual configuration using 'make xconfig' if you are using X, or 'make menuconfig'. ## From top-level dir of Palacios source tree $make menuconfig * Essential options o Under Target Configuration -> Target Host OS, select the Linux Module option o Target Configuration -> Linux Module -> Linux Kernel Source Directory should be set to the full path of the source tree of the host kernel o Target Configuration -> X86 Decoder should have the Internal Palacios Decoder selected * Other options Please refer to the technical report. - Compilation * Build palacios after Palacios is properly configured by runing: ## From top-level dir of Palacios source tree $make all The compilation creates a static library named libv3vee.a which contains Palacios in your directory. If your host OS is the Linux kernel module, the compilation will then create this module v3vee.ko based on this library. * Insert the v3vee module into the kernel using: $sudo insmod path_to_v3vee.ko After this step, you may want to run 'dmesg' to see if Palacios reported any errors while loading and configuring the machine. * Build the tools that run in the userspace of the host OS $cd palacios/linux_usr $make The tools are named as v3_ in the linux_usr directory. 5. Guest configuration The guest images are built from an XML-based configuration file. There is a default guest configuration file named default.xml in the palacios/utils/guest_creator directory. This file contains most of the currently possible options. But you can specify the configuration of a new VM by yourself. - Build the guest using the .xml configuration file * The guest VM image file can be created using the tool 'build_vm'. To build this tool, run: $cd palacios/utils/guest_creator $make * Create the VM image by running: $./build_vm /path/to/my_config.xml -o /path/to/my_guest_image.img - Note, the output file "my_guest_image.img" can be loaded directly into Palacios. 6. Run Palacios and its VMs Before you start interacting with Palacios in the host, make sure all of the executables prefixed with "v3" that were built earlier are in your PATH. - Allocate memory for a new VM by running: #v3_mem MEM_MB MEM_MB is the size of the physical memory that should be reserved for Palacios in mega-bytes. This memory will be controlled by Palacios exclusively. - Create a new VM, run: #v3_create /path/to/my_guest_image.img MyGuestName After these two steps, a new VM named MyGuestName will be created and this VM is represented as a device named v3-vm stored in /dev. should be replaced by the number corresponding to the sequence in which you create the VM(s). Therefore, the first VM created is /dev/v3-vm0. The VMs can be referred to by the other v3_* utilities. - Launch the VM: #v3_launch /dev/v3-vm You can see this running VM by using 'ps'. A kernel thread [MyGuestName-0] will be shown in the output. This kernel thread represents the first virtual core of the VM. Additional cores will appear as other kernel threads, with core numbers given as suffixes. So if MyGuestName were a four core VM, 'ps' would show: [MyGuestName-0] [MyGuestName-1] [MyGuestName-2] [MyGuestName-3] - Interacting with the VM's console * If the guest includes a CURSES_CONSOLE console backend, you should be able to connect to the guest console by running #v3_cons /dev/v3-vm You will automatically be connected to the console of the guest, but to exit you can press the Escape ('ESC') key. v3_cons only works correctly when you are directly connected to the console of the physical host machine. If you are using a virtual terminal (xterm, etc), you will want to use: #v3_cons_sc /dev/v3-vm 2 > debug.log * Pausing and contiuning a VM o To pause a VM, use #v3_pause /dev/v3-vm o To resume execution of a paused VM, use #v3_continue /dev/v3-vm * Migrating a VM's virtual cores A VM's virtual core to physical core mapping can be changed by using: #v3_core_move /dev/v3-vm VCORE-ID PCORE-ID * Stopping and freeing VMs o To turn off a VM, run #v3_stop /dev/v3-vm o You can free the resources after the VM is stopped by running: #v3_free # $Id: user-guide.txt 24 2011-11-03 14:48:58Z tjn $