Xenballoond.README
Preliminary version 0.1, 2008/06/30

Copyright (C) 2008 Oracle Corporation and/or its affiliates.
All rights reserved.
Written by Dan Magenheimer <dan.magenheimer@oracle.com>

INTRODUCTION

Xenballoond runs in guest domains and both implements selfballooning and
provides metrics to dom0 for (future) directed ballooning.  Both capabilities
provide a foundation for basic "memory overcommit" functionality.

With selfballooning enabled, xenballoond uses the Committed_AS value found
in /proc/meminfo as a first approximation of how much memory is required
by the guest and feeds this statistic back to the balloon driver to inflate
or deflate the balloon as required to achieve the target guest memory size.
Hysteresis parameters may be adjusted to rate-limit balloon inflation
and deflation.

If configured, certain selfballooning parameters -- including notably
enabling/disabling of self-ballooning -- can be controlled from domain0.
(These are fully documented in xenballoon.conf.)

If configured, the following guest statistics are sent back to domain0:
- /proc/meminfo
- /proc/vmstat
- /proc/uptime
In a future release, some of these values will be used by a policy module
in domain0 to control guest balloon size and provide memory balancing
across all guests on a given system.

Note that no page sharing (content-based or otherwise) is implemented
and no VMM-based swapping is necessary.

For more information, see:
http://www.xen.org/files/xensummitboston08/MemoryOvercommit-XenSummit2008.pdf
http://wiki.xensource.com/xenwiki/Open_Topics_For_Discussion?action=AttachFile&do=get&target=Memory+Overcommit.pdf

INSTALLATION AND DEPLOYMENT

In this preliminary release:
- directed ballooning is not implemented, though a monitor is provided
- only Redhat-based guests are supported

Guest prerequisites to use xenballoond:
- each guest must be configured with adequate[1] swap space
- each guest must have the balloon driver installed (/proc/xen/balloon exists) 
- if directed ballooning (or monitoring) is desired, xenstore tools must be
  installed in each guest in /usr/bin [2]

[1] for best results, for a guest that is configured with maxmem=N and
    requires Z MB of swap space without xenballoond, available swap should
    be increased to N+Z MB when xenballoond is running
[2] specifically xenstore-read, xenstore-exists, and xenstore-write must
    be installed.  Binaries can be obtained, for example, by building
    xen-vvv.gz/tools in a guest-binary-compatible development tree

Instructions to install/deploy xenballoond (in Redhat-based system):
- in each guest:
  - ensure pre-requisites are met (see above)
  - place xenballoon.conf in /etc/sysconfig
  - place xenballoond in /usr/sbin
  - copy xenballoond.init to /etc/rc.d/init.d/xenballoond (note file rename)
  - edit /etc/sysconfig/xenballoond.conf as desired (especially note that
    selfballooning defaults as off)
  - start xenballoond with "service xenballoond start", and/or configure
    xenballoond to start at init (e.g. "chkconfig xenballoond on")
- in domain0:
  - if monitoring is desired, xenballoon-monitor may be installed in /usr/sbin
- note that certain xenballoond.conf variables may be overridden by domain0
  if xenstore is running in the guest; these are fully documented in
  xenballoond.conf

TODO:
080630 modifications to support SUSE-based and debian-based guests
080630 domain0 ballooning policy module
080630 experiment with more aggressive (optionally) memory minimum targets
080630 BUG: xenballoond doesn't properly record the fact that it's running;
       e.g. flipping between run levels 5 and 3 launches additional daemons
080630 BUG: reports of possible incompatibilites between ballooning and
       save/restore/migrate have not been duplicated
