From patchwork Wed Apr 9 09:55:13 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ian Campbell X-Patchwork-Id: 28074 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-yh0-f72.google.com (mail-yh0-f72.google.com [209.85.213.72]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 187B8202DD for ; Wed, 9 Apr 2014 09:57:37 +0000 (UTC) Received: by mail-yh0-f72.google.com with SMTP id f10sf6776348yha.7 for ; Wed, 09 Apr 2014 02:57:36 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:from:to:date:message-id :mime-version:cc:subject:precedence:list-id:list-unsubscribe :list-post:list-help:list-subscribe:sender:errors-to :x-original-sender:x-original-authentication-results:mailing-list :list-archive:content-type:content-transfer-encoding; bh=U8PfuQAerzb0MUF5tZyTXb5MfVS5iBS1jS2NfCTFAno=; b=mFUFk40qCVB43NqIdxRAddHGqDWTHS+lwiaOiVL0nlsKVep5enJlyYC4NsKsfaNgtb yPrsWYwzevqgoEgBWs0A3AakgMaWV1ZnZYgwEoXMSWm0CQF0JBWPItZxK2DPQVymubvT 4ZXE9lpIkgpBiQTwfq0o8+oIo4jKBDRbypDRLyPmKX+aXcMgQD/RdXrSyOVESN2fLP7P OM2q9/WkrWM7aJf/42wB4ZHeUoHBk8mOh+oIexhxZQNbS8KHQ03fi6aoSGAQJdjgeCV8 IUjUgdsgna0VriHsEesZ82pd6aSKvNkIT8vp8aDhxuOslvz6BszrQjUGCsYmVBszG3pv 8C8g== X-Gm-Message-State: ALoCoQnVlZcR8AmySAYasBLtvy7w3DutOgnxUbGoHnWc0O4jxjl380yT4wtAjpHYxvq+R5INrRe9 X-Received: by 10.236.134.98 with SMTP id r62mr3616913yhi.14.1397037456652; Wed, 09 Apr 2014 02:57:36 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.140.20.22 with SMTP id 22ls529812qgi.63.gmail; Wed, 09 Apr 2014 02:57:36 -0700 (PDT) X-Received: by 10.52.23.97 with SMTP id l1mr6740567vdf.11.1397037456476; Wed, 09 Apr 2014 02:57:36 -0700 (PDT) Received: from mail-vc0-f181.google.com (mail-vc0-f181.google.com [209.85.220.181]) by mx.google.com with ESMTPS id v14si61108vco.111.2014.04.09.02.57.36 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 09 Apr 2014 02:57:36 -0700 (PDT) Received-SPF: neutral (google.com: 209.85.220.181 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) client-ip=209.85.220.181; Received: by mail-vc0-f181.google.com with SMTP id id10so1805896vcb.40 for ; Wed, 09 Apr 2014 02:57:36 -0700 (PDT) X-Received: by 10.58.31.136 with SMTP id a8mr8269732vei.20.1397037456337; Wed, 09 Apr 2014 02:57:36 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.220.12.8 with SMTP id v8csp315948vcv; Wed, 9 Apr 2014 02:57:36 -0700 (PDT) X-Received: by 10.224.36.194 with SMTP id u2mr10727022qad.73.1397037455874; Wed, 09 Apr 2014 02:57:35 -0700 (PDT) Received: from lists.xen.org (lists.xen.org. [50.57.142.19]) by mx.google.com with ESMTPS id l5si159605qai.261.2014.04.09.02.57.35 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Wed, 09 Apr 2014 02:57:35 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of xen-devel-bounces@lists.xen.org designates 50.57.142.19 as permitted sender) client-ip=50.57.142.19; Received: from localhost ([127.0.0.1] helo=lists.xen.org) by lists.xen.org with esmtp (Exim 4.72) (envelope-from ) id 1WXpDz-0002Lr-Lg; Wed, 09 Apr 2014 09:55:19 +0000 Received: from mail6.bemta4.messagelabs.com ([85.158.143.247]) by lists.xen.org with esmtp (Exim 4.72) (envelope-from ) id 1WXpDx-0002La-CM for xen-devel@lists.xen.org; Wed, 09 Apr 2014 09:55:17 +0000 Received: from [85.158.143.35:57893] by server-2.bemta-4.messagelabs.com id 4D/B0-06539-40915435; Wed, 09 Apr 2014 09:55:16 +0000 X-Env-Sender: Ian.Campbell@citrix.com X-Msg-Ref: server-7.tower-21.messagelabs.com!1397037313!8012362!2 X-Originating-IP: [66.165.176.89] X-SpamReason: No, hits=0.0 required=7.0 tests=sa_preprocessor: VHJ1c3RlZCBJUDogNjYuMTY1LjE3Ni44OSA9PiAyMDMwMDc=\n X-StarScan-Received: X-StarScan-Version: 6.11.1; banners=-,-,- X-VirusChecked: Checked Received: (qmail 32070 invoked from network); 9 Apr 2014 09:55:15 -0000 Received: from smtp.citrix.com (HELO SMTP.CITRIX.COM) (66.165.176.89) by server-7.tower-21.messagelabs.com with RC4-SHA encrypted SMTP; 9 Apr 2014 09:55:15 -0000 X-IronPort-AV: E=Sophos;i="4.97,825,1389744000"; d="scan'208";a="119430980" Received: from accessns.citrite.net (HELO FTLPEX01CL02.citrite.net) ([10.9.154.239]) by FTLPIPO01.CITRIX.COM with ESMTP; 09 Apr 2014 09:55:15 +0000 Received: from norwich.cam.xci-test.com (10.80.248.129) by smtprelay.citrix.com (10.13.107.79) with Microsoft SMTP Server id 14.2.342.4; Wed, 9 Apr 2014 05:55:14 -0400 Received: from cosworth.uk.xensource.com ([10.80.16.52] helo=cosworth.uk.xensource.com.) by norwich.cam.xci-test.com with esmtp (Exim 4.72) (envelope-from ) id 1WXpDt-0002Vi-TL; Wed, 09 Apr 2014 09:55:13 +0000 From: Ian Campbell To: , Date: Wed, 9 Apr 2014 10:55:13 +0100 Message-ID: <1397037313-24850-1-git-send-email-ian.campbell@citrix.com> X-Mailer: git-send-email 1.7.10.4 MIME-Version: 1.0 X-DLP: MIA2 Cc: Ian Campbell Subject: [Xen-devel] [PATCH] docs: remove xend latex source X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Post: , List-Help: , List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: ian.campbell@citrix.com X-Original-Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.220.181 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 List-Archive: AFAICT this hasn't actually been built since 8311d176ea6ff "docs: Remove outdated LaTex documentation". Signed-off-by: Ian Campbell Acked-by: Ian Jackson --- docs/misc/xend.tex | 419 ---------------------------------------------------- 1 file changed, 419 deletions(-) delete mode 100644 docs/misc/xend.tex diff --git a/docs/misc/xend.tex b/docs/misc/xend.tex deleted file mode 100644 index 1a6c687..0000000 --- a/docs/misc/xend.tex +++ /dev/null @@ -1,419 +0,0 @@ -% -*- mode: LaTeX -*- -\def\seca{\chapter} -\def\secb{\section} -\def\secc{\subsection} -\def\secd{\subsubsection} -\def\refa{chapter} -\def\refb{section} -\def\refc{section} -\def\refd{section} - -%\def\seca{\section} -%\def\secb{\subsection} -%\def\secc{\subsubsection} -%\def\refa{section} -%\def\refb{section} -%\def\refc{section} - -\documentclass[11pt,twoside,final,openright]{report} -\usepackage{a4,graphicx,setspace} -\setstretch{1.15} - -\begin{document} - -% TITLE PAGE -\pagestyle{empty} -\begin{center} -\vspace*{\fill} -\includegraphics{figs/xenlogo.eps} -\vfill -\vfill -\vfill -\begin{tabular}{l} -{\Huge \bf Xend} \\[4mm] -{\huge Xen v2.0 for x86} \\[80mm] - -{\Large Xen is Copyright (c) 2004, The Xen Team} \\[3mm] -{\Large University of Cambridge, UK} \\[20mm] -{\large Last updated 30 August 2004} -\end{tabular} -\vfill -\end{center} -\cleardoublepage - -% TABLE OF CONTENTS -\pagestyle{plain} -\pagenumbering{roman} -{ \parskip 0pt plus 1pt - \tableofcontents } -\cleardoublepage -% PREPARE FOR MAIN TEXT -\pagenumbering{arabic} -\raggedbottom -\widowpenalty=10000 -\clubpenalty=10000 -\parindent=0pt -\renewcommand{\topfraction}{.8} -\renewcommand{\bottomfraction}{.8} -\renewcommand{\textfraction}{.2} -\renewcommand{\floatpagefraction}{.8} - -\setstretch{1.15} - -\seca{Introduction} -Xend is the control daemon used to manage a machine running the Xen hypervisor. -Xend is responsible for creating and destroying domains and managing their -resources, such as virtual block devices and virtual network interfaces. - -Xend exists because the Xen hypervisor itself only manages the memory image -of a domain and its scheduling. Xen provides the event channels that connect -a domain to its devices, but is intentionally not involved in setting them up. - -Xend runs as a daemon in the privileged domain 0 and uses a low-level api -to communicate with Xen via the domain 0 kernel. Xend exports its control -interface to its clients using HTTP. Most programming languages have -HTTP client libraries, so this interface can be used from most popular -languages, for example Python, Perl, C, Java. -Xend itself is written in Python, as are most of the Xen tools. - -The xend interface is intended to be a complete interface for the creation -and management of domains. It supports domain creation, shutdown, reboot, -destruction, save, restore and migration. - -When xend creates a domain it creates the domain memory image and communicates -with the device driver domain(s) to configure the devices for the domain. -This sets up connections between the domain and backend device controllers -in the driver domain. When a domain shuts down its memory image cannot be fully released -unless its backend devices are released and disconnected. This is done by xend. -In order to protect against loss of this information when xend is restarted, -xend maintains a persistent database of domain configurations. This allows -xend to be stopped and restarted without loss of configuration information. -For example, in order to upgrade the xend software. - -\seca{Domain lifecycle} -\secb{Domain creation} -Xend is instructed to create a domain by posting a domain\_create message to it, -containing the domain configuration to be instantiated. The domain configuration -is in sxp format and is as far as possible {\em fully-bound}, that is, all -parameters are fully-specified. The domain configuration is saved in the filesystem -so that it can be reused later if necessary. - -The domain configuration specifies the domain name, memory size, kernel image -and parameters, and all the domain devices. Xend uses the Xen api to create -the domain memory image, and then {\em builds} the memory image for the domain -using the kernel image. At this point the domain exists, but it cannot be run because -it has no devices. Xend then communicates with the device driver domain to create -the configured devices. Once the devices are created it sets up event channels -for them between the driver domain and the new domain, and notifies the new domain -that its devices are connected. At this point the domain can be started. - -Xend is also responsible for managing domain consoles. When a domain is created, -xend sets up a console event channel to the domain, and creates a TCP listening port -for the domain console. When a connection is accepted to the port, xend -connects input and output for the port to the domain console channel. - -\secb{Domain destruction} -When a domain terminates, because it has been shutdown or it has crashed, the -domain resources must be released so that the domain memory image can be -finally removed from xen. Xend monitors the domains, and is also signaled by -xen (using a VIRQ) when a domain exits. Xend examines the domain states and -determines which domains have exited. It then communicates with the driver domain -to release the devices for exited domains. Xend also closes any open console -connections and removes the TCP listeners for exited domains. -Once all devices have been released it instructs xen to destroy the memory image. - -\secb{Domain restart} -Domain restart is the xen equivalent of a machine reboot. When a domain -exits because it has been shutdown in reboot mode, its exit code is reboot. -When examining domains to find those that have exited and destroy them, -xend detects those that have exited for reboot and does not completely destroy -them. It disconnects all their devices, and detaches the console listener -from its channel to the domain, but does not close it. Instead it schedules -a call to rebuild the domain from its configuration. This proceeds almost -identically to creating the domain, except that the console listener is -reused and connected to the new domain. This allows existing console -connections to remain connected across a domain restart. The restarted -domain keeps the same name and domain id. - -The determination of when to restart a domain is in fact slightly more -complex than described above. A domain is configured with a -{\em restart mode}. If the restart mode is {\em onreboot}, the default, -restart happens when the domain is shutdown normally and -exits with code reboot. If the restart mode is {\em never} the domain is -not restarted. If the restart mode is {\em always} the domain is always -restarted, regardless of how it exited. - -In order to prevent continual domain crash causing restart loops, xend -has a {\em minimum restart time}. Xend remembers when a domain was last -restarted and will fail a restart that happens inside the minimum -restart time. - -\seca{Devices} -\secb{Virtual network interfaces} -Each virtual network interface (vif) has 2 parts: the font-end device in its domain, -and the back-end device in the driver domain. Usually the driver domain is domain 0, -and there is a linux network device corresponding to the vif. The linux device for -interface N on domain D is called vifD.N. When a packet is sent on the vif in the -domain the packet is received from the linux device. The linux devices are connected -to network interfaces using ethernet bridging. - -The default setup is a bridge xen-br0, with eth0 connected to it, and the routes -for eth0 directed at xen-br0. This is controlled by the xend network setup script, -default {\tt /etc/xen/network}, which is run when xend starts. - -When the vifs for a domain are created, a vif control script, default {\tt /etc/xen/vif-bridge}, -is run to connect the vif to its bridge. The default script connects the vif -to xen-br0 and optionally sets up iptables rules to prevent IP address spoofing. -The bridge a vif is connected to can be defined in its configuration, and this is useful -for setting up virtual networks using several bridges. - -\secb{Virtual block devices} -Virtual block devices in a domain are interfaces onto back-end device drivers -that export physical devices to domains. In the default configuration the back-end -driver is in domain 0 and can export any linux block device to a domain. This includes -physical disk partitions, LVM volumes and loopback mounts of files. In fact anything -that linux can represent as a block device can be exported to a domain as virtual -block device. - -\seca{Xend invocation} -Xend is started (by root) using the command -\begin{verbatim} -xend start -\end{verbatim} -Xend can be stopped using -\begin{verbatim} -xend stop -\end{verbatim} -Xend must be started before any domains (apart from domain 0) can be created. -If you try to use the {\tt xm} tool when xend is not running you will get a -'connection refused' message. - -\secb{Xend configuration} -Xend reads its own configuration from {\tt /etc/xen/xend-config.sxp}, which is -a sequence of s-expressions. The configuration parameters are: -\begin{itemize} - -\item xend-port: Port xend should use for the HTTP interface (default 8000). - -\item xend-address: Address xend should listen on. - Specifying 'localhost' prevents remote connections. - Specifying the empty string '' allows all connections, and is the default. - -\item network-script: The script used to start/stop networking for xend (default network). - -\item vif-bridge: The default bridge that virtual interfaces should be connected to - (default xen-br0). - -\item vif-script: The default script used to control virtual interfaces - (default vif-bridge). - -\item vif-antispoof: Whether iptables should be set up to prevent IP spoofing for - virtual interfaces (default yes). -\end{itemize} - -Configuration scripts ({\it e.g.} for network-script) are looked for in {\tt /etc/xen} -unless their name begins with '/'. - -Xend sends its log output to {\tt /var/log/xen/xend.log}. This is a rotating logfile, -and logs are moved onto {\tt xend.log.1} {\it etc.} as they get large. Old logs may -be deleted. - -\secb{Xend database} -Xend needs to make some data persistent, and it uses files under {\tt /var/xen/xend-db} -for this. The persistent data is stored in files in SXP format. Domain information -is saved when domains are created. When xend starts it reads the file {\tt /var/xen/lastboot} -(if it exists) to determine the last time the system was rebooted. It compares this time -with the last reboot time in {\tt wtmp} to determine if the system has been rebooted -since xend last ran. If the system has been rebooted xend removes all its saved data -that is not persistent across reboots (for example domain data). - -\seca{Xend HTTP Interface} - The xend interface uses HTTP 1.1 \cite{http} as its transport. -Simple PUT and GET calls can encode parameters using the standard url-encoding -for parameters: MIME type {\tt application/x-www-form-urlencoded}. -When file upload is required, the {\tt multipart/form-data} encoding is used. -See the HTML 4.1 specification for details \cite{html}. - -Xend functions as a webserver and supports two interfaces: one -for web-browsers and one for programs. -The web-browser interface returns replies in HTML and includes forms -for interactive operations such as stopping domains and creating domains -from an uploaded configuration. The programmatic interface usually returns replies -in s-expression format. Both interfaces are accessed -in exactly the same way over HTTP - the only difference is the data returned. - -The webserver distinguishes browsers from programs using the {\tt User-Agent} -and {\tt Accept} headers in the HTTP request. If there is no {\tt User-Agent} or no -{\tt Acccept} header, or {\tt Accept} includes the type {\tt application/sxp}, the -webserver assumes the client is a program and returns SXP. Otherwise -it assumes the client is a webserver and returns HTML. -In some cases the return value is essentially a string, so {\tt Content-Type} -{\tt text/plain} is returned. - -The HTTP api supported is listed below. All paths in it are relative to the -server root, for example {\tt http://localhost:8000/xend}. -As defined in the HTTP specification, we use GET for side-effect free -operations that may safely be repeated, and POST for operations with -side-effects. For each request we list the HTTP method (GET or POST), -the url relative to the server root, the operation name and arguments (if any). -The operation name is passed as request parameter 'op', and the arguments -are passed by name. Operation name and parameters can be encoded using either -encoding described above. We also list the corresponding api function from the -Python client interface in {\tt xen.xend.XendClient}. - -\begin{itemize} -\item {\tt GET /},\\ - {\tt xend()}:\\ - Get list of urls under xend root. - -\item {\tt GET /node},\\ - {\tt xend\_node()}:\\ - Get node information. - -\item {\tt POST /node shutdown()},\\ - {\tt xend\_node\_shutdown()}:\\ - Shutdown the node - -\item {\tt POST /node reboot()},\\ - {\tt xend\_node\_reboot()}:\\ - Reboot the node - -\item {\tt POST /node notify()}:\\ - Set node notification url - -\item {\tt GET /node/dmesg},\\ - {\tt xend\_node\_dmesg()}:\\ - Get xen boot message. - -\item {\tt GET /node/log},\\ - {\tt xend\_node\_log()}:\\ - Get xend log. - -\item {\tt GET /domain}\\ - {\tt xend\_domains()}:\\ - Get list of domains. - -\item {\tt POST /domain create(config)},\\ - {\tt xend\_domain\_create(config)}:\\ - Create a domain. - -\item {\tt POST /domain restore(file)},\\ - {\tt xend\_domain\_restore(filename)}:\\ - Restore a saved domain. - -\item {\tt GET /domain/},\\ - {\tt xend\_domain(dom)}:\\ - Get domain information. - -\item {\tt POST /domain/[dom] configure(config)},\\ - {\tt xend\_domain\_configure(dom, conf)}:\\ - Configure an existing domain (for internal use by restore and migrate). - -\item {\tt POST /domain/[dom] unpause()},\\ - {\tt xend\_domain\_unpause(dom)}:\\ - Start domain running - -\item {\tt POST /domain/[dom] pause()},\\ - {\tt xend\_domain\_pause(dom)}:\\ - Stop domain running. - -\item {\tt POST /domain/[dom] shutdown(reason)},\\ - {\tt xend\_domain\_shutdown(dom, reason)}:\\ - Shutdown domain, reason can be reboot, poweroff, halt. - -\item {\tt POST /domain/[dom] destroy(reason)},\\ - {\tt xend\_domain\_destroy(dom, reason)}:\\ - Destroy domain, reason can be reboot, halt. - -\item {\tt POST /domain/[dom] save(file)},\\ - {\tt xend\_domain\_save(dom, filename)}:\\ - Save a domain to a file. - -\item {\tt POST /domain/[dom] migrate(dst)},\\ - {\tt xend\_domain\_migrate(dom, dst)}:\\ - Migrate a domain. - -\item {\tt POST /domain/[dom] pincpu(cpu)},\\ - {\tt xend\_domain\_pincpu(self, id, cpu)}\\: - Pin a domain to a cpu. - -\item {\tt POST /domain/[dom] maxmem\_set(memory)},\\ - {\tt xend\_domain\_maxmem\_set(dom, memory)}:\\ - Set domain maximum memory limit. - -\item {\tt POST /domain/[dom] device\_create(config)}\\ - {\tt xend\_domain\_device\_create(dom, config)}:\\ - Add a device to a domain. - -\item {\tt POST /domain/[dom] device\_destroy(type, index)},\\ - {\tt xend\_domain\_device\_destroy(dom, type, index)}:\\ - Delete a device from a domain - -\item {\tt GET /domain/[dom] vifs()},\\ - {\tt xend\_domain\_vifs(dom)}:\\ - Get virtual network interfaces. - -\item {\tt GET /domain/[dom] vif(vif)},\\ - {\tt xend\_domain\_vif(dom, vif)}:\\ - Get virtual network interface. - -\item {\tt GET /domain/[dom] vbds()},\\ - {\tt xend\_domain\_vbds(dom)}:\\ - Get virtual block devices. - -\item {\tt GET /domain/[dom] vbd(vbd)},\\ - {\tt xend\_domain\_vbd(dom, vbd)}:\\ - Get virtual block device. - -\item {\tt GET /console},\\ - {\tt xend\_consoles()}:\\ - Get list of consoles. - -\item {\tt GET /console/[id]}\\ - {\tt xend\_console(id)}:\\ - Get information about a console. - -\item {\tt GET /console/[id] disconnect()}\\ - {\tt xend\_console\_disconnect(self, id)}:\\ - Disconnect any console TCP connection. - -\item {\tt POST /event inject(event)}\\ - {\tt xend\_event\_inject(sxpr)}:\\ - Inject an event. - -\end{itemize} - -\secb{Xend debugging interface} -Xend also listens on port 8001. Connecting to this port (for example via telnet) -allows access to some debugging functions: -\begin{itemize} -\item help: list functions -\item traceon: turn xend tracing on -\item traceoff: turn xend tracing off -\item quit: disconnect. -\item info: list console listeners, block and network device controllers. -\end{itemize} - -When tracing is on xend logs all functions calls and exceptions to -{\tt /var/log/xen/xend.trace}. - -\begin{thebibliography}{99} - -\bibitem{html} -HTML 4.01 Specification,\\ -http://www.w3.org/TR/html4/,\\ -W3C Recommendation, 24 December 1999. - -\bibitem{http} -Hypertext Transfer Protocol -- HTTP/1.1,\\ -http://www.ietf.org/rfc/rfc2616.txt,\\ -RFC 2616, IETF 1999. - -\bibitem{ssh} -http://www.openssh.org. - -\bibitem{stunnel} -http://www.stunnel.org. - -\end{thebibliography} -\end{document}