Changeset 563
- Timestamp:
- 02/22/07 14:53:30 (2 years ago)
- Files:
-
- trunk/doc/manual/intro/vcd.tex (modified) (10 diffs)
- trunk/doc/manual/manual.bib (modified) (1 diff)
- trunk/doc/manual/manual.tex (modified) (3 diffs)
- trunk/doc/manual/rpcref/commands.tex (modified) (3 diffs)
- trunk/doc/manual/rpcref/intro.tex (modified) (7 diffs)
- trunk/doc/manual/rpcref/vcd.tex (modified) (1 diff)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
trunk/doc/manual/intro/vcd.tex
r562 r563 36 36 37 37 \begin{labeling}[~~]{\labelingfont{vwrappers}} 38 \labelingitem{libvserver} The libvserver module contains a library that implements39 the Linux-VServer system call in the C language. It provides a convenient40 way to execute Linux-VServer commands in other programs or libraries.41 Additionally basic low-level command-line tools are provided to work with42 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. 43 43 44 44 \labelingitem{vcd} The VServer Control Daemon module uses -- among other 45 libraries -- libvserver to implement the core of the package. This modules46 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 for50 coreutils/util-linux/procps and other system packages. This provides a51 convenient way to execute commands inside virtual private servers.52 Additionally, some utilities for the extended filesystem attributes are53 provided enhancing the versions in libvserver with recursion and various54 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 private58 servers. For statistical analysis all collected data is stored in a59 round-robin database (RRD), the industry standard data logging and graphing60 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. 61 61 \end{labeling} 62 62 … … 77 77 For a long time the Linux-VServer project used a few different system calls to 78 78 accomplish different aspects of virtualization and configuration. However, the 79 number of commands grew rapidly and a few system calls were simply not enough to80 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.79 number of commands grew rapidly and a few system calls were simply not enough 80 to handle every aspect of virtualization. Therefore, the Linux-VServer system 81 call now uses a system call multiplexer based on a command identifier, which 82 has similar semantics like the \texttt{ioctl} system call. 83 83 84 84 The Linux kernel maintainers have reserved a system call number for the … … 111 111 112 112 In 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 be114 required.113 allowing for 4096 revisions of each command, which is far more than will ever 114 be required. 115 115 116 116 The following categories and commands are defined in the Linux-VServer 2.2.0 … … 151 151 \end{center} 152 152 153 While a single system call is advantageous from the kernel point of view, 154 userprograms and libraries tend to have a single function per command, although153 While a single system call is advantageous from the kernel point of view, user 154 programs and libraries tend to have a single function per command, although 155 155 this is not always the case for multiplexed system calls, as can be seen with 156 156 \texttt{ioctl}. Nevertheless, the libvserver module implements a function for … … 170 170 The Vserver Control Daemon is the core of the the package and implements all 171 171 aspects 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 datastorage. Figure~\ref{fig:vcd-overview} illustrates the basic relationship172 system calls, xmlrpc-c to implement the XML-RPC protocol and SQLite3 for data 173 storage. Figure~\ref{fig:vcd-overview} illustrates the basic relationship 174 174 between libraries, methods and clients. 175 175 … … 269 269 On startup, the server defines a global registry of methods accessible by its 270 270 clients. 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, or271 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 273 273 \verb,helper.shutdown, for the start and shutdown methods of the vx and helper 274 274 namespace, respectively. … … 295 295 client will send the password as plain-text -- the server then creates a 296 296 WHIRLPOOL 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. 297 hash stored in VXDB. It is also possible to create the hash digest on the client 298 side, prefix the result with the string \texttt{WHIRLPOOLENC//} and send the 299 result to the server for authentication. The server then compares the hash after 300 stripping the the prefix again. 300 301 301 302 Note that an attacker can still authenticate against the server with the hash 302 only, he just cannot retreive the original password again. Therefore, the server303 s hould \emph{never} listen on an untrusted network if no other security measures304 have been setup, like an SSL or VPN tunnel.303 only, he just cannot retreive the original password again. Therefore, the 304 server should \emph{never} listen on an untrusted network if no other security 305 measures have been setup, like an SSL or VPN tunnel. 305 306 306 307 … … 309 310 For a fine-grained access control the server implements its own set of 310 311 capabilities. 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). 312 consider your car license. It allows you to drive a certain set of vehicles (it 313 designates a particular object set, in our case XML-PRC methods), and anyone 314 holding a car license is allowed to drive the same set of objects (cars). 315 315 316 316 Refer 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. 317 description of available access restrictions and their usage in defined 318 methods. 318 319 319 320 \subsubsection{Owner Checks} … … 321 322 To ensure the distinction between your car and your neighbours Lamborghini 322 323 another 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 to324 t he capability model explained above. The server implements another object set325 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.324 implements owner checks for most of its methods. This results in an extension 325 to the capability model explained above. The server implements another object 326 set based on the ownership information stored in the database. Instead of 327 allowing everyone holding a certain capability to operate on all virtual 328 servers, only the intersection of both object sets is permitted for operation. 328 329 329 330 Still, 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 checksare passed without even consulting the owner lists in the database.331 and the top management should have access to all cars. Adding all members of 332 the management to the owner list of every single car can become a pain in the 333 ass very quickly. Therefore the user database in VXDB implements an additional 334 configuration option~--~the adminstrator flag. Using this flag all owner checks 335 are passed without even consulting the owner lists in the database. 335 336 336 337 … … 372 373 \emph{Round Robin Databases (RRD)} - the industry standard data for logging and 373 374 graphing applications - for later use in reports or graphing processes. 374 trunk/doc/manual/manual.bib
r562 r563 77 77 year = {2006} 78 78 } 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} 2 3 3 4 % input encoding 4 5 \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} 5 23 6 24 % graphics support … … 15 33 % url and hyperref 16 34 \usepackage[plainpages=false,colorlinks=true]{hyperref} 17 18 % page style19 \pagestyle{plain}20 21 % no paragraph indention22 \setlength{\parindent}{0pt}23 \setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}24 35 25 36 % bibliography … … 36 47 37 48 \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 50 Luca Longinotti \texttt{<chtekk@gentoo.org>}} 39 51 40 52 \begin{document} trunk/doc/manual/rpcref/commands.tex
r562 r563 17 17 \end{quote} 18 18 19 \begin{labeling}{000000000 }19 \begin{labeling}{0000000000} 20 20 }{ 21 21 \end{labeling} … … 59 59 \end{quote} 60 60 61 \begin{labeling}{000000000 }61 \begin{labeling}{0000000000} 62 62 }{ 63 63 \end{labeling} … … 79 79 specific errors: 80 80 81 \begin{labeling}{000000000 }81 \begin{labeling}{00000000000000} 82 82 }{ 83 83 \end{labeling} trunk/doc/manual/rpcref/intro.tex
r562 r563 5 5 \section{XML-RPC Signatures} 6 6 7 The XML RPC signatures used in this part of the manual define a translation8 between the XML RPC value and C-friendly data types that represent the same7 The XML-RPC signatures used in this part of the manual define a translation 8 between the XML-RPC value and C-friendly data types that represent the same 9 9 information. For example, it might say that a floating point number translates 10 10 to or from a C double value, or that an array of 4 integers translates to or 11 11 from 4 C int values. 12 12 13 A format string usually describes the type of one XML RPC value. But some types13 A format string usually describes the type of one XML-RPC value. But some types 14 14 (array and structure) are compound types -- they are composed recursively of 15 other XML RPC values. So a single format string might involve multiple XMLRPC15 other XML-RPC values. So a single format string might involve multiple XML-RPC 16 16 values. 17 17 … … 20 20 is called a format specifier, and in particular a simple format specifier. 21 21 22 The XML RPC 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 length28 \end{labeling} 29 30 Unfortunately the XML RPC protocol does not define 64-bit integer values,31 therefore the XML RPC server uses the native string datatype and converts all22 The 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 30 Unfortunately the XML-RPC protocol does not define 64-bit integer values, 31 therefore the XML-RPC server uses the native string datatype and converts all 32 32 leading digit characters to 64-bit integer representation. 33 33 34 34 This chapter uses the following convention to denote these integer datatypes: 35 35 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$) 45 41 \end{labeling} 46 42 47 43 The 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 44 efficient way. Therefore compound datatypes are defined in XML-RPC. There are 45 two 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 57 52 a name which is used to select it from the structure. A structure is a 58 53 convenient way of grouping several pieces of related information together. 59 54 \end{labeling} 60 55 61 Here are some examples of XMLRPC signatures: 56 The signature denotes arrays using normal braces, structures use curly braces. 57 Here are some examples of XML-RPC signatures: 62 58 63 59 \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 one69 \ 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, 72 68 datatype:\\ 73 \ texttt{\{string name, int id\}}69 \verb|{string name, int id}| 74 70 \end{itemize} 75 71 … … 78 74 79 75 \begin{quote} 80 \ texttt{vx.create(string name, string template, int rebuild)}76 \verb|vx.create(string name, string template, int rebuild)| 81 77 \end{quote} 82 78 83 79 Instead this convention matches the function declaration in the C language. 84 Translated to a XML RPC signature format string the above would become a struct:80 Translated to a XML-RPC signature format string the above would become a struct: 85 81 86 82 \begin{quote} 87 \ texttt{\{string name, string template, int rebuild\}}83 \verb|{string name, string template, int rebuild}| 88 84 \end{quote} 89 85 90 86 Read on to the next section to learn how method requests are performed and how 91 this struct is placed in the request.87 this struct of parameters is placed in the request. 92 88 93 89 94 90 \section{Performing XML-RPC Requests} 95 91 96 An XML RPC method call is an HTTP-POST request. The body of the request is in92 An XML-RPC method call is an HTTP-POST request. The body of the request is in 97 93 XML. The specified method executes on the server and the value it returns is 98 94 also formatted in XML. … … 109 105 <?xml version="1.0"?> 110 106 <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> 117 113 </methodCall> 118 114 \end{verbatim} … … 121 117 \subsection{Header Requirements} 122 118 123 The following requirements must be met when sending requests to the XML RPC119 The following requirements must be met when sending requests to the XML-RPC 124 120 server: 125 121 126 122 \begin{itemize} 127 \item The \ texttt{/RPC2} location handler to explicitly denote XMLRPC requests123 \item The \verb,/RPC2, location handler to explicitly denote XML-RPC requests 128 124 \item A User-Agent and Host must be specified 129 \item The Content-Type is text/xml125 \item The Content-Type is \verb,text/xml, 130 126 \item The Content-Length must be specified and must be correct 131 127 \end{itemize} … … 134 130 \subsection{Payload Format} 135 131 136 The payload is in XML, a single \ texttt{<methodCall>}structure.137 138 The \ texttt{<methodCall>} must contain a \texttt{<methodName>}sub-item, a132 The payload is in XML, a single \verb,<methodCall>, structure. 133 134 The \verb,<methodCall>, must contain a \verb,<methodName>, sub-item, a 139 135 string, containing the name of the method to be called. The string may only 140 136 contain identifier characters, upper and lower-case A-Z, the numeric 141 137 characters, 0-9, underscore, dot, colon and slash. 142 138 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>.139 If the procedure call has parameters, the \verb,<methodCall>, must contain a 140 \verb,<params>, sub-item. The \verb,<params>, sub-item can contain any 141 number of \verb,<param>,s, each of which has a \verb,<value>,. 146 142 147 143 148 144 \subsubsection{Simple Datatypes} 149 145 150 The XML RPC server only uses three native datatypes as mentioned above:151 152 \begin{labeling}{ 00.00.0000}153 \ item [{\texttt{<int>}}]signed 32-bit integer154 \ item [{\texttt{<boolean>}}]0 (false) or 1 (true)155 \ item [{\texttt{<string>}}]character string of arbitrary length146 The 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 156 152 \end{labeling} 157 153 … … 161 157 \subsubsection{Structures} 162 158 159 A 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 176 Structures can be recursive, any \verb,<value>, may contain a 177 \verb,<struct>, or any other datatype, including an \verb,<array>,, 178 described below. 179 180 163 181 \subsubsection{Arrays} 164 182 183 A 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 185 an 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 198 Unlike structures array elements do not have names. In contrary to C arrays you 199 can mix datatypes as the example above illustrates. 200 201 Arrays can be recursive, any value may contain an \verb,<array>, or any other 202 type, including a \verb,<struct>,, described above. 203 204 165 205 \subsection{Method Initialization} 166 206 207 The XML-RPC server implemented in VCD extends the request format to allow user 208 authentication. This extension is fully compatible with the standard XML-RPC 209 protocol, since it is implemented using the \verb,<params>, section of the 210 XML-RPC request. A client submits username and password as first 211 \verb,<param>, in the \verb,<params>, section using the following struct 212 signature: 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 223 The second \verb,<param>, in the \verb,<params>, section is a variable-length 224 struct of parameters specific to the requested method. Refer to the next 225 chapters for a description of all methods and their parameters. 226 227 Here 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 258 Once the XML-RPC request has been received by the server it translates the XML 259 payload to internal data representation, performs user authentication and calls 260 the specified method using the struct in the second \verb,<param>, value as method 261 parameters. 262 263 167 264 \subsection{Authentication and Access Restrictions} 168 265 266 As mentioned in section~\ref{sec:intro:vcd:vcd} authentication is based on the 267 cryptographic hash function WHIRLPOOL. The server generates a WHIRLPOOL hash 268 using the specified password in the authentication struct in the first 269 \verb,<param>, value. Afterwards it looks up the specified user in the database 270 and compares the stored password hash with the previously generated hash. If 271 the hashes do not match the server returns an error. 272 273 Additionally the XML-RPC server implements a set of capabilities to enable 274 certain functionality for specific users only. If the requested method requires 275 capabilities not configured for the authenticated user the server returns an 276 error. 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 296 Please refer to the next chapters to learn which method requires which 297 capability. 298 299 If the user has passed authentication most of the implemented methods in VCD do 300 owner checks. In general all methods expecting a string name as first parameter 301 do 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 308 Once the user has passed all the authentication steps mentioned above, the 309 specified method executes and returns a fault notification or a method specific 310 return value. 311 312 169 313 \subsection{Response Format} 170 314 315 An XML-RPC response is a normal HTTP response. The body of the response is in 316 XML. The specified method has executed on the server and the value it now 317 returns 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 325 The body of the response is a single XML structure, a \verb,<methodResponse>,, 326 which can contain a single \verb,<params>, which contains a single 327 \verb,<param>, which contains a single \verb,<value>,. 328 329 The \verb,<methodResponse>, could also contain a \verb,<fault>, which contains 330 a \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 334 A \verb,<methodResponse>, can not contain both a \verb,<fault>, and a \verb,<params>,. Here is an 335 example of a response to an XML-RPC request: 336 337 \begin{verbatim} 338 HTTP/1.1 200 OK 339 Connection: close 340 Content-Length: 158 341 Content-Type: text/xml 342 Date: Fri, 17 Jul 1998 19:55:08 GMT 343 Server: 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 355 A fault might look like the following example: 356 357 \begin{verbatim} 358 HTTP/1.1 200 OK 359 Connection: close 360 Content-Length: 426 361 Content-Type: text/xml 362 Date: Fri, 17 Jul 1998 19:55:02 GMT 363 Server: 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 382 Please note that even in the case of a fault notification the HTTP status code 383 is still 200 OK. Refer to the next section to learn about possible error codes 384 and their meaning. 171 385 172 386 173 387 \section{Method Error Codes} 388 389 This part of the manual devides error codes in two categories: generic method 390 errors and specific method errors. Although they do not differ in their value 391 or implementation it is advisable to know that the same error code may have a 392 slightly different meaning for a specific method. The following table explains 393 all 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 416 Please refer to the next chapters to learn which methods apply different meaning 417 to these error codes. trunk/doc/manual/rpcref/vcd.tex
r562 r563 114 114 \end{rpcaccess} 115 115 116 \begin{rpcreturncomplex}{ \texttt{struct}}{string password, bool admin}116 \begin{rpcreturncomplex}{a \texttt{struct}}{string password, bool admin} 117 117 \rpcreturnparam{password}{Password hash for the specified user} 118 118 \rpcreturnparam{admin}{Set the administrator flag for the specified user}
