Parallax Quick Overview

This is intended to provide a quick set of instructions to let users
experiment with the current parallax source. In it's current form,
the code will let you run an arbitrary number of VMs off of a single
disk image, doing copy-on-write as they make updates. Each domain is
assigned a virtual disk image (VDI), which may be based on a snapshot
of an existing image. All of the VDI and snapshot management should
currently work.

Here's how to get going:

0. Setup:
---------

Pick a partition or directory with lots of room, no less than 12GB.
You should be running from a privileged domain (e.g. dom0). You will
be using this as the blockstore for all disk images.

1. Populate the blockstore:
---------------------------

First you need to put at least one image into the blockstore. You
will need a disk image, either as a file or local partition.

(a) make a really big sparse file with

dd if=/dev/zero of=./image bs=4K count=1 seek=[big value]

(b) put a filesystem into it

mkfs.ext3 ./image

(c) mount it using loopback

mkdir ./mnt
mount -o loop ./image

(d) cd into it and untar/install an image of your choice

(e) unmount the image

cd ..
umount mnt

(f) Create the base structure for the storage file in the root
directory. Symlink your blockstore to "/blockstore.dat", which is
hard-coded into parallax. See section 4 for changing this default.
The following parameters create six 2GB extents (a 2GB extent size is
standard and recommended). The number of extents can be chosen
arbitrarily but should be at least 6.

(g) Start the lock manager

(h) now, create a new VDI to hold the system image

(i) get the id of the new VDI.

./vdi_list

| 0 My new FC3 VDI

(0 is the VDI id... create a few more if you want.)

(j) put your image into the new VDI.

This will pull the entire image into the blockstore and set up a
mapping tree for it for VDI 0. Passing a device (i.e. /dev/sda3)
should also work.

vdi_fill will count up until it is done, and you should be ready to
go. You can use vdi_validate to test the VDI against the original
image.

2. Create some extra VDIs
-------------------------

VDIs are actually a list of snapshots, and each snapshot is a full
image of mappings. So, to preserve an immutable copy of a current
VDI, do this:

(a) Snapshot your new VDI. If a disk is currently mounted by a guest,
you should use vdi_snap, otherwise, use vdi_snap_offline.

./vdi_snap_offline 0

Snapshotting writes the current radix root to the VDI's snapshot log,
and assigns it a new writable root.

(b) look at the VDI's snapshot log.

./vdi_snap_list 0

| 16 0 Thu Mar 3 19:27:48 2005 565111 31

The first two columns constitute a snapshot id and represent the
(block, offset) of the snapshot record. The Date tells you when the
snapshot was made, and 31 is the radix root node of the snapshot.

(c) Create a new VDI, based on that snapshot, and look at the list.

./vdi_create "FC3 - Copy 1" 16 0
./vdi_list

| 0 My new FC3 VDI
| 1 FC3 - Copy 1

NOTE: If you have Graphviz installed on your system, you can use
vdi_tree to generate a postscript of your current set of VDIs and
snapshots.

Create as many VDIs as you need for the VMs that you want to run.

3. Boot some VMs:
-----------------

You need to modify the disk line of the Xen VM config that is going to
boot.

(a) set up your vm config, by using the following disk line:

This example uses VDI 1 (from vdi_list above), presents it as sda1
(writable), and uses dom 0 as the backend. If you were running the
daemon (and tap driver) in some domain other than 0, you would change
this last parameter.

(b) create your new domain.

xm create ...

4. (Optional) Modify your parallax configuration:
-------------------------------------------------

The following configuration options are available in blockstore.h

A single blockstore can safely serve a number of parallax clients, as
long as the lockMaster is properly configured. LockMaster location and port:

#define BLOCKSTORE_MASTER "127.0.0.1"
#define MASTER_PORT 8440

For a multiple machine setup, these will have to be changed to specify
a machine running the lockMaster and an associated open port.
Modifying the code here will change the lockMaster, parallax, and all
vdi tools.

Blockstore location:

# define BLOCKSTORE_DATA "/dev/sdb"

This is the location of the blockstore used by parallax, the
lockMaster, and all vdi_tools. It can be modified to target any
device or file.