Changeset 563

Show
Ignore:
Timestamp:
02/22/07 14:53:30 (2 years ago)
Author:
hollow
Message:

use own page style; add missing sections to rpcref; cleanup

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • trunk/doc/manual/intro/vcd.tex

    r562 r563  
    3636 
    3737\begin{labeling}[~~]{\labelingfont{vwrappers}} 
    38         \labelingitem{libvserver} The libvserver module contains a library that implements 
    39                the Linux-VServer system call in the C language. It provides a convenient 
    40                way to execute Linux-VServer commands in other programs or libraries. 
    41                Additionally basic low-level command-line tools are provided to work with 
    42                these commands. 
     38        \labelingitem{libvserver} The libvserver module contains a library that 
     39        implements the Linux-VServer system call in the C language. It provides a 
     40        convenient way to execute Linux-VServer commands in other programs or 
     41        libraries.  Additionally basic low-level command-line tools are provided to 
     42        work with these commands. 
    4343 
    4444        \labelingitem{vcd} The VServer Control Daemon module uses -- among other 
    45                libraries -- libvserver to implement the core of the package. This modules 
    46                includes the configuration storage backend, the XML-RPC server, 
    47                command-line clients and the kernel user-space helper. 
    48  
    49         \labelingitem{vwrappers} The vwrappers module contains a lot of wrappers for 
    50                coreutils/util-linux/procps and other system packages. This provides a 
    51                convenient way to execute commands inside virtual private servers. 
    52                Additionally, some utilities for the extended filesystem attributes are 
    53                provided enhancing the versions in libvserver with recursion and various 
    54                other options. 
    55  
    56         \labelingitem{vstatd} The VServer Statistics Daemon module contains a \emph{very} 
    57                small daemon that keeps track of resource utilization of virtual private 
    58                servers. For statistical analysis all collected data is stored in a 
    59                round-robin database (RRD), the industry standard data logging and graphing 
    60                application. 
     45        libraries -- libvserver to implement the core of the package. This modules 
     46        includes the configuration storage backend, the XML-RPC server, 
     47        command-line clients and the kernel user-space helper. 
     48 
     49        \labelingitem{vwrappers} The vwrappers module contains a lot of wrappers 
     50        for coreutils/util-linux/procps and other system packages. This provides a 
     51        convenient way to execute commands inside virtual private servers. 
     52        Additionally, some utilities for the extended filesystem attributes are 
     53        provided enhancing the versions in libvserver with recursion and various 
     54        other options. 
     55 
     56        \labelingitem{vstatd} The VServer Statistics Daemon module contains a 
     57        \emph{very} small daemon that keeps track of resource utilization of 
     58        virtual private servers. For statistical analysis all collected data is 
     59        stored in a round-robin database (RRD), the industry standard data logging 
     60        and graphing application. 
    6161\end{labeling} 
    6262 
     
    7777For a long time the Linux-VServer project used a few different system calls to 
    7878accomplish different aspects of virtualization and configuration. However, the 
    79 number of commands grew rapidly and a few system calls were simply not enough to 
    80 handle every aspect of virtualization. Therefore, the Linux-VServer system call 
    81 now uses a system call multiplexer based on a command identifier, which has 
    82 similar semantics like the \texttt{ioctl} system call. 
     79number of commands grew rapidly and a few system calls were simply not enough 
     80to handle every aspect of virtualization. Therefore, the Linux-VServer system 
     81call now uses a system call multiplexer based on a command identifier, which 
     82has similar semantics like the \texttt{ioctl} system call. 
    8383 
    8484The Linux kernel maintainers have reserved a system call number for the 
     
    111111 
    112112In theory, there are 64 categories with up to 256 commands in each category, 
    113 allowing for 4096 revisions of each command, which is far more than will ever be 
    114 required. 
     113allowing for 4096 revisions of each command, which is far more than will ever 
     114be required. 
    115115 
    116116The following categories and commands are defined in the Linux-VServer 2.2.0 
     
    151151\end{center} 
    152152 
    153 While a single system call is advantageous from the kernel point of view, 
    154 user programs and libraries tend to have a single function per command, although 
     153While a single system call is advantageous from the kernel point of view, user 
     154programs and libraries tend to have a single function per command, although 
    155155this is not always the case for multiplexed system calls, as can be seen with 
    156156\texttt{ioctl}. Nevertheless, the libvserver module implements a function for 
     
    170170The Vserver Control Daemon is the core of the the package and implements all 
    171171aspects of virtual server management using libvserver to issue Linux-VServer 
    172 system calls, xmlrpc-c to implement the XML-RPC protocol and SQLite3 for 
    173 data storage. Figure~\ref{fig:vcd-overview} illustrates the basic relationship 
     172system calls, xmlrpc-c to implement the XML-RPC protocol and SQLite3 for data 
     173storage. Figure~\ref{fig:vcd-overview} illustrates the basic relationship 
    174174between libraries, methods and clients. 
    175175 
     
    269269On startup, the server defines a global registry of methods accessible by its 
    270270clients. In order to allow structure for the amount of methods currently 
    271 defined, all methods are devided in logical units -- also known as namespaces -- 
    272 and prefixed with the namespace and a dot, like \verb,vx.start, or 
     271defined, all methods are devided in logical units -- also known as namespaces 
     272-- and prefixed with the namespace and a dot, like \verb,vx.start, or 
    273273\verb,helper.shutdown, for the start and shutdown methods of the vx and helper 
    274274namespace, respectively. 
     
    295295client will send the password as plain-text -- the server then creates a 
    296296WHIRLPOOL hash using the submitted password and compares its result with the 
    297 hash stored in VXDB. It is also possible to create the hash on the client side, 
    298 prefix the result with \verb,WHIRLPOOLENC//, and send the result to the server 
    299 for authentication. The server then compares the hash after the prefix. 
     297hash stored in VXDB. It is also possible to create the hash digest on the client 
     298side, prefix the result with the string \texttt{WHIRLPOOLENC//} and send the 
     299result to the server for authentication. The server then compares the hash after  
     300stripping the the prefix again. 
    300301 
    301302Note that an attacker can still authenticate against the server with the hash 
    302 only, he just cannot retreive the original password again. Therefore, the server 
    303 should \emph{never} listen on an untrusted network if no other security measures 
    304 have been setup, like an SSL or VPN tunnel. 
     303only, he just cannot retreive the original password again. Therefore, the 
     304server should \emph{never} listen on an untrusted network if no other security 
     305measures have been setup, like an SSL or VPN tunnel. 
    305306 
    306307 
     
    309310For a fine-grained access control the server implements its own set of 
    310311capabilities.  A capability is a lot like a drivers license. As an example, 
    311 consider your car license. It allows you to drive a certain set of 
    312 vehicles (it designates a particular object set, in our case XML-PRC methods), 
    313 and anyone holding a car license is allowed to drive the same set of objects 
    314 (cars). 
     312consider your car license. It allows you to drive a certain set of vehicles (it 
     313designates a particular object set, in our case XML-PRC methods), and anyone 
     314holding a car license is allowed to drive the same set of objects (cars). 
    315315 
    316316Refer to part~\ref{pt:rpcref} on page~\pageref{pt:rpcref} for a detailed 
    317 description of available access restrictions and their usage in defined methods. 
     317description of available access restrictions and their usage in defined 
     318methods. 
    318319 
    319320\subsubsection{Owner Checks} 
     
    321322To ensure the distinction between your car and your neighbours Lamborghini 
    322323another access control system has to be implemented. Therefore the server also 
    323 implements owner checks for most of its methods. This results in an extension to 
    324 the capability model explained above. The server implements another object se
    325 based on the ownership information stored in the database. Instead of allowing 
    326 everyone holding a certain capability to operate on all virtual servers, only 
    327 the intersection of both object sets is permitted for operation. 
     324implements owner checks for most of its methods. This results in an extension 
     325to the capability model explained above. The server implements another objec
     326set based on the ownership information stored in the database. Instead of 
     327allowing everyone holding a certain capability to operate on all virtual 
     328servers, only the intersection of both object sets is permitted for operation. 
    328329 
    329330Still, this model has a noticable flaw: Imagine a company has two hundred cars 
    330 and the top management should have access to all cars. Adding all members 
    331 of the management to the owner list of every single car can become a pain in 
    332 the ass very quickly. Therefore the user database in VXDB implements an 
    333 additional configuration option~--~the adminstrator flag. Using this flag all 
    334 owner checks are passed without even consulting the owner lists in the database. 
     331and the top management should have access to all cars. Adding all members of 
     332the management to the owner list of every single car can become a pain in the 
     333ass very quickly. Therefore the user database in VXDB implements an additional 
     334configuration option~--~the adminstrator flag. Using this flag all owner checks 
     335are passed without even consulting the owner lists in the database. 
    335336 
    336337 
     
    372373\emph{Round Robin Databases (RRD)} - the industry standard data for logging and 
    373374graphing applications - for later use in reports or graphing processes. 
    374  
  • trunk/doc/manual/manual.bib

    r562 r563  
    7777        year      = {2006} 
    7878} 
     79 
     80@Misc{libvserver-doc, 
     81        author = {Benedikt Böhm}, 
     82        title  = {libvserver API Documentation}, 
     83        year   = {2007}, 
     84        note   = {\url{http://people.linux-vserver.org/~hollow/libvserver/doc}} 
     85} 
  • trunk/doc/manual/manual.tex

    r562 r563  
    1 \documentclass[a4paper,10pt,oneside]{scrbook} 
     1\documentclass[10pt,oneside,halfparskip]{scrbook} 
     2\usepackage[a4paper,includeheadfoot,margin=10em]{geometry} 
    23 
    34% input encoding 
    45\usepackage[utf8]{inputenc} 
     6 
     7% header and footer 
     8\usepackage[footexclude,markuppercase]{scrpage2} 
     9\automark{section} 
     10\setheadwidth{text} 
     11\setfootwidth{text} 
     12 
     13\deftripstyle{vcdmanual}[1pt][.3pt] 
     14        {\pagemark}{}{\MakeUppercase{\headmark}} 
     15        {}{\small\textsf{This work is licensed under a Creative 
     16        Commons Attribution-NonCommercial-ShareAlike 2.5 License}}{} 
     17 
     18% page style 
     19\pagestyle{vcdmanual} 
     20\renewcommand*{\partpagestyle}{empty} 
     21\renewcommand*{\chapterpagestyle}{vcdmanual} 
     22\renewcommand*{\chapterformat}{\thechapter\autodot\enskip} 
    523 
    624% graphics support 
     
    1533% url and hyperref 
    1634\usepackage[plainpages=false,colorlinks=true]{hyperref} 
    17  
    18 % page style 
    19 \pagestyle{plain} 
    20  
    21 % no paragraph indention 
    22 \setlength{\parindent}{0pt} 
    23 \setlength{\parskip}{1ex plus 0.5ex minus 0.2ex} 
    2435 
    2536% bibliography 
     
    3647 
    3748\title{VServer Control Daemon\\Reference Manual} 
    38 \author{Benedikt Böhm \texttt{<hollow@gentoo.org>}} 
     49\author{Benedikt Böhm \texttt{<hollow@gentoo.org>} \and 
     50Luca Longinotti \texttt{<chtekk@gentoo.org>}} 
    3951 
    4052\begin{document} 
  • trunk/doc/manual/rpcref/commands.tex

    r562 r563  
    1717        \end{quote} 
    1818 
    19         \begin{labeling}{000000000
     19        \begin{labeling}{0000000000
    2020}{ 
    2121        \end{labeling} 
     
    5959        \end{quote} 
    6060 
    61         \begin{labeling}{000000000
     61        \begin{labeling}{0000000000
    6262}{ 
    6363        \end{labeling} 
     
    7979        specific errors: 
    8080 
    81         \begin{labeling}{000000000
     81        \begin{labeling}{00000000000000
    8282}{ 
    8383        \end{labeling} 
  • trunk/doc/manual/rpcref/intro.tex

    r562 r563  
    55\section{XML-RPC Signatures} 
    66 
    7 The XMLRPC signatures used in this part of the manual define a translation 
    8 between the XMLRPC value and C-friendly data types that represent the same 
     7The XML-RPC signatures used in this part of the manual define a translation 
     8between the XML-RPC value and C-friendly data types that represent the same 
    99information. For example, it might say that a floating point number translates 
    1010to or from a C double value, or that an array of 4 integers translates to or 
    1111from 4 C int values. 
    1212 
    13 A format string usually describes the type of one XMLRPC value. But some types 
     13A format string usually describes the type of one XML-RPC value. But some types 
    1414(array and structure) are compound types -- they are composed recursively of 
    15 other XMLRPC values. So a single format string might involve multiple XMLRPC 
     15other XML-RPC values. So a single format string might involve multiple XML-RPC 
    1616values. 
    1717 
     
    2020is called a format specifier, and in particular a simple format specifier. 
    2121 
    22 The XMLRPC server uses only three native XMLRPC datatypes: 
    23  
    24 \begin{labeling}{00.00.0000
    25 \item [{\texttt{int}}] signed 32-bit integer (-2,147,483,648 to +2,147,483,647) 
    26 \item [{\texttt{bool}}] boolean value (true/false) 
    27 \item [{\texttt{string}}] character string of arbitrary length 
    28 \end{labeling} 
    29  
    30 Unfortunately the XMLRPC protocol does not define 64-bit integer values, 
    31 therefore the XMLRPC server uses the native string datatype and converts all 
     22The XML-RPC server uses only three native XML-RPC datatypes: 
     23 
     24\begin{labeling}{\labelingfont{string}
     25\labelingitem{int} signed 32-bit integer (-2,147,483,648 to +2,147,483,647) 
     26\labelingitem{bool} boolean value (true/false) 
     27\labelingitem{string} character string of arbitrary length 
     28\end{labeling} 
     29 
     30Unfortunately the XML-RPC protocol does not define 64-bit integer values, 
     31therefore the XML-RPC server uses the native string datatype and converts all 
    3232leading digit characters to 64-bit integer representation. 
    3333 
    3434This chapter uses the following convention to denote these integer datatypes: 
    3535 
    36 \begin{labeling}{00.00.0000} 
    37 \item [{\texttt{int32}}] signed 32-bit integer 
    38         (-2,147,483,648 to +2,147,483,647) 
    39 \item [{\texttt{uint32}}] unsigned 32-bit integer 
    40         (0 to +4,294,967,295) 
    41 \item [{\texttt{int64}}] signed 64-bit integer 
    42         (-9,223,372,036,854,775,808 to +9,223,372,036,854,775,807) 
    43 \item [{\texttt{uint64}}] unsigned 64-bit integer 
    44         (0 to +18,446,744,073,709,551,615) 
     36\begin{labeling}{\labelingfont{uint64}} 
     37\labelingitem{int32}  signed 32-bit integer ($-2^{31} \cdots 2^{31}-1$) 
     38\labelingitem{uint32} unsigned 32-bit integer ($0 \cdots 2^{32}-1$) 
     39\labelingitem{int64}  signed 64-bit integer ($-2^{63} \cdots 2^{63}-1$) 
     40\labelingitem{uint64} unsigned 64-bit integer ($0 \cdots 2^{64}-1$) 
    4541\end{labeling} 
    4642 
    4743The simple datatypes mentioned above are not sufficent to represent data in an 
    48 efficient way. Therefore compound datatypes are defined in XMLRPC. There are two 
    49 compound datatypes: array and struct.  The signature denotes arrays using 
    50 normal braces, structs use curly braces. 
    51  
    52 \begin{labeling}{00.00.0000} 
    53 \item [{\texttt{array}}] An array holds a series of data elements. Individual 
    54         elements are accessed by their position array in the array. 
    55 \item [{\texttt{struct}}] A structure is a collection of simple datatypes under 
    56         a single compund. This collection can be of different types, and each has 
     44efficient way. Therefore compound datatypes are defined in XML-RPC. There are 
     45two compound datatypes: 
     46 
     47\begin{labeling}{\labelingfont{struct}} 
     48\labelingitem{array} An array holds a series of data elements. Individual 
     49        elements are accessed by their position in the array. 
     50\labelingitem{struct} A structure is a collection of simple datatypes under 
     51        a single compound. This collection can be of different types, and each has 
    5752        a name which is used to select it from the structure. A structure is a 
    5853        convenient way of grouping several pieces of related information together. 
    5954\end{labeling} 
    6055 
    61 Here are some examples of XMLRPC signatures: 
     56The signature denotes arrays using normal braces, structures use curly braces. 
     57Here are some examples of XML-RPC signatures: 
    6258 
    6359\begin{itemize} 
    64 \item A single \texttt{string} datatype named \emph{path}:\\ 
    65         \texttt{string path} 
    66 \item An \texttt{array} of three int datatypes:\\ 
    67         \texttt{(int, int, int)} 
    68 \item An \texttt{array} with one \texttt{bool}, one \texttt{string} and one 
    69         \texttt{int} datatype:\\ 
    70         \texttt{(bool, string, int)} 
    71 \item A \texttt{struct} with one \texttt{string} and one \texttt{int} 
     60\item A single \verb,string, datatype named \emph{path}:\\ 
     61        \verb,string path, 
     62\item An \verb,array, of three int datatypes:\\ 
     63        \verb|(int int, int)| 
     64\item An \verb,array, with one \verb,bool,, one \verb,string, and one 
     65        \verb,int, datatype:\\ 
     66        \verb|(bool, string, int)| 
     67\item A \verb,struct, with one \verb,string, and one \verb,int, 
    7268        datatype:\\ 
    73         \texttt{\{string name, int id\}} 
     69        \verb|{string name, int id}| 
    7470\end{itemize} 
    7571 
     
    7874 
    7975\begin{quote} 
    80 \texttt{vx.create(string name, string template, int rebuild)} 
     76\verb|vx.create(string name, string template, int rebuild)| 
    8177\end{quote} 
    8278 
    8379Instead this convention matches the function declaration in the C language. 
    84 Translated to a XMLRPC signature format string the above would become a struct: 
     80Translated to a XML-RPC signature format string the above would become a struct: 
    8581 
    8682\begin{quote} 
    87 \texttt{\{string name, string template, int rebuild\}} 
     83\verb|{string name, string template, int rebuild}| 
    8884\end{quote} 
    8985 
    9086Read on to the next section to learn how method requests are performed and how 
    91 this struct is placed in the request. 
     87this struct of parameters is placed in the request. 
    9288 
    9389 
    9490\section{Performing XML-RPC Requests} 
    9591 
    96 An XMLRPC method call is an HTTP-POST request. The body of the request is in 
     92An XML-RPC method call is an HTTP-POST request. The body of the request is in 
    9793XML. The specified method executes on the server and the value it returns is 
    9894also formatted in XML. 
     
    109105<?xml version="1.0"?> 
    110106<methodCall> 
    111 <methodName>examples.getStateName</methodName> 
    112 <params> 
    113 <param> 
    114 <value><i4>41</i4></value> 
    115 </param> 
    116 </params> 
     107  <methodName>examples.getStateName</methodName> 
     108  <params> 
     109    <param> 
     110      <value><int>41</int></value> 
     111    </param> 
     112  </params> 
    117113</methodCall> 
    118114\end{verbatim} 
     
    121117\subsection{Header Requirements} 
    122118 
    123 The following requirements must be met when sending requests to the XMLRPC 
     119The following requirements must be met when sending requests to the XML-RPC 
    124120server: 
    125121 
    126122\begin{itemize} 
    127 \item The \texttt{/RPC2} location handler to explicitly denote XMLRPC requests 
     123\item The \verb,/RPC2, location handler to explicitly denote XML-RPC requests 
    128124\item A User-Agent and Host must be specified 
    129 \item The Content-Type is text/xml 
     125\item The Content-Type is \verb,text/xml, 
    130126\item The Content-Length must be specified and must be correct 
    131127\end{itemize} 
     
    134130\subsection{Payload Format} 
    135131 
    136 The payload is in XML, a single \texttt{<methodCall>} structure. 
    137  
    138 The \texttt{<methodCall>} must contain a \texttt{<methodName>} sub-item, a 
     132The payload is in XML, a single \verb,<methodCall>, structure. 
     133 
     134The \verb,<methodCall>, must contain a \verb,<methodName>, sub-item, a 
    139135string, containing the name of the method to be called. The string may only 
    140136contain identifier characters, upper and lower-case A-Z, the numeric 
    141137characters, 0-9, underscore, dot, colon and slash. 
    142138 
    143 If the procedure call has parameters, the <methodCall> must contain a <params> 
    144 sub-item. The <params> sub-item can contain any number of <param>s, each of 
    145 which has a <value>
     139If the procedure call has parameters, the \verb,<methodCall>, must contain a 
     140\verb,<params>, sub-item. The \verb,<params>, sub-item can contain any 
     141number of \verb,<param>,s, each of which has a \verb,<value>,
    146142 
    147143 
    148144\subsubsection{Simple Datatypes} 
    149145 
    150 The XMLRPC server only uses three native datatypes as mentioned above: 
    151  
    152 \begin{labeling}{00.00.0000
    153 \item [{\texttt{<int>}}] signed 32-bit integer 
    154 \item [{\texttt{<boolean>}}] 0 (false) or 1 (true) 
    155 \item [{\texttt{<string>}}] character string of arbitrary length 
     146The XML-RPC server only uses three native datatypes as mentioned above: 
     147 
     148\begin{labeling}{\labelingfont{boolean}
     149\labelingitem{int} signed 32-bit integer 
     150\labelingitem{boolean} 0 (false) or 1 (true) 
     151\labelingitem{string} character string of arbitrary length 
    156152\end{labeling} 
    157153 
     
    161157\subsubsection{Structures} 
    162158 
     159A value can also be of type \verb,<struct>,. A structure contains 
     160\verb,<member>,s and each \verb,<member>, contains a \verb,<name>, and a 
     161\verb,<value>,. Here is an example of a two-element \verb,<struct>,: 
     162 
     163\begin{verbatim} 
     164<struct> 
     165  <member> 
     166    <name>lowerBound</name> 
     167    <value><int>18</int></value> 
     168  </member> 
     169  <member> 
     170    <name>upperBound</name> 
     171    <value><int>139</int></value> 
     172  </member> 
     173</struct> 
     174\end{verbatim} 
     175 
     176Structures can be recursive, any \verb,<value>, may contain a 
     177\verb,<struct>, or any other datatype, including an \verb,<array>,, 
     178described below. 
     179 
     180 
    163181\subsubsection{Arrays} 
    164182 
     183A value can also be of type \verb,<array>,. An array contains a single 
     184\verb,<data>, element, which can contain any number of \verb,<value>,s. Here's 
     185an example of a four-element array: 
     186 
     187\begin{verbatim} 
     188<array> 
     189  <data> 
     190    <value><int>12</int></value> 
     191    <value><string>Egypt</string></value> 
     192    <value><boolean>0</boolean></value> 
     193    <value><int>-31</int></value> 
     194  </data> 
     195</array> 
     196\end{verbatim} 
     197 
     198Unlike structures array elements do not have names. In contrary to C arrays you 
     199can mix datatypes as the example above illustrates. 
     200 
     201Arrays can be recursive, any value may contain an \verb,<array>, or any other 
     202type, including a \verb,<struct>,, described above. 
     203 
     204 
    165205\subsection{Method Initialization} 
    166206 
     207The XML-RPC server implemented in VCD extends the request format to allow user 
     208authentication. This extension is fully compatible with the standard XML-RPC 
     209protocol, since it is implemented using the \verb,<params>, section of the 
     210XML-RPC request. A client submits username and password as first 
     211\verb,<param>, in the \verb,<params>, section using the following struct 
     212signature: 
     213 
     214\begin{quote} 
     215\verb|{string username, string password}| 
     216\end{quote} 
     217 
     218\begin{labeling}{\labelingfont{username}} 
     219\labelingitem{username} unique username with a maximum of 64 characters 
     220\labelingitem{password} password for the specified user 
     221\end{labeling} 
     222 
     223The second \verb,<param>, in the \verb,<params>, section is a variable-length 
     224struct of parameters specific to the requested method. Refer to the next 
     225chapters for a description of all methods and their parameters. 
     226 
     227Here is an example of a valid XML-RPC request to VCD: 
     228 
     229\begin{verbatim} 
     230<?xml version="1.0" encoding="UTF-8"?> 
     231<methodCall> 
     232  <methodName>vx.status</methodName> 
     233  <params> 
     234    <param> 
     235      <value><struct> 
     236        <member> 
     237          <name>username</name> 
     238          <value><string>admin</string></value> 
     239        </member> 
     240        <member> 
     241          <name>password</name> 
     242          <value><string>MySecret</string></value> 
     243        </member> 
     244      </struct></value> 
     245    </param> 
     246    <param> 
     247      <value><struct> 
     248        <member> 
     249          <name>name</name> 
     250          <value><string>vx1</string></value> 
     251        </member> 
     252      </struct></value> 
     253    </param> 
     254  </params> 
     255</methodCall> 
     256\end{verbatim} 
     257 
     258Once the XML-RPC request has been received by the server it translates the XML 
     259payload to internal data representation, performs user authentication and calls 
     260the specified method using the struct in the second \verb,<param>, value as method 
     261parameters. 
     262 
     263 
    167264\subsection{Authentication and Access Restrictions} 
    168265 
     266As mentioned in section~\ref{sec:intro:vcd:vcd} authentication is based on the 
     267cryptographic hash function WHIRLPOOL. The server generates a WHIRLPOOL hash 
     268using the specified password in the authentication struct in the first 
     269\verb,<param>, value. Afterwards it looks up the specified user in the database 
     270and compares the stored password hash with the previously generated hash. If 
     271the hashes do not match the server returns an error. 
     272 
     273Additionally the XML-RPC server implements a set of capabilities to enable 
     274certain functionality for specific users only. If the requested method requires 
     275capabilities not configured for the authenticated user the server returns an 
     276error. The server implements the following capabilities: 
     277 
     278\begin{labeling}{\labelingfont{HELPER}} 
     279\labelingitem{AUTH}   User may modify the internal user database 
     280\labelingitem{DLIM}   User may modify disk limits 
     281\labelingitem{INIT}   User may start/stop virtual servers 
     282\labelingitem{MOUNT}  User may modify mount points 
     283\labelingitem{NET}    User may modify network interfaces 
     284\labelingitem{BCAP}   User may modify system capabilities 
     285\labelingitem{CCAP}   User may modify context capabilities 
     286\labelingitem{CFLAG}  User may modify context flags 
     287\labelingitem{RLIM}   User may modify resource limits 
     288\labelingitem{SCHED}  User may modify context schedulers 
     289\labelingitem{UNAME}  User may modify utsname/virtual host information 
     290\labelingitem{CREATE} User may create and destruct virtual servers 
     291\labelingitem{EXEC}   User may execute commands in virtual server 
     292\labelingitem{INFO}   User may retrieve internal server information 
     293\labelingitem{HELPER} User may call helper methods 
     294\end{labeling} 
     295 
     296Please refer to the next chapters to learn which method requires which 
     297capability. 
     298 
     299If the user has passed authentication most of the implemented methods in VCD do 
     300owner checks. In general all methods expecting a string name as first parameter 
     301do owner checks. A user can pass owner checks in two ways: 
     302 
     303\begin{itemize} 
     304\item He is listed as owner in the owner list of the virtual server specified in name 
     305\item He has the admin flag enabled in VXDB 
     306\end{itemize} 
     307 
     308Once the user has passed all the authentication steps mentioned above, the 
     309specified method executes and returns a fault notification or a method specific 
     310return value. 
     311 
     312 
    169313\subsection{Response Format} 
    170314 
     315An XML-RPC response is a normal HTTP response. The body of the response is in 
     316XML. The specified method has executed on the server and the value it now 
     317returns is also formatted in XML. 
     318 
     319\begin{itemize} 
     320\item Unless there is a low-level error, the HTTP server always returns 200 OK. 
     321\item The Content-Type is \verb,text/xml,. 
     322\item Content-Length must be present and correct. 
     323\end{itemize} 
     324 
     325The body of the response is a single XML structure, a \verb,<methodResponse>,, 
     326which can contain a single \verb,<params>, which contains a single 
     327\verb,<param>, which contains a single \verb,<value>,. 
     328 
     329The \verb,<methodResponse>, could also contain a \verb,<fault>, which contains 
     330a \verb,<value>, which is a \verb,<struct>, containing two elements, one named 
     331\verb,<faultCode>,, an \verb,<int>, and one named \verb,<faultString>,, a 
     332\verb,<string>,. 
     333 
     334A \verb,<methodResponse>, can not contain both a \verb,<fault>, and a \verb,<params>,. Here is an 
     335example of a response to an XML-RPC request: 
     336 
     337\begin{verbatim} 
     338HTTP/1.1 200 OK 
     339Connection: close 
     340Content-Length: 158 
     341Content-Type: text/xml 
     342Date: Fri, 17 Jul 1998 19:55:08 GMT 
     343Server: VCD/1.0 
     344 
     345<?xml version="1.0"?> 
     346<methodResponse> 
     347  <params> 
     348    <param> 
     349      <value><string>South Dakota</string></value> 
     350    </param> 
     351  </params> 
     352</methodResponse> 
     353\end{verbatim} 
     354 
     355A fault might look like the following example: 
     356 
     357\begin{verbatim} 
     358HTTP/1.1 200 OK 
     359Connection: close 
     360Content-Length: 426 
     361Content-Type: text/xml 
     362Date: Fri, 17 Jul 1998 19:55:02 GMT 
     363Server: VCD/1.0 
     364 
     365<?xml version="1.0"?> 
     366<methodResponse> 
     367  <fault> 
     368    <value><struct> 
     369      <member> 
     370        <name>faultCode</name> 
     371        <value><int>4</int></value> 
     372      </member> 
     373      <member> 
     374        <name>faultString</name> 
     375        <value><string>Too many parameters.</string></value> 
     376      </member> 
     377    </struct></value> 
     378  </fault> 
     379</methodResponse> 
     380\end{verbatim} 
     381 
     382Please note that even in the case of a fault notification the HTTP status code 
     383is still 200 OK. Refer to the next section to learn about possible error codes 
     384and their meaning. 
    171385 
    172386 
    173387\section{Method Error Codes} 
     388 
     389This part of the manual devides error codes in two categories: generic method 
     390errors and specific method errors. Although they do not differ in their value 
     391or implementation it is advisable to know that the same error code may have a 
     392slightly different meaning for a specific method. The following table explains 
     393all error codes and their generic meaning. 
     394 
     395\begin{center} 
     396\begin{tabular}{l|c|l} 
     397\labelingfont{Constant} & \labelingfont{Value} & \labelingfont{Description}\\ 
     398\hline 
     399\labelingfont{MEAUTH}    & 100 & Unauthorized\\ 
     400\labelingfont{MEPERM}    & 101 & Operation not permitted\\ 
     401\labelingfont{MENOUSER}  & 102 & User does not exist\\ 
     402\labelingfont{MEINVAL}   & 200 & Invalid argument\\ 
     403\labelingfont{MEEXIST}   & 201 & An object already exists\\ 
     404\labelingfont{MENOVPS}   & 202 & Virtual server does not exist\\ 
     405\labelingfont{MENOVG}    & 203 & Virtual server group does not exist\\ 
     406\labelingfont{MESTOPPED} & 300 & Virtual server not running\\ 
     407\labelingfont{MERUNNING} & 301 & Virtual server still/already running\\ 
     408\labelingfont{MEBUSY}    & 302 & Operation still in progress\\ 
     409\labelingfont{MEVXDB}    & 400 & Low-level database error\\ 
     410\labelingfont{MECONF}    & 401 & Invalid configuration file\\ 
     411\labelingfont{MESYS}     & 500 & System call or library call failed\\ 
     412\labelingfont{MEEXEC}    & 1000+ & Command execution failed\\ 
     413\end{tabular} 
     414\end{center} 
     415 
     416Please refer to the next chapters to learn which methods apply different meaning 
     417to these error codes. 
  • trunk/doc/manual/rpcref/vcd.tex

    r562 r563  
    114114\end{rpcaccess} 
    115115 
    116 \begin{rpcreturncomplex}{\texttt{struct}}{string password, bool admin} 
     116\begin{rpcreturncomplex}{a \texttt{struct}}{string password, bool admin} 
    117117\rpcreturnparam{password}{Password hash for the specified user} 
    118118\rpcreturnparam{admin}{Set the administrator flag for the specified user}