Changeset 564

Show
Ignore:
Timestamp:
02/22/07 22:26:46 (2 years ago)
Author:
hollow
Message:

use empty page style for ToC; add explanation of kernel helper

Files:

Legend:

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

    r563 r564  
    341341provide facilities to connect and execute methods on remote servers. Several 
    342342clients exist for different purpose, in most cases they are aligned with the 
    343 method namespaces mentioned above. 
     343method namespaces mentioned above. Available commands are discussed in detail 
     344in part~\ref{pt:cmdref} on page~\pageref{pt:cmdref}. 
    344345 
    345346It is important to know that the connection between server and client is not 
     
    352353Refer to part~\ref{pt:rpcref} on page~\pageref{pt:rpcref} for a detailed 
    353354description of the XML-RPC protocol and the request and response format used 
    354 for defined methods asw well as error codes and their meaning. 
     355for defined methods as well as error codes and their meaning. 
     356 
     357 
     358\subsection{Kernel Helper} 
     359 
     360For some purposes, it makes sense to have a user-space tool to act on behalf 
     361of the kernel, when a process inside a context requests something usually 
     362available on a real server, but naturally not available inside a context. 
     363 
     364The best example for this is the \verb,reboot, system call, when invoked from 
     365inside a virtual server, the kernel helper on the host system will be called 
     366to perform the shutdown (and probably startup) procedure for this particular 
     367virtual server and not for the physical machine. 
     368 
     369Previously, the kernel helpers sole purpose was to handle reboot requests. The 
     370helper implemented for VCD, however, uses the full aspect of the helper 
     371interface now. This includes creation and disposal of virtual servers and 
     372keeping track of reboot requests. Figures~\ref{fig:vshelper-startup} 
     373and~\ref{fig:vshelper-shutdown} illustrate the rather complex assembly of the 
     374startup 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 
     383During startup of virtual servers, i.e. a client has called the \verb,vx.start, 
     384method, the daemon issues a system call to create the necessary network and 
     385process context. The kernel then calls the kernel helper using the 
     386\verb,startup, action, which in turn calls the \verb,helper.startup, method. 
     387 
     388The daemon then queries the database for initial configuration, like 
     389capabilities, network addresses or scheduler values, issues the approriate 
     390system calls to set these configuration values on the network and process 
     391context and returns the absolute path to the init binary relative to the 
     392virtual servers root filesystem to the helper. 
     393 
     394Having successfully retreived the path to the init binary the kernel helper is 
     395now able to fork a new process, migrate it to the network and process context 
     396created before, and execute the init binary. The parent process then blocks 
     397until at least one process appeared inside the context. However, this is the 
     398case as soon as the child process has issued the system call for migration, 
     399therefore the helper is not able to check if the init command actually 
     400succeeded. 
     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 
     409Disposal and potential restart is even more complicated by the fact that the 
     410helper 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 
     413services and calls \verb,sys_reboot, afterwards, with a special magic to 
     414distinct halt and reboot. 
     415 
     416On a reboot request the kernel then calls the helper using the \verb,reboot, 
     417action, which in turn calls the \verb,helper.reboot, method to record the 
     418reboot request in the database as it is neede later. As soon as the helper 
     419returns the kernel kills the init process -- and possibly other remaining 
     420processes -- and calls the helper a second time using the \verb,shutdown, 
     421action. 
     422 
     423The shutdown helper in turn waits for the network and process context to 
     424disappear and calls the \verb,helper.shutdown, method afterwards. As long as no 
     425reboot request was recorded the daemon does nothing and returns immediately. 
     426Otherwise, it will call itself using the \verb,vx.start, method to initiate the 
     427startup sequence again. 
    355428 
    356429 
     
    362435process assembles a complete root filesystem usable in virtual private servers, 
    363436and stores its content in a single tarball, the \emph{Template Cache.} 
     437 
     438 
     439\section{Command Line Wrappers} 
    364440 
    365441 
  • trunk/doc/manual/manual.tex

    r563 r564  
    1212 
    1313\deftripstyle{vcdmanual}[1pt][.3pt] 
    14         {\pagemark}{}{\MakeUppercase{\headmark}
     14        {\pagemark}{}{\MakeUppercase{\headmark}~
    1515        {}{\small\textsf{This work is licensed under a Creative 
    1616        Commons Attribution-NonCommercial-ShareAlike 2.5 License}}{} 
    1717 
    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}{} 
    2332 
    2433% graphics support 
     
    5665 
    5766\frontmatter 
     67\pagestyle{plain} 
    5868\setcounter{tocdepth}{1} 
    5969\tableofcontents 
     
    6171 
    6272\mainmatter 
     73\renewcommand*{\partpagestyle}{empty} 
     74\renewcommand*{\chapterpagestyle}{vcdmanual} 
     75\pagestyle{vcdmanual} 
     76 
    6377\part{Introduction} 
    6478\label{pt:intro} 
  • trunk/doc/manual/rpcref/intro.tex

    r563 r564  
    2222The XML-RPC server uses only three native XML-RPC datatypes: 
    2323 
    24 \begin{labeling}{\labelingfont{string}} 
     24\begin{labeling}{\labelingfont{string~}} 
    2525\labelingitem{int} signed 32-bit integer (-2,147,483,648 to +2,147,483,647) 
    2626\labelingitem{bool} boolean value (true/false) 
     
    3434This chapter uses the following convention to denote these integer datatypes: 
    3535 
    36 \begin{labeling}{\labelingfont{uint64}} 
     36\begin{labeling}{\labelingfont{uint64~}} 
    3737\labelingitem{int32}  signed 32-bit integer ($-2^{31} \cdots 2^{31}-1$) 
    3838\labelingitem{uint32} unsigned 32-bit integer ($0 \cdots 2^{32}-1$) 
     
    4545two compound datatypes: 
    4646 
    47 \begin{labeling}{\labelingfont{struct}} 
     47\begin{labeling}{\labelingfont{struct~}} 
    4848\labelingitem{array} An array holds a series of data elements. Individual 
    4949        elements are accessed by their position in the array. 
     
    9696Here is an example of an XML-RPC request: 
    9797 
    98 \begin{verbatim} 
     98\begin{lstverbatim} 
    9999POST /RPC2 HTTP/1.0 
    100100User-Agent: VCC/1.0 
     
    112112  </params> 
    113113</methodCall> 
    114 \end{verbatim} 
     114\end{lstverbatim} 
    115115 
    116116 
     
    161161\verb,<value>,. Here is an example of a two-element \verb,<struct>,: 
    162162 
    163 \begin{verbatim} 
     163\begin{lstverbatim} 
    164164<struct> 
    165165  <member> 
     
    172172  </member> 
    173173</struct> 
    174 \end{verbatim} 
     174\end{lstverbatim} 
    175175 
    176176Structures can be recursive, any \verb,<value>, may contain a 
     
    185185an example of a four-element array: 
    186186 
    187 \begin{verbatim} 
     187\begin{lstverbatim} 
    188188<array> 
    189189  <data> 
     
    194194  </data> 
    195195</array> 
    196 \end{verbatim} 
     196\end{lstverbatim} 
    197197 
    198198Unlike structures array elements do not have names. In contrary to C arrays you 
     
    227227Here is an example of a valid XML-RPC request to VCD: 
    228228 
    229 \begin{verbatim} 
     229\begin{lstverbatim} 
    230230<?xml version="1.0" encoding="UTF-8"?> 
    231231<methodCall> 
     
    254254  </params> 
    255255</methodCall> 
    256 \end{verbatim} 
     256\end{lstverbatim} 
    257257 
    258258Once the XML-RPC request has been received by the server it translates the XML 
    259259payload 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. 
     260the specified method using the struct in the second \verb,<param>, value as 
     261method parameters. 
    262262 
    263263 
     
    335335example of a response to an XML-RPC request: 
    336336 
    337 \begin{verbatim} 
     337\begin{lstverbatim} 
    338338HTTP/1.1 200 OK 
    339339Connection: close 
     
    351351  </params> 
    352352</methodResponse> 
    353 \end{verbatim} 
     353\end{lstverbatim} 
    354354 
    355355A fault might look like the following example: 
    356356 
    357 \begin{verbatim} 
     357\begin{lstverbatim} 
    358358HTTP/1.1 200 OK 
    359359Connection: close 
     
    378378  </fault> 
    379379</methodResponse> 
    380 \end{verbatim} 
     380\end{lstverbatim} 
    381381 
    382382Please note that even in the case of a fault notification the HTTP status code