LibVMI v0.9_alpha README
by Bryan D. Payne
=====================

This file contains very basic instructions to get you up and running.  If you
want more details about installation, or programming with LibVMI, then see
the documentation included in the doc/ subdirectory of LibVMI, or view the
documentation online at http://vmitools.sandia.gov.

Transition from XenAccess
-------------------------
The core LibVMI code is based on XenAccess, but there have been many API changes
to make this library faster, easier to use, and more flexible.  XenAccess code
will not directly compile using LibVMI.  However, the migration path is usually
straightforward.  Below are a few notes on the most obvious API changes:

* There are no longer strict / lax versions of the init functions.  The
  remaining init function simply takes a Name to identify the guest VM.  The
  new init function also take an argument that specifies where to access the
  memory from (e.g., Xen, KVM, or a File).  You can also have LibVMI
  automatically determine where to access memory.  For example, the example
  code uses a Name to identify the guest.  Using the auto mode, if this is a
  KVM VM name then LibVMI will connect via KVM.  Similarly, if you specifiy a
  file name, then LibVMI will access that file as a raw memory dump.  All of
  this happens under the hood, so you can write code once that can be readily
  used on a variety of platforms.

* The xa_access_* functions have been replaced with vmi_read_* functions.
  The read functions give you the flexibility to read as much or as little
  memory as you desire, so you are no longer working within page boundaries.
  The read functions also handle page mapping management transparently, so 
  you never need to worry about unmapping pages or writing code in a specific
  way for performance reasons.  You can simply use the read functions and
  LibVMI will work to make your memory accesses as fast as possible.

* The xa_read_long_* functions have been renamed for clarity.  These functions
  continue to work in the same way, just with different names.  For example:
     xa_read_long_sym --> vmi_read_32_ksym
     xa_read_long_long_virt --> vmi_read_64_va
  Using this new naming convention, there are also new functions to make it
  simple to read 8 bits / 1 byte and 16 bites / 2 bytes at a time.

* There are now translation routines to perform kernel virtual address lookups,
  user virtual address lookups, and kernel symbol lookups.

* Kernel symbols on Windows are now available from both the kernel header
  exports and the KPCR table.  The KPCR symbols are new, and useful because
  these include many otherwise hard to find data locations.

* The LibVMI instance structure is now opaque.  There are accessor functions
  available to return useful information from this structure.

For more details on using LibVMI, see the online documentation available at
http://vmitools.sandia.gov.

Python Interface
----------------
LibVMI is written in C.  If you would rather work with Python, then look at
the tools/pyvmi/ directory after installing LibVMI.  PyVMI provides a
feature complete python interface to LibVMI with a relatively small
performance overhead.

Dependencies
------------
The following libraries are used in building this code:

libxc (from Xen, the Xen Control library, required for Xen support)
libxenstore (from Xen, access to the xenstore, required for Xen support)
libvirt (from Red Hat, access to KVM guests, 0.8.7 or newer required for KVM
    support, MUST BE BUILT WITH QMP SUPPORT -- THIS REQUIRES yajl)
qemu-kvm patch (option 1 for KVM memory access, optional for KVM support,
    still buggy but faster than alternative option, see Note 2)
gdb enabled kvm VM (option 2 for KVM memory access, optional for KVM
    support, more stable than option 1 but slower, see Note 2)
yacc OR bison (for reading the configuration file)
lex OR flex (for reading the configuration file)
glib (version 2.22 or better is required)

Note 1: If you are installing a packaged version of Xen, you will likely
  need to install something like 'xen-devel' to obtain the files needed
  from libxc and libxenstore in the dependencies listed above.

Note 2: If you want KVM support then you will need to build your own 
  version of QEMU-KVM or enable GDB support for your VM.  See the
  section on KVM support (below) for additional information.

Xen Support
-----------
If you would like LibVMI to work on Xen domains, you must simply ensure
that you have Xen installed along with any Xen development packages.
LibVMI should effectively just work on any recent version of Xen.

KVM Support
-----------
If you would like LibVMI to work on KVM VM's, you must do some additional
setup.  This is because KVM doesn't have much built-in capability for
introspection.  For KVM support you need to do the following:

* Ensure that you have libvirt version 0.8.7 or newer
* Ensure that your libvirt installation supports QMP commands, most 
  prepackaged versions do not support this by default so you may need
  to install libvirt from source yourself.  To enable QMP support 
  when installing from source, ensure that you have libyajl-dev (or 
  the equivalent from your linux distro) installed, then run the
  configure script from libvirt.  Ensure that the configure script
  reports that it found yajl.  Then run make && make install.
* Choose a memory access technique:
  1) Patch QEMU-KVM with the provided patch.  This technique will 
     provide the fastest memory access, but is buggy and may cause
     your VM to crash / lose data / etc.  To use this method, 
     follow the instructions in the libvmi/tools/qemu-kvm-patch
     directory.
  2) Enable GDB access to your KVM VM.  This is done by adding
     '-s' to the VM creation line or, by modifying the VM XML
     definition used by libvirt as follows:
     - Change <domain type='kvm'> to
       <domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
     - Add...
       <qemu:commandline>
         <qemu:arg value='-s'/>
       </qemu:commandline>
       ...under the <domain> level of the XML.
* You only need one memory access technique.  LibVMI will first look
  for the QEMU-KVM patch and use that if it is installed.  Otherwise
  it will fall back to using GDB.  So if you want to use GDB, you 
  should both enable GDB and ensure that QEMU-KVM does not have the
  LibVMI patch.

File / Snapshot Support
-----------------------
If you would like LibVMI to work on physical memory snapshots saved to
a file, then you don't need any special setup.

Building
--------
LibVMI uses the standard GNU build system.  To compile this library, simply
follow the steps below:

./autogen.sh
./configure
make

The example code will work without installing LibVMI.  However, you may
choose to install the library into the prefix specified to 'configure' by:

make install

The default installation prefix is /usr/local.  You may need to run
'ldconfig' after performing a 'make install'.