xend: Add support for URI ('file:' and 'data:' scheme) for PV/kernel and PV/ramdisk

Add support for 'file:' and 'data:' URI schemes for the parameters
'PV/kernel' and 'PV/ramdisk' in the VM.create() call.  The 'data:'
scheme handling enables using a file which is stored inside the
management system (from where the XenAPI call is send) as kernel or
ramdisk.

Notes:
o all included: a detailed description can be found in the xenapi
documentation
o bumped up the version of the API document to 1.0.8 (because of
(minimal) interface extension)
o Future enhancements (like http:, ftp: schemes) fit seamlessly into
the current design / classes

Signed-off-by: Andreas Florath <xen@flonatel.org>

5 files changed, 115 insertions, 45 deletions

diff --git a/docs/xen-api/bibliography.tex b/docs/xen-api/bibliography.tex
new file mode 100644
index 0000000000..30df3875b2
--- /dev/null
+++ b/docs/xen-api/bibliography.tex
@@ -0,0 +1,5 @@
+\begin{thebibliography}{9}
+\bibitem[RFC2397]{RFC2397}
+Masinter L., \textbf{The "data" URL scheme}, RFC 2397, August 1998,
+Network Working Group, http://www.ietf.org/rfc/rfc2397.txt
+\end{thebibliography}
diff --git a/docs/xen-api/revision-history.tex b/docs/xen-api/revision-history.tex
index 2e41b38581..ef214af16c 100644
--- a/docs/xen-api/revision-history.tex
+++ b/docs/xen-api/revision-history.tex
@@ -1,69 +1,49 @@
 { \bf Revision History}
 
+% Please do not use minipages in a tabular environment; this results
+% in bad vertical alignment. 
+
+\begin{flushleft}
 \begin{center}
- \begin{tabular}{|l|l|l|l|}
+ \begin{tabular}{|l|l|l|>{\raggedright}p{7cm}|}
   \hline
   1.0.0 & 27th April 07 & Xensource et al. &
-   \begin{minipage}[t][.7cm]{7cm}
-     Initial Revision
-   \end{minipage}\\
+     Initial Revision\tabularnewline
   \hline
   1.0.1 & 10th Dec. 07 & S. Berger &
-   \begin{minipage}[t]{7cm}
-    \begin{flushleft}
      Added XSPolicy.reset\_xspolicy, VTPM.get\_other\_config,
-     VTPM.set\_otherconfig. ACMPolicy.get\_enforced\_binary methods.
-    \end{flushleft}
-   \end{minipage}\\
+     VTPM.set\_otherconfig. ACMPolicy.get\_enforced\_binary methods.\tabularnewline
   \hline
   1.0.2 & 25th Jan. 08 & J. Fehlig &
-   \begin{minipage}[t]{7cm}
-    \begin{flushleft}
-     Added Crashed VM power state.
-    \end{flushleft}
-   \end{minipage}\\
+     Added Crashed VM power state.\tabularnewline
   \hline
   1.0.3 & 11th Feb. 08 & S. Berger &
-   \begin{minipage}[t]{7cm}
-    \begin{flushleft}
-     Added table of contents and hyperlink cross reference.
-    \end{flushleft}
-   \end{minipage}\\
+     Added table of contents and hyperlink cross reference.\tabularnewline
   \hline
   1.0.4 & 23rd March 08 & S. Berger &
-   \begin{minipage}[t]{7cm}
-    \begin{flushleft}
-     Added XSPolicy.can\_run
-    \end{flushleft}
-   \end{minipage}\\
+     Added XSPolicy.can\_run\tabularnewline
   \hline
   1.0.5 & 17th Apr. 08 & S. Berger &
-   \begin{minipage}[t]{7cm}
-    \begin{flushleft}
      Added undocumented fields and methods for default\_netmask and
      default\_gateway to the Network class. Removed an unimplemented
      method from the XSPolicy class and removed the 'optional' from
-     'oldlabel' parameters.
-    \end{flushleft}
-   \end{minipage}\\
+     'oldlabel' parameters.\tabularnewline
   \hline
   1.0.6 & 24th Jul. 08 & Y. Iwamatsu &
-   \begin{minipage}[t]{7cm}
-    \begin{flushleft}
      Added definitions of new classes DPCI and PPCI. Updated the table
      and the diagram representing relationships between classes.
-     Added host.PPCIs and VM.DPCIs fields.
-    \end{flushleft}
-   \end{minipage}\\
+     Added host.PPCIs and VM.DPCIs fields.\tabularnewline
   \hline
   1.0.7 & 20th Oct. 08 & M. Kanno &
-   \begin{minipage}[t]{7cm}
-    \begin{flushleft}
      Added definitions of new classes DSCSI and PSCSI. Updated the table
      and the diagram representing relationships between classes.
-     Added host.PSCSIs and VM.DSCSIs fields.
-    \end{flushleft}
-   \end{minipage}\\
+     Added host.PSCSIs and VM.DSCSIs fields.\tabularnewline
+  \hline
+  1.0.8 & 17th Jun. 09 & A. Florath &
+     Updated interactive session example.
+     Added description for \texttt{PV/kernel} and \texttt{PV/ramdisk}
+     parameters using URIs.\tabularnewline
   \hline
  \end{tabular}
 \end{center}
+\end{flushleft}
diff --git a/docs/xen-api/xenapi-coversheet.tex b/docs/xen-api/xenapi-coversheet.tex
index 231afed091..42b4ebd07b 100644
--- a/docs/xen-api/xenapi-coversheet.tex
+++ b/docs/xen-api/xenapi-coversheet.tex
@@ -17,12 +17,12 @@
 \newcommand{\coversheetlogo}{xen.eps}
 
 %% Document date
-\newcommand{\datestring}{20th October 2008}
+\newcommand{\datestring}{17th June 2009}
 
 \newcommand{\releasestatement}{Stable Release}
 
 %% Document revision
-\newcommand{\revstring}{API Revision 1.0.7}
+\newcommand{\revstring}{API Revision 1.0.8}
 
 %% Document authors
 \newcommand{\docauthors}{
diff --git a/docs/xen-api/xenapi-datamodel.tex b/docs/xen-api/xenapi-datamodel.tex
index 6eb2a41e06..fb76ade6bf 100644
--- a/docs/xen-api/xenapi-datamodel.tex
+++ b/docs/xen-api/xenapi-datamodel.tex
@@ -1,5 +1,6 @@
 %
 % Copyright (c) 2006-2007 XenSource, Inc.
+% Copyright (c) 2009 flonatel GmbH & Co. KG
 %
 % Permission is granted to copy, distribute and/or modify this document under
 % the terms of the GNU Free Documentation License, Version 1.2 or any later
@@ -9,6 +10,7 @@
 % "GNU Free Documentation License" or the file fdl.tex.
 %
 % Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
+% Contributor: Andreas Florath
 %
 
 \chapter{API Reference}
@@ -1378,10 +1380,10 @@ the batch of events
 \newpage
 \section{Class: VM}
 \subsection{Fields for class: VM}
-\begin{longtable}{|lllp{0.38\textwidth}|}
+\begin{longtable}{|llp{0.21\textwidth}p{0.33\textwidth}|}
 \hline
 \multicolumn{1}{|l}{Name} & \multicolumn{3}{l|}{\bf VM} \\
-\multicolumn{1}{|l}{Description} & \multicolumn{3}{l|}{\parbox{11cm}{\em A
+\multicolumn{4}{|l|}{\parbox{11cm}{\em Description: A
 virtual machine (or 'guest').}} \\
 \hline
 Quals & Field & Type & Description \\
@@ -1413,8 +1415,8 @@ $\mathit{RO}_\mathit{run}$ &  {\tt VTPMs} & (VTPM ref) Set & virtual TPMs \\
 $\mathit{RO}_\mathit{run}$ &  {\tt DPCIs} & (DPCI ref) Set & pass-through PCI devices \\
 $\mathit{RO}_\mathit{run}$ &  {\tt DSCSIs} & (DSCSI ref) Set & half-virtualized SCSI devices \\
 $\mathit{RW}$ &  {\tt PV/bootloader} & string & name of or path to bootloader \\
-$\mathit{RW}$ &  {\tt PV/kernel} & string & path to the kernel \\
-$\mathit{RW}$ &  {\tt PV/ramdisk} & string & path to the initrd \\
+$\mathit{RW}$ &  {\tt PV/kernel} & string & URI of kernel \\
+$\mathit{RW}$ &  {\tt PV/ramdisk} & string & URI of initrd \\
 $\mathit{RW}$ &  {\tt PV/args} & string & kernel command-line arguments \\
 $\mathit{RW}$ &  {\tt PV/bootloader\_args} & string & miscellaneous arguments for the bootloader \\
 $\mathit{RW}$ &  {\tt HVM/boot\_policy} & string & HVM boot policy \\
@@ -1429,6 +1431,87 @@ $\mathit{RO}_\mathit{run}$ &  {\tt guest\_metrics} & VM\_guest\_metrics ref & me
 $\mathit{RO}_\mathit{run}$ &  {\tt security/label} & string & the VM's security label \\
 \hline
 \end{longtable}
+\subsection{Parameter Details}
+\subsubsection{PV/kernel and PV/ramdisk}
+The \texttt{PV/kernel} and \texttt{PV/ramdisk} parameters should be
+specified as URIs with either a \texttt{file} or \texttt{data} scheme.
+
+The \texttt{file} scheme must be used when a file on the remote dom0
+should be used.  The remote dom0 is the one where the guest system
+should be started on. Only absolute filenames are supported, i.e. the
+string must start with \texttt{file://} appended with the absolute
+path.  This is typically used when the guest system use the same
+operating systems as the dom0 or there is some kind of shared storage
+for the images inside the dom0s.
+
+Note that for compatibility reasons it is possible --- but not
+recommended --- to leave out the scheme specification for
+\texttt{file}, i.e. \texttt{file:///some/path} and \texttt{/some/path}
+is equivalent.
+
+Examples (in python):
+
+Use kernel image which resides in the \texttt{/boot} directory:
+\begin{verbatim}
+xenapi.VM.create({ ...
+   'PV_kernel': 'file:///boot/vmlinuz-2.6.26-2-xen-686',
+   ... })
+\end{verbatim}
+
+Use ramdisk image which resides on a (shared) nfs directory:
+\begin{verbatim}
+xenapi.VM.create({ ...
+   'PV_ramdisk': 'file:///nfs/xen/debian/5.0.1/initrd.img-2.6.26-2-xen-686'
+   ... })
+\end{verbatim}
+
+When an image should be used which resides on the local system,
+i.e. the system where the XenAPI call is send from, it is possible to
+use the \texttt{data} URI scheme as described in \cite{RFC2397}.  The
+media-type must be set to \texttt{application/octet-stream}.
+Currently only base64 encoding is supported.  The URI must therefore
+start with \texttt{data:application/octet-stream;base64,} followed by
+the base64 encoded image.
+
+The \texttt{xen/util/fileuri.py} provides a helper function which
+takes a local filename as parameter and build up the correct URI from
+this.
+
+Examples (in python):
+
+Use kernel image specified inline:
+\begin{verbatim}
+xenapi.VM.create({ ...
+   'PV_kernel': 'data:application/octet-stream;base64,H4Zu....'
+      # most of base64 encoded data is omitted 
+   ... })
+\end{verbatim}
+
+Using the utility function:
+\begin{verbatim}
+from xen.util.fileuri import scheme_data
+xenapi.VM.create({ ...
+   'PV_kernel': scheme_data.create_from_file(
+       "/xen/guests/images/debian/5.0.1/vmlinuz-2.6.26-2-xen-686"),
+   ... })
+\end{verbatim}
+
+Currently when using the \texttt{data} URI scheme, a temporary file is
+created on the remote dom0 in the directory
+\texttt{/var/run/xend/boot} which is then used for booting. When not
+used any longer the file is deleted.  (Therefore reading of the
+\texttt{PV/kernel} or \texttt{PV/ramdisk} parameters when created with
+a \texttt{data} URI scheme returns a filename to a temporary file ---
+which might even not exists when querying.)  This implementation might
+change in the way that the data is directly used --- without the
+indirection using a file.  Therefore do not rely on the data resulting
+from a read of a variables which was set using the \texttt{data}
+scheme.
+
+Note: a mix of different schemes for the parameters is possible; e.g.
+the kernel can be specified with a \texttt{file} and the ramdisk with
+the \texttt{data} URI scheme.
+
 \subsection{RPCs associated with class: VM}
 \subsubsection{RPC name:~clone}
 
diff --git a/docs/xen-api/xenapi.tex b/docs/xen-api/xenapi.tex
index 902d9b2daf..68e68fae61 100644
--- a/docs/xen-api/xenapi.tex
+++ b/docs/xen-api/xenapi.tex
@@ -18,6 +18,7 @@
 \usepackage{longtable}
 \usepackage{fancyhdr}
 \usepackage{hyperref}
+\usepackage{array}
 
 \setlength\topskip{0cm}
 \setlength\topmargin{0cm}
@@ -54,5 +55,6 @@ Xen-enabled host.
 \include{vm-lifecycle}
 \include{xenapi-datamodel}
 \include{fdl}
+\include{bibliography}
 
 \end{document}