Changeset 564
- Timestamp:
- 02/22/07 22:26:46 (2 years ago)
- Files:
-
- trunk/doc/manual/intro/vcd.tex (modified) (3 diffs)
- trunk/doc/manual/intro/vshelper-shutdown.pdf (added)
- trunk/doc/manual/intro/vshelper-startup.pdf (added)
- trunk/doc/manual/manual.tex (modified) (3 diffs)
- trunk/doc/manual/rpcref/intro.tex (modified) (14 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
trunk/doc/manual/intro/vcd.tex
r563 r564 341 341 provide facilities to connect and execute methods on remote servers. Several 342 342 clients exist for different purpose, in most cases they are aligned with the 343 method namespaces mentioned above. 343 method namespaces mentioned above. Available commands are discussed in detail 344 in part~\ref{pt:cmdref} on page~\pageref{pt:cmdref}. 344 345 345 346 It is important to know that the connection between server and client is not … … 352 353 Refer to part~\ref{pt:rpcref} on page~\pageref{pt:rpcref} for a detailed 353 354 description of the XML-RPC protocol and the request and response format used 354 for defined methods asw well as error codes and their meaning. 355 for defined methods as well as error codes and their meaning. 356 357 358 \subsection{Kernel Helper} 359 360 For some purposes, it makes sense to have a user-space tool to act on behalf 361 of the kernel, when a process inside a context requests something usually 362 available on a real server, but naturally not available inside a context. 363 364 The best example for this is the \verb,reboot, system call, when invoked from 365 inside a virtual server, the kernel helper on the host system will be called 366 to perform the shutdown (and probably startup) procedure for this particular 367 virtual server and not for the physical machine. 368 369 Previously, the kernel helpers sole purpose was to handle reboot requests. The 370 helper implemented for VCD, however, uses the full aspect of the helper 371 interface now. This includes creation and disposal of virtual servers and 372 keeping track of reboot requests. Figures~\ref{fig:vshelper-startup} 373 and~\ref{fig:vshelper-shutdown} illustrate the rather complex assembly of the 374 startup and shutdown procedure, respectively. 375 376 \begin{figure}[hbt] 377 \center 378 \includegraphics[scale=0.6]{intro/vshelper-startup} 379 \caption{Interaction between vshelper and vcd on startup} 380 \label{fig:vshelper-startup} 381 \end{figure} 382 383 During startup of virtual servers, i.e. a client has called the \verb,vx.start, 384 method, the daemon issues a system call to create the necessary network and 385 process context. The kernel then calls the kernel helper using the 386 \verb,startup, action, which in turn calls the \verb,helper.startup, method. 387 388 The daemon then queries the database for initial configuration, like 389 capabilities, network addresses or scheduler values, issues the approriate 390 system calls to set these configuration values on the network and process 391 context and returns the absolute path to the init binary relative to the 392 virtual servers root filesystem to the helper. 393 394 Having successfully retreived the path to the init binary the kernel helper is 395 now able to fork a new process, migrate it to the network and process context 396 created before, and execute the init binary. The parent process then blocks 397 until at least one process appeared inside the context. However, this is the 398 case as soon as the child process has issued the system call for migration, 399 therefore the helper is not able to check if the init command actually 400 succeeded. 401 402 \begin{figure}[hbt] 403 \center 404 \includegraphics[scale=0.6]{intro/vshelper-shutdown} 405 \caption{Interaction between vshelper and vcd on shutdown} 406 \label{fig:vshelper-shutdown} 407 \end{figure} 408 409 Disposal and potential restart is even more complicated by the fact that the 410 helper is called twice during shutdown. Once a client has called the 411 \verb,vx.stop, method or the root user inside the virtual server has called the 412 \verb,halt, command, the virtual servers init system shuts down all running 413 services and calls \verb,sys_reboot, afterwards, with a special magic to 414 distinct halt and reboot. 415 416 On a reboot request the kernel then calls the helper using the \verb,reboot, 417 action, which in turn calls the \verb,helper.reboot, method to record the 418 reboot request in the database as it is neede later. As soon as the helper 419 returns the kernel kills the init process -- and possibly other remaining 420 processes -- and calls the helper a second time using the \verb,shutdown, 421 action. 422 423 The shutdown helper in turn waits for the network and process context to 424 disappear and calls the \verb,helper.shutdown, method afterwards. As long as no 425 reboot request was recorded the daemon does nothing and returns immediately. 426 Otherwise, it will call itself using the \verb,vx.start, method to initiate the 427 startup sequence again. 355 428 356 429 … … 362 435 process assembles a complete root filesystem usable in virtual private servers, 363 436 and stores its content in a single tarball, the \emph{Template Cache.} 437 438 439 \section{Command Line Wrappers} 364 440 365 441 trunk/doc/manual/manual.tex
r563 r564 12 12 13 13 \deftripstyle{vcdmanual}[1pt][.3pt] 14 {\pagemark}{}{\MakeUppercase{\headmark} }14 {\pagemark}{}{\MakeUppercase{\headmark}~} 15 15 {}{\small\textsf{This work is licensed under a Creative 16 16 Commons Attribution-NonCommercial-ShareAlike 2.5 License}}{} 17 17 18 % page style 19 \pagestyle{vcdmanual} 20 \renewcommand*{\partpagestyle}{empty} 21 \renewcommand*{\chapterpagestyle}{vcdmanual} 22 \renewcommand*{\chapterformat}{\thechapter\autodot\enskip} 18 % code listings 19 \usepackage{listings} 20 21 \lstnewenvironment{lstverbatim}{ 22 \lstset{ 23 frame=L, 24 xleftmargin=4em, 25 framesep=1em, 26 basicstyle=\small\ttfamily, 27 tabsize=2, 28 columns=fixed, 29 emphstyle=\bold, 30 inputencoding=utf8} 31 }{} 23 32 24 33 % graphics support … … 56 65 57 66 \frontmatter 67 \pagestyle{plain} 58 68 \setcounter{tocdepth}{1} 59 69 \tableofcontents … … 61 71 62 72 \mainmatter 73 \renewcommand*{\partpagestyle}{empty} 74 \renewcommand*{\chapterpagestyle}{vcdmanual} 75 \pagestyle{vcdmanual} 76 63 77 \part{Introduction} 64 78 \label{pt:intro} trunk/doc/manual/rpcref/intro.tex
r563 r564 22 22 The XML-RPC server uses only three native XML-RPC datatypes: 23 23 24 \begin{labeling}{\labelingfont{string }}24 \begin{labeling}{\labelingfont{string~}} 25 25 \labelingitem{int} signed 32-bit integer (-2,147,483,648 to +2,147,483,647) 26 26 \labelingitem{bool} boolean value (true/false) … … 34 34 This chapter uses the following convention to denote these integer datatypes: 35 35 36 \begin{labeling}{\labelingfont{uint64 }}36 \begin{labeling}{\labelingfont{uint64~}} 37 37 \labelingitem{int32} signed 32-bit integer ($-2^{31} \cdots 2^{31}-1$) 38 38 \labelingitem{uint32} unsigned 32-bit integer ($0 \cdots 2^{32}-1$) … … 45 45 two compound datatypes: 46 46 47 \begin{labeling}{\labelingfont{struct }}47 \begin{labeling}{\labelingfont{struct~}} 48 48 \labelingitem{array} An array holds a series of data elements. Individual 49 49 elements are accessed by their position in the array. … … 96 96 Here is an example of an XML-RPC request: 97 97 98 \begin{ verbatim}98 \begin{lstverbatim} 99 99 POST /RPC2 HTTP/1.0 100 100 User-Agent: VCC/1.0 … … 112 112 </params> 113 113 </methodCall> 114 \end{ verbatim}114 \end{lstverbatim} 115 115 116 116 … … 161 161 \verb,<value>,. Here is an example of a two-element \verb,<struct>,: 162 162 163 \begin{ verbatim}163 \begin{lstverbatim} 164 164 <struct> 165 165 <member> … … 172 172 </member> 173 173 </struct> 174 \end{ verbatim}174 \end{lstverbatim} 175 175 176 176 Structures can be recursive, any \verb,<value>, may contain a … … 185 185 an example of a four-element array: 186 186 187 \begin{ verbatim}187 \begin{lstverbatim} 188 188 <array> 189 189 <data> … … 194 194 </data> 195 195 </array> 196 \end{ verbatim}196 \end{lstverbatim} 197 197 198 198 Unlike structures array elements do not have names. In contrary to C arrays you … … 227 227 Here is an example of a valid XML-RPC request to VCD: 228 228 229 \begin{ verbatim}229 \begin{lstverbatim} 230 230 <?xml version="1.0" encoding="UTF-8"?> 231 231 <methodCall> … … 254 254 </params> 255 255 </methodCall> 256 \end{ verbatim}256 \end{lstverbatim} 257 257 258 258 Once the XML-RPC request has been received by the server it translates the XML 259 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 method261 parameters.260 the specified method using the struct in the second \verb,<param>, value as 261 method parameters. 262 262 263 263 … … 335 335 example of a response to an XML-RPC request: 336 336 337 \begin{ verbatim}337 \begin{lstverbatim} 338 338 HTTP/1.1 200 OK 339 339 Connection: close … … 351 351 </params> 352 352 </methodResponse> 353 \end{ verbatim}353 \end{lstverbatim} 354 354 355 355 A fault might look like the following example: 356 356 357 \begin{ verbatim}357 \begin{lstverbatim} 358 358 HTTP/1.1 200 OK 359 359 Connection: close … … 378 378 </fault> 379 379 </methodResponse> 380 \end{ verbatim}380 \end{lstverbatim} 381 381 382 382 Please note that even in the case of a fault notification the HTTP status code
