--- xen-unstable.hg/docs/xen-api/xenapi-datamodel-graph.dot | 4 xen-unstable.hg/docs/xen-api/xenapi-datamodel.tex | 707 +++++++++++++++- 2 files changed, 709 insertions(+), 2 deletions(-) Index: root/xen-unstable.hg/docs/xen-api/xenapi-datamodel.tex =================================================================== --- root.orig/xen-unstable.hg/docs/xen-api/xenapi-datamodel.tex +++ root/xen-unstable.hg/docs/xen-api/xenapi-datamodel.tex @@ -46,6 +46,8 @@ Name & Description \\ {\tt console} & A console \\ {\tt user} & A user of the system \\ {\tt debug} & A basic class for testing \\ +{\tt XSPolicy} & A class for handling Xen Security Policies \\ +{\tt ACMPolicy} & A class for handling ACM-type policies \\ \hline \end{tabular}\end{center} \section{Relationships Between Classes} @@ -1153,6 +1155,7 @@ $\mathit{RO}_\mathit{run}$ & {\tt domid $\mathit{RO}_\mathit{run}$ & {\tt is\_control\_domain} & bool & true if this is a control domain (domain 0 or a driver domain) \\ $\mathit{RO}_\mathit{run}$ & {\tt metrics} & VM\_metrics ref & metrics associated with this VM \\ $\mathit{RO}_\mathit{run}$ & {\tt guest\_metrics} & VM\_guest\_metrics ref & metrics associated with the running guest \\ +$\mathit{RO}_\mathit{run}$ & {\tt security/label} & string & the VM's security label \\ \hline \end{longtable} \subsection{RPCs associated with class: VM} @@ -4150,6 +4153,78 @@ value of the field \vspace{0.3cm} \vspace{0.3cm} \vspace{0.3cm} +\subsubsection{RPC name:~get\_security\_label} + +{\bf Overview:} +Get the security label field of the given VM. Refer to the XSPolicy class +for the format of the security label. + + \noindent {\bf Signature:} +\begin{verbatim} string get_security_label (session_id s, VM ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt VM ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +value of the field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~set\_security\_label} + +{\bf Overview:} +Set the security label field of the given VM. Refer to the XSPolicy class +for the format of the security label. + + \noindent {\bf Signature:} +\begin{verbatim} int set_security_label (session_id s, VM ref self, string +security_label, string old_label)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt VM ref } & self & reference to the object \\ \hline +{\tt string } & security\_label & security label for the VM \\ \hline +{\tt string } & old\_label & Optional label value that the security label \\ +& & must currently have for the change to succeed.\\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +int +} + + +Returns the ssidref in case of an VM that is currently running or +paused, zero in case of a dormant VM (halted, suspended) or a negative +error value in case an error occurred. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} \subsubsection{RPC name:~create} {\bf Overview:} @@ -11065,6 +11140,76 @@ void \vspace{0.3cm} \vspace{0.3cm} \vspace{0.3cm} +\subsubsection{RPC name:~set\_security\_label} + +{\bf Overview:} +Set the security label of the given VDI. Refer to the XSPolicy class +for the format of the security label. + + \noindent {\bf Signature:} +\begin{verbatim} int set_security_label (session_id s, VDI ref self, string +security_label, string old_label)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt VDI ref } & self & reference to the object \\ \hline + +{\tt string } & security\_label & New value of the security label \\ \hline +{\tt string } & old\_label & Optional label value that the security label \\ +& & must currently have for the change to succeed.\\ \hline +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +int +} + + +Success or error code. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_security\_label} + +{\bf Overview:} +Get the security label of the given VDI. + + \noindent {\bf Signature:} +\begin{verbatim} string get_security_label (session_id s, VDI ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt VDI ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +value of the given field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} \subsubsection{RPC name:~create} {\bf Overview:} @@ -13109,7 +13254,6 @@ value of the field \vspace{0.3cm} \vspace{0.3cm} \subsubsection{RPC name:~get\_VM} - {\bf Overview:} Get the VM field of the given VTPM. @@ -13172,6 +13316,38 @@ value of the field \vspace{0.3cm} \vspace{0.3cm} \vspace{0.3cm} +\subsubsection{RPC name:~get\_runtime\_properties} + +{\bf Overview:} +Get the runtime\_properties field of the given VTPM. + +\noindent {\bf Signature:} +\begin{verbatim} ((string -> string) Map) get_runtime_properties (session_id s, VTPM ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt VTPM ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +(string $\rightarrow$ string) Map +} + + +value of the field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} \subsubsection{RPC name:~create} {\bf Overview:} @@ -14194,6 +14370,535 @@ all fields from the object \vspace{1cm} \newpage +\section{Class: XSPolicy} +\subsection{Fields for class: XSPolicy} +\begin{longtable}{|lllp{0.38\textwidth}|} +\hline +\multicolumn{1}{|l}{Name} & \multicolumn{3}{l|}{\bf XSPolicy} \\ +\multicolumn{1}{|l}{Description} & \multicolumn{3}{l|}{\parbox{11cm}{\em A Xen Security Policy}} \\ +\hline +Quals & Field & Type & Description \\ +\hline +$\mathit{RO}_\mathit{run}$ & {\tt uuid} & string & unique identifier / object reference \\ +$\mathit{RW}$ & {\tt repr} & string & representation of policy, i.e., XML \\ +\hline +\end{longtable} + +\subsection{Semantics of the class: XSPolicy} + +The XSPolicy class is used for administering Xen Security policies. Through +this class a new policy can be uploaded to the system, loaded into the +Xen hypervisor for enforcement and be set as the policy that the +system is automatically loading when the machine is started. + +This class returns information about the currently administered policy, +including a reference to the policy. This reference can then be used with +policy-specific classes, i.e., the ACMPolicy class, to allow retrieval of +information or changes to be made to a particular policy. + +\subsection{Structure and datatypes of class: XSPolicy} + +Format of the security label: + +A security label consist of the three different parts {\it policy type}, +{\it policy name} and {\it label} separated with colons. To specify +the virtual machine label for an ACM-type policy {\it xm-test}, the +security label string would be {\it ACM:xm-test:blue}, where blue +denotes the virtual machine's label. The format of resource labels is +the same.\\[0.5cm] +The following flags are used by this class: + +\begin{longtable}{|l|l|l|} +\hline +{\tt xs\_type} & value & meaning \\ +\hline +\hspace{0.5cm}{\tt XS\_POLICY\_ACM} & (1 $<<$ 0) & ACM-type policy \\ +\hline +\end{longtable} + +\begin{longtable}{|l|l|l|} +\hline +{\tt xs\_instantiationflags} & value & meaning \\ +\hline +\hspace{0.5cm}{\tt XS\_INST\_NONE} & 0 & do nothing \\ +\hspace{0.5cm}{\tt XS\_INST\_BOOT} & (1 $<<$ 0) & make system boot with this policy \\ +\hspace{0.5cm}{\tt XS\_INST\_LOAD} & (1 $<<$ 1) & load policy immediately \\ +\hline +\end{longtable} + + +\begin{longtable}{|l|l|l|} +\hline +{\tt xs\_policystate} & type & meaning \\ +\hline +\hspace{0.5cm}{\tt xserr} & int & Error code from operation (if applicable) \\ +\hspace{0.5cm}{\tt xs\_ref} & XSPolicy ref & reference to the XS policy as returned by the API \\ +\hspace{0.5cm}{\tt repr} & string & representation of the policy, i.e., XML \\ +\hspace{0.5cm}{\tt type} & xs\_type & the type of the policy \\ +\hspace{0.5cm}{\tt flags } & xs\_instantiationflags & instantiation flags of the policy \\ +\hspace{0.5cm}{\tt version} & int & version of the policy \\ +\hspace{0.5cm}{\tt errors} & string & Base64-encoded sequence of integer tuples consisting \\ +& & of (error code, detail); will be returned as part \\ +& & of the xs\_setpolicy function. \\ +\hline +\end{longtable} + + +\subsection{Additional RPCs associated with class: XSPolicy} +\subsubsection{RPC name:~get\_xstype} + +{\bf Overview:} +Return the Xen Security Policy types supported by this system + + \noindent {\bf Signature:} +\begin{verbatim} xs_type get_xstype (session_id s)\end{verbatim} + + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +xs\_type +} + + +flags representing the supported Xen Security Policies +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~set\_xspolicy} + +{\bf Overview:} +Set the current XSPolicy. This function can also be be used for updating of +an existing policy whose name must be equivalent to the one of the +currently running policy. + + \noindent {\bf Signature:} +\begin{verbatim} xs_policystate set_xspolicy (session_id s, xs_type type, string repr, +xs_instantiationflags flags, bool overwrite)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt xs\_type } & type & the type of policy \\ \hline +{\tt string} & repr & representation of the policy, i.e., XML \\ \hline +{\tt xs\_instantiationflags} & flags & flags for the setting of the policy \\ \hline +{\tt bool} & overwrite & whether to overwrite an existing policy \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +xs\_policystate +} + + +State information about the policy. In case an error occurred, the 'type' +member is '0' and the 'xs\_ref' member empty. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_xspolicy} + +{\bf Overview:} +Get information regarding the currently set Xen Security Policy + + \noindent {\bf Signature:} +\begin{verbatim} xs_policystate get_xspolicy (session_id s)\end{verbatim} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +xs\_policystate +} + + +State information about the currently active policy. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~rm\_xsbootpolicy} + +{\bf Overview:} +Remove any policy from the default boot configuration. + + \noindent {\bf Signature:} +\begin{verbatim} void rm_xsbootpolicy (session_id s)\end{verbatim} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +bool +} + + +Indicates success or failure of the operation +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_labeled\_resources} + +{\bf Overview:} +Get a list of resources that have been labeled. + + \noindent {\bf Signature:} +\begin{verbatim} ((string -> string) Map) get_labeled_resources (session_id s)\end{verbatim} + + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +(string $\rightarrow$ string) Map +} + + +A map of resources with their labels. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~set\_resource\_label} + +{\bf Overview:} +Label the given resource with the given label. An empty label removes any label +from the resource. + + \noindent {\bf Signature:} +\begin{verbatim} int set_resource_label (session_id s, string resource, string +label, string old_label)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt string } & resource & resource to label \\ \hline +{\tt string } & label & label for the resource \\ \hline +{\tt string } & old\_label & Optional label value that the security label \\ +& & must currently have for the change to succeed. \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +int +} + + +Indicates success or an error code of the operation +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_resource\_label} + +{\bf Overview:} +Get the label of the given resource. + + \noindent {\bf Signature:} +\begin{verbatim} string get_resource_label (session_id s, string resource)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt string } & resource & resource to label \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +The label of the given resource. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~activate\_xspolicy} + +{\bf Overview:} +Load the referenced policy into the hypervisor. + + \noindent {\bf Signature:} +\begin{verbatim} int activate_xspolicy (session_id s, xs_ref xspolicy, +xs_instantiationflags flags)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt xs ref } & self & reference to the object \\ \hline +{\tt xs\_instantiationflags } & flags & flags to activate on a policy; flags + can only be set \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +int +} + + +Indicates success or an error code of the operation. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_record} + +{\bf Overview:} +Get a record of the referenced XSPolicy. + + \noindent {\bf Signature:} +\begin{verbatim} (XSPolicy record) get_record (session_id s, xs_ref xspolicy)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt xs ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +XSPolicy record +} + + +all fields from the object +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\newpage +\section{Class: ACMPolicy} +\subsection{Fields for class: ACMPolicy} +\begin{longtable}{|lllp{0.38\textwidth}|} +\hline +\multicolumn{1}{|l}{Name} & \multicolumn{3}{l|}{\bf ACMPolicy} \\ +\multicolumn{1}{|l}{Description} & \multicolumn{3}{l|}{\parbox{11cm}{\em An ACM Security Policy}} \\ +\hline +Quals & Field & Type & Description \\ +\hline +$\mathit{RO}_\mathit{run}$ & {\tt uuid} & string & unique identifier / object reference \\ +$\mathit{RW}$ & {\tt repr} & string & representation of policy, in XML \\ +\hline +\end{longtable} + +\subsection{Structure and datatypes of class: ACMPolicy} + +\vspace{0.5cm} +The following data structures are used: + +\begin{longtable}{|l|l|l|} +\hline +{\tt RIP acm\_policyheader} & type & meaning \\ +\hline +\hspace{0.5cm}{\tt policyname} & string & name of the policy \\ +\hspace{0.5cm}{\tt policyurl } & string & URL of the policy \\ +\hspace{0.5cm}{\tt date} & string & data of the policy \\ +\hspace{0.5cm}{\tt reference} & string & reference of the policy \\ +\hspace{0.5cm}{\tt namespaceurl} & string & namespaceurl of the policy \\ +\hspace{0.5cm}{\tt version} & string & version of the policy \\ +\hline +\end{longtable} + +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_header} + +{\bf Overview:} +Get the referenced policy's header information. + + \noindent {\bf Signature:} +\begin{verbatim} acm_policyheader get_header (session_id s, xs ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt xs ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +acm\_policyheader +} + + +The policy's header information. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_xml} + +{\bf Overview:} +Get the XML representation of the given policy. + + \noindent {\bf Signature:} +\begin{verbatim} string get_XML (session_id s, xs ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt xs ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +XML representation of the referenced policy +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_map} + +{\bf Overview:} +Get the mapping information of the given policy. + + \noindent {\bf Signature:} +\begin{verbatim} string get_map (session_id s, xs ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt xs ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +Mapping information of the referenced policy. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_binary} + +{\bf Overview:} +Get the binary policy representation of the referenced policy. + + \noindent {\bf Signature:} +\begin{verbatim} string get_map (session_id s, xs ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt xs ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +Base64-encoded representation of the binary policy. +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_record} + +{\bf Overview:} +Get a record of the referenced ACMPolicy. + + \noindent {\bf Signature:} +\begin{verbatim} (XSPolicy record) get_record (session_id s, xs_ref xspolicy)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt xs ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +XSPolicy record +} + + +all fields from the object +\newpage \section{Error Handling} When a low-level transport error occurs, or a request is malformed at the HTTP or XML-RPC level, the server may send an XML-RPC Fault response, or the client Index: root/xen-unstable.hg/docs/xen-api/xenapi-datamodel-graph.dot =================================================================== --- root.orig/xen-unstable.hg/docs/xen-api/xenapi-datamodel-graph.dot +++ root/xen-unstable.hg/docs/xen-api/xenapi-datamodel-graph.dot @@ -12,7 +12,7 @@ digraph "Xen-API Class Diagram" { fontname="Verdana"; -node [ shape=box ]; session VM host network VIF PIF SR VDI VBD PBD user; +node [ shape=box ]; session VM host network VIF PIF SR VDI VBD PBD user XSPolicy ACMPolicy; node [shape=ellipse]; PIF_metrics VIF_metrics VM_metrics VBD_metrics PBD_metrics VM_guest_metrics host_metrics; node [shape=box]; host_cpu console session -> host [ arrowhead="none" ] @@ -36,4 +36,6 @@ VDI -> VBD [ arrowhead="crow", arrowtail VBD -> VM [ arrowhead="none", arrowtail="crow" ] VTPM -> VM [ arrowhead="none", arrowtail="crow" ] VBD -> VBD_metrics [ arrowhead="none" ] +XSPolicy -> host [ arrowhead="none" ] +XSPolicy -> ACMPolicy [ arrowhead="none" ] }