[haizea-commit] r472 - in trunk: . doc doc/manual doc/manual/images html
haizea-commit at mailman.cs.uchicago.edu
haizea-commit at mailman.cs.uchicago.edu
Thu Aug 28 10:16:06 CDT 2008
Author: borja
Date: 2008-08-28 10:16:06 -0500 (Thu, 28 Aug 2008)
New Revision: 472
Added:
trunk/doc/
trunk/doc/manual/
trunk/doc/manual/analysing.tex
trunk/doc/manual/appendix_cli.tex
trunk/doc/manual/appendix_conf.tex
trunk/doc/manual/images/
trunk/doc/manual/images/haizea.png
trunk/doc/manual/images/quickstart_leasegraph1.png
trunk/doc/manual/images/quickstart_leasegraph2.png
trunk/doc/manual/images/quickstart_leasegraph3.png
trunk/doc/manual/images/quickstart_leasegraph4.png
trunk/doc/manual/install.tex
trunk/doc/manual/intro.tex
trunk/doc/manual/manual.tex
trunk/doc/manual/opennebula.tex
trunk/doc/manual/quickstart.tex
trunk/doc/manual/simulation.tex
trunk/doc/manual/title.tex
trunk/doc/manual/utils.tex
Modified:
trunk/html/doc_multiple.html
trunk/html/documentation.html
trunk/html/haizea.css
Log:
Created Haizea Manual in LaTeX, and ported most documentation there.
Added: trunk/doc/manual/analysing.tex
===================================================================
--- trunk/doc/manual/analysing.tex (rev 0)
+++ trunk/doc/manual/analysing.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,42 @@
+While Haizea is running, it collects data that can be analysed offline (accepted/rejected leases, waiting times, etc.). This data is saved to disk when Haizea stops running so, for now, this information is (in practice) only useful for simulation experiments. In the future, Haizea will save data periodically to disk so it can also be analysed online.
+
+The file where the collected data will be saved is specified in the datafile option of the general section:
+
+\begin{wideshellverbatim}
+[general]
+...
+
+datafile: /var/tmp/haizea.dat
+
+...
+\end{wideshellverbatim}
+
+Haizea currently includes no tools to easily convert this datafile into an easily readable format (like a graph) although these will eventually be added to Haizea. For now, if you want to access the data collected by Haizea, you will have to do so programatically. The data file contains a pickled \texttt{StatsData} object (see module \texttt{haizea.resourcemanager.stats}) with all the information collected during a simulation experiment. An example of how this file is unpickled, and some of its information accessed, can be found in function \texttt{haizea\_convert\_data} in module \texttt{haizea.cli.commands}.
+
+The \texttt{StatsData} object contains the following information:
+
+\begin{description}
+ \item[Counter lists] Haizea keeps tracks of several metrics, such as the number of accepted AR leases or the number of best-effort leases completed, and keeps a log of how these metrics varied over time. In particular, it keeps track of the following:
+\begin{itemize}
+
+ \item \texttt{COUNTER\_ARACCEPTED}: Number of accepted AR leases.
+ \item \texttt{COUNTER\_ARREJECTED}: Number of rejected AR leases.
+ \item \texttt{COUNTER\_IMACCEPTED}: Number of accepted immediate leases.
+ \item \texttt{COUNTER\_IMREJECTED}: Number of rejected immediate leases.
+ \item \texttt{COUNTER\_BESTEFFORTCOMPLETED}: Number of completed best-effort leases.
+ \item \texttt{COUNTER\_QUEUESIZE}: Queue size (best-effort leases)
+ \item \texttt{COUNTER\_DISKUSAGE}: Total disk space used by VM images in the node pool.
+ \item \texttt{COUNTER\_CPUUTILIZATION}: Percentage of CPUs used in node pool.
+\end{itemize}
+ A "counter list" (which should more appropriately be called a "metric log") includes an entry for each time a metric changes. Each entry is a tuple (time, lease\_id, value, average). If the metric is not associated with any particular lease, then the lease ID will be \texttt{None}. The average is a running average which will be \texttt{None} when it does not make sense to keep an average (e.g., the number of accepted AR requests).
+\item[Node state log] A dictionary with one entry per physical node. Each entry has a list with the state of a physical node at certain points in time. The possible states are:
+\begin{itemize}
+ \item \texttt{DOING\_IDLE}: The node is idle.
+ \item \texttt{DOING\_VM\_RUN}: The node is running a VM.
+ \item \texttt{DOING\_VM\_SUSPEND}: The node is suspending a VM.
+ \item \texttt{DOING\_VM\_RESUME}: The node is resuming a VM.
+ \item \texttt{DOING\_TRANSFER\_NOVM}: The node is idle, and an image transfer is in progress.
+\end{itemize}
+ This information is only useful if you have one VM per physical node. The node state log will be modified in future versions of Haizea to provide more useful utilization data for configurations that have more than one VM per physical node.
+\item[Lease descriptors] The lease descriptors (i.e., \texttt{ARLease}, \texttt{BestEffortLease}, or \texttt{ImmediateLease} objects) of all the leases that have been scheduled are included in the object. The resource reservations are removed, as it would make the datafile too big. However, this still conserves interesting metrics like starting and ending times, waiting times, etc.
+\end{description}
Added: trunk/doc/manual/appendix_cli.tex
===================================================================
--- trunk/doc/manual/appendix_cli.tex (rev 0)
+++ trunk/doc/manual/appendix_cli.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,19 @@
+\section{The \texttt{haizea} command}
+
+\section{Lease management}
+
+\subsection{\texttt{haizea-request-lease}}
+
+\subsection{\texttt{haizea-list-leases}}
+
+\subsection{\texttt{haizea-cancel-lease}}
+
+\section{Running multiple simulations}
+
+\subsection{\texttt{haizea-generate-configs}}
+
+\subsection{\texttt{haizea-generate-scripts}}
+
+\section{Data analysis}
+
+\subsection{\texttt{haizea-convert-data}}
Added: trunk/doc/manual/appendix_conf.tex
===================================================================
Added: trunk/doc/manual/images/haizea.png
===================================================================
(Binary files differ)
Property changes on: trunk/doc/manual/images/haizea.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/doc/manual/images/quickstart_leasegraph1.png
===================================================================
(Binary files differ)
Property changes on: trunk/doc/manual/images/quickstart_leasegraph1.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/doc/manual/images/quickstart_leasegraph2.png
===================================================================
(Binary files differ)
Property changes on: trunk/doc/manual/images/quickstart_leasegraph2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/doc/manual/images/quickstart_leasegraph3.png
===================================================================
(Binary files differ)
Property changes on: trunk/doc/manual/images/quickstart_leasegraph3.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/doc/manual/images/quickstart_leasegraph4.png
===================================================================
(Binary files differ)
Property changes on: trunk/doc/manual/images/quickstart_leasegraph4.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/doc/manual/install.tex
===================================================================
--- trunk/doc/manual/install.tex (rev 0)
+++ trunk/doc/manual/install.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,93 @@
+Haizea has been tested only on Unix systems, and these installation instructions are given with a Unix system in mind. However, Haizea includes no platform-specific code, and should run fine on other systems. If there is enough interest, we can produce installers and installation instructions for other platforms.
+
+Installing Haizea can be accomplished in four simple steps:
+
+\section{Install dependencies}
+
+Haizea has a couple of software dependencies. Let's get them out of the way first:
+
+\begin{itemize}
+\item Python 2.5. (\url{http://www.python.org/})
+\item mxDateTime 3.1.0 (\url{http://www.egenix.com/products/python/mxBase/mxDateTime/}), part of the eGenix.com mx Base Distribution).
+\item Optional: pysqlite (\url{http://oss.itsystementwicklung.de/trac/pysqlite/}). This package is only necessary if you want to use the OpenNebula modules.
+\item Optional: Mako Templates for Python 0.2.2 (\url{http://www.makotemplates.org/}). This package is only necessary if you want to automate running multiple simulation experiments (if this doesn't make any sense, you can skip this prerequisite for now; you will be pointed to this prerequisite again in the documentation when you get to running multiple experiments).
+\item Optional: Psyco 1.6 (\url{http://psyco.sourceforge.net/}). This package optimizes the execution of Python code, resulting in the simulation code running much faster. You can skip this prerequisite if you are not going to use Haizea to run simulations, or if you are only going to run short simulations.
+\end{itemize}
+
+Note that mxDateTime, pysqlite, Mako, and Psyco are all available as packages (DEB, RPM, etc.) on most Linux distributions. If you don't install any of the optional dependencies, Haizea will still run fine, but some functionality may not be available, as noted above.
+
+\section{Download Haizea}
+
+Go to the \htmladdnormallink{download page}{http://haizea.cs.uchicago.edu/download.html} and download the latest version of Haizea. This will be a tarball called \texttt{haizea-XXX.tar.gz}, where XXX will be the version number. For the remainder of the instructions, let's assume that you've saved this file in a directory called \texttt{\$HAIZEA\_INST}.
+
+\section{Install Haizea}
+
+Go into directory \texttt{\$HAIZEA\_INST} and un-tar the installation package:
+
+\begin{shellverbatim}
+tar xvzf haizea-XXX.tar.gz
+\end{shellverbatim}
+
+This will create a directory called \texttt{haizea-XXX} in \texttt{\$HAIZEA\_INST}. Go into that directory, and as root, run the following:
+
+\begin{shellverbatim}
+python setup.py install
+\end{shellverbatim}
+
+If you do not have root access, or want to install Haizea in your home directory, run the following:
+
+\begin{shellverbatim}
+python setup.py install --home=\$HOME
+\end{shellverbatim}
+
+Note: If you have never installed a Python package in your home directory before, make sure you set the environment variable \texttt{PYTHONPATH} appropriately so Python will be aware of the Haizea modules.
+
+\begin{shellverbatim}
+export PYTHONPATH=\$HOME/lib/python
+\end{shellverbatim}
+
+After running the setup script, you should see a long list of installation and build messages, ending with the following:
+
+\begin{wideshellverbatim}
+creating /usr/share/haizea/traces/multi
+copying traces/multi/inj1.lwf -> /usr/share/haizea/traces/multi
+copying traces/multi/inj2.lwf -> /usr/share/haizea/traces/multi
+copying traces/multi/withprematureend.lwf -> /usr/share/haizea/traces/multi
+copying traces/multi/withoutprematureend.lwf -> /usr/share/haizea/traces/multi
+running install_egg_info
+Writing /usr/lib/python2.5/site-packages/haizea-TP1.XXX.egg-info
+\end{wideshellverbatim}
+
+If you see this, installation has been successful!
+
+\section{Verify installation}
+
+Haizea includes some sample configuration files and lease request tracefiles that you can use to test Haizea. If you installed Haizea as root, you can run the following to test your installation:
+
+\begin{shellverbatim}
+haizea -c /usr/share/haizea/etc/sample_trace.conf
+\end{shellverbatim}
+
+This will use a sample configuration file to simulate running the scheduler with no requests, resulting in the following (somewhat anticlimactic) output:
+
+\begin{wideshellverbatim}
+[2006-11-25 13:00:00.00] TFILE Loading tracefile /usr/share/haizea/traces/sample.lwf
+[2006-11-25 13:00:00.00] TRACE Loaded workload with 0 requests (0 best-effort + 0 AR)
+[2006-11-25 13:00:00.00] RM Starting resource manager
+[2006-11-25 13:00:00.00] CLOCK Starting simulated clock
+[2006-11-25 13:00:00.00] CLOCK Stopping simulated clock
+[2006-11-25 13:00:00.00] RM Stopping resource manager
+[2006-11-25 13:00:00.00] RM Completed best-effort leases: 0
+[2006-11-25 13:00:00.00] RM Accepted AR leases: 0
+[2006-11-25 13:00:00.00] RM Rejected AR leases: 0
+\end{wideshellverbatim}
+
+Ok, not terribly exciting, but if you see this then the basic machinery is working fine. To see how to do more elaborate simulations, take a look at the Quickstart Guide.
+
+Note: If you installed Haizea in your home directory, you will have to run the following:
+
+\begin{shellverbatim}
+haizea -c \$HOME/share/haizea/etc/sample.conf
+\end{shellverbatim}
+
+Additionally, you will have to modify the tracefile option in the sample configuration so it will point to the sample tracefile located in \texttt{\$HOME/share/haizea/traces/sample.lwf} (instead of under the \texttt{/usr} directory).
\ No newline at end of file
Added: trunk/doc/manual/intro.tex
===================================================================
--- trunk/doc/manual/intro.tex (rev 0)
+++ trunk/doc/manual/intro.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,3 @@
+\section*{What is Haizea?}
+\section*{How to read this manual}
+\section*{Document conventions}
\ No newline at end of file
Added: trunk/doc/manual/manual.tex
===================================================================
--- trunk/doc/manual/manual.tex (rev 0)
+++ trunk/doc/manual/manual.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,86 @@
+\documentclass[a4paper,11pt]{scrbook}
+\usepackage[pdftex]{graphicx}
+\usepackage{url}
+\usepackage{fullpage}
+\usepackage{html}
+\usepackage{notes}
+
+\include{utils}
+
+\begin{document}
+\frontmatter
+\title{The Haizea Manual}
+\author{Borja Sotomayor}
+
+\begin{latexonly}
+\input{title}
+\end{latexonly}
+\begin{htmlonly}
+\maketitle
+\end{htmlonly}
+
+
+\tableofcontents
+
+\chapter{Preface}
+\input{intro}
+
+\mainmatter
+
+\part{Fundamental Concepts}
+
+\chapter{What is Haizea?}
+
+\chapter{Resource leases}
+
+
+\part{Using Haizea}
+
+Foobar foobaz
+
+\chapter{Installing Haizea}
+
+\input{install}
+
+\chapter{Quickstart guide}
+
+\input{quickstart}
+
+\chapter{Running scheduling simulations}
+
+\input{simulation}
+
+\chapter{Haizea and OpenNebula}
+
+\input{opennebula}
+
+\chapter{Analysing scheduling data}
+
+\input{analysing}
+
+
+%\part{Advanced Topics}
+
+%\chapter{Haizea's resource and leasing model}
+
+%\chapter{Scheduling algorithms}
+
+%\chapter{The Haizea architecture}
+
+%\section{Extending Haizea}
+
+\part{Appendices}
+\appendix
+
+\chapter{Command-line interface reference}
+
+\input{appendix_cli}
+
+\chapter{Configuration file reference}
+
+\input{appendix_conf}
+
+\chapter{LWF file format}
+
+
+\end{document}
Added: trunk/doc/manual/opennebula.tex
===================================================================
--- trunk/doc/manual/opennebula.tex (rev 0)
+++ trunk/doc/manual/opennebula.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,289 @@
+OpenNebula is a virtual infrastructure manager that enables the dynamic deployment and re-allocation of virtual machines on a pool of physical resources. Haizea can be used to extend OpenNebula's scheduling capabilities, allowing it to support advance reservation of resources and queuing of best effort requests (more generally, it allows you to lease your resources as VMs, with a variety of lease terms). OpenNebula and Haizea complement each other, since OpenNebula provides all the enactment muscle (OpenNebula can manage Xen and KVM VMs on a cluster, with VMWare support to follow shortly) and Haizea provides the scheduling brains. Using them together is very simple since Haizea can be installed as a drop-in replacement for OpenNebula's scheduling daemon (i.e., you can use the latest version of OpenNebula, without any modifications).
+
+This document explains how to use OpenNebula and Haizea together, and explains how to submit requests to OpenNebula to use Haizea's scheduling capabilities.
+
+NOTE: Although Haizea supports scheduling multiple VMs in parallel (e.g., 16 VMs which must run at the same time, or not at all), the current 1.0 version of OpenNebula only allows VMs to be managed one at a time (OpenNebula 1.2 will include support for "VM groups"). As such, this document only explains how to schedule individual VMs. There is a "dirty hack" way of scheduling groups of VMs with Haizea and OpenNebula 1.0, but we're not including it here since OpenNebula 1.2 will make this issue moot. However, if you really really really need to schedule VMs as groups and can't wait for OpenNebula 1.2, please don't hesitate to contact us.
+
+\begin{warning}
+Please remember that, although we have tested Haizea considerably with OpenNebula 1.0, Haizea is still a technology preview and, thus, not a good choice for production environments (yet). There are a couple of known issues and limitations which are listed at the end of this document. If you need to use OpenNebula in a production environment, and don't need any of Haizea's scheduling features (advance reservations, queuing of requests, etc.), you may want to use OpenNebula's default scheduler instead.
+\end{warning}
+
+\section{Installing OpenNebula and Haizea}
+
+If you have not already done so, you will need to install OpenNebula 1.0 and Haizea Technology Preview 1.1. Start by installing OpenNebula, and then installing Haizea.
+
+Before proceeding, you may want to follow the OpenNebula quickstart guide to verify that your OpenNebula installation is working fine. The rest of this document assumes that OpenNebula is correctly installed, and that you know what a virtual machine template is ("VM templates" is how VMs are requested to OpenNebula, so we'll be working with them quite a bit). You may also want to follow the Haizea Quickstart Guide, to verify that Haizea is correctly installed.
+
+\section{Configuring Haizea}
+
+Haizea must be configured to run in OpenNebula mode. Haizea includes a sample OpenNebula configuration file that you can use as a starting point. This file is installed, by default, in \texttt{/usr/share/haizea/etc/sample\_opennebula.conf}.
+
+In OpenNebula mode, Haizea will process requests coming from OpenNebula, and will send all enactment commands to OpenNebula. To activate this mode, the \texttt{mode} option of the \texttt{general} section in the Haizea configuration file must be set to \texttt{opennebula}:
+
+\begin{wideshellverbatim}
+[general]
+...
+mode: opennebula
+...
+\end{wideshellverbatim}
+
+Next, you need to tell Haizea where the OpenNebula database and \texttt{onevm} command are located. This is done in the \texttt{opennebula} section:
+
+\begin{wideshellverbatim}
+[opennebula]
+# The following assumes that \$ONE_LOCATION is /opt/nebula/ONE
+# If you used a different \$ONE_LOCATION, modify the paths
+# accordingly
+db: /opt/nebula/ONE/var/one.db
+onevm: /opt/nebula/ONE/bin/onevm
+\end{wideshellverbatim}
+
+There are some additional options described at the end of this document, but which you do not need to concern yourself with yet.
+
+\section{Running OpenNebula and Haizea together}
+
+Now that Haizea is configured to run alongside OpenNebula, running them is as simple as starting the OpenNebula daemon:
+
+\begin{wideshellverbatim}
+oned
+\end{wideshellverbatim}
+
+Followed by Haizea:
+
+\begin{wideshellverbatim}
+haizea -c /usr/share/haizea/etc/sample_opennebula.conf
+\end{wideshellverbatim}
+
+Haizea currently always runs in the foreground (a daemon mode will be added in future versions). If you want Haizea to run in the background, you can run it like this:
+
+\begin{wideshellverbatim}
+nohup haizea -c /usr/share/haizea/etc/sample_opennebula.conf 2> /var/tmp/haizea.log &
+\end{wideshellverbatim}
+
+When Haizea starts up, it will print out something like this:
+
+\begin{wideshellverbatim}
+[2008-07-21 11:49:00.63] ONE Fetched N nodes from ONE db
+[2008-07-21 11:49:00.63] RM Starting resource manager
+[2008-07-21 11:49:00.63] CLOCK Starting clock
+\end{wideshellverbatim}
+
+This means that Haizea has correctly started up, accessed OpenNebula's database and detected that there are N physical nodes (the value of N will depend, of course, on how many nodes you have in your system).
+
+\begin{warning}
+Haizea is a drop-in replacement for OpenNebula's default scheduler (\texttt{mm\_sched}). Do not run Haizea and \texttt{mm\_sched} at the same time, or funny things will happen.
+\end{warning}
+
+\section{A quick test}
+
+At this point, OpenNebula and Haizea are both running together, and waiting for you to submit a VM request. From the user's perspective, you will still be submitting your requests to OpenNebula, and Haizea will do all the scheduling work backstage. However, you will be able to add an \texttt{HAIZEA} parameter to your OpenNebula request to access Haizea's features.
+
+So, to test that OpenNebula and Haizea are working correctly, start by taking a known-good OpenNebula template. Just to be on the safe side, you may want to try it with the default scheduler first, to make sure that the VM itself works correctly, etc. Then, just add the following parameter to the template:
+
+\begin{wideshellverbatim}
+HAIZEA = [
+ start = "+00:00:30",
+ duration = "00:01:00",
+ preemptible = "no"
+]
+\end{wideshellverbatim}
+
+The exact meaning of these parameters is explained later on in this document. In a nutshell, the values specified above tell Haizea to schedule the VM to start exactly 30 seconds in the future, to run for one minute, and to not allow the allocated resources to be preempted by other requests. As we will see later on, this is called an "advance reservation" (or AR) request.
+
+Before you submit your request to OpenNebula, take a look at the Haizea log. You should see something like this repeating every minute:
+
+\begin{wideshellverbatim}
+[2008-07-21 11:49:00.63] CLOCK Waking up to manage resources
+[2008-07-21 11:49:00.63] CLOCK Wake-up time recorded as 2008-07-21 11:49:01.00
+[2008-07-21 11:49:00.63] CLOCK Going back to sleep.
+ Waking up at 2008-07-21 11:50:01.00
+ to see if something interesting has happened by then.
+\end{wideshellverbatim}
+
+Haizea is configured, by default, to ask OpenNebula if there are any pending requests every minute. Since you haven't submitted anything, Haizea just wakes up every minute and goes right back to sleep. So, go ahead and submit your request (the one where you added the HAIZEA parameter). Assuming you named the template ar.one, run the following:
+
+\begin{wideshellverbatim}
+onevm submit ar.one
+\end{wideshellverbatim}
+
+If you run \texttt{onevm list} to see the VMs managed by OpenNebula, you'll see that the request is in a \texttt{pending} state:
+
+\begin{wideshellverbatim}
+ ID NAME STAT CPU MEM HOSTNAME TIME
+----------------------------------------------------------
+ 42 test pend 0 0 00 00:00:04
+\end{wideshellverbatim}
+
+Next time Haizea wakes up, you should see something like this:
+
+\begin{wideshellverbatim}
+[2008-07-21 11:50:00.99] CLOCK Waking up to manage resources
+[2008-07-21 11:50:00.99] CLOCK Wake-up time recorded as 2008-07-21 11:50:01.00
+[2008-07-21 11:50:01.03] SCHED Received AR lease request #1, 1 nodes
+ from 2008-07-21 11:50:31.00
+ to 2008-07-21 11:51:31.00.
+[2008-07-21 11:50:01.03] SCHED AR lease request #1 has been accepted.
+[2008-07-21 11:50:01.03] CLOCK Going back to sleep.
+ Waking up at 2008-07-21 11:50:31.00
+ to handle slot table event.
+\end{wideshellverbatim}
+
+Notice how Haizea detected that OpenNebula had an AR request, and then scheduled it to start 30 seconds in the future. In fact, Haizea takes care to wake up at that time so the VM can start at exactly that time.
+
+\begin{warning}
+If you run \texttt{onevm list}, the request will still be shown as \texttt{pending}. OpenNebula doesn't track Haizea's internal states, so it will consider the request "pending" until Haizea starts up the VM. Future versions will provide more information on a VMs state.
+\end{warning}
+
+\begin{warning}
+Currently, Haizea has to poll OpenNebula every minute to ask if there are any new requests. An upcoming version of Haizea will support an event-based model where OpenNebula can send Haizea a notification as soon as a new request is received (so the user doesn't have to wait until the next time Haizea wakes up to process the request).
+\end{warning}
+
+When the VM is scheduled to start, you will see the following in the Haizea logs:
+
+\begin{wideshellverbatim}
+[2008-07-21 11:50:30.99] CLOCK Waking up to manage resources
+[2008-07-21 11:50:30.99] CLOCK Wake-up time recorded as 2008-07-21 11:50:31.00
+[2008-07-21 11:50:31.32] SCHED Started VMs for lease 1 on nodes [1]
+[2008-07-21 11:50:31.32] CLOCK Going back to sleep.
+ Waking up at 2008-07-21 11:51:31.00
+ to handle slot table event.
+\end{wideshellverbatim}
+
+Haizea has instructed OpenNebula to start the VM for the advance reservation. If you run \texttt{onevm list}, the VM will now show up as running:
+
+\begin{wideshellverbatim}
+ ID NAME STAT CPU MEM HOSTNAME TIME
+----------------------------------------------------------
+ 42 test runn 2 262144 ursa03 00 00:01:04
+\end{wideshellverbatim}
+
+You should be able to access the VM (if you configured it with networking and SSH). However, since we requested the VM to run for just a minute, you will soon see the following in the Haizea logs:
+
+\begin{wideshellverbatim}
+[2008-07-21 11:51:31.00] CLOCK Waking up to manage resources
+[2008-07-21 11:51:31.00] CLOCK Wake-up time recorded as 2008-07-21 11:51:31.00
+[2008-07-21 11:51:31.17] SCHED Stopped VMs for lease 1 on nodes [1]
+[2008-07-21 11:51:31.17] CLOCK Going back to sleep.
+ Waking up at 2008-07-21 11:52:31.00
+ to see if something interesting has happened by then.
+\end{wideshellverbatim}
+
+\section{The \texttt{HAIZEA} parameter in OpenNebula}
+
+The previous section showed how you can add an \texttt{HAIZEA} parameter to your OpenNebula VM template to request a simple advance reservation. The three Haizea options (\texttt{start}, \texttt{duration}, and \texttt{preemptible}) can take other values:
+
+\begin{itemize}
+\item \texttt{start}: This option specifies when the VM will start. Valid values are:
+\begin{itemize}
+\item \texttt{best\_effort}: The VM will be scheduled as soon as resources are available. If resources are not available right now, the request is put on a queue and it remains there until there are sufficient resources (requests are scheduled on a first-come-first-serve basis).
+\item \texttt{now}: The VM will be scheduled right now. If resources are not available right now, the request is rejected.
+\item Exact ISO timestamp: i.e., \texttt{YYYY-MM-DD HH:MM:SS}. The VM must start at exactly that time. If enough resources are not available at that time, the resource is not requested.
+\item Relative ISO timestamp: For convenience's sake (and also for testing) this provides an easy way of specifying that a VM must start "at T time after the VM is submitted". The format would be \texttt{+HH:MM:SS} (the "\texttt{+}" is not ISO, but is used by Haizea to determine that it is a relative timestamp)
+\end{itemize}
+\item \texttt{duration}: The duration of the lease. Possible values are:
+\begin{itemize}
+\item \texttt{unlimited}: The lease will run forever, until explicitly stopped
+\item ISO-formatted time: i.e., \texttt{HH:MM:SS}
+\end{itemize}
+\item \texttt{preemptible}: This option can be either yes or no. Haizea currently uses a very simple priority scheme where VMs are either preemptible or non-preemptible (furthermore, a non-preemptible VM can preempt preemptible VMs, while preemptible VMs can't preempt anything). If a VM is preemptible, and a preempting VM needs its resources, then the preemptible VM will be suspended while the preempting VM is running. Future versions of Haizea will include better priority schemes.
+\end{itemize}
+
+Usually, you will want to use these options to create one of Haizea's supported lease types:
+
+\subsection{Advance reservations}
+
+When you need your VM available at a specific time, this is called an advance reservation, or AR. The VM we used above is an example of an AR:
+
+\begin{wideshellverbatim}
+HAIZEA = [
+ start = "+00:00:30",
+ duration = "00:01:00",
+ preemptible = "no"
+]
+\end{wideshellverbatim}
+
+Of course, instead of specifying that you want your VM to start after a certain amount of time has passed (30 seconds, in this case), you can also specify an exact start time:
+
+\begin{wideshellverbatim}
+HAIZEA = [
+ start = "2008-11-04 11:00:00",
+ duration = "03:00:00",
+ preemptible = "no"
+]
+\end{wideshellverbatim}
+
+NOTE: Haizea currently only supports non-preemptible ARs.
+
+\subsection{Best-effort provisioning}
+
+When you instruct Haizea to determine the start time on a best-effort basis, your request will be allocated resources as soon as they become available. Take into account that your request may be placed on a queue, and you'll have to wait until your turn is up (there is currently no way to query the state of the queue, although this functionality will be added soon).
+
+\begin{wideshellverbatim}
+HAIZEA = [
+ start = "best_effort",
+ duration = "01:00:00",
+ preemptible = "yes"
+]
+\end{wideshellverbatim}
+
+A best-effort VM can be preemptible or non-preemptible. If you request a non-preemptible VM, you may still have to wait in the queue until you get your resources but, once you do, no one can take them from you.
+
+\subsection{Immediate provisioning}
+
+Sometimes, you need a VM right now or not at all. In that case, you can set the starting time to \texttt{now}.
+
+\begin{wideshellverbatim}
+HAIZEA = [
+ start = "now",
+ duration = "unlimited",
+ preemptible = "no"
+]
+\end{wideshellverbatim}
+
+\section{Additional OpenNebula configuration options}
+
+When running Haizea with OpenNebula, you must specify at least the \texttt{db} and \texttt{onevm} options in the \texttt{[opennebula]} section of the configuration file. However, there are additional options you can tweak:
+
+\subsection{Wakeup interval}
+
+This is the interval, in seconds, at which Haizea will wake up to process pending requests in OpenNebula. The default is 60 seconds.
+
+\begin{wideshellverbatim}
+[opennebula]
+...
+wakeup-interval: 60
+...
+\end{wideshellverbatim}
+
+\subsection{Suspend/resume rate interval}
+
+This option provides Haizea with an estimate of how long it takes for OpenNebula to suspend or resume a virtual machine. This is estimated in MB per second, and is largely dependent on the disk read/write transfer speeds on your system (so, if a VM has 1024 MB of memory, and the suspend rate is estimated to be 64MB/s, Haizea will estimate that suspension will take 16 seconds). If you do not specify a value, Haizea will conservatively assume a rate of 32MB/s. A good estimate will allow Haizea to more correctly schedule resources, but an incorrect estimation will not result in an error (although a warning will be noted in the logs).
+
+\begin{wideshellverbatim}
+[opennebula]
+...
+suspendresume-rate-estimate: 32
+...
+\end{wideshellverbatim}
+
+\subsection{Non-schedulable interval}
+
+The minimum amount of time that must pass between when a request is scheduled to when it can actually start (i.e., this makes sure that the scheduling function doesn't make reservations with starting times that will be in the past by the time the scheduling function ends). The default (10 seconds) should be good for most configurations, but may need to be increased if you're dealing with exceptionally high loads.
+
+\begin{wideshellverbatim}
+[opennebula]
+...
+non-schedulable-interval: 10
+...
+\end{wideshellverbatim}
+
+\section{Known issues and limitations}
+
+Known issues and limitations when using Haizea with OpenNebula:
+
+\begin{itemize}
+\item As pointed out in this guide, Haizea has to poll OpenNebula every minute to ask if there are any new requests. Additionally, OpenNebula has no way of notifying Haizea of a change of state in a VM (e.g., a VM that died, a suspend operation that finished before expected, etc.). An upcoming version of OpenNebula will add this feature, and Haizea (in turn) will support receiving events from OpenNebula (this includes being instantly notified of new requests, instead of having to poll OpenNebula periodically).
+\item If a command sent to OpenNebula fails, Haizea currently ignores this. This will be fixed in Haizea TP 1.3. Nonetheless, OpenNebula commands run from Haizea shouldn't fail unless you're running incredibly heavy loads, or if you manually shutdown a VM managed by Haizea.
+\item Haizea currently cannot do any image deployment with OpenNebula, and VM images are assumed to be predeployed on the physical nodes, or available on a shared NFS filesystem. An upcoming version of OpenNebula will allow OpenNebula and Haizea to work with a \emph{transfer manager} to handle various VM deployment scenarios.
+\item Haizea cannot enact cold migrations in OpenNebula (i.e., migrating a suspended VM to a different node if resources become available earlier on a different node than the one where the VM was suspended on). Haizea actually has all the scheduling code for this, and only the enactment "glue" is missing (should be added in TP 1.3 or 1.4)
+\end{itemize}
\ No newline at end of file
Added: trunk/doc/manual/quickstart.tex
===================================================================
--- trunk/doc/manual/quickstart.tex (rev 0)
+++ trunk/doc/manual/quickstart.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,239 @@
+This guide provides an introduction to using Haizea in simulation mode. Even if you intend to use Haizea in combination with another system, such as OpenNebula, you may still find this guide useful to familiarize yourself with the Haizea configuration file and command-line interface. This guide assumes that you've downloaded and installed Haizea. Also, make sure you've read the What is Haizea? page before following this guide.
+
+\section{The \texttt{haizea} command}
+
+The main command in the Haizea system is, unsurprisingly, the haizea command. Running this command starts up the Haizea lease manager, which is then ready to receive and schedule lease requests. When running Haizea in simulation mode, lease requests are read from a tracefile, a text file containing a list of lease requests. Based on these requests, the simulator produces a schedule for those leases, which you will be able to follow through the logging messages printed by Haizea. At the end of the simulation, Haizea also saves a fair amount of raw data and statistics to disk which can be used to produce reports and graphs (a module to do this for you is in the works).
+
+When not running in simulation, Haizea runs as a daemon that can accept requests (e.g., through a command-line interface) and sends out enactment commands ("start VM", "stop VM", etc.) to the appropriate enactment module. For example, when running OpenNebula with Haizea as a scheduling backend, Haizea is in charge of processing the requests received by OpenNebula, coming up with a schedule, and then instructing OpenNebula on when VMs should be start/stop/suspend/resume on what physical nodes. A document describing how to use Haizea with OpenNebula will be available soon.
+
+But, anyway, back to how to run Haizea in simulation. The first thing we need to do is to write a configuration file specifying simulation options (e.g., the characteristics of the simulated cluster) and scheduling options.
+
+\section{The configuration file}
+
+A sample configuration file is provided with Haizea and is located in /usr/share/haizea/etc/sample.conf (or \$HOME/share/haizea/etc/sample.conf if you installed Haizea in your home directory). For this guide, you may want to make a copy of this file and use that instead (so you can preserve the original sample file). If you look at the contents of the file, you will see that it also includes documentation on every option. For now, take a look at the following three options:
+
+\begin{wideshellverbatim}
+[simulation]
+starttime: 2006-11-25 13:00:00
+nodes: 4
+resources: CPU,1;Mem,1024;Net (in),100;Net (out),100;Disk,20000
+\end{wideshellverbatim}
+
+These options are used to describe the characteristics of our simulated cluster. In particular, we're using a 4-node cluster, each node with 1 CPU, 1024 MB of memory, 20GB of disk space, and 100Mbps of inbound/outbound network bandwidth. In this document, we will represent this cluster over time like this:
+
+\begin{center}
+\includegraphics{images/quickstart_leasegraph1.png}
+\end{center}
+
+For example, the following figure shows a lease scheduled on Node 1 from 13:00 to 14:00:
+
+\begin{center}
+\includegraphics{images/quickstart_leasegraph2.png}
+\end{center}
+
+The starttime option is used to specify the time at which the simulated clock should start. As you will see, the configuration file has an abundance of other options. We will explain some of them in this document.
+
+\section{The tracefile}
+
+As mentioned earlier, the simulator will read trace requests from a tracefile. The location of this tracefile is specified in the configuration file, in the \texttt{[tracefile]} section:
+
+\begin{wideshellverbatim}
+[tracefile]
+tracefile: /usr/share/haizea/traces/sample.lwf
+\end{wideshellverbatim}
+
+The default value is a sample tracefile included with Haizea. If you copy the file to a different location, make sure to update the tracefile option accordingly. The format of this file is LWF (Lease Workload Format), which is particular to Haizea. The sample file includes documentation on the file format, and several sample workloads. For now, we will focus on the first workload, "PREEMPT":
+
+\begin{wideshellverbatim}
+# 0 -1 3600 3600 1 1 1024 0 foobar.img 1024
+# 900 1800 1800 1800 4 1 1024 0 foobar.img 1024
+\end{wideshellverbatim}
+
+For now, don't worry about parsing the trace format in detail. The above represents two lease requests:
+
+\begin{itemize}
+\item The first line is a request for a best-effort lease, requested at time 0 (right at the start of the simulation), requiring 1 hour (3600 seconds), and only one node.
+\item The second line is an advance reservation (AR) lease, requested 15 minutes into the simulation (900 seconds), starting 30 minutes into the simulation (1800 seconds), requiring 30 minutes (1800 seconds), and all four nodes in the cluster. Since the start time of the simulation is set to 13:00, this means the lease request is received at 13:15, and that the lease must run from 13:30 to 14:00.
+\end{itemize}
+
+Both leases require 1 CPU per node, 1024 MB of memory, a disk image called "foobar.img" (which uses up 1024MB of disk space). The \# characters are used to comment out the lease requests. Do not change this for now.
+
+\section{Running the simulator}
+
+Now that we have a configuration file and a tracefile, we can run the simulator. As shown in the installation guide, you can run Haizea with the sample configuration file like this:
+
+\begin{shellverbatim}
+haizea -c /usr/share/haizea/etc/sample.conf
+\end{shellverbatim}
+
+Which results in the following output:
+
+\begin{wideshellverbatim}
+[2006-11-25 13:00:00.00] TFILE Loading tracefile /usr/share/haizea/traces/sample.lwf
+[2006-11-25 13:00:00.00] TFILE Loaded workload with 0 requests (0 best-effort + 0 AR)
+[2006-11-25 13:00:00.00] RM Starting resource manager
+[2006-11-25 13:00:00.00] CLOCK Starting simulated clock
+[2006-11-25 13:00:00.00] CLOCK Stopping simulated clock
+[2006-11-25 13:00:00.00] RM Stopping resource manager
+[2006-11-25 13:00:00.00] RM Completed best-effort leases: 0
+[2006-11-25 13:00:00.00] RM Accepted AR leases: 0
+[2006-11-25 13:00:00.00] RM Rejected AR leases: 0
+\end{wideshellverbatim}
+
+Now that you've seen the tracefile, you can see why the simulator starts up and immediately stops: all the lease requests in the tracefile are commented out, and there's nothing to schedule. Go ahead and uncomment only the first lease request and run Haizea again. You should now see the following:
+
+\begin{wideshellverbatim}
+[2006-11-25 13:00:00.00] TFILE Loading tracefile /usr/share/haizea/traces/sample.lwf
+[2006-11-25 13:00:00.00] TFILE Loaded workload with 1 requests (1 best-effort + 0 AR)
+[2006-11-25 13:00:00.00] RM Starting resource manager
+[2006-11-25 13:00:00.00] CLOCK Starting simulated clock
+[2006-11-25 13:00:00.00] SCHED Received (and queueing) best-effort lease request #1,
+ 1 nodes for 01:00:00.00.
+[2006-11-25 13:00:00.00] SCHED Next request in the queue is lease 1.
+ Attempting to schedule...
+[2006-11-25 13:00:00.00] SLOT Lease #1 has been scheduled on nodes [1]
+ from 2006-11-25 13:00:00.00
+ to 2006-11-25 14:00:00.00
+[2006-11-25 13:00:00.00] SCHED Started VMs for lease 1 on nodes [1]
+[2006-11-25 14:00:00.00] SCHED Stopped VMs for lease 1 on nodes [1]
+[2006-11-25 14:00:00.00] CLOCK Stopping simulated clock
+[2006-11-25 14:00:00.00] RM Stopping resource manager
+[2006-11-25 14:00:00.00] RM Completed best-effort leases: 1
+[2006-11-25 14:00:00.00] RM Accepted AR leases: 0
+[2006-11-25 14:00:00.00] RM Rejected AR leases: 0
+\end{wideshellverbatim}
+
+The above corresponds to the following schedule:
+
+\begin{center}
+\includegraphics{images/quickstart_leasegraph2.png}
+\end{center}
+
+A best-effort request is received at 13:00 and, since the cluster is empty, it is scheduled immediately. Notice how the VMs for the lease start at 13:00 and stop at 14:00. For now, we're assuming that the disk images are predeployed on the physical nodes (we will modify this option in the next section).
+
+So, what would happen if we also added the AR lease? Since it requires all the cluster resources from 13:30 to 14:00, the best-effort lease will be unable to run in that time interval. Since the leases are implemented as VMs, Haizea will still schedule the best-effort lease to start at 13:00, but will suspend it before the AR lease starts, and will resume it one the AR lease has finished. In effect, we want the schedule to look like this:
+
+\begin{center}
+\includegraphics{images/quickstart_leasegraph3.png}
+\end{center}
+
+Uncomment the AR lease request, and run Haizea again. You should now see the following (for clarity, log messages pertaining to the best-effort lease are highlighted in green, and those pertaining to the AR lease are highlighted in brown):
+
+\begin{wideshellverbatim}
+[2006-11-25 13:00:00.00] TRACE Loading tracefile /usr/share/haizea/traces/sample.lwf
+[2006-11-25 13:00:00.00] TRACE Loaded workload with 2 requests (1 best-effort + 1 AR)
+[2006-11-25 13:00:00.00] RM Starting resource manager
+[2006-11-25 13:00:00.00] CLOCK Starting simulated clock
+[2006-11-25 13:00:00.00] SCHED Received (and queueing) best-effort lease request #1,
+ 1 nodes for 01:00:00.00.
+[2006-11-25 13:00:00.00] SCHED Next request in the queue is lease 1.
+ Attempting to schedule...
+[2006-11-25 13:00:00.00] SLOT Lease #1 has been scheduled on nodes [1]
+ from 2006-11-25 13:00:00.00
+ to 2006-11-25 14:00:00.00
+[2006-11-25 13:00:00.00] SCHED Started VMs for lease 1 on nodes [1]
+
+[2006-11-25 13:15:00.00] SCHED Received AR lease request #2, 4 nodes
+ from 2006-11-25 13:30:00.00
+ to 2006-11-25 14:00:00.00.
+[2006-11-25 13:15:00.00] SCHED Must preempt leases [1] to make room for AR lease #2
+[2006-11-25 13:15:00.00] SCHED Preempting lease #1...
+[2006-11-25 13:15:00.00] SCHED ... lease #1 will be suspended
+ at 2006-11-25 13:30:00.00.
+[2006-11-25 13:15:00.00] SCHED AR lease request #2 has been accepted.
+
+[2006-11-25 13:29:39.00] SCHED Stopped VMs for lease 1 on nodes [1]
+[2006-11-25 13:29:39.00] SCHED Suspending lease 1...
+
+[2006-11-25 13:30:00.00] SCHED Lease 1 suspended.
+[2006-11-25 13:30:00.00] SCHED Started VMs for lease 2 on nodes [2, 3, 4, 1]
+[2006-11-25 13:30:00.00] SCHED Next request in the queue is lease 1.
+ Attempting to schedule...
+[2006-11-25 13:30:00.00] SLOT Lease #1 has been scheduled on nodes [1]
+ from 2006-11-25 14:00:21.00 (resuming)
+ to 2006-11-25 14:30:42.00
+
+[2006-11-25 14:00:00.00] SCHED Stopped VMs for lease 2 on nodes [2, 3, 4, 1]
+[2006-11-25 14:00:00.00] SCHED Resuming lease 1...
+
+[2006-11-25 14:00:21.00] SCHED Resumed lease 1
+[2006-11-25 14:00:21.00] SCHED Started VMs for lease 1 on nodes [1]
+
+[2006-11-25 14:30:42.00] SCHED Stopped VMs for lease 1 on nodes [1]
+[2006-11-25 14:30:42.00] CLOCK Stopping simulated clock
+[2006-11-25 14:30:42.00] RM Stopping resource manager
+[2006-11-25 14:30:42.00] RM Completed best-effort leases: 1
+[2006-11-25 14:30:42.00] RM Accepted AR leases: 1
+[2006-11-25 14:30:42.00] RM Rejected AR leases: 0
+\end{wideshellverbatim}
+
+Notice how the above corresponds to the previous figure. In particular, notice the following:
+
+\begin{itemize}
+ \item When the AR lease request is received, Haizea looks at the schedule and determines that the only way to schedule the AR lease is to preempt the best-effort lease. However, instead of canceling that lease, it will just reschedule it so it is suspended right before the AR lease start. Note that Haizea will always try to minimize the number of preemption (in this case, we're forcing the situation for demonstration purposes) by assigning the AR lease to resources that are available without preempting other leases.
+ \item Shortly before the AR lease starts, the best-effort lease is suspended (the time required to do this is estimated by Haizea based on an option in the configuration file). When the AR lease ends at 14:00, Haizea begins resuming the suspended best-effort lease.
+\end{itemize}
+
+\section{The scheduling options}
+
+Haizea has several scheduling options that control how Haizea selects resources and schedules leases. For example, the above example assumed that leases can be suspended (which they generally always can be when running as virtual machines). What would happen if this were not possible? You can modify the suspension option in the [scheduling] section to find out:
+
+[scheduling]
+...
+
+suspension: none
+
+...
+
+Rerun Haizea. Now, when the AR lease arrives at 13:15, the scheduler will realize it has to preempt the best-effort lease to make room for the AR lease, but will no longer be able to suspend it. The only option is to cancel the best-effort lease and resubmit it to the queue:
+
+\begin{wideshellverbatim}
+[2006-11-25 13:15:00.00] SCHED Preempting lease #1...
+[2006-11-25 13:15:00.00] SCHED ... lease #1 has been cancelled and requeued
+ (cannot be suspended)
+\end{wideshellverbatim}
+
+Now, the best-effort lease can only be scheduled after the AR lease, at 14:00:
+
+\begin{wideshellverbatim}
+[2006-11-25 13:15:00.00] SLOT Lease #1 has been scheduled on nodes [1]
+ from 2006-11-25 14:00:00.00
+ to 2006-11-25 15:00:00.00
+\end{wideshellverbatim}
+
+So, the schedule would end up looking like this:
+
+\begin{center}
+\includegraphics{images/quickstart_leasegraph4.png}
+\end{center}
+
+Notice how, although suspending a lease is a disruptive activity which can delay the completion time of a best-effort request, it is still much better than completely canceling a request and waiting for enough resources to accommodate the entire (uninterrupted) duration of the lease.
+
+Another scheduling option you can modify is whether Haizea should transfer the VM's disk image from an image repository before the lease can start. You can do this by modifying the lease-deployment option:
+
+\begin{wideshellverbatim}
+[general]
+...
+lease-deployment: imagetransfer
+...
+\end{wideshellverbatim}
+
+If you look at the bottom of the sample configuration file, you will find a section called \texttt{[deploy-imagetransfer]} with all the image transfer options.
+
+Rerun Haizea again. You should get a schedule similar to the previous one, but with some extra messages indicating that image transfers are taking place:
+
+[2006-11-25 13:00:00.00] SCHED Starting image transfer for lease 1
+[2006-11-25 13:01:22.00] SCHED Completed image transfer for lease 1
+
+As you can see, the best-effort lease can no longer start right at 13:00, since an image transfer has to take place before the starting time. The same is true of the AR lease, but notice how Haizea schedules the image transfer in such a way that the AR lease can still start at 13:30 as planned (instead of delaying the starting time until 13:31:22).
+
+There are several other options you can modify in the [scheduling] section, such as what backfilling algorithm to use, whether to allow lease migration or not, etc. See the description of these option in the sample configuration file for more details.
+Other things you can do with Haizea
+
+At this point, you can run simple simulations with Haizea. However, there is a lot more that you can do with Haizea:
+
+\begin{itemize}
+\item Run on real hardware: First and foremost, everything you just saw above in simulation can be done on real hardware. This is accomplished by using Haizea with the OpenNebula virtual infrastructure manager. So, if you have a Xen or KVM cluster, you can just install OpenNebula and Haizea to enable your users to request VM-based leases on your cluster.
+\item Run complex simulations: The above shows only two leases on a 4-node cluster during a span of roughly 2 hours. Boring. Haizea can handle more complex simulations, and also provides the necessary tools for you to easily run multiple simulations with different profiles. For example, in the Haizea paper Combining Batch Execution and Leasing Using Virtual Machines we simulated running 72 30-day workloads in six different configurations, or 36 years of lease scheduling. To set up this kind of simulations, take a look at the Running Multiple Simulation Experiments with Haizea document.
+\item Produce reports and graphs: The above examples relied on you reading the Haizea log messages, which is ok for a simple simulation, but no fun when you're scheduling thousands of leases. Haizea saves a fair amount of raw data to disk with scheduling metrics, utilization information, etc. which can be used to generate reports and graphs. We are in the process of producing tools that will allow you to easily analyse that data and create graphs.
+\end{itemize}
\ No newline at end of file
Added: trunk/doc/manual/simulation.tex
===================================================================
--- trunk/doc/manual/simulation.tex (rev 0)
+++ trunk/doc/manual/simulation.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,63 @@
+
+\section{Interactive simulations}
+
+\section{Unattended simulations}
+
+\section{Scheduling options}
+
+\section{Running multiple unattended simulations}
+
+Haizea's regular configuration file (the one that is provided to the haizea command) allows for, at most, one tracefile to be used. However, when running simulations, it is often necessary to run through multiple tracefiles in a variety of configurations to compare the results of each tracefile/configuration combination. The "multi-configuration" file allows you to easily do just this. It is similar to the regular configuration file (all the options are the same), but it allows you to specify multiple tracefiles and multiple configuration profiles.
+
+The multi-configuration file must contain a section called "\texttt{multi}" where you must specify the following:
+
+\begin{itemize}
+\item The tracefiles you want to use
+\item The "injected tracefiles" you want to use. In our own experiments, we found that it was easier to create workloads starting from a base workload and then "injecting" different types of workloads (e.g., a base workload of best-effort leases where AR leases of varying characteristics are "injected"). You can, of course, not specify any injected tracefiles.
+\item The directory where Haizea should store all the information it collects during the simulation (scheduling metrics, utilization information, etc.)
+\end{itemize}
+
+The [multi] section should look like this:
+
+\begin{wideshellverbatim}
+[multi]
+tracedir: Directory with tracefiles
+tracefiles: Tracefiles to use in experiments
+injectiondir: Directory with injectable tracefiles
+injectionfiles: Injectable tracefiles
+basedatadir: Directory where raw data will be saved
+\end{wideshellverbatim}
+
+Next, for each section you would ordinarily include in a regular configuration file, you can include common options (shared by all profiles) and profile-specific options. For example, assuming you want to specify options in the general and simulation sections, and you want to create two profiles called nobackfilling and withbackfilling, you would have to create the following sections:
+
+\begin{wideshellverbatim}
+[common:general]
+...
+
+[common:simulation]
+...
+
+[nobackfilling:general]
+...
+
+[nobackfilling:simulation]
+...
+
+[withbackfilling:general]
+...
+
+[withbackfilling:simulation]
+...
+\end{wideshellverbatim}
+
+An example multi-configuration file is provided in /usr/share/haizea/etc/sample-multi.conf. Using this file, or once you've created your own, you can use the haizea-generate-configs to create the individual configuration files (one for every combination of tracefile, injected tracefile, and profile):
+
+\begin{wideshellverbatim}
+haizea-generate-configs -c config -d dir
+\end{wideshellverbatim}
+
+The -c parameter is used to specify the multi-config file, and the -d parameter is used to specify where the configuration files should be created. Since running each configuration individually would be cumbersome, you can also use the haizea-generate-script command to generate a script that will run through all the generated configuration files. This command requires Mako Templates for Python, so make sure you install Mako before using haizea-generate-scripts. Haizea currently includes two script templates: one to generate a BASH script that will call haizea with each individual configuration file, and one to generate a basic Condor submission script. For example, to generate the BASH script, you would run the command like this:
+
+\begin{wideshellverbatim}
+haizea-generate-scripts -c config -d dir -t /usr/share/haizea/etc/run.sh.template
+\end{wideshellverbatim}
Added: trunk/doc/manual/title.tex
===================================================================
--- trunk/doc/manual/title.tex (rev 0)
+++ trunk/doc/manual/title.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,26 @@
+\newcommand{\HRule}{\rule{\linewidth}{0.5mm}}
+
+\begin{titlepage}
+
+\begin{center}
+
+% Title
+\HRule \\[0.4cm]
+\includegraphics[width=0.6\textwidth]{images/haizea.png}\\[1cm]
+\textsc{ \huge Haizea Manual}\\[0.4cm]
+
+\HRule \\[1.5cm]
+\url{http://haizea.cs.uchicago.edu/}
+
+\vfill
+
+\begin{flushright} \large
+Borja Sotomayor\\
+Department of Computer Science\\
+University of Chicago\\
+\texttt{borja at cs.uchicago.edu}
+\end{flushright}
+
+\end{center}
+
+\end{titlepage}
Added: trunk/doc/manual/utils.tex
===================================================================
--- trunk/doc/manual/utils.tex (rev 0)
+++ trunk/doc/manual/utils.tex 2008-08-28 15:16:06 UTC (rev 472)
@@ -0,0 +1,34 @@
+\usepackage[pdftex]{color}
+\usepackage{fancybox}
+\usepackage{fancyvrb}
+
+\newcommand{\htmldiv}[2]{\HTMLcode[id="#1"]{div}{#2}}
+
+%%
+%% COLOR
+%%
+
+\definecolor{backgroundgray}{gray}{0.9}
+
+%%
+%% FANCYVRB
+%%
+
+% Las tabulaciones se substituyen por dos espacios
+\fvset{tabsize=2}
+
+% Creamos un nuevo environment de fancyvrb para los ejemplos enmarcados
+\DefineVerbatimEnvironment{VerbShell}{BVerbatim}{boxwidth=0.8\textwidth,fontsize=\small,samepage=true,commandchars=\\\{\}}
+\DefineVerbatimEnvironment{VerbWideShell}{BVerbatim}{boxwidth=1\textwidth,fontsize=\small,commandchars=\\\{\}}
+
+\newenvironment{shellverbatim}%
+{\VerbatimEnvironment\begin{Sbox}\begin{VerbShell}}%
+{\end{VerbShell}\end{Sbox}\setlength{\fboxsep}{8pt}\begin{center}\fcolorbox{black}{backgroundgray}{\TheSbox}\end{center}}
+
+\newenvironment{wideshellverbatim}%
+{\VerbatimEnvironment\begin{Sbox}\begin{VerbWideShell}}%
+{\end{VerbWideShell}\end{Sbox}\setlength{\fboxsep}{8pt}\begin{center}\fcolorbox{black}{backgroundgray}{\TheSbox}\end{center}}
+
+\newenvironment{warning}
+{\latexhtml{\begin{importantnote}}{\begin{rawhtml}<div class='warning'>\end{rawhtml}}}
+{\latexhtml{\end{importantnote}}{\begin{rawhtml}</div>\end{rawhtml}}}
Modified: trunk/html/doc_multiple.html
===================================================================
--- trunk/html/doc_multiple.html 2008-08-07 17:03:06 UTC (rev 471)
+++ trunk/html/doc_multiple.html 2008-08-28 15:16:06 UTC (rev 472)
@@ -22,91 +22,16 @@
<a href="support.html">Support</a> |
<a href="pubs.html">Publications</a> |
<a href="credits.html">Credits</a></div>
-<h1>Running Multiple Simulation Experiments</h1>
+<h1>The Haizea Manual</h1>
-<p>
-Haizea's regular configuration file (the one that is provided
-to the <tt>haizea</tt> command) allows for, at most, one tracefile to
-be used. However, when running simulations, it is often necessary
-to run through multiple tracefiles in a variety of configurations to
-compare the results of each tracefile/configuration combination.
-The "multi-configuration" file allows you to easily do just this.
-It is similar to the regular configuration file (all the options
-are the same), but it allows you to specify multiple tracefiles
-and multiple configuration profiles.
-</p>
+<div class="center">
+<object data="manual/index.html" type="text/html" width="750" height="500" id="manualframe">
+ alt : <a href="manual/index.html">test.html</a>
+</object>
+</div>
<p>
-The multi-configuration file must contain a section called "multi"
-where you must specify the following:
</p>
-
-<ul>
-<li>The tracefiles you want to use</li>
-<li>The "injected tracefiles" you want to use. In our own experiments, we found that it was easier to create workloads starting from a base workload and then "injecting" different types of workloads (e.g., a base workload of best-effort leases where AR leases of varying characteristics are "injected"). You can, of course, not specify any injected tracefiles.</li>
-<li>The directory where Haizea should store all the information it collects during the simulation (scheduling metrics, utilization information, etc.)</li>
-</ul>
-
-<p>The <tt>[multi]</tt> section should look like this:</p>
-
-<pre class="shell">
-[multi]
-tracedir: <em>Directory with tracefiles</em>
-tracefiles: <em>Tracefiles to use in experiments</em>
-injectiondir: <em>Directory with injectable tracefiles</em>
-injectionfiles: <em>Injectable tracefiles</em>
-basedatadir: <em>Directory where raw data will be saved</em>
-</pre>
-
-<p>
-Next, for each section you would ordinarily include
-in a regular configuration file, you can include common options
-(shared by all profiles) and profile-specific options. For example,
-assuming you want to specify options in the <tt>general</tt> and
-<tt>simulation</tt> sections, and you want to create two profiles
-called <tt>nobackfilling</tt> and <tt>withbackfilling</tt>, you would
-have to create the following sections:
-</p>
-
-<pre class="shell">
-[common:general]
-...
-
-[common:simulation]
-...
-
-[nobackfilling:general]
-...
-
-[nobackfilling:simulation]
-...
-
-[withbackfilling:general]
-...
-
-[withbackfilling:simulation]
-...
-</pre>
-
-<p>
-An example multi-configuration file is provided in <tt>/usr/share/haizea/etc/sample-multi.conf</tt>. Using this file, or once you've created your own, you can use the <tt>haizea-generate-configs</tt> to create the individual configuration files (one for every combination of tracefile, injected tracefile, and profile):
-</p>
-
-<pre class="shell">
-haizea-generate-configs -c <em>config</em> -d <em>dir</em>
-</pre>
-
-<p>
-The <tt>-c</tt> parameter is used to specify the multi-config file, and the <tt>-d</tt> parameter is used to specify where the configuration files should be created. Since running each configuration individually would be cumbersome, you can
-also use the <tt>haizea-generate-script</tt> command to generate a script that will run through all the generated configuration files. This command requires <a href="http://www.makotemplates.org/">Mako Templates for Python</a>, so make sure you install Mako before using <tt>haizea-generate-scripts</tt>. Haizea currently includes two script templates: one to generate a BASH script that will call <tt>haizea</tt> with each individual configuration file, and one to generate a basic Condor submission script. For example, to generate the BASH script, you would run the command like this:
-</p>
-
-<pre class="shell">
-haizea-generate-scripts -c <em>config</em> -d <em>dir</em> -t /usr/share/haizea/etc/run.sh.template
-</pre>
-
-<p>
-</p>
<table border="0" align="center">
<tr>
<td>
Modified: trunk/html/documentation.html
===================================================================
--- trunk/html/documentation.html 2008-08-07 17:03:06 UTC (rev 471)
+++ trunk/html/documentation.html 2008-08-28 15:16:06 UTC (rev 472)
@@ -24,7 +24,35 @@
<a href="credits.html">Credits</a></div>
<h1>Documentation</h1>
+<h2>Getting started</h2>
+
+<p>Most of the documentation is contained in the Haizea Manual (see below). However, to get started, you may want to start by reading the <a href="whatis.html">What is Haizea?</a> page, and then skip straight to the following sections of the manual, which can be read as standalone sections:</p>
+
<ul>
+<li><a href="#">Installing Haizea</a></li>
+<li><a href="#">Haizea Quickstart Guide</a></li>
+<li><a href="#">Using OpenNebula and Haizea to manage VMs on a cluster</a><br/>
+</ul>
+
+<h2>The Haizea Manual</h2>
+
+<p>The Haizea Manual includes (almost) everything you need to know about using Haizea. You can read it in the following formats:</p>
+
+<ul>
+<li><a href="doc_multiple.html">Multiple HTML pages</a> (one page per section)</li>
+<li><a href="manual_single/index.html">A single HTML document</li>
+<li><a href="haizea_manual.pdf">PDF</a></li>
+</ul>
+
+<h2>Scholarly publications</h2>
+
+<p>We have a couple publications that talk about the more theoretical concepts behind Haizea. You can read them in our <a href="pubs.html">publications</a> page.</p>
+
+<h2>Still need help?</h2>
+
+<p>Do you have a question that is not answered in the documentation? Just send a message to our <a href="support.html">mailing list</a> and we'll try to help you out.</p>
+<!--
+<ul>
<li><a href="whatis.html">What is Haizea?</a></li>
<li><a href="doc_install.html">Installing Haizea</a></li>
<li><a href="doc_quickstart.html">Haizea Quickstart Guide</a></li>
@@ -34,8 +62,9 @@
<li><a href="doc_arch.html">The Haizea Architecture</a></li>
<li><a href="changelog.html">Changelog</a></li>
<li><a href="doc_roadmap.html">Roadmap</a></li>
-<!--<li><a href="doc_extending.html">Extending Haizea</a></li>-->
+<li><a href="doc_extending.html">Extending Haizea</a></li>
</ul>
+-->
<div class="back">
<a href="index.html">
Modified: trunk/html/haizea.css
===================================================================
--- trunk/html/haizea.css 2008-08-07 17:03:06 UTC (rev 471)
+++ trunk/html/haizea.css 2008-08-28 15:16:06 UTC (rev 472)
@@ -155,3 +155,7 @@
padding:10px 30px 30px 30px;
float:right;
}
+
+#manualframe {
+ border: 1px solid #999;
+}
More information about the Haizea-commit
mailing list