xenvm.readme

= Description

xenvm is a single VM monitor. it's a single process that follow the life of
a VM, and open a command socket where you can send command, just like xm to xend

xenvm expose the uuid of the domain to outside world, so instead of having to
refer to the domid of the domain, all outside command use the uuid. the uuid
beeing stable, all command will use the same uuid after reboot/suspend/resume
cycle.

= Config file

you can put the following parameters in your config file:

(common options)
hvm = true|false -- specify if it's an hvm guest
paused = true|false -- specify if the domain start paused
debug = true|false -- logs all operations to /tmp/xenvm-debug-%uuid
uuid = uuidstring -- specify the domain uuid (default to autogenerating one)
on_crash = preserve|reboot|destroy -- specify the action to be taken after notifying a crash
on_halt = preserve|reboot|destroy -- specify the action to be taken after notifying a halt
on_reboot = preserve|reboot|destroy -- specify the action to be taken after notifying a reboot
kernel = string -- specify where to find the kernel to boot
                   you can leave that empty for hvm, it will default
		   to hvmloader
memory = int -- specify the memory given to the guest in megabytes
vcpus = int -- number of vcpus available to the guest

disk = physpath:phystype:virtpath:mode:devtype
	-> physpath = path to the physical device (/dev/vg/test)
	-> phystype = phy | qcow | aio | file
	-> virtpath = hd(a-d) | sd(a-.) | xvd(a-p)
	-> mode = r | w
	-> devtype = cdrom | disk

vif = comma,separated,key,value,pair

	key supported : bridge and mac
	leaving empty configuration string after the first equal will
	create default values.

	example:
		"vif = bridge=xen-br0,mac=ab:de:fe:dc:ba:ab"
		"vif = mac=ab:de:fe:dc:ba:ab"
		"vif = "

(the following are just useful for pv)
cmdline = string -- command line given to the kernel
initrd = string -- specify the initrd use, leave empty for none

(the following are just useful for hvm)
pae = true|false -- specify the guest is using pae
acpi = true|false -- specify the guest is using acpi
apic = true|false -- specify the guest is using apic
boot = string -- specify the qemu boot string
vnc = int -- specify the vnc port to use
vnc_keymap = string - specify the vnc keymap to use

= Sending command to the monitor

xenvm bind a unix socket to the uuid specified/generated
You can easily send command to the monitor with xenvm-cmd using the simple
syntax:

	xenvm-cmd <uuid> <cmds> <args>

The following command are supported:

	- pause
	- unpause
	- destroy
	- suspend <file>
	- suspend live <file>
	- restore <file>
	- checkpoint <file>
	- shutdown
	- restart
	- quit (quit the monitor leaving the vm untouched)

= Running with xen-unstable

It's possible to run with xen-unstable directly, but you need the
qemu-dm-wrapper script and xenguest binary in <base_path>/bin/.
They are available in ocaml/xenguest/xenguest and scripts/qemu-dm-wrapper
in the api repository. For people that can't build ocaml tools,
you can get the binary/script on some testings machines, but be careful about
architecture, and out-of-date-ness.

And you need to replace your udev rules by the one available in
scripts/xen-backend.rules and scripts/xen-frontend.rules and add the
scripts/tap scripts/block scripts/block-front scripts/vif into
@SCRIPTSDIR@/

Also note that since xen-unstable doesn't have the dm-ready patch,
hvm domain takes unfortunately a substantial time (around 20s.) to start.

On a rio build, xenvm should be ready out-of-the-box

= Example of config

PV config with one LVM disk and one VIF :

----8<----
uuid = 00000000-0000-0000-0000-000000000001
hvm = false
kernel = /boot/vmlinuz-2.6.18-xenU
cmdline = root=/dev/sda1 ro
memory = 64
disk = /dev/VG_XenStorage-8cbac5b8-edeb-b04b-d455-e08e07ec3088/test:phy:sda:w:disk
vif =
----8<----

HVM config for installing a win2k3.. iso :

----8<----
uuid = 00000000-0000-0000-0000-000000000002
hvm = true
memory = 256
disk = /dev/VG_XenStorage-8cbac5b8-edeb-b04b-d455-e08e07ec3088/testhvm:phy:hda:w:disk
disk = /var/opt/xen/iso_import/w2k3eesp2.iso:file:hdd:r:cdrom
boot = dc
pae = false
acpi = false
apic = false
----8<----