Index: trunk/doc/manual/Makefile.kmk
===================================================================
--- trunk/doc/manual/Makefile.kmk	(revision 33552)
+++ trunk/doc/manual/Makefile.kmk	(revision 33555)
@@ -67,5 +67,5 @@
 ifdef VBOX_WITH_DOCS
  # Default language
- VBOX_MANUAL_LANGUAGES = en_US
+ VBOX_MANUAL_ADD_LANGUAGES = en_US fr_FR
 
  if defined(VBOX_ONLY_SDK) || defined(VBOX_WITH_DOCS_SDKREF)
@@ -95,11 +95,13 @@
   	$(VBOX_PATH_BIN_CHM)
 
-  OTHERS += \
-  	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_BIN)/UserManual_$(f).pdf)
-  ifdef VBOX_WITH_DOCS_CHM
-  OTHERS.win += \
-  	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_BIN)/VirtualBox_$(f).chm)
-  OTHERS.linux += \
-  	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_BIN)/VirtualBox_$(f).chm)
+  ifdef VBOX_WITH_DOCS_TRANSLATIONS
+   OTHERS += \
+   	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_BIN)/UserManual_$(f).pdf)
+   ifdef VBOX_WITH_DOCS_CHM
+   OTHERS.win += \
+   	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_BIN)/VirtualBox_$(f).chm)
+   OTHERS.linux += \
+   	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_BIN)/VirtualBox_$(f).chm)
+   endif
   endif
  endif # !VBOX_ONLY_SDK
Index: trunk/doc/manual/fr_FR/SDKRef.xml
===================================================================
--- trunk/doc/manual/fr_FR/SDKRef.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/SDKRef.xml	(revision 33555)
@@ -0,0 +1,4183 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<book>
+  <bookinfo>
+    <title>$VBOX_PRODUCT<superscript>®</superscript></title>
+
+    <subtitle>Programming Guide and Reference</subtitle>
+
+    <edition>Version $VBOX_VERSION_STRING</edition>
+
+    <corpauthor>$VBOX_VENDOR</corpauthor>
+
+    <address>http://www.virtualbox.org</address>
+
+    <copyright>
+      <year>2004-$VBOX_C_YEAR</year>
+
+      <holder>$VBOX_VENDOR</holder>
+    </copyright>
+  </bookinfo>
+
+  <chapter>
+    <title>Introduction</title>
+
+    <para>VirtualBox comes with comprehensive support for third-party
+    developers. This Software Development Kit (SDK) contains all the
+    documentation and interface files that are needed to write code that
+    interacts with VirtualBox.</para>
+
+    <sect1>
+      <title>Modularity: the building blocks of VirtualBox</title>
+
+      <para>VirtualBox is cleanly separated into several layers, which can be
+      visualized like in the picture below:</para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/vbox-components.png"
+                     width="12cm" />
+        </imageobject>
+      </mediaobject>
+
+      <para>The orange area represents code that runs in kernel mode, the blue
+      area represents userspace code.</para>
+
+      <para>At the bottom of the stack resides the hypervisor -- the core of
+      the virtualization engine, controlling execution of the virtual machines
+      and making sure they do not conflict with each other or whatever the
+      host computer is doing otherwise.</para>
+
+      <para>On top of the hypervisor, additional internal modules provide
+      extra functionality. For example, the RDP server, which can deliver the
+      graphical output of a VM remotely to an RDP client, is a separate module
+      that is only loosely tacked into the virtual graphics device. Live
+      Migration and Resource Monitor are additional modules currently in the
+      process of being added to VirtualBox.</para>
+
+      <para>What is primarily of interest for purposes of the SDK is the API
+      layer block that sits on top of all the previously mentioned blocks.
+      This API, which we call the <emphasis role="bold">"Main API"</emphasis>,
+      exposes the entire feature set of the virtualization engine below. It is
+      completely documented in this SDK Reference -- see <xref
+      linkend="sdkref_classes" /> and <xref linkend="sdkref_enums" /> -- and
+      available to anyone who wishes to control VirtualBox programmatically.
+      We chose the name "Main API" to differentiate it from other programming
+      interfaces of VirtualBox that may be publicly accessible.</para>
+
+      <para>With the Main API, you can create, configure, start, stop and
+      delete virtual machines, retrieve performance statistics about running
+      VMs, configure the VirtualBox installation in general, and more. In
+      fact, internally, the front-end programs
+      <computeroutput>VirtualBox</computeroutput> and
+      <computeroutput>VBoxManage</computeroutput> use nothing but this API as
+      well -- there are no hidden backdoors into the virtualization engine for
+      our own front-ends. This ensures the entire Main API is both
+      well-documented and well-tested. (The same applies to
+      <computeroutput>VBoxHeadless</computeroutput>, which is not shown in the
+      image.)</para>
+    </sect1>
+
+    <sect1 id="webservice-or-com">
+      <title>Two guises of the same "Main API": the web service or
+      COM/XPCOM</title>
+
+      <para>There are several ways in which the Main API can be called by
+      other code:<orderedlist>
+          <listitem>
+            <para>VirtualBox comes with a <emphasis role="bold">web
+            service</emphasis> that maps nearly the entire Main API. The web
+            service ships in a stand-alone executable
+            (<computeroutput>vboxwebsrv</computeroutput>) that, when running,
+            acts as an HTTP server, accepts SOAP connections and processes
+            them.</para>
+
+            <para>Since the entire web service API is publicly described in a
+            web service description file (in WSDL format), you can write
+            client programs that call the web service in any language with a
+            toolkit that understands WSDL. These days, that includes most
+            programming languages that are available: Java, C++, .NET, PHP,
+            Python, Perl and probably many more.</para>
+
+            <para>All of this is explained in detail in subsequent chapters of
+            this book.</para>
+
+            <para>There are two ways in which you can write client code that
+            uses the web service:<orderedlist>
+                <listitem>
+                  <para>For Java as well as Python, the SDK contains
+                  easy-to-use classes that allow you to use the web service in
+                  an object-oriented, straightforward manner. We shall refer
+                  to this as the <emphasis role="bold">"object-oriented web
+                  service (OOWS)"</emphasis>.</para>
+
+                  <para>The OO bindings for Java are described in <xref
+                  linkend="javaapi" />, those for Python in <xref lang=""
+                  linkend="glue-python-ws" />.</para>
+                </listitem>
+
+                <listitem>
+                  <para>Alternatively, you can use the web service directly,
+                  without the object-oriented client layer. We shall refer to
+                  this as the <emphasis role="bold">"raw web
+                  service"</emphasis>.</para>
+
+                  <para>You will then have neither native object orientation
+                  nor full type safety, since web services are neither
+                  object-oriented nor stateful. However, in this way, you can
+                  write client code even in languages for which we do not ship
+                  object-oriented client code; all you need is a programming
+                  language with a toolkit that can parse WSDL and generate
+                  client wrapper code from it.</para>
+
+                  <para>We describe this further in <xref
+                  linkend="raw-webservice" />, with samples for Java and
+                  Perl.</para>
+                </listitem>
+              </orderedlist></para>
+          </listitem>
+
+          <listitem>
+            <para>Internally, for portability and easier maintenance, the Main
+            API is implemented using the <emphasis role="bold">Component
+            Object Model (COM),</emphasis> an interprocess mechanism for
+            software components originally introduced by Microsoft for
+            Microsoft Windows. On a Windows host, VirtualBox will use
+            Microsoft COM; on other hosts where COM is not present, it ships
+            with XPCOM, a free software implementation of COM originally
+            created by the Mozilla project for their browsers.</para>
+
+            <para>So, if you are familiar with COM and the C++ programming
+            language (or with any other programming language that can handle
+            COM/XPCOM objects, such as Java, Visual Basic or C#), then you can
+            use the COM/XPCOM API directly. VirtualBox comes with all
+            necessary files and documentation to build fully functional COM
+            applications. For an introduction, please see <xref
+            linkend="api_com" /> below.</para>
+
+            <para>The VirtualBox front-ends (the graphical user interfaces as
+            well as the command line), which are all written in C++, use
+            COM/XPCOM to call the Main API. Technically, the web service is
+            another front-end to this COM API, mapping almost all of it to
+            SOAP clients.</para>
+          </listitem>
+        </orderedlist></para>
+
+      <para>If you wonder which way to choose, here are a few
+      comparisons:<table>
+          <title>Comparison web service vs. COM/XPCOM</title>
+
+          <tgroup cols="2">
+            <tbody>
+              <row>
+                <entry><emphasis role="bold">Web service</emphasis></entry>
+
+                <entry><emphasis role="bold">COM/XPCOM</emphasis></entry>
+              </row>
+
+              <row>
+                <entry><emphasis role="bold">Pro:</emphasis> Easy to use with
+                Java and Python with the object-oriented web service;
+                extensive support even with other languages (C++, .NET, PHP,
+                Perl and others)</entry>
+
+                <entry><emphasis role="bold">Con:</emphasis> Usable from
+                languages where COM bridge available (most languages on
+                Windows platform, Python and C++ on other hosts)</entry>
+              </row>
+
+              <row>
+                <entry><emphasis role="bold">Pro:</emphasis> Client can be on
+                remote machine</entry>
+
+                <entry><emphasis role="bold">Con: </emphasis>Client must be on
+                the same host where virtual machine is executed</entry>
+              </row>
+
+              <row>
+                <entry><emphasis role="bold">Con: </emphasis>Significant
+                overhead due to XML marshalling over the wire for each method
+                call</entry>
+
+                <entry><emphasis role="bold">Pro: </emphasis>Relatively low
+                invocation overhead</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table></para>
+
+      <para>In the following chapters, we will describe the different ways in
+      which to program VirtualBox, starting with the method that is easiest to
+      use and then increase complexity as we go along.</para>
+    </sect1>
+
+    <sect1 id="api_soap_intro">
+      <title>About web services in general</title>
+
+      <para>Web services are a particular type of programming interface.
+      Whereas, with "normal" programming, a program calls an application
+      programming interface (API) defined by another program or the operating
+      system and both sides of the interface have to agree on the calling
+      convention and, in most cases, use the same programming language, web
+      services use Internet standards such as HTTP and XML to
+      communicate.<footnote>
+          <para>In some ways, web services promise to deliver the same thing
+          as CORBA and DCOM did years ago. However, while these previous
+          technologies relied on specific binary protocols and thus proved to
+          be difficult to use between diverging platforms, web services
+          circumvent these incompatibilities by using text-only standards like
+          HTTP and XML. On the downside (and, one could say, typical of things
+          related to XML), a lot of standards are involved before a web
+          service can be implemented. Many of the standards invented around
+          XML are used one way or another. As a result, web services are slow
+          and verbose, and the details can be incredibly messy. The relevant
+          standards here are called SOAP and WSDL, where SOAP describes the
+          format of the messages that are exchanged (an XML document wrapped
+          in an HTTP header), and WSDL is an XML format that describes a
+          complete API provided by a web service. WSDL in turn uses XML Schema
+          to describe types, which is not exactly terse either. However, as
+          you will see from the samples provided in this chapter, the
+          VirtualBox web service shields you from these details and is easy to
+          use.</para>
+        </footnote></para>
+
+      <para>In order to successfully use a web service, a number of things are
+      required -- primarily, a web service accepting connections; service
+      descriptions; and then a client that connects to that web service. The
+      connections are governed by the SOAP standard, which describes how
+      messages are to be exchanged between a service and its clients; the
+      service descriptions are governed by WSDL.</para>
+
+      <para>In the case of VirtualBox, this translates into the following
+      three components:<orderedlist>
+          <listitem>
+            <para>The VirtualBox web service (the "server"): this is the
+            <computeroutput>vboxwebsrv</computeroutput> executable shipped
+            with VirtualBox. Once you start this executable (which acts as a
+            HTTP server on a specific TCP/IP port), clients can connect to the
+            web service and thus control a VirtualBox installation.</para>
+          </listitem>
+
+          <listitem>
+            <para>VirtualBox also comes with WSDL files that describe the
+            services provided by the web service. You can find these files in
+            the <computeroutput>sdk/bindings/webservice/</computeroutput>
+            directory. These files are understood by the web service toolkits
+            that are shipped with most programming languages and enable you to
+            easily access a web service even if you don't use our
+            object-oriented client layers. VirtualBox is shipped with
+            pregenerated web service glue code for several languages (Python,
+            Perl, Java).</para>
+          </listitem>
+
+          <listitem>
+            <para>A client that connects to the web service in order to
+            control the VirtualBox installation.</para>
+
+            <para>Unless you play with some of the samples shipped with
+            VirtualBox, this needs to be written by you.</para>
+          </listitem>
+        </orderedlist></para>
+    </sect1>
+
+    <sect1 id="runvboxwebsrv">
+      <title>Running the web service</title>
+
+      <para>The web service ships in an stand-alone executable,
+      <computeroutput>vboxwebsrv</computeroutput>, that, when running, acts as
+      a HTTP server, accepts SOAP connections and processes them -- remotely
+      or from the same machine.<note>
+          <para>The web service executable is not contained with the
+          VirtualBox SDK, but instead ships with the standard VirtualBox
+          binary package for your specific platform. Since the SDK contains
+          only platform-independent text files and documentation, the binaries
+          are instead shipped with the platform-specific packages.</para>
+        </note></para>
+
+      <para>The <computeroutput>vboxwebsrv</computeroutput> program, which
+      implements the web service, is a text-mode (console) program which,
+      after being started, simply runs until it is interrupted with Ctrl-C or
+      a kill command.</para>
+
+      <para>Once the web service is started, it acts as a front-end to the
+      VirtualBox installation of the user account that it is running under. In
+      other words, if the web service is run under the user account of
+      <computeroutput>user1</computeroutput>, it will see and manipulate the
+      virtual machines and other data represented by the VirtualBox data of
+      that user (e.g., on a Linux machine, under
+      <computeroutput>/home/user1/.VirtualBox</computeroutput>; see the
+      VirtualBox User Manual for details on where this data is stored).</para>
+
+      <sect2 id="vboxwebsrv-ref">
+        <title>Command line options of vboxwebsrv</title>
+
+        <para>The web service supports the following command line
+        options:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para><computeroutput>--help</computeroutput> (or
+            <computeroutput>-h</computeroutput>): print a brief summary of
+            command line options.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--background</computeroutput> (or
+            <computeroutput>-b</computeroutput>): run the web service as a
+            background daemon. This option is not supported on Windows
+            hosts.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--host</computeroutput> (or
+            <computeroutput>-H</computeroutput>): This specifies the host to
+            bind to and defaults to "localhost".</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--port</computeroutput> (or
+            <computeroutput>-p</computeroutput>): This specifies which port to
+            bind to on the host and defaults to 18083.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--timeout</computeroutput> (or
+            <computeroutput>-t</computeroutput>): This specifies the session
+            timeout, in seconds, and defaults to 300 (five minutes). A web
+            service client that has logged on but makes no calls to the web
+            service will automatically be disconnected after the number of
+            seconds specified here, as if it had called the
+            <computeroutput>IWebSessionManager::logoff()</computeroutput>
+            method provided by the web service itself.</para>
+
+            <para>It is normally vital that each web service client call this
+            method, as the web service can accumulate large amounts of memory
+            when running, especially if a web service client does not properly
+            release managed object references. As a result, this timeout value
+            should not be set too high, especially on machines with a high
+            load on the web service, or the web service may eventually deny
+            service.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--check-interval</computeroutput> (or
+            <computeroutput>-i</computeroutput>): This specifies the interval
+            in which the web service checks for timed-out clients, in seconds,
+            and defaults to 5. This normally does not need to be
+            changed.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--verbose</computeroutput> (or
+            <computeroutput>-v</computeroutput>): Normally, the webservice
+            outputs only brief messages to the console each time a request is
+            served. With this option, the webservice prints much more detailed
+            data about every request and the COM methods that those requests
+            are mapped to internally, which can be useful for debugging client
+            programs.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--logfile</computeroutput> (or
+            <computeroutput>-F</computeroutput>)
+            <computeroutput>&lt;file&gt;</computeroutput>: If this is
+            specified, the webservice not only prints its output to the
+            console, but also writes it to the specified file. The file is
+            created if it does not exist; if it does exist, new output is
+            appended to it. This is useful if you run the webservice
+            unattended and need to debug problems after they have
+            occurred.</para>
+          </listitem>
+        </itemizedlist>
+      </sect2>
+
+      <sect2 id="websrv_authenticate">
+        <title>Authenticating at web service logon</title>
+
+        <para>As opposed to the COM/XPCOM variant of the Main API, a client
+        that wants to use the web service must first log on by calling the
+        <computeroutput>IWebsessionManager::logon()</computeroutput> API (see
+        <xref linkend="IWebsessionManager__logon" />) that is specific to the
+        web service. Logon is necessary for the web service to be stateful;
+        internally, it maintains a session for each client that connects to
+        it.</para>
+
+        <para>The <computeroutput>IWebsessionManager::logon()</computeroutput>
+        API takes a user name and a password as arguments, which the web
+        service then passes to a customizable authentication plugin that
+        performs the actual authentication.</para>
+
+        <para>For testing purposes, it is recommended that you first disable
+        authentication with this command:<screen>VBoxManage setproperty websrvauthlibrary null</screen></para>
+
+        <para><warning>
+            <para>This will cause all logons to succeed, regardless of user
+            name or password. This should of course not be used in a
+            production environment.</para>
+          </warning>Generally, the mechanism by which clients are
+        authenticated is configurable by way of the
+        <computeroutput>VBoxManage</computeroutput> command:</para>
+
+        <para><screen>VBoxManage setproperty websrvauthlibrary default|null|&lt;library&gt;</screen></para>
+
+        <para>This way you can specify any shared object/dynamic link module
+        that conforms with the specifications for authentication modules as
+        laid out in section 9.3 of the VirtualBox User Manual; the web service
+        uses the same kind of modules as the VirtualBox RDP server.</para>
+
+        <para>By default, after installation, the web service uses the
+        VRDPAuth module that ships with VirtualBox. This module uses PAM on
+        Linux hosts to authenticate users. Any valid username/password
+        combination is accepted, it does not have to be the username and
+        password of the user running the webservice daemon. Unless
+        <computeroutput>vboxwebsrv</computeroutput> runs as root, PAM
+        authentication can fail, because sometimes the file
+        <computeroutput>/etc/shadow</computeroutput>, which is used by PAM, is
+        not readable. On most Linux distribution PAM uses a suid root helper
+        internally, so make sure you test this before deploying it. One can
+        override this behavior by setting the environment variable
+        <computeroutput>VBOX_PAM_ALLOW_INACTIVE</computeroutput> which will
+        suppress failures when unable to read the shadow password file. Please
+        use this variable carefully, and only if you fully understand what
+        you're doing.</para>
+      </sect2>
+
+      <sect2>
+        <title>Solaris host: starting the web service via SMF</title>
+
+        <para>On Solaris hosts, the VirtualBox web service daemon is
+        integrated into the SMF framework. You can change the parameters, but
+        don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
+svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
+svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>
+
+        <para>If you made any change, don't forget to run the following
+        command to put the changes into effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>
+
+        <para>If you forget the above command then the previous settings will
+        be used when enabling the service. Check the current property settings
+        with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>
+
+        <para>When everything is configured correctly you can start the
+        VirtualBox webservice with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>
+
+        <para>For more information about SMF, please refer to the Solaris
+        documentation.</para>
+      </sect2>
+    </sect1>
+  </chapter>
+
+  <chapter>
+    <title>Environment-specific notes</title>
+
+    <para>The Main API described in <xref linkend="sdkref_classes" /> and
+    <xref linkend="sdkref_enums" /> is mostly identical in all the supported
+    programming environments which have been briefly mentioned in the
+    introduction of this book. As a result, the Main API's general concepts
+    described in <xref linkend="concepts" /> are the same whether you use the
+    object-oriented web service (OOWS) for JAX-WS or a raw web service
+    connection via, say, Perl, or whether you use C++ COM bindings.</para>
+
+    <para>Some things are different depending on your environment, however.
+    These differences are explained in this chapter.</para>
+
+    <sect1 id="glue">
+      <title>Using the object-oriented web service (OOWS)</title>
+
+      <para>As explained in <xref linkend="webservice-or-com" />, VirtualBox
+      ships with client-side libraries for Java, Python and PHP that allow you
+      to use the VirtualBox web service in an intuitive, object-oriented way.
+      These libraries shield you from the client-side complications of managed
+      object references and other implementation details that come with the
+      VirtualBox web service. (If you are interested in these complications,
+      have a look at <xref linkend="raw-webservice" />).</para>
+
+      <para>We recommend that you start your experiments with the VirtualBox
+      web service by using our object-oriented client libraries for JAX-WS, a
+      web service toolkit for Java, which enables you to write code to
+      interact with VirtualBox in the simplest manner possible.</para>
+
+      <para>As "interfaces", "attributes" and "methods" are COM concepts,
+      please read the documentation in <xref linkend="sdkref_classes" /> and
+      <xref linkend="sdkref_enums" /> with the following notes in mind.</para>
+
+      <para>The OOWS bindings attempt to map the Main API as closely as
+      possible to the Java, Python and PHP languages. In other words, objects
+      are objects, interfaces become classes, and you can call methods on
+      objects as you would on local objects.</para>
+
+      <para>The main difference remains with attributes: to read an attribute,
+      call a "getXXX" method, with "XXX" being the attribute name with a
+      capitalized first letter. So when the Main API Reference says that
+      <computeroutput>IMachine</computeroutput> has a "name" attribute (see
+      <xref linkend="IMachine__name" xreflabel="IMachine::name" />), call
+      <computeroutput>getName()</computeroutput> on an IMachine object to
+      obtain a machine's name. Unless the attribute is marked as read-only in
+      the documentation, there will also be a corresponding "set"
+      method.</para>
+
+      <sect2 id="glue-jax-ws">
+        <title>The object-oriented web service for JAX-WS</title>
+
+        <para>JAX-WS is a powerful toolkit by Sun Microsystems to build both
+        server and client code with Java. It is part of Java 6 (JDK 1.6), but
+        can also be obtained separately for Java 5 (JDK 1.5). The VirtualBox
+        SDK comes with precompiled OOWS bindings working with both Java 5 and
+        6.</para>
+
+        <para>The following sections explain how to get the JAX-WS sample code
+        running and explain a few common practices when using the JAX-WS
+        object-oriented web service.</para>
+
+        <sect3>
+          <title>Preparations</title>
+
+          <para>Since JAX-WS is already integrated into Java 6, no additional
+          preparations are needed for Java 6.</para>
+
+          <para>If you are using Java 5 (JDK 1.5.x), you will first need to
+          download and install an external JAX-WS implementation, as Java 5
+          does not support JAX-WS out of the box; for example, you can
+          download one from here: <ulink
+          url="https://jax-ws.dev.java.net/2.1.4/JAXWS2.1.4-20080502.jar">https://jax-ws.dev.java.net/2.1.4/JAXWS2.1.4-20080502.jar</ulink>.
+          Then perform the installation (<computeroutput>java -jar
+          JAXWS2.1.4-20080502.jar</computeroutput>).</para>
+        </sect3>
+
+        <sect3>
+          <title>Getting started: running the sample code</title>
+
+          <para>To run the OOWS for JAX-WS samples that we ship with the SDK,
+          perform the following steps: <orderedlist>
+              <listitem>
+                <para>Open a terminal and change to the directory where the
+                JAX-WS samples reside.<footnote>
+                    <para>In
+                    <computeroutput>sdk/bindings/webservice/java/jax-ws/samples/</computeroutput>.</para>
+                  </footnote> Examine the header of
+                <computeroutput>Makefile</computeroutput> to see if the
+                supplied variables (Java compiler, Java executable) and a few
+                other details match your system settings.</para>
+              </listitem>
+
+              <listitem>
+                <para>To start the VirtualBox web service, open a second
+                terminal and change to the directory where the VirtualBox
+                executables are located. Then type:<screen>./vboxwebsrv -v</screen></para>
+
+                <para>The web service now waits for connections and will run
+                until you press Ctrl+C in this second terminal. The -v
+                argument causes it to log all connections to the terminal.
+                (See <xref linkend="runvboxwebsrv" os="" /> for details on how
+                to run the web service.)</para>
+              </listitem>
+
+              <listitem>
+                <para>Back in the first terminal and still in the samples
+                directory, to start a simple client example just type:<screen>make run16</screen></para>
+
+                <para>if you're on a Java 6 system; on a Java 5 system, run
+                <computeroutput>make run15</computeroutput> instead.</para>
+
+                <para>This should work on all Unix-like systems such as Linux
+                and Solaris. For Windows systems, use commands similar to what
+                is used in the Makefile.</para>
+
+                <para>This will compile the
+                <computeroutput>clienttest.java</computeroutput> code on the
+                first call and then execute the resulting
+                <computeroutput>clienttest</computeroutput> class to show the
+                locally installed VMs (see below).</para>
+              </listitem>
+            </orderedlist></para>
+
+          <para>The <computeroutput>clienttest</computeroutput> sample
+          imitates a few typical command line tasks that
+          <computeroutput>VBoxManage</computeroutput>, VirtualBox's regular
+          command-line front-end, would provide (see the VirtualBox User
+          Manual for details). In particular, you can run:<itemizedlist>
+              <listitem>
+                <para><computeroutput>java clienttest show
+                vms</computeroutput>: show the virtual machines that are
+                registered locally.</para>
+              </listitem>
+
+              <listitem>
+                <para><computeroutput>java clienttest list
+                hostinfo</computeroutput>: show various information about the
+                host this VirtualBox installation runs on.</para>
+              </listitem>
+
+              <listitem>
+                <para><computeroutput>java clienttest startvm
+                &lt;vmname|uuid&gt;</computeroutput>: start the given virtual
+                machine.</para>
+              </listitem>
+            </itemizedlist></para>
+
+          <para>The <computeroutput>clienttest.java</computeroutput> sample
+          code illustrates common basic practices how to use the VirtualBox
+          OOWS for JAX-WS, which we will explain in more detail in the
+          following chapters.</para>
+        </sect3>
+
+        <sect3>
+          <title>Logging on to the web service</title>
+
+          <para>Before a web service client can do anything useful, two
+          objects need to be created, as can be seen in the
+          <computeroutput>clienttest</computeroutput> constructor:<orderedlist>
+              <listitem>
+                <para>An instance of <xref linkend="IWebsessionManager"
+                xreflabel="IWebsessionManager" />, which is an interface
+                provided by the web service to manage "web sessions" -- that
+                is, stateful connections to the web service with persistent
+                objects upon which methods can be invoked.</para>
+
+                <para>In the OOWS for JAX-WS, the IWebsessionManager class
+                must be constructed explicitly, and a URL must be provided in
+                the constructor that specifies where the web service (the
+                server) awaits connections. The code in
+                <computeroutput>clienttest.java</computeroutput> connects to
+                "http://localhost:18083/", which is the default.</para>
+
+                <para>The port number, by default 18083, must match the port
+                number given to the
+                <computeroutput>vboxwebsrv</computeroutput> command line; see
+                <xref linkend="vboxwebsrv-ref" />.</para>
+              </listitem>
+
+              <listitem>
+                <para>After that, the code calls <xref
+                linkend="IWebsessionManager__logon"
+                xreflabel="IWebsessionManager::logon()" />, which is the first
+                call that actually communicates with the server. This
+                authenticates the client with the web service and returns an
+                instance of <xref linkend="IVirtualBox"
+                xreflabel="IVirtualBox" />, the most fundamental interface of
+                the VirtualBox web service, from which all other functionality
+                can be derived.</para>
+
+                <para>If logon doesn't work, please take another look at <xref
+                linkend="websrv_authenticate" />.</para>
+              </listitem>
+            </orderedlist></para>
+        </sect3>
+
+        <sect3>
+          <title>Object management</title>
+
+          <para>The current OOWS for JAX-WS has certain memory management
+          related limitations. When you no longer need an object, call its
+          <xref linkend="IManagedObjectRef__release"
+          xreflabel="IManagedObjectRef::release()" /> method explicitly, which
+          frees appropriate managed reference, as is required by the raw
+          webservice; see <xref linkend="managed-object-references" /> for
+          details. This limitation may be reconsidered in a future version of
+          the VirtualBox SDK.</para>
+        </sect3>
+      </sect2>
+
+      <sect2 id="glue-python-ws">
+        <title>The object-oriented web service for Python</title>
+
+        <para>VirtualBox comes with two flavors of a Python API: one for web
+        service, discussed here, and one for the COM/XPCOM API discussed in
+        <xref linkend="pycom" />. The client code is mostly similar, except
+        for the initialization part, so it is up to the application developer
+        to choose the appropriate technology. Moreover, a common Python glue
+        layer exists, abstracting out concrete platform access details, see
+        <xref linkend="glue-python" />.</para>
+
+        <para>As indicated in <xref linkend="webservice-or-com" />, the
+        COM/XPCOM API gives better performance without the SOAP overhead, and
+        does not require a web server to be running. On the other hand, the
+        COM/XPCOM Python API requires a suitable Python bridge for your Python
+        installation (VirtualBox ships the most important ones for each
+        platform<footnote>
+            <para>On On Mac OS X only the Python versions bundled with the OS
+            are officially supported. This means Python 2.3 for 10.4, Python
+            2.5 for 10.5 and Python 2.5 and 2.6 for 10.6.</para>
+          </footnote>), and you cannot connect to VirtualBox remotely. On
+        Windows, you can use the Main API from Python if the Win32 extensions
+        package for Python<footnote>
+            <para>See <ulink
+            url="http://sourceforge.net/project/showfiles.php?group_id=78018">http://sourceforge.net/project/showfiles.php?group_id=78018</ulink>.</para>
+          </footnote> is installed.</para>
+
+        <para>The VirtualBox OOWS for Python relies on the Python ZSI SOAP
+        implementation (see <ulink
+        url="http://pywebsvcs.sourceforge.net/zsi.html">http://pywebsvcs.sourceforge.net/zsi.html</ulink>),
+        which you will need to install locally before trying the examples.
+        Most Linux distributions come with package for ZSI, such as
+        <computeroutput>python-zsi</computeroutput> in Ubuntu.</para>
+
+        <para>To get started, open a terminal and change to the
+        <computeroutput>bindings/glue/python/sample</computeroutput>
+        directory, which contains an example of a simple interactive shell
+        able to control a VirtualBox instance. The shell is written using the
+        API layer, thereby hiding different implementation details, so it is
+        actually an example of code share among XPCOM, MSCOM and web services.
+        If you are interested in how to interact with the webservices layer
+        directly, have a look at
+        <computeroutput>install/vboxapi/__init__.py</computeroutput> which
+        contains the glue layer for all target platforms (i.e. XPCOM, MSCOM
+        and web services).</para>
+
+        <para>To start the shell, perform the following commands: <screen>/opt/VirtualBox/vboxwebsrv -t 0
+            # start webservice with object autocollection disabled
+export VBOX_PROGRAM_PATH=/opt/VirtualBox
+            # your VirtualBox installation directory
+export VBOX_SDK_PATH=/home/youruser/vbox-sdk
+            # where you've extracted the SDK
+./vboxshell.py -w        </screen>See <xref linkend="vboxshell" /> for more
+        details on the shell's functionality. For you, as a VirtualBox
+        application developer, the vboxshell sample could be interesting as an
+        example of how to write code targeting both local and remote cases
+        (COM/XPCOM and SOAP). The common part of the shell is the same -- the
+        only difference is how it interacts with the invocation layer. You can
+        use the <computeroutput>connect</computeroutput> shell command to
+        connect to remote VirtualBox servers; in this case you can skip
+        starting the local webserver.</para>
+      </sect2>
+
+      <sect2>
+        <title>The object-oriented web service for PHP</title>
+
+        <para>VirtualBox also comes with object-oriented web service (OOWS)
+        wrappers for PHP5. These wrappers rely on the PHP SOAP
+        Extension<footnote>
+            <para>See <ulink url="???">http://www.php.net/soap</ulink>.</para>
+          </footnote>, which can be installed by configuring PHP with
+        <computeroutput>--enable-soap</computeroutput>.</para>
+      </sect2>
+    </sect1>
+
+    <sect1 id="raw-webservice">
+      <title>Using the raw web service with any language</title>
+
+      <para>The following examples show you how to use the raw web service,
+      without the object-oriented client-side code that was described in the
+      previous chapter.</para>
+
+      <para>Generally, when reading the documentation in <xref
+      linkend="sdkref_classes" /> and <xref linkend="sdkref_enums" />, due to
+      the limitations of SOAP and WSDL lined out in <xref
+      linkend="rawws-conventions" />, please have the following notes in
+      mind:</para>
+
+      <para><orderedlist>
+          <listitem>
+            <para>Any COM method call becomes a <emphasis role="bold">plain
+            function call</emphasis> in the raw web service, with the object
+            as an additional first parameter (before the "real" parameters
+            listed in the documentation). So when the documentation says that
+            the <computeroutput>IVirtualBox</computeroutput> interface
+            supports the <computeroutput>createMachine()</computeroutput>
+            method (see <xref linkend="IVirtualBox__createMachine"
+            xreflabel="IVirtualBox::createMachine()" />), the web service
+            operation is
+            <computeroutput>IVirtualBox_createMachine(...)</computeroutput>,
+            and a managed object reference to an
+            <computeroutput>IVirtualBox</computeroutput> object must be passed
+            as the first argument.</para>
+          </listitem>
+
+          <listitem>
+            <para>For <emphasis role="bold">attributes</emphasis> in
+            interfaces, there will be at least one "get" function; there will
+            also be a "set" function, unless the attribute is "readonly". The
+            attribute name will be appended to the "get" or "set" prefix, with
+            a capitalized first letter. So, the "version" readonly attribute
+            of the <computeroutput>IVirtualBox</computeroutput> interface can
+            be retrieved by calling
+            <computeroutput>IVirtualBox_getVersion(vbox)</computeroutput>,
+            with <computeroutput>vbox</computeroutput> being the VirtualBox
+            object.</para>
+          </listitem>
+
+          <listitem>
+            <para>Whenever the API documentation says that a method (or an
+            attribute getter) returns an <emphasis
+            role="bold">object</emphasis>, it will returned a managed object
+            reference in the web service instead. As said above, managed
+            object references should be released if the web service client
+            does not log off again immediately!</para>
+          </listitem>
+        </orderedlist></para>
+
+      <para></para>
+
+      <sect2 id="webservice-java-sample">
+        <title>Raw web service example for Java with Axis</title>
+
+        <para>Axis is an older web service toolkit created by the Apache
+        foundation. If your distribution does not have it installed, you can
+        get a binary from <ulink
+        url="http://www.apache.org">http://www.apache.org</ulink>. The
+        following examples assume that you have Axis 1.4 installed.</para>
+
+        <para>The VirtualBox SDK ships with an example for Axis that, again,
+        is called <computeroutput>clienttest.java</computeroutput> and that
+        imitates a few of the commands of
+        <computeroutput>VBoxManage</computeroutput> over the wire.</para>
+
+        <para>Then perform the following steps:<orderedlist>
+            <listitem>
+              <para>Create a working directory somewhere. Under your
+              VirtualBox installation directory, find the
+              <computeroutput>sdk/webservice/samples/java/axis/</computeroutput>
+              directory and copy the file
+              <computeroutput>clienttest.java</computeroutput> to your working
+              directory.</para>
+            </listitem>
+
+            <listitem>
+              <para>Open a terminal in your working directory. Execute the
+              following command:<screen> java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl</screen></para>
+
+              <para>The <computeroutput>vboxwebService.wsdl</computeroutput>
+              file should be located in the
+              <computeroutput>sdk/webservice/</computeroutput>
+              directory.</para>
+
+              <para>If this fails, your Apache Axis may not be located on your
+              system classpath, and you may have to adjust the CLASSPATH
+              environment variable. Something like this:<screen>export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH</screen></para>
+
+              <para>Use the directory where the Axis JAR files are located.
+              Mind the quotes so that your shell passes the "*" character to
+              the java executable without expanding. Alternatively, add a
+              corresponding <computeroutput>-classpath</computeroutput>
+              argument to the "java" call above.</para>
+
+              <para>If the command executes successfully, you should see an
+              "org" directory with subdirectories containing Java source files
+              in your working directory. These classes represent the
+              interfaces that the VirtualBox web service offers, as described
+              by the WSDL file.</para>
+
+              <para>This is the bit that makes using web services so
+              attractive to client developers: if a language's toolkit
+              understands WSDL, it can generate large amounts of support code
+              automatically. Clients can then easily use this support code and
+              can be done with just a few lines of code.</para>
+            </listitem>
+
+            <listitem>
+              <para>Next, compile the
+              <computeroutput>clienttest.java</computeroutput> source:<screen>javac clienttest.java </screen></para>
+
+              <para>This should yield a "clienttest.class" file.</para>
+            </listitem>
+
+            <listitem>
+              <para>To start the VirtualBox web service, open a second
+              terminal and change to the directory where the VirtualBox
+              executables are located. Then type:<screen>./vboxwebsrv -v</screen></para>
+
+              <para>The web service now waits for connections and will run
+              until you press Ctrl+C in this second terminal. The -v argument
+              causes it to log all connections to the terminal. (See <xref
+              linkend="runvboxwebsrv" os="" /> for details on how to run the
+              web service.)</para>
+            </listitem>
+
+            <listitem>
+              <para>Back in the original terminal where you compiled the Java
+              source, run the resulting binary, which will then connect to the
+              web service:<screen>java clienttest</screen></para>
+
+              <para>The client sample will connect to the web service (on
+              localhost, but the code could be changed to connect remotely if
+              the web service was running on a different machine) and make a
+              number of method calls. It will output the version number of
+              your VirtualBox installation and a list of all virtual machines
+              that are currently registered (with a bit of seemingly random
+              data, which will be explained later).</para>
+            </listitem>
+          </orderedlist></para>
+      </sect2>
+
+      <sect2 id="raw-webservice-perl">
+        <title>Raw web service example for Perl</title>
+
+        <para>We also ship a small sample for Perl. It uses the SOAP::Lite
+        perl module to communicate with the VirtualBox web service.</para>
+
+        <para>The
+        <computeroutput>sdk/bindings/webservice/perl/lib/</computeroutput>
+        directory contains a pre-generated Perl module that allows for
+        communicating with the web service from Perl. You can generate such a
+        module yourself using the "stubmaker" tool that comes with SOAP::Lite,
+        but since that tool is slow as well as sometimes unreliable, we are
+        shipping a working module with the SDK for your convenience.</para>
+
+        <para>Perform the following steps:<orderedlist>
+            <listitem>
+              <para>If SOAP::Lite is not yet installed on your system, you
+              will need to install the package first. On Debian-based systems,
+              the package is called
+              <computeroutput>libsoap-lite-perl</computeroutput>; on Gentoo,
+              it's <computeroutput>dev-perl/SOAP-Lite</computeroutput>.</para>
+            </listitem>
+
+            <listitem>
+              <para>Open a terminal in the
+              <computeroutput>sdk/bindings/webservice/perl/samples/</computeroutput>
+              directory.</para>
+            </listitem>
+
+            <listitem>
+              <para>To start the VirtualBox web service, open a second
+              terminal and change to the directory where the VirtualBox
+              executables are located. Then type:<screen>./vboxwebsrv -v</screen></para>
+
+              <para>The web service now waits for connections and will run
+              until you press Ctrl+C in this second terminal. The -v argument
+              causes it to log all connections to the terminal. (See <xref
+              linkend="runvboxwebsrv" os="" /> for details on how to run the
+              web service.)</para>
+            </listitem>
+
+            <listitem>
+              <para>In the first terminal with the Perl sample, run the
+              clienttest.pl script:<screen>perl -I ../lib clienttest.pl</screen></para>
+            </listitem>
+          </orderedlist></para>
+      </sect2>
+
+      <sect2>
+        <title>Programming considerations for the raw web service</title>
+
+        <para>If you use the raw web service, you need to keep a number of
+        things in mind, or you will sooner or later run into issues that are
+        not immediately obvious. By contrast, the object-oriented client-side
+        libraries described in <xref linkend="glue" /> take care of these
+        things automatically and thus greatly simplify using the web
+        service.</para>
+
+        <sect3 id="rawws-conventions">
+          <title>Fundamental conventions</title>
+
+          <para>If you are familiar with other web services, you may find the
+          VirtualBox web service to behave a bit differently to accommodate
+          for the fact that VirtualBox web service more or less maps the
+          VirtualBox Main COM API. The following main differences had to be
+          taken care of:<itemizedlist>
+              <listitem>
+                <para>Web services, as expressed by WSDL, are not
+                object-oriented. Even worse, they are normally stateless (or,
+                in web services terminology, "loosely coupled"). Web service
+                operations are entirely procedural, and one cannot normally
+                make assumptions about the state of a web service between
+                function calls.</para>
+
+                <para>In particular, this normally means that you cannot work
+                on objects in one method call that were created by another
+                call.</para>
+              </listitem>
+
+              <listitem>
+                <para>By contrast, the VirtualBox Main API, being expressed in
+                COM, is object-oriented and works entirely on objects, which
+                are grouped into public interfaces, which in turn have
+                attributes and methods associated with them.</para>
+              </listitem>
+            </itemizedlist> For the VirtualBox web service, this results in
+          three fundamental conventions:<orderedlist>
+              <listitem>
+                <para>All <emphasis role="bold">function names</emphasis> in
+                the VirtualBox web service consist of an interface name and a
+                method name, joined together by an underscore. This is because
+                there are only functions ("operations") in WSDL, but no
+                classes, interfaces, or methods.</para>
+
+                <para>In addition, all calls to the VirtualBox web service
+                (except for logon, see below) take a <emphasis
+                role="bold">managed object reference</emphasis> as the first
+                argument, representing the object upon which the underlying
+                method is invoked. (Managed object references are explained in
+                detail below; see <xref
+                linkend="managed-object-references" />.)</para>
+
+                <para>So, when one would normally code, in the pseudo-code of
+                an object-oriented language, to invoke a method upon an
+                object:<screen>IMachine machine;
+result = machine.getName();</screen></para>
+
+                <para>In the VirtualBox web service, this looks something like
+                this (again, pseudo-code):<screen>IMachineRef machine;
+result = IMachine_getName(machine);</screen></para>
+              </listitem>
+
+              <listitem>
+                <para>To make the web service stateful, and objects persistent
+                between method calls, the VirtualBox web service introduces a
+                <emphasis role="bold">session manager</emphasis> (by way of
+                the <xref linkend="IWebsessionManager"
+                xreflabel="IWebsessionManager" /> interface), which manages
+                object references. Any client wishing to interact with the web
+                service must first log on to the session manager and in turn
+                receives a managed object reference to an object that supports
+                the <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />
+                interface (the basic interface in the Main API).</para>
+              </listitem>
+            </orderedlist></para>
+
+          <para>In other words, as opposed to other web services, <emphasis
+          role="bold">the VirtualBox web service is both object-oriented and
+          stateful.</emphasis></para>
+        </sect3>
+
+        <sect3>
+          <title>Example: A typical web service client session</title>
+
+          <para>A typical short web service session to retrieve the version
+          number of the VirtualBox web service (to be precise, the underlying
+          Main API version number) looks like this:<orderedlist>
+              <listitem>
+                <para>A client logs on to the web service by calling <xref
+                linkend="IWebsessionManager__logon"
+                xreflabel="IWebsessionManager::logon()" /> with a valid user
+                name and password. See <xref linkend="websrv_authenticate" />
+                for details about how authentication works.</para>
+              </listitem>
+
+              <listitem>
+                <para>On the server side,
+                <computeroutput>vboxwebsrv</computeroutput> creates a session,
+                which persists until the client calls <xref
+                linkend="IWebsessionManager__logoff"
+                xreflabel="IWebsessionManager::logoff()" /> or the session
+                times out after a configurable period of inactivity (see <xref
+                linkend="vboxwebsrv-ref" />).</para>
+
+                <para>For the new session, the web service creates an instance
+                of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />.
+                This interface is the most central one in the Main API and
+                allows access to all other interfaces, either through
+                attributes or method calls. For example, IVirtualBox contains
+                a list of all virtual machines that are currently registered
+                (as they would be listed on the left side of the VirtualBox
+                main program).</para>
+
+                <para>The web service then creates a managed object reference
+                for this instance of IVirtualBox and returns it to the calling
+                client, which receives it as the return value of the logon
+                call. Something like this:</para>
+
+                <screen>string oVirtualBox;
+oVirtualBox = webservice.IWebsessionManager_logon("user", "pass");</screen>
+
+                <para>(The managed object reference "oVirtualBox" is just a
+                string consisting of digits and dashes. However, it is a
+                string with a meaning and will be checked by the web service.
+                For details, see below. As hinted above, <xref
+                linkend="IWebsessionManager__logon"
+                xreflabel="IWebsessionManager::logon()" /> is the
+                <emphasis>only</emphasis> operation provided by the web
+                service which does not take a managed object reference as the
+                first argument!)</para>
+              </listitem>
+
+              <listitem>
+                <para>The VirtualBox Main API documentation says that the
+                <computeroutput>IVirtualBox</computeroutput> interface has a
+                <xref linkend="IVirtualBox__version" xreflabel="version" />
+                attribute, which is a string. For each attribute, there is a
+                "get" and a "set" method in COM, which maps to according
+                operations in the web service. So, to retrieve the "version"
+                attribute of this <computeroutput>IVirtualBox</computeroutput>
+                object, the web service client does this:<screen>string version;
+version = webservice.IVirtualBox_getVersion(oVirtualBox);
+
+print version;</screen></para>
+
+                <para>And it will print
+                "$VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD".</para>
+              </listitem>
+
+              <listitem>
+                <para>The web service client calls <xref
+                linkend="IWebsessionManager__logoff"
+                xreflabel="IWebsessionManager::logoff()" /> with the
+                VirtualBox managed object reference. This will clean up all
+                allocated resources.</para>
+              </listitem>
+            </orderedlist></para>
+        </sect3>
+
+        <sect3 id="managed-object-references">
+          <title>Managed object references</title>
+
+          <para>To a web service client, a managed object reference looks like
+          a string: two 64-bit hex numbers separated by a dash. This string,
+          however, represents a COM object that "lives" in the web service
+          process. The two 64-bit numbers encoded in the managed object
+          reference represent a session ID (which is the same for all objects
+          in the same web service session, i.e. for all objects after one
+          logon) and a unique object ID within that session.</para>
+
+          <para>Managed object references are created in two
+          situations:<orderedlist>
+              <listitem>
+                <para>When a client logs on, by calling <xref
+                linkend="IWebsessionManager__logon"
+                xreflabel="IWebsessionManager::logon()" />.</para>
+
+                <para>Upon logon, the websession manager creates one instance
+                of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" /> and
+                another object of <xref linkend="ISession"
+                xreflabel="ISession" /> representing the web service session.
+                This can be retrieved using <xref
+                linkend="IWebsessionManager__getSessionObject"
+                xreflabel="IWebsessionManager::getSessionObject()" />.</para>
+
+                <para>(Technically, there is always only one <xref
+                linkend="IVirtualBox" xreflabel="IVirtualBox" /> object, which
+                is shared between all sessions and clients, as it is a COM
+                singleton. However, each session receives its own managed
+                object reference to it. The <xref linkend="ISession"
+                xreflabel="ISession" /> object, however, is created and
+                destroyed for each session.)</para>
+              </listitem>
+
+              <listitem>
+                <para>Whenever a web service clients invokes an operation
+                whose COM implementation creates COM objects.</para>
+
+                <para>For example, <xref linkend="IVirtualBox__createMachine"
+                xreflabel="IVirtualBox::createMachine()" /> creates a new
+                instance of <xref linkend="IMachine" xreflabel="IMachine" />;
+                the COM object returned by the COM method call is then wrapped
+                into a managed object reference by the web server, and this
+                reference is returned to the web service client.</para>
+              </listitem>
+            </orderedlist></para>
+
+          <para>Internally, in the web service process, each managed object
+          reference is simply a small data structure, containing a COM pointer
+          to the "real" COM object, the web session ID and the object ID. This
+          structure is allocated on creation and stored efficiently in hashes,
+          so that the web service can look up the COM object quickly whenever
+          a web service client wishes to make a method call. The random
+          session ID also ensures that one web service client cannot intercept
+          the objects of another.</para>
+
+          <para>Managed object references are not destroyed automatically and
+          must be released by explicitly calling <xref
+          linkend="IManagedObjectRef__release"
+          xreflabel="IManagedObjectRef::release()" />. This is important, as
+          otherwise hundreds or thousands of managed object references (and
+          corresponding COM objects, which can consume much more memory!) can
+          pile up in the web service process and eventually cause it to deny
+          service.</para>
+
+          <para>To reiterate: The underlying COM object, which the reference
+          points to, is only freed if the managed object reference is
+          released. It is therefore vital that web service clients properly
+          clean up after the managed object references that are returned to
+          them.</para>
+
+          <para>When a web service client calls <xref
+          linkend="IWebsessionManager__logoff"
+          xreflabel="IWebsessionManager::logoff()" />, all managed object
+          references created during the session are automatically freed. For
+          short-lived sessions that do not create a lot of objects, logging
+          off may therefore be sufficient, although it is certainly not "best
+          practice".</para>
+        </sect3>
+
+        <sect3>
+          <title>Some more detail about web service operation</title>
+
+          <sect4 id="soap">
+            <title>SOAP messages</title>
+
+            <para>Whenever a client makes a call to a web service, this
+            involves a complicated procedure internally. These calls are
+            remote procedure calls. Each such procedure call typically
+            consists of two "message" being passed, where each message is a
+            plain-text HTTP request with a standard HTTP header and a special
+            XML document following. This XML document encodes the name of the
+            procedure to call and the argument names and values passed to
+            it.</para>
+
+            <para>To give you an idea of what such a message looks like,
+            assuming that a web service provides a procedure called
+            "SayHello", which takes a string "name" as an argument and returns
+            "Hello" with a space and that name appended, the request message
+            could look like this:</para>
+
+            <para><screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;SOAP-ENV:Envelope
+ xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:test="http://test/"&gt;
+&lt;SOAP-ENV:Body&gt;
+   &lt;test:SayHello&gt;
+    &lt;name&gt;Peter&lt;/name&gt;
+   &lt;/test:SayHello&gt;
+ &lt;/SOAP-ENV:Body&gt;
+&lt;/SOAP-ENV:Envelope&gt;</screen>A similar message -- the "response" message
+            -- would be sent back from the web service to the client,
+            containing the return value "Hello Peter".</para>
+
+            <para>Most programming languages provide automatic support to
+            generate such messages whenever code in that programming language
+            makes such a request. In other words, these programming languages
+            allow for writing something like this (in pseudo-C++ code):</para>
+
+            <para><screen>webServiceClass service("localhost", 18083); // server and port
+string result = service.SayHello("Peter");  // invoke remote procedure</screen>and
+            would, for these two pseudo-lines, automatically perform these
+            steps:</para>
+
+            <para><orderedlist>
+                <listitem>
+                  <para>prepare a connection to a web service running on port
+                  18083 of "localhost";</para>
+                </listitem>
+
+                <listitem>
+                  <para>for the <computeroutput>SayHello()</computeroutput>
+                  function of the web service, generate a SOAP message like in
+                  the above example by encoding all arguments of the remote
+                  procedure call (which could involve all kinds of type
+                  conversions and complex marshalling for arrays and
+                  structures);</para>
+                </listitem>
+
+                <listitem>
+                  <para>connect to the web service via HTTP and send that
+                  message;</para>
+                </listitem>
+
+                <listitem>
+                  <para>wait for the web service to send a response
+                  message;</para>
+                </listitem>
+
+                <listitem>
+                  <para>decode that response message and put the return value
+                  of the remote procedure into the "result" variable.</para>
+                </listitem>
+              </orderedlist></para>
+          </sect4>
+
+          <sect4 id="wsdl">
+            <title>Service descriptions in WSDL</title>
+
+            <para>In the above explanations about SOAP, it was left open how
+            the programming language learns about how to translate function
+            calls in its own syntax into proper SOAP messages. In other words,
+            the programming language needs to know what operations the web
+            service supports and what types of arguments are required for the
+            operation's data in order to be able to properly serialize and
+            deserialize the data to and from the web service. For example, if
+            a web service operation expects a number in "double" floating
+            point format for a particular parameter, the programming language
+            cannot send to it a string instead.</para>
+
+            <para>For this, the Web Service Definition Language (WSDL) was
+            invented, another XML substandard that describes exactly what
+            operations the web service supports and, for each operation, which
+            parameters and types are needed with each request and response
+            message. WSDL descriptions can be incredibly verbose, and one of
+            the few good things that can be said about this standard is that
+            it is indeed supported by most programming languages.</para>
+
+            <para>So, if it is said that a programming language "supports" web
+            services, this typically means that a programming language has
+            support for parsing WSDL files and somehow integrating the remote
+            procedure calls into the native language syntax -- for example,
+            like in the Java sample shown in <xref
+            linkend="webservice-java-sample" />.</para>
+
+            <para>For details about how programming languages support web
+            services, please refer to the documentation that comes with the
+            individual languages. Here are a few pointers:</para>
+
+            <orderedlist>
+              <listitem>
+                <para>For <emphasis role="bold">C++,</emphasis> among many
+                others, the gSOAP toolkit is a good option. Parts of gSOAP are
+                also used in VirtualBox to implement the VirtualBox web
+                service.</para>
+              </listitem>
+
+              <listitem>
+                <para>For <emphasis role="bold">Java,</emphasis> there are
+                several implementations already described in this document
+                (see <xref linkend="glue-jax-ws" /> and <xref
+                linkend="webservice-java-sample" />).</para>
+              </listitem>
+
+              <listitem>
+                <para><emphasis role="bold">Perl</emphasis> supports WSDL via
+                the SOAP::Lite package. This in turn comes with a tool called
+                <computeroutput>stubmaker.pl</computeroutput> that allows you
+                to turn any WSDL file into a Perl package that you can import.
+                (You can also import any WSDL file "live" by having it parsed
+                every time the script runs, but that can take a while.) You
+                can then code (again, assuming the above example):<screen>my $result = servicename-&gt;sayHello("Peter");</screen></para>
+
+                <para>A sample that uses SOAP::Lite was described in <xref
+                linkend="raw-webservice-perl" />.</para>
+              </listitem>
+            </orderedlist>
+          </sect4>
+        </sect3>
+      </sect2>
+    </sect1>
+
+    <sect1 id="api_com">
+      <title>Using COM/XPCOM directly</title>
+
+      <para>If you do not require <emphasis>remote</emphasis> procedure calls
+      such as those offered by the VirtualBox web service, and if you know
+      Python or C++ as well as COM, you might find it preferable to program
+      VirtualBox's Main API directly via COM.</para>
+
+      <para>COM stands for "Component Object Model" and is a standard
+      originally introduced by Microsoft in the 1990s for Microsoft Windows.
+      It allows for organizing software in an object-oriented way and across
+      processes; code in one process may access objects that live in another
+      process.</para>
+
+      <para>COM has several advantages: it is language-neutral, meaning that
+      even though all of VirtualBox is internally written in C++, programs
+      written in other languages could communicate with it. COM also cleanly
+      separates interface from implementation, so that external programs need
+      not know anything about the messy and complicated details of VirtualBox
+      internals.</para>
+
+      <para>On a Windows host, all parts of VirtualBox will use the COM
+      functionality that is native to Windows. On other hosts (including
+      Linux), VirtualBox comes with a built-in implementation of XPCOM, as
+      originally created by the Mozilla project, which we have enhanced to
+      support interprocess communication on a level comparable to Microsoft
+      COM. Internally, VirtualBox has an abstraction layer that allows the
+      same VirtualBox code to work both with native COM as well as our XPCOM
+      implementation.</para>
+
+      <sect2 id="pycom">
+        <title>Python COM API</title>
+
+        <para>On Windows, Python scripts can use COM and VirtualBox interfaces
+        to control almost all aspects of virtual machine execution. As an
+        example, use the following commands to instantiate the VirtualBox
+        object and start a VM: <screen>
+       vbox = win32com.client.Dispatch("VirtualBox.VirtualBox")
+       session = win32com.client.Dispatch("VirtualBox.Session")
+       mach = vbox.findMachine("uuid or name  of machine to start")
+       progress = mach.launchVMProcess(session, "gui", "")
+       progress.waitForCompletion(-1)
+      </screen> Also, see
+        <computeroutput>/bindings/glue/python/samples/vboxshell.py</computeroutput>
+        for more advanced usage scenarious. However, unless you have specific
+        requirements, we strongly recommend to use the generic glue layer
+        described in the next section to access MS COM objects.</para>
+      </sect2>
+
+      <sect2 id="glue-python">
+        <title>Common Python bindings layer</title>
+
+        <para>As different wrappers ultimately provide access to the same
+        underlying API, and to simplify porting and development of Python
+        application using the VirtualBox Main API, we developed a common glue
+        layer that abstracts out most platform-specific details from the
+        application and allows the developer to focus on application logic.
+        The VirtualBox installer automatically sets up this glue layer for the
+        system default Python install. See below for details on how to set up
+        the glue layer if you want to use a different Python
+        installation.</para>
+
+        <para>In this layer, the class
+        <computeroutput>VirtualBoxManager</computeroutput> hides most
+        platform-specific details. It can be used to access both the local
+        (COM) and the webservice-based API. The following code can be used by
+        an application to use the glue layer.</para>
+
+        <screen># This code assumes vboxapi.py from VirtualBox distribution
+# being in PYTHONPATH, or installed system-wide
+from vboxapi import VirtualBoxManager
+
+# This code initializes VirtualBox manager with default style
+# and parameters
+virtualBoxManager = VirtualBoxManager(None, None)
+
+# Alternatively, one can be more verbose, and initialize
+# glue with webservice backend, and provide authentication
+# information
+virtualBoxManager = VirtualBoxManager("WEBSERVICE",
+                                      {'url':'http://myhost.com::18083/',
+                                      'user':'me',
+                                      'password':'secret'})        </screen>
+
+        <para>We supply the <computeroutput>VirtualBoxManager</computeroutput>
+        constructor with 2 arguments: style and parameters. Style defines
+        which bindings style to use (could be "MSCOM", "XPCOM" or
+        "WEBSERVICE"), and if set to <computeroutput>None</computeroutput>
+        defaults to usable platform bindings (MS COM on Windows, XPCOM on
+        other platforms). The second argument defines parameters, passed to
+        the platform-specific module, as we do in the second example, where we
+        pass username and password to be used to authenticate against the web
+        service.</para>
+
+        <para>After obtaining the
+        <computeroutput>VirtualBoxManager</computeroutput> instance, one can
+        perform operations on the IVirtualBox class. For example, the
+        following code will a start virtual machine by name or ID:</para>
+
+        <screen>vbox = virtualBoxManager.vbox
+mgr = virtualBoxManager.mgr
+print "Version is",vbox.version
+
+def machById(id):
+    mach = None
+    for m in virtualBoxManager.getArray(vbox, 'machines'):
+        if m.name == id or mach.id == id:
+            mach = m
+            break
+    return mach
+
+name = "Linux"
+mach = machById(name)
+if mach is None:
+    print "cannot find machine",name
+else:
+    session = mgr.getSessionObject(vbox)
+    # one can also start headless session with "vrdp" instead of "gui"
+    progress = vb.openRemoteSession(session, mach.id, "gui", "")
+    progress.waitForCompletion(-1)
+    session.close()
+        </screen>
+
+        <para>This code also shows cross-platform access to array properties
+        (certain limitations prevent one from using
+        <computeroutput>vbox.machines</computeroutput> to access a list of
+        available virtual machines in case of XPCOM), and a mechanism of
+        uniform session creation
+        (<computeroutput>virtualBoxManager.mgr.getSessionObject()</computeroutput>).</para>
+
+        <para>In case you want to use the glue layer with a different Python
+        installation, use these steps in a shell to add the necessary
+        files:</para>
+
+        <screen>    # cd VBOX_INSTALL_PATH/sdk/installer
+    # PYTHON vboxapisetup.py install</screen>
+      </sect2>
+
+      <sect2 id="cppcom">
+        <title>C++ COM API</title>
+
+        <para>C++ is the language that VirtualBox itself is written in, so C++
+        is the most direct way to use the Main API -- but it is not
+        necessarily the easiest, as using COM and XPCOM has its own set of
+        complications.</para>
+
+        <para>VirtualBox ships with sample programs that demonstrate how to
+        use the Main API to implement a number of tasks on your host platform.
+        These samples can be found in the
+        <computeroutput>/bindings/xpcom/samples</computeroutput> directory for
+        Linux, Mac OS X and Solaris and
+        <computeroutput>/bindings/mscom/samples</computeroutput> for Windows.
+        The two samples are actually different, because the one for Windows
+        uses native COM, whereas the other uses our XPCOM implementation, as
+        described above.</para>
+
+        <para>Since COM and XPCOM are conceptually very similar but vary in
+        the implementation details, we have created a "glue" layer that
+        shields COM client code from these differences. All VirtualBox uses is
+        this glue layer, so the same code written once works on both Windows
+        hosts (with native COM) as well as on other hosts (with our XPCOM
+        implementation). It is recommended to always use this glue code
+        instead of using the COM and XPCOM APIs directly, as it is very easy
+        to make your code completely independent from the platform it is
+        running on.<!--    A third sample,
+        <computeroutput>tstVBoxAPIGlue.cpp</computeroutput>, illustrates how to
+        use the glue layer.
+--></para>
+
+        <para>In order to encapsulate platform differences between Microsoft
+        COM and XPCOM, the following items should be kept in mind when using
+        the glue layer:</para>
+
+        <para><orderedlist>
+            <listitem>
+              <para><emphasis role="bold">Attribute getters and
+              setters.</emphasis> COM has the notion of "attributes" in
+              interfaces, which roughly compare to C++ member variables in
+              classes. The difference is that for each attribute declared in
+              an interface, COM automatically provides a "get" method to
+              return the attribute's value. Unless the attribute has been
+              marked as "readonly", a "set" attribute is also provided.</para>
+
+              <para>To illustrate, the IVirtualBox interface has a "version"
+              attribute, which is read-only and of the "wstring" type (the
+              standard string type in COM). As a result, you can call the
+              "get" method for this attribute to retrieve the version number
+              of VirtualBox.</para>
+
+              <para>Unfortunately, the implementation differs between COM and
+              XPCOM. Microsoft COM names the "get" method like this:
+              <computeroutput>get_Attribute()</computeroutput>, whereas XPCOM
+              uses this syntax:
+              <computeroutput>GetAttribute()</computeroutput> (and accordingly
+              for "set" methods). To hide these differences, the VirtualBox
+              glue code provides the
+              <computeroutput>COMGETTER(attrib)</computeroutput> and
+              <computeroutput>COMSETTER(attrib)</computeroutput> macros. So,
+              <computeroutput>COMGETTER(version)()</computeroutput> (note, two
+              pairs of brackets) expands to
+              <computeroutput>get_Version()</computeroutput> on Windows and
+              <computeroutput>GetVersion()</computeroutput> on other
+              platforms.</para>
+            </listitem>
+
+            <listitem>
+              <para><emphasis role="bold">Unicode conversions.</emphasis>
+              While the rest of the modern world has pretty much settled on
+              encoding strings in UTF-8, COM, unfortunately, uses UCS-16
+              encoding. This requires a lot of conversions, in particular
+              between the VirtualBox Main API and the Qt GUI, which, like the
+              rest of Qt, likes to use UTF-8.</para>
+
+              <para>To facilitate these conversions, VirtualBox provides the
+              <computeroutput>com::Bstr</computeroutput> and
+              <computeroutput>com::Utf8Str</computeroutput> classes, which
+              support all kinds of conversions back and forth.</para>
+            </listitem>
+
+            <listitem>
+              <para><emphasis role="bold">COM autopointers.</emphasis>
+              Possibly the greatest pain of using COM -- reference counting --
+              is alleviated by the
+              <computeroutput>ComPtr&lt;&gt;</computeroutput> template
+              provided by the <computeroutput>ptr.h</computeroutput> file in
+              the glue layer.</para>
+            </listitem>
+          </orderedlist></para>
+      </sect2>
+
+      <sect2 id="event-queue">
+        <title>Event queue processing</title>
+
+        <para>Both VirtualBox client programs and frontends should
+        periodically perform processing of the main event queue, and do that
+        on the application's main thread. In case of a typical GUI Windows/Mac
+        OS application this happens automatically in the GUI's dispatch loop.
+        However, for CLI only application, the appropriate actions have to be
+        taken. For C++ applications, the VirtualBox SDK provided glue method
+        <screen>
+            int EventQueue::processEventQueue(uint32_t cMsTimeout)
+         </screen> can be used for both blocking and non-blocking operations.
+        For the Python bindings, a common layer provides the method <screen>
+          VirtualBoxManager.waitForEvents(ms)
+         </screen> with similar semantics.</para>
+
+        <para>Things get somewhat more complicated for situations where an
+        application using VirtualBox cannot directly control the main event
+        loop and the main event queue is separated from the event queue of the
+        programming librarly (for example in case of Qt on Unix platforms). In
+        such a case, the application developer is advised to use a
+        platform/toolkit specific event injection mechanism to force event
+        queue checks either based on periodical timer events delivered to the
+        main thread, or by using custom platform messages to notify the main
+        thread when events are available. See the VBoxSDL and Qt (VirtualBox)
+        frontends as examples.</para>
+      </sect2>
+
+      <sect2 id="vbcom">
+        <title>Visual Basic and Visual Basic Script (VBS) on Windows
+        hosts</title>
+
+        <para>On Windows hosts, one can control some of the VirtualBox Main
+        API functionality from VBS scripts, and pretty much everything from
+        Visual Basic programs.<footnote>
+            <para>The difference results from the way VBS treats COM
+            safearrays, which are used to keep lists in the Main API. VBS
+            expects every array element to be a
+            <computeroutput>VARIANT</computeroutput>, which is too strict a
+            limitation for any high performance API. We may lift this
+            restriction for interface APIs in a future version, or
+            alternatively provide conversion APIs.</para>
+          </footnote></para>
+
+        <para>VBS is scripting language available in any recent Windows
+        environment. As an example, the following VBS code will print
+        VirtualBox version: <screen>
+         set vb = CreateObject("VirtualBox.VirtualBox")
+         Wscript.Echo "VirtualBox version " &amp; vb.version
+       </screen> See
+        <computeroutput>bindings/mscom/vbs/sample/vboxinfo.vbs</computeroutput>
+        for the complete sample.</para>
+
+        <para>Visual Basic is a popular high level language capable of
+        accessing COM objects. The following VB code will iterate over all
+        available virtual machines:<screen>
+         Dim vb As VirtualBox.IVirtualBox
+
+         vb = CreateObject("VirtualBox.VirtualBox")
+         machines = ""
+         For Each m In vb.Machines
+            m = m &amp; " " &amp; m.Name
+         Next
+       </screen> See
+        <computeroutput>bindings/mscom/vb/sample/vboxinfo.vb</computeroutput>
+        for the complete sample.</para>
+      </sect2>
+
+      <sect2 id="cbinding">
+        <title>C binding to XPCOM API</title>
+
+        <note>
+          <para>This section currently applies to Linux hosts only.</para>
+        </note>
+
+        <para>Starting with version 2.2, VirtualBox offers a C binding for the
+        XPCOM API.</para>
+
+        <para>The C binding provides a layer enabling object creation, method
+        invocation and attribute access from C.</para>
+
+        <sect3 id="c-gettingstarted">
+          <title>Getting started</title>
+
+          <para>The following sections describe how to use the C binding in a
+          C program.</para>
+
+          <para>For Linux, a sample program is provided which demonstrates use
+          of the C binding to initialize XPCOM, get handles for VirtualBox and
+          Session objects, make calls to list and start virtual machines, and
+          uninitialize resources when done. The program uses the VBoxGlue
+          library to open the C binding layer during runtime.</para>
+
+          <para>The sample program
+          <computeroutput>tstXPCOMCGlue</computeroutput> is located in the bin
+          directory and can be run without arguments. It lists registered
+          machines on the host along with some additional information and ask
+          for a machine to start. The source for this program is available in
+          <computeroutput>sdk/bindings/xpcom/cbinding/samples/</computeroutput>
+          directory. The source for the VBoxGlue library is available in the
+          <computeroutput>sdk/bindings/xpcom/cbinding/</computeroutput>
+          directory.</para>
+        </sect3>
+
+        <sect3 id="c-initialization">
+          <title>XPCOM initialization</title>
+
+          <para>Just like in C++, XPCOM needs to be initialized before it can
+          be used. The <computeroutput>VBoxCAPI_v2_5.h</computeroutput> header
+          provides the interface to the C binding. Here's how to initialize
+          XPCOM:</para>
+
+          <screen>#include "VBoxCAPI_v2_5.h"
+...
+PCVBOXXPCOM g_pVBoxFuncs = NULL;
+IVirtualBox *vbox        = NULL;
+ISession *session        = NULL;
+
+/*
+ * VBoxGetXPCOMCFunctions() is the only function exported by
+ * VBoxXPCOMC.so and the only one needed to make virtualbox
+ * work with C. This functions gives you the pointer to the
+ * function table (g_pVBoxFuncs).
+ *
+ * Once you get the function table, then how and which functions
+ * to use is explained below.
+ *
+ * g_pVBoxFuncs-&gt;pfnComInitialize does all the necessary startup
+ * action and provides us with pointers to vbox and session handles.
+ * It should be matched by a call to g_pVBoxFuncs-&gt;pfnComUninitialize()
+ * when done.
+ */
+
+g_pVBoxFuncs = VBoxGetXPCOMCFunctions(VBOX_XPCOMC_VERSION);
+g_pVBoxFuncs-&gt;pfnComInitialize(&amp;vbox, &amp;session);</screen>
+
+          <para>If either <computeroutput>vbox</computeroutput> or
+          <computeroutput>session</computeroutput> is still
+          <computeroutput>NULL</computeroutput>, initialization failed and the
+          XPCOM API cannot be used.</para>
+        </sect3>
+
+        <sect3 id="c-invocation">
+          <title>XPCOM method invocation</title>
+
+          <para>Method invocation is straightforward. It looks pretty much
+          like the C++ way, augmented with an extra indirection due to
+          accessing the vtable and passing a pointer to the object as the
+          first argument to serve as the <computeroutput>this</computeroutput>
+          pointer.</para>
+
+          <para>Using the C binding, all method invocations return a numeric
+          result code.</para>
+
+          <para>If an interface is specified as returning an object, a pointer
+          to a pointer to the appropriate object must be passed as the last
+          argument. The method will then store an object pointer in that
+          location.</para>
+
+          <para>In other words, to call an object's method what you need
+          is</para>
+
+          <screen>IObject *object;
+nsresult rc;
+...
+/*
+ * Calling void IObject::method(arg, ...)
+ */
+rc = object-&gt;vtbl-&gt;Method(object, arg, ...);
+
+...
+IFoo *foo;
+/*
+ * Calling IFoo IObject::method(arg, ...)
+ */
+rc = object-&gt;vtbl-&gt;Method(object, args, ..., &amp;foo);</screen>
+
+          <para>As a real-world example of a method invocation, let's call
+          <xref linkend="IVirtualBox__openRemoteSession"
+          xreflabel="IVirtualBox::openRemoteSession" /> which returns an
+          IProgress object. Note again that the method name is
+          capitalized.</para>
+
+          <screen>IProgress *progress;
+...
+rc = vbox-&gt;vtbl-&gt;OpenRemoteSession(
+    vbox,          /* this  */
+    session,       /* arg 1 */
+    id,            /* arg 2 */
+    sessionType,   /* arg 3 */
+    env,           /* arg 4 */
+    &amp;progress      /* Out   */
+);
+</screen>
+        </sect3>
+
+        <sect3 id="c-attributes">
+          <title>XPCOM attribute access</title>
+
+          <para>A construct similar to calling non-void methods is used to
+          access object attributes. For each attribute there exists a getter
+          method, the name of which is composed of
+          <computeroutput>Get</computeroutput> followed by the capitalized
+          attribute name. Unless the attribute is read-only, an analogous
+          <computeroutput>Set</computeroutput> method exists. Let's apply
+          these rules to read the <xref linkend="IVirtualBox__revision"
+          xreflabel="IVirtualBox::revision" /> attribute.</para>
+
+          <para>Using the <computeroutput>IVirtualBox</computeroutput> handle
+          <computeroutput>vbox</computeroutput> obtained above, calling its
+          <computeroutput>GetRevision</computeroutput> method looks like
+          this:</para>
+
+          <screen>PRUint32   rev;
+
+rc = vbox-&gt;vtbl-&gt;GetRevision(vbox, &amp;rev);
+if (NS_SUCCEEDED(rc))
+{
+    printf("Revision: %u\n", (unsigned)rev);
+}
+</screen>
+
+          <para>All objects with their methods and attributes are documented
+          in <xref linkend="sdkref_classes" />.</para>
+        </sect3>
+
+        <sect3 id="c-string-handling">
+          <title>String handling</title>
+
+          <para>When dealing with strings you have to be aware of a string's
+          encoding and ownership.</para>
+
+          <para>Internally, XPCOM uses UTF-16 encoded strings. A set of
+          conversion functions is provided to convert other encodings to and
+          from UTF-16. The type of a UTF-16 character is
+          <computeroutput>PRUnichar</computeroutput>. Strings of UTF-16
+          characters are arrays of that type. Most string handling functions
+          take pointers to that type. Prototypes for the following conversion
+          functions are declared in
+          <computeroutput>VBoxCAPI_v2_5.h</computeroutput>.</para>
+
+          <sect4>
+            <title>Conversion of UTF-16 to and from UTF-8</title>
+
+            <screen>int (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString);
+int (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString);
+</screen>
+          </sect4>
+
+          <sect4>
+            <title>Ownership</title>
+
+            <para>The ownership of a string determines who is responsible for
+            releasing resources associated with the string. Whenever XPCOM
+            creates a string, ownership is transferred to the caller. To avoid
+            resource leaks, the caller should release resources once the
+            string is no longer needed.</para>
+          </sect4>
+        </sect3>
+
+        <sect3 id="c-uninitialization">
+          <title>XPCOM uninitialization</title>
+
+          <para>Uninitialization is performed by
+          <computeroutput>g_pVBoxFuncs-&gt;pfnComUninitialize().</computeroutput>
+          If your program can exit from more than one place, it is a good idea
+          to install this function as an exit handler with Standard C's
+          <computeroutput>atexit()</computeroutput> just after calling
+          <computeroutput>g_pVBoxFuncs-&gt;pfnComInitialize()</computeroutput>
+          , e.g. <screen>#include &lt;stdlib.h&gt;
+#include &lt;stdio.h&gt;
+
+...
+
+/*
+ * Make sure g_pVBoxFuncs-&gt;pfnComUninitialize() is called at exit, no
+ * matter if we return from the initial call to main or call exit()
+ * somewhere else. Note that atexit registered functions are not
+ * called upon abnormal termination, i.e. when calling abort() or
+ * signal(). Separate provisions must be taken for these cases.
+ */
+
+if (atexit(g_pVBoxFuncs-&gt;pfnComUninitialize()) != 0) {
+    fprintf(stderr, "failed to register g_pVBoxFuncs-&gt;pfnComUninitialize()\n");
+    exit(EXIT_FAILURE);
+}
+</screen></para>
+
+          <para>Another idea would be to write your own <computeroutput>void
+          myexit(int status)</computeroutput> function, calling
+          <computeroutput>g_pVBoxFuncs-&gt;pfnComUninitialize()</computeroutput>
+          followed by the real <computeroutput>exit()</computeroutput>, and
+          use it instead of <computeroutput>exit()</computeroutput> throughout
+          your program and at the end of
+          <computeroutput>main.</computeroutput></para>
+
+          <para>If you expect the program to be terminated by a signal (e.g.
+          user types CTRL-C sending SIGINT) you might want to install a signal
+          handler setting a flag noting that a signal was sent and then
+          calling
+          <computeroutput>g_pVBoxFuncs-&gt;pfnComUninitialize()</computeroutput>
+          later on (usually <emphasis>not</emphasis> from the handler itself
+          .)</para>
+
+          <para>That said, if a client program forgets to call
+          <computeroutput>g_pVBoxFuncs-&gt;pfnComUninitialize()</computeroutput>
+          before it terminates, there is a mechanism in place which will
+          eventually release references held by the client. You should not
+          rely on this, however.</para>
+        </sect3>
+
+        <sect3 id="c-linking">
+          <title>Compiling and linking</title>
+
+          <para>A program using the C binding has to open the library during
+          runtime using the help of glue code provided and as shown in the
+          example <computeroutput>tstXPCOMCGlue.c</computeroutput>.
+          Compilation and linking can be achieved, e.g., with a makefile
+          fragment similar to</para>
+
+          <screen># Where is the XPCOM include directory?
+INCS_XPCOM    = -I../../include
+# Where is the glue code directory?
+GLUE_DIR      = ..
+GLUE_INC      = -I..
+
+#Compile Glue Library
+VBoxXPCOMCGlue.o: $(GLUE_DIR)/VBoxXPCOMCGlue.c
+    $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $&lt;
+
+# Compile.
+program.o: program.c VBoxCAPI_v2_5.h
+    $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $&lt;
+
+# Link.
+program: program.o VBoxXPCOMCGlue.o
+    $(CC) -o $@ $^ -ldl</screen>
+        </sect3>
+      </sect2>
+    </sect1>
+  </chapter>
+
+  <chapter id="concepts">
+    <title>Basic VirtualBox concepts; some examples</title>
+
+    <para>The following explains some basic VirtualBox concepts such as the
+    VirtualBox object, sessions and how virtual machines are manipulated and
+    launched using the Main API. The coding examples use a pseudo-code style
+    closely related to the object-oriented web service (OOWS) for JAX-WS.
+    Depending on which environment you are using, you will need to adjust the
+    examples.</para>
+
+    <sect1>
+      <title>Obtaining basic machine information. Reading attributes</title>
+
+      <para>Any program using the Main API will first need access to the
+      global VirtualBox object (see <xref linkend="IVirtualBox"
+      xreflabel="IVirtualBox" />), from which all other functionality of the
+      API is derived. With the OOWS for JAX-WS, this is returned from the
+      <xref linkend="???" xreflabel="IWebsessionManager::logon()" />
+      call.</para>
+
+      <para>To enumerate virtual machines, one would look at the "machines"
+      array attribute in the VirtualBox object (see <xref
+      linkend="IVirtualBox__machines" xreflabel="IVirtualBox::machines" />).
+      This array contains all virtual machines currently registered with the
+      host, each of them being an instance of <xref linkend="IMachine"
+      xreflabel="IMachine" />. From each such instance, one can query
+      additional information, such as the UUID, the name, memory, operating
+      system and more by looking at the attributes; see the attributes list in
+      <xref linkend="IMachine" xreflabel="IMachine documentation" />.</para>
+
+      <para>As mentioned in the preceding chapters, depending on your
+      programming environment, attributes are mapped to corresponding "get"
+      and (if the attribute is not read-only) "set" methods. So when the
+      documentation says that IMachine has a "<xref linkend="IMachine__name"
+      xreflabel="name" />" attribute, this means you need to code something
+      like the following to get the machine's name:<screen>IMachine machine = ...;
+String name = machine.getName();</screen>Boolean attribute getters can
+      sometimes be called <computeroutput>isAttribute()</computeroutput> due
+      to JAX-WS naming conventions.</para>
+    </sect1>
+
+    <sect1>
+      <title>Changing machine settings. Sessions</title>
+
+      <para>As said in the previous section, to read a machine's attribute,
+      one invokes the corresponding "get" method. One would think that to
+      change settings of a machine, it would suffice to call the corresponding
+      "set" method -- for example, to set a VM's memory to 1024 MB, one would
+      call <computeroutput>setMemorySize(1024)</computeroutput>. Try that, and
+      you will get an error: "The machine is not mutable."</para>
+
+      <para>So unfortunately, things are not that easy. VirtualBox is a
+      complicated environment in which multiple processes compete for possibly
+      the same resources, especially machine settings. As a result, machines
+      must be "locked" before they can either be modified or started. This is
+      to prevent multiple processes from making conflicting changes to a
+      machine: it should, for example, not be allowed to change the memory
+      size of a virtual machine while it is running. (You can't add more
+      memory to a real computer while it is running either, at least not to an
+      ordinary PC.) Also, two processes must not change settings at the same
+      time, or start a machine at the same time.</para>
+
+      <para>These requirements are implemented in the Main API by way of
+      "sessions", in particular, the <xref linkend="ISession"
+      xreflabel="ISession" /> interface. Each process which talks to
+      VirtualBox needs its own instance of ISession. In the web service, you
+      cannot create such an object, but
+      <computeroutput>vboxwebsrv</computeroutput> creates one for you when you
+      log on, which you can obtain by calling <xref
+      linkend="IWebsessionManager__getSessionObject"
+      xreflabel="IWebsessionManager::getSessionObject()" />.</para>
+
+      <para>This session object must then be used like a mutex semaphore in
+      common programming environments. Before you can change machine settings,
+      you must write-lock the machine by calling <xref
+      linkend="IMachine__lockMachine" xreflabel="IMachine::lockMachine()" />
+      with your process's session object.</para>
+
+      <para>After the machine has been locked, the <xref
+      linkend="ISession__machine" xreflabel="ISession::machine" /> attribute
+      contains a copy of the original IMachine object upon which the session
+      was opened, but this copy is "mutable": you can invoke "set" methods on
+      it.</para>
+
+      <para>When done making the changes to the machine, you must call <xref
+      linkend="IMachine__saveSettings"
+      xreflabel="IMachine::saveSettings()" />, which will copy the changes you
+      have made from your "mutable" machine back to the real machine and write
+      them out to the machine settings XML file. This will make your changes
+      permanent.</para>
+
+      <para>Finally, it is important to always unlock the machine again, by
+      calling <xref linkend="ISession__unlockMachine"
+      xreflabel="ISession::unlockMachine()" />. Otherwise, when the calling
+      process end, the machine will receive the "aborted" state, which can
+      lead to loss of data.</para>
+
+      <para>So, as an example, the sequence to change a machine's memory to
+      1024 MB is something like this:<screen>IWebsessionManager mgr ...;
+IVirtualBox vbox = mgr.logon(user, pass);
+...
+IMachine machine = ...;  // read-only machine
+ISession session = mgr.getSessionObject();
+machine.lockMachine(session, LockType.Write); // machine is now locked for writing
+IMachine mutable = session.getMachine();      // obtain the mutable machine copy
+mutable.setMemorySize(1024);
+mutable.saveSettings();                       // write settings to XML
+session.unlockMachine();</screen></para>
+    </sect1>
+
+    <sect1>
+      <title>Launching virtual machines</title>
+
+      <para>To launch a virtual machine, you call <xref
+      linkend="IMachine__launchVMProcess"
+      xreflabel="IMachine::launchVMProcess()" />. In doing so, the caller
+      instructs the VirtualBox engine to start a new process with the virtual
+      machine in it, since to the host, each virtual machine looks like a
+      single process, even if it has hundreds of its own processes inside.
+      (This new VM process in turn obtains a write lock on the machine, as
+      described above, to prevent conflicting changes from other processes;
+      this is why opening another session will fail while the VM is
+      running.)</para>
+
+      <para>Starting a machine looks something like this:<screen>IWebsessionManager mgr ...;
+IVirtualBox vbox = mgr.logon(user, pass);
+...
+IMachine machine = ...;  // read-only machine
+ISession session = mgr.getSessionObject();
+IProgress prog = machine.launchVMProcess(session,
+                                         "gui",  // session type
+                                         "");    // possibly environment setting
+prog.waitForCompletion(10000);  // give the process 10 secs
+if (prog.getResultCode() != 0)  // check success
+    System.out.println("Cannot launch VM!")</screen></para>
+
+      <para>The caller's session object can then be used as a sort of remote
+      control to the VM process that was launched. It contains a "console"
+      object (see <xref linkend="ISession__console"
+      xreflabel="ISession::console" />) with which the VM can be paused,
+      stopped, snapshotted or other things.</para>
+    </sect1>
+
+    <sect1>
+      <title>VirtualBox events</title>
+
+      <para>In VirtualBox, "events" provide a uniform mechanism to register
+      for and consume specific events. A VirtualBox client can register an
+      "event listener" (represented by the <xref linkend="IEventListener"
+      xreflabel="IEventListener" /> interface), which will then get notified
+      by the server when an event (represented by the <xref linkend="IEvent"
+      xreflabel="IEvent" /> interface) happens.</para>
+
+      <para>The IEvent interface is an abstract parent interface for all
+      events that can occur in VirtualBox. The actual events that the server
+      sends out are then of one of the specific subclasses, for example <xref
+      linkend="IMachineStateChangedEvent"
+      xreflabel="IMachineStateChangedEvent" /> or <xref
+      linkend="IMediumChangedEvent" xreflabel="IMediumChangedEvent" />.</para>
+
+      <para>As an example, the VirtualBox GUI waits for machine events and can
+      thus update its display when the machine state changes or machine
+      settings are modified, even if this happens in another client. This is
+      how the GUI can automatically refresh its display even if you manipulate
+      a machine from another client, for example, from VBoxManage.</para>
+
+      <para>To register an event listener to listen to events, use code like
+      this:<screen>EventSource es = console.getEventSource();
+IEventListener listener = es.createListener();
+VBoxEventType aTypes[] = (VBoxEventType.OnMachineStateChanged);
+        // list of event types to listen for
+es.registerListener(listener, aTypes, false /* active */);
+        // register passive listener
+IEvent ev = es.getEvent(listener, 1000);
+        // wait up to one second for event to happen
+if (ev != null)
+{
+    // downcast to specific event interface (in this case we have only registered
+    // for one type, otherwise IEvent::type would tell us)
+    IMachineStateChangedEvent mcse = IMachineStateChangedEvent.queryInterface(ev);
+    ... // inspect and do something
+    es.eventProcessed(listener, ev);
+}
+...
+es.unregisterListener(listener); </screen></para>
+
+      <para>A graphical user interface would probably best start its own
+      thread to wait for events and then process these in a loop.</para>
+
+      <para>The events mechanism was introduced with VirtualBox 3.3 and
+      replaces various callback interfaces which were called for each event in
+      the interface. The callback mechanism was not compatible with scripting
+      languages, local Java bindings and remote web services as they do not
+      support callbacks. The new mechanism with events and event listeners
+      works with all of these.</para>
+      <para>To simplify developement of application using events, 
+      concept of event aggregator was introduced. Essentially it's
+      mechanism to aggregate multiple event sources into single one,
+      and then work with this single aggregated event source instead of
+      original sources. As an example, one can evaluate demo recorder
+      in VirtualBox Python shell, shipped with SDK - it records mouse 
+      and keyboard events, represented as separate event sources.
+      Code is essentially like this:<screen>
+          listener = console.eventSource.createListener()
+          agg = console.eventSource.createAggregator([console.keyboard.eventSource, console.mouse.eventSource])
+          agg.registerListener(listener, [ctx['global'].constants.VBoxEventType_Any], False)
+          registered = True
+          end = time.time() + dur
+          while  time.time() < end:
+              ev = agg.getEvent(listener, 1000)
+              processEent(ev)
+          agg.unregisterListener(listener)</screen>
+         Without using aggregators consumer have to poll on both 
+         sources, or start multiple threads to block on those sources.
+      </para>
+    </sect1>
+  </chapter>
+
+  <chapter id="vboxshell">
+    <title>The VirtualBox shell</title>
+
+    <para>VirtualBox comes with an extensible shell, which allows you to
+    control your virtual machines from the command line. It is also a
+    nontrivial example of how to use the VirtualBox APIs from Python, for all
+    three COM/XPCOM/WS styles of the API.</para>
+
+    <para>You can easily extend this shell with your own commands. Create a
+    subdirectory named <computeroutput>.VirtualBox/shexts</computeroutput>
+    below your home directory and put a Python file implementing your shell
+    extension commands in this directory. This file must contain an array
+    named <computeroutput>commands</computeroutput> containing your command
+    definitions: <screen>
+        commands = {
+        'cmd1': ['Command cmd1 help', cmd1],
+        'cmd2': ['Command cmd2 help', cmd2]
+        }
+       </screen> For example, to create a command for creating hard drive
+    images, the following code can be used: <screen>
+        def createHdd(ctx,args):
+          # Show some meaningful error message on wrong input
+          if (len(args) &lt; 3):
+            print "usage: createHdd sizeM location type"
+            return 0
+
+          # Get arguments
+          size = int(args[1])
+          loc = args[2]
+          if len(args) &gt; 3:
+            format = args[3]
+          else:
+            # And provide some meaningful defaults
+            format = "vdi"
+
+        # Call VirtualBox API, using context's fields
+        hdd = ctx['vb'].createHardDisk(format, loc)
+        # Access constants using ctx['global'].constants
+        progress = hdd.createBaseStorage(size, ctx['global'].constants.HardDiskVariant_Standard)
+        # use standard progress bar mechanism
+        ctx['progressBar'](progress)
+
+
+        # Report errors
+        if not hdd.id:
+           print "cannot create disk (file %s exist?)" %(loc)
+           return 0
+
+        # Give user some feedback on success too
+        print "created HDD with id: %s" %(hdd.id)
+
+        # 0 means continue execution, other values mean exit from the interpreter
+        return 0
+
+      commands = {
+        'myCreateHDD': ['Create virtual HDD, createHdd size location type', createHdd]
+        }
+      </screen> Just store the above text in the file
+    <computeroutput>createHdd</computeroutput> (or any other meaningful name)
+    in <computeroutput>.VirtualBox/shexts/</computeroutput>. Start the
+    VirtualBox shell, or just issue the
+    <computeroutput>reloadExts</computeroutput> command, if the shell is
+    already running. Your new command will now be available.</para>
+  </chapter>
+
+  <!--$VIRTUALBOX_MAIN_API_REFERENCE-->
+
+  <chapter id="hgcm">
+    <title>Host-Guest Communication Manager</title>
+
+    <para>The VirtualBox Host-Guest Communication Manager (HGCM) allows a
+    guest application or a guest driver to call a host shared library. The
+    following features of VirtualBox are implemented using HGCM: <itemizedlist>
+        <listitem>
+          <para>Shared Folders</para>
+        </listitem>
+
+        <listitem>
+          <para>Shared Clipboard</para>
+        </listitem>
+
+        <listitem>
+          <para>Guest configuration interface</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>The shared library contains a so called HGCM service. The guest HGCM
+    clients establish connections to the service to call it. When calling a
+    HGCM service the client supplies a function code and a number of
+    parameters for the function.</para>
+
+    <sect1>
+      <title>Virtual hardware implementation</title>
+
+      <para>HGCM uses the VMM virtual PCI device to exchange data between the
+      guest and the host. The guest always acts as an initiator of requests. A
+      request is constructed in the guest physical memory, which must be
+      locked by the guest. The physical address is passed to the VMM device
+      using a 32 bit <computeroutput>out edx, eax</computeroutput>
+      instruction. The physical memory must be allocated below 4GB by 64 bit
+      guests.</para>
+
+      <para>The host parses the request header and data and queues the request
+      for a host HGCM service. The guest continues execution and usually waits
+      on a HGCM event semaphore.</para>
+
+      <para>When the request has been processed by the HGCM service, the VMM
+      device sets the completion flag in the request header, sets the HGCM
+      event and raises an IRQ for the guest. The IRQ handler signals the HGCM
+      event semaphore and all HGCM callers check the completion flag in the
+      corresponding request header. If the flag is set, the request is
+      considered completed.</para>
+    </sect1>
+
+    <sect1>
+      <title>Protocol specification</title>
+
+      <para>The HGCM protocol definitions are contained in the
+      <computeroutput>VBox/VBoxGuest.h</computeroutput></para>
+
+      <sect2>
+        <title>Request header</title>
+
+        <para>HGCM request structures contains a generic header
+        (VMMDevHGCMRequestHeader): <table>
+            <title>HGCM Request Generic Header</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Name</emphasis></entry>
+
+                  <entry><emphasis role="bold">Description</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>size</entry>
+
+                  <entry>Size of the entire request.</entry>
+                </row>
+
+                <row>
+                  <entry>version</entry>
+
+                  <entry>Version of the header, must be set to
+                  <computeroutput>0x10001</computeroutput>.</entry>
+                </row>
+
+                <row>
+                  <entry>type</entry>
+
+                  <entry>Type of the request.</entry>
+                </row>
+
+                <row>
+                  <entry>rc</entry>
+
+                  <entry>HGCM return code, which will be set by the VMM
+                  device.</entry>
+                </row>
+
+                <row>
+                  <entry>reserved1</entry>
+
+                  <entry>A reserved field 1.</entry>
+                </row>
+
+                <row>
+                  <entry>reserved2</entry>
+
+                  <entry>A reserved field 2.</entry>
+                </row>
+
+                <row>
+                  <entry>flags</entry>
+
+                  <entry>HGCM flags, set by the VMM device.</entry>
+                </row>
+
+                <row>
+                  <entry>result</entry>
+
+                  <entry>The HGCM result code, set by the VMM device.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table> <note>
+            <itemizedlist>
+              <listitem>
+                <para>All fields are 32 bit.</para>
+              </listitem>
+
+              <listitem>
+                <para>Fields from <computeroutput>size</computeroutput> to
+                <computeroutput>reserved2</computeroutput> are a standard VMM
+                device request header, which is used for other interfaces as
+                well.</para>
+              </listitem>
+            </itemizedlist>
+          </note></para>
+
+        <para>The <emphasis role="bold">type</emphasis> field indicates the
+        type of the HGCM request: <table>
+            <title>Request Types</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Name (decimal
+                  value)</emphasis></entry>
+
+                  <entry><emphasis role="bold">Description</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevReq_HGCMConnect
+                  (<computeroutput>60</computeroutput>)</entry>
+
+                  <entry>Connect to a HGCM service.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevReq_HGCMDisconnect
+                  (<computeroutput>61</computeroutput>)</entry>
+
+                  <entry>Disconnect from the service.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevReq_HGCMCall32
+                  (<computeroutput>62</computeroutput>)</entry>
+
+                  <entry>Call a HGCM function using the 32 bit
+                  interface.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevReq_HGCMCall64
+                  (<computeroutput>63</computeroutput>)</entry>
+
+                  <entry>Call a HGCM function using the 64 bit
+                  interface.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevReq_HGCMCancel
+                  (<computeroutput>64</computeroutput>)</entry>
+
+                  <entry>Cancel a HGCM request currently being processed by a
+                  host HGCM service.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table></para>
+
+        <para>The <emphasis role="bold">flags</emphasis> field may contain:
+        <table>
+            <title>Flags</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Name (hexadecimal
+                  value)</emphasis></entry>
+
+                  <entry><emphasis role="bold">Description</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>VBOX_HGCM_REQ_DONE
+                  (<computeroutput>0x00000001</computeroutput>)</entry>
+
+                  <entry>The request has been processed by the host
+                  service.</entry>
+                </row>
+
+                <row>
+                  <entry>VBOX_HGCM_REQ_CANCELLED
+                  (<computeroutput>0x00000002</computeroutput>)</entry>
+
+                  <entry>This request was cancelled.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table></para>
+      </sect2>
+
+      <sect2>
+        <title>Connect</title>
+
+        <para>The connection request must be issued by the guest HGCM client
+        before it can call the HGCM service (VMMDevHGCMConnect): <table>
+            <title>Connect request</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Name</emphasis></entry>
+
+                  <entry><emphasis role="bold">Description</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>header</entry>
+
+                  <entry>The generic HGCM request header with type equal to
+                  VMMDevReq_HGCMConnect
+                  (<computeroutput>60</computeroutput>).</entry>
+                </row>
+
+                <row>
+                  <entry>type</entry>
+
+                  <entry>The type of the service location information (32
+                  bit).</entry>
+                </row>
+
+                <row>
+                  <entry>location</entry>
+
+                  <entry>The service location information (128 bytes).</entry>
+                </row>
+
+                <row>
+                  <entry>clientId</entry>
+
+                  <entry>The client identifier assigned to the connecting
+                  client by the HGCM subsystem (32 bit).</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table> The <emphasis role="bold">type</emphasis> field tells the
+        HGCM how to look for the requested service: <table>
+            <title>Location Information Types</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Name (hexadecimal
+                  value)</emphasis></entry>
+
+                  <entry><emphasis role="bold">Description</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMLoc_LocalHost
+                  (<computeroutput>0x1</computeroutput>)</entry>
+
+                  <entry>The requested service is a shared library located on
+                  the host and the location information contains the library
+                  name.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMLoc_LocalHost_Existing
+                  (<computeroutput>0x2</computeroutput>)</entry>
+
+                  <entry>The requested service is a preloaded one and the
+                  location information contains the service name.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table> <note>
+            <para>Currently preloaded HGCM services are hard-coded in
+            VirtualBox: <itemizedlist>
+                <listitem>
+                  <para>VBoxSharedFolders</para>
+                </listitem>
+
+                <listitem>
+                  <para>VBoxSharedClipboard</para>
+                </listitem>
+
+                <listitem>
+                  <para>VBoxGuestPropSvc</para>
+                </listitem>
+
+                <listitem>
+                  <para>VBoxSharedOpenGL</para>
+                </listitem>
+              </itemizedlist></para>
+          </note> There is no difference between both types of HGCM services,
+        only the location mechanism is different.</para>
+
+        <para>The client identifier is returned by the host and must be used
+        in all subsequent requests by the client.</para>
+      </sect2>
+
+      <sect2>
+        <title>Disconnect</title>
+
+        <para>This request disconnects the client and makes the client
+        identifier invalid (VMMDevHGCMDisconnect): <table>
+            <title>Disconnect request</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Name</emphasis></entry>
+
+                  <entry><emphasis role="bold">Description</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>header</entry>
+
+                  <entry>The generic HGCM request header with type equal to
+                  VMMDevReq_HGCMDisconnect
+                  (<computeroutput>61</computeroutput>).</entry>
+                </row>
+
+                <row>
+                  <entry>clientId</entry>
+
+                  <entry>The client identifier previously returned by the
+                  connect request (32 bit).</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table></para>
+      </sect2>
+
+      <sect2>
+        <title>Call32 and Call64</title>
+
+        <para>Calls the HGCM service entry point (VMMDevHGCMCall) using 32 bit
+        or 64 bit addresses: <table>
+            <title>Call request</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Name</emphasis></entry>
+
+                  <entry><emphasis role="bold">Description</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>header</entry>
+
+                  <entry>The generic HGCM request header with type equal to
+                  either VMMDevReq_HGCMCall32
+                  (<computeroutput>62</computeroutput>) or
+                  VMMDevReq_HGCMCall64
+                  (<computeroutput>63</computeroutput>).</entry>
+                </row>
+
+                <row>
+                  <entry>clientId</entry>
+
+                  <entry>The client identifier previously returned by the
+                  connect request (32 bit).</entry>
+                </row>
+
+                <row>
+                  <entry>function</entry>
+
+                  <entry>The function code to be processed by the service (32
+                  bit).</entry>
+                </row>
+
+                <row>
+                  <entry>cParms</entry>
+
+                  <entry>The number of following parameters (32 bit). This
+                  value is 0 if the function requires no parameters.</entry>
+                </row>
+
+                <row>
+                  <entry>parms</entry>
+
+                  <entry>An array of parameter description structures
+                  (HGCMFunctionParameter32 or
+                  HGCMFunctionParameter64).</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table></para>
+
+        <para>The 32 bit parameter description (HGCMFunctionParameter32)
+        consists of 32 bit type field and 8 bytes of an opaque value, so 12
+        bytes in total. The 64 bit variant (HGCMFunctionParameter64) consists
+        of the type and 12 bytes of a value, so 16 bytes in total.</para>
+
+        <para><table>
+            <title>Parameter types</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Type</emphasis></entry>
+
+                  <entry><emphasis role="bold">Format of the
+                  value</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_32bit (1)</entry>
+
+                  <entry>A 32 bit value.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_64bit (2)</entry>
+
+                  <entry>A 64 bit value.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_PhysAddr (3)</entry>
+
+                  <entry>A 32 bit size followed by a 32 bit or 64 bit guest
+                  physical address.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_LinAddr (4)</entry>
+
+                  <entry>A 32 bit size followed by a 32 bit or 64 bit guest
+                  linear address. The buffer is used both for guest to host
+                  and for host to guest data.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_LinAddr_In (5)</entry>
+
+                  <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
+                  used only for host to guest data.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_LinAddr_Out (6)</entry>
+
+                  <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
+                  used only for guest to host data.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_LinAddr_Locked (7)</entry>
+
+                  <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
+                  already locked by the guest.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_LinAddr_Locked_In (1)</entry>
+
+                  <entry>Same as VMMDevHGCMParmType_LinAddr_In but the buffer
+                  is already locked by the guest.</entry>
+                </row>
+
+                <row>
+                  <entry>VMMDevHGCMParmType_LinAddr_Locked_Out (1)</entry>
+
+                  <entry>Same as VMMDevHGCMParmType_LinAddr_Out but the buffer
+                  is already locked by the guest.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table></para>
+
+        <para>The</para>
+      </sect2>
+
+      <sect2>
+        <title>Cancel</title>
+
+        <para>This request cancels a call request (VMMDevHGCMCancel): <table>
+            <title>Cancel request</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Name</emphasis></entry>
+
+                  <entry><emphasis role="bold">Description</emphasis></entry>
+                </row>
+
+                <row>
+                  <entry>header</entry>
+
+                  <entry>The generic HGCM request header with type equal to
+                  VMMDevReq_HGCMCancel
+                  (<computeroutput>64</computeroutput>).</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table></para>
+      </sect2>
+    </sect1>
+
+    <sect1>
+      <title>Guest software interface</title>
+
+      <para>The guest HGCM clients can call HGCM services from both drivers
+      and applications.</para>
+
+      <sect2>
+        <title>The guest driver interface</title>
+
+        <para>The driver interface is implemented in the VirtualBox guest
+        additions driver (VBoxGuest), which works with the VMM virtual device.
+        Drivers must use the VBox Guest Library (VBGL), which provides an API
+        for HGCM clients (<computeroutput>VBox/VBoxGuestLib.h</computeroutput>
+        and <computeroutput>VBox/VBoxGuest.h</computeroutput>).</para>
+
+        <para><screen>
+DECLVBGL(int) VbglHGCMConnect (VBGLHGCMHANDLE *pHandle, VBoxGuestHGCMConnectInfo *pData);
+          </screen> Connects to the service: <screen>
+    VBoxGuestHGCMConnectInfo data;
+
+    memset (&amp;data, sizeof (VBoxGuestHGCMConnectInfo));
+
+    data.result   = VINF_SUCCESS;
+    data.Loc.type = VMMDevHGCMLoc_LocalHost_Existing;
+    strcpy (data.Loc.u.host.achName, "VBoxSharedFolders");
+
+    rc = VbglHGCMConnect (&amp;handle, &amp;data);
+
+    if (RT_SUCCESS (rc))
+    {
+        rc = data.result;
+    }
+
+    if (RT_SUCCESS (rc))
+    {
+        /* Get the assigned client identifier. */
+        ulClientID = data.u32ClientID;
+    }
+          </screen></para>
+
+        <para><screen>
+DECLVBGL(int) VbglHGCMDisconnect (VBGLHGCMHANDLE handle, VBoxGuestHGCMDisconnectInfo *pData);
+          </screen> Disconnects from the service. <screen>
+    VBoxGuestHGCMDisconnectInfo data;
+
+    RtlZeroMemory (&amp;data, sizeof (VBoxGuestHGCMDisconnectInfo));
+
+    data.result      = VINF_SUCCESS;
+    data.u32ClientID = ulClientID;
+
+    rc = VbglHGCMDisconnect (handle, &amp;data);
+          </screen></para>
+
+        <para><screen>
+DECLVBGL(int) VbglHGCMCall (VBGLHGCMHANDLE handle, VBoxGuestHGCMCallInfo *pData, uint32_t cbData);
+          </screen> Calls a function in the service. <screen>
+typedef struct _VBoxSFRead
+{
+    VBoxGuestHGCMCallInfo callInfo;
+
+    /** pointer, in: SHFLROOT
+     * Root handle of the mapping which name is queried.
+     */
+    HGCMFunctionParameter root;
+
+    /** value64, in:
+     * SHFLHANDLE of object to read from.
+     */
+    HGCMFunctionParameter handle;
+
+    /** value64, in:
+     * Offset to read from.
+     */
+    HGCMFunctionParameter offset;
+
+    /** value64, in/out:
+     * Bytes to read/How many were read.
+     */
+    HGCMFunctionParameter cb;
+
+    /** pointer, out:
+     * Buffer to place data to.
+     */
+    HGCMFunctionParameter buffer;
+
+} VBoxSFRead;
+
+/** Number of parameters */
+#define SHFL_CPARMS_READ (5)
+
+...
+
+    VBoxSFRead data;
+
+    /* The call information. */
+    data.callInfo.result      = VINF_SUCCESS;     /* Will be returned by HGCM. */
+    data.callInfo.u32ClientID = ulClientID;       /* Client identifier. */
+    data.callInfo.u32Function = SHFL_FN_READ;     /* The function code. */
+    data.callInfo.cParms      = SHFL_CPARMS_READ; /* Number of parameters. */
+
+    /* Initialize parameters. */
+    data.root.type                      = VMMDevHGCMParmType_32bit;
+    data.root.u.value32                 = pMap-&gt;root;
+
+    data.handle.type                    = VMMDevHGCMParmType_64bit;
+    data.handle.u.value64               = hFile;
+
+    data.offset.type                    = VMMDevHGCMParmType_64bit;
+    data.offset.u.value64               = offset;
+
+    data.cb.type                        = VMMDevHGCMParmType_32bit;
+    data.cb.u.value32                   = *pcbBuffer;
+
+    data.buffer.type                    = VMMDevHGCMParmType_LinAddr_Out;
+    data.buffer.u.Pointer.size          = *pcbBuffer;
+    data.buffer.u.Pointer.u.linearAddr  = (uintptr_t)pBuffer;
+
+    rc = VbglHGCMCall (handle, &amp;data.callInfo, sizeof (data));
+
+    if (RT_SUCCESS (rc))
+    {
+        rc = data.callInfo.result;
+        *pcbBuffer = data.cb.u.value32; /* This is returned by the HGCM service. */
+    }
+          </screen></para>
+      </sect2>
+
+      <sect2>
+        <title>Guest application interface</title>
+
+        <para>Applications call the VirtualBox Guest Additions driver to
+        utilize the HGCM interface. There are IOCTL's which correspond to the
+        <computeroutput>Vbgl*</computeroutput> functions: <itemizedlist>
+            <listitem>
+              <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CONNECT</computeroutput></para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>VBOXGUEST_IOCTL_HGCM_DISCONNECT</computeroutput></para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CALL</computeroutput></para>
+            </listitem>
+          </itemizedlist></para>
+
+        <para>These IOCTL's get the same input buffer as
+        <computeroutput>VbglHGCM*</computeroutput> functions and the output
+        buffer has the same format as the input buffer. The same address can
+        be used as the input and output buffers.</para>
+
+        <para>For example see the guest part of shared clipboard, which runs
+        as an application and uses the HGCM interface.</para>
+      </sect2>
+    </sect1>
+
+    <sect1>
+      <title>HGCM Service Implementation</title>
+
+      <para>The HGCM service is a shared library with a specific set of entry
+      points. The library must export the
+      <computeroutput>VBoxHGCMSvcLoad</computeroutput> entry point: <screen>
+extern "C" DECLCALLBACK(DECLEXPORT(int)) VBoxHGCMSvcLoad (VBOXHGCMSVCFNTABLE *ptable)
+      </screen></para>
+
+      <para>The service must check the
+      <computeroutput>ptable-&gt;cbSize</computeroutput> and
+      <computeroutput>ptable-&gt;u32Version</computeroutput> fields of the
+      input structure and fill the remaining fields with function pointers of
+      entry points and the size of the required client buffer size.</para>
+
+      <para>The HGCM service gets a dedicated thread, which calls service
+      entry points synchronously, that is the service will be called again
+      only when a previous call has returned. However, the guest calls can be
+      processed asynchronously. The service must call a completion callback
+      when the operation is actually completed. The callback can be issued
+      from another thread as well.</para>
+
+      <para>Service entry points are listed in the
+      <computeroutput>VBox/hgcmsvc.h</computeroutput> in the
+      <computeroutput>VBOXHGCMSVCFNTABLE</computeroutput> structure. <table>
+          <title>Service entry points</title>
+
+          <tgroup cols="2">
+            <tbody>
+              <row>
+                <entry><emphasis role="bold">Entry</emphasis></entry>
+
+                <entry><emphasis role="bold">Description</emphasis></entry>
+              </row>
+
+              <row>
+                <entry>pfnUnload</entry>
+
+                <entry>The service is being unloaded.</entry>
+              </row>
+
+              <row>
+                <entry>pfnConnect</entry>
+
+                <entry>A client <computeroutput>u32ClientID</computeroutput>
+                is connected to the service. The
+                <computeroutput>pvClient</computeroutput> parameter points to
+                an allocated memory buffer which can be used by the service to
+                store the client information.</entry>
+              </row>
+
+              <row>
+                <entry>pfnDisconnect</entry>
+
+                <entry>A client is being disconnected.</entry>
+              </row>
+
+              <row>
+                <entry>pfnCall</entry>
+
+                <entry>A guest client calls a service function. The
+                <computeroutput>callHandle</computeroutput> must be used in
+                the VBOXHGCMSVCHELPERS::pfnCallComplete callback when the call
+                has been processed.</entry>
+              </row>
+
+              <row>
+                <entry>pfnHostCall</entry>
+
+                <entry>Called by the VirtualBox host components to perform
+                functions which should be not accessible by the guest. Usually
+                this entry point is used by VirtualBox to configure the
+                service.</entry>
+              </row>
+
+              <row>
+                <entry>pfnSaveState</entry>
+
+                <entry>The VM state is being saved and the service must save
+                relevant information using the SSM API
+                (<computeroutput>VBox/ssm.h</computeroutput>).</entry>
+              </row>
+
+              <row>
+                <entry>pfnLoadState</entry>
+
+                <entry>The VM is being restored from the saved state and the
+                service must load the saved information and be able to
+                continue operations from the saved state.</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table></para>
+    </sect1>
+  </chapter>
+
+  <chapter id="rdpweb">
+    <title>RDP Web Control</title>
+
+    <para>The VirtualBox <emphasis>RDP Web Control</emphasis> (RDPWeb)
+    provides remote access to a running VM. RDPWeb is a RDP (Remote Desktop
+    Protocol) client based on Flash technology and can be used from a Web
+    browser with a Flash plugin.</para>
+
+    <sect1>
+      <title>RDPWeb features</title>
+
+      <para>RDPWeb is embedded into a Web page and can connect to VRDP server
+      in order to displays the VM screen and pass keyboard and mouse events to
+      the VM.</para>
+    </sect1>
+
+    <sect1>
+      <title>RDPWeb reference</title>
+
+      <para>RDPWeb consists of two required components:<itemizedlist>
+          <listitem>
+            <para>Flash movie
+            <computeroutput>RDPClientUI.swf</computeroutput></para>
+          </listitem>
+
+          <listitem>
+            <para>JavaScript helpers
+            <computeroutput>webclient.js</computeroutput></para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>The VirtualBox SDK contains sample HTML code
+      including:<itemizedlist>
+          <listitem>
+            <para>JavaScript library for embedding Flash content
+            <computeroutput>SWFObject.js</computeroutput></para>
+          </listitem>
+
+          <listitem>
+            <para>Sample HTML page
+            <computeroutput>webclient3.html</computeroutput></para>
+          </listitem>
+        </itemizedlist></para>
+
+      <sect2>
+        <title>RDPWeb functions</title>
+
+        <para><computeroutput>RDPClientUI.swf</computeroutput> and
+        <computeroutput>webclient.js</computeroutput> work with each other.
+        JavaScript code is responsible for a proper SWF initialization,
+        delivering mouse events to the SWF and processing resize requests from
+        the SWF. On the other hand, the SWF contains a few JavaScript callable
+        methods, which are used both from
+        <computeroutput>webclient.js</computeroutput> and the user HTML
+        page.</para>
+
+        <sect3>
+          <title>JavaScript functions</title>
+
+          <para><computeroutput>webclient.js</computeroutput> contains helper
+          functions. In the following table ElementId refers to an HTML
+          element name or attribute, and Element to the HTML element itself.
+          HTML code<programlisting>
+    &lt;div id="FlashRDP"&gt;
+    &lt;/div&gt;
+</programlisting> would have ElementId equal to FlashRDP and Element equal to
+          the div element.</para>
+
+          <para><itemizedlist>
+              <listitem>
+                <programlisting>RDPWebClient.embedSWF(SWFFileName, ElementId)</programlisting>
+
+                <para>Uses SWFObject library to replace the HTML element with
+                the Flash movie.</para>
+              </listitem>
+
+              <listitem>
+                 RDPWebClient.isRDPWebControlById(ElementId) 
+
+                <para>Returns true if the given id refers to a RDPWeb Flash
+                element.</para>
+
+                 
+              </listitem>
+
+              <listitem>
+                 RDPWebClient.isRDPWebControlByElement(Element) 
+
+                <para>Returns true if the given element is a RDPWeb Flash
+                element.</para>
+
+                 
+              </listitem>
+
+              <listitem>
+                 RDPWebClient.getFlashById(ElementId) 
+
+                <para>Returns an element, which is referenced by the given id.
+                This function will try to resolve any element, event if it is
+                not a Flash movie.</para>
+
+                 
+              </listitem>
+            </itemizedlist></para>
+        </sect3>
+
+        <sect3>
+          <title>Flash methods callable from JavaScript</title>
+
+          <para><computeroutput>RDPWebClienUI.swf</computeroutput> methods can
+          be called directly from JavaScript code on a HTML page.</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>getProperty(Name)</para>
+            </listitem>
+
+            <listitem>
+              <para>setProperty(Name)</para>
+            </listitem>
+
+            <listitem>
+              <para>connect()</para>
+            </listitem>
+
+            <listitem>
+              <para>disconnect()</para>
+            </listitem>
+
+            <listitem>
+              <para>keyboardSendCAD()</para>
+            </listitem>
+          </itemizedlist>
+        </sect3>
+
+        <sect3>
+          <title>Flash JavaScript callbacks</title>
+
+          <para><computeroutput>RDPWebClienUI.swf</computeroutput> calls
+          JavaScript functions provided by the HTML page.</para>
+        </sect3>
+      </sect2>
+
+      <sect2>
+        <title>Embedding RDPWeb in an HTML page</title>
+
+        <para>It is necessary to include
+        <computeroutput>webclient.js</computeroutput> helper script. If
+        SWFObject library is used, the
+        <computeroutput>swfobject.js</computeroutput> must be also included
+        and RDPWeb flash content can be embedded to a Web page using dynamic
+        HTML. The HTML must include a "placeholder", which consists of 2
+        <computeroutput>div</computeroutput> elements.</para>
+      </sect2>
+    </sect1>
+
+    <sect1>
+      <title>RDPWeb change log</title>
+
+      <sect2>
+        <title>Version 1.2.28</title>
+
+        <itemizedlist>
+          <listitem>
+            <para><computeroutput>keyboardLayout</computeroutput>,
+            <computeroutput>keyboardLayouts</computeroutput>,
+            <computeroutput>UUID</computeroutput> properties.</para>
+          </listitem>
+
+          <listitem>
+            <para>Support for German keyboard layout on the client.</para>
+          </listitem>
+
+          <listitem>
+            <para>Rebranding to Oracle.</para>
+          </listitem>
+        </itemizedlist>
+      </sect2>
+
+      <sect2>
+        <title>Version 1.1.26</title>
+
+        <itemizedlist>
+          <listitem>
+            <para><computeroutput>webclient.js</computeroutput> is a part of
+            the distribution package.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>lastError</computeroutput> property.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>keyboardSendScancodes</computeroutput> and
+            <computeroutput>keyboardSendCAD</computeroutput> methods.</para>
+          </listitem>
+        </itemizedlist>
+      </sect2>
+
+      <sect2>
+        <title>Version 1.0.24</title>
+
+        <itemizedlist>
+          <listitem>
+            <para>Initial release.</para>
+          </listitem>
+        </itemizedlist>
+      </sect2>
+    </sect1>
+  </chapter>
+
+  <chapter id="javaapi">
+    <title>Using Java API</title>
+
+    <sect1>
+      <title>Introduction</title>
+
+      <para>VirtualBox can be controlled by a Java API, both locally
+      (COM/XPCOM) and from remote (SOAP) clients. As with the Python bindings,
+      a generic glue layer tries to hide all platform differences, allowing
+      for source and binary compatibility on different platforms.</para>
+    </sect1>
+
+    <sect1>
+      <title>Requirements</title>
+
+      <para>To use the Java bindings, there are certain requirements depending
+      on the platform. First of all, you need JDK 1.5 (Java 5) or later. Also
+      please make sure that the version of the VirtualBox API .jar file
+      exactly matches the version of VirtualBox you use. To avoid confusion,
+      the VirtualBox API provides versioning in the Java package name, e.g.
+      the package is named <computeroutput>org.virtualbox_3_2</computeroutput>
+      for VirtualBox version 3.2. <itemizedlist>
+          <listitem>
+            <para><emphasis role="bold">XPCOM:</emphasis> - for all platforms,
+            but Microsoft Windows. A Java bridge based on JavaXPCOM is shipped
+            with VirtualBox. The classpath must contain
+            <computeroutput>vboxjxpcom.jar</computeroutput> and the
+            <computeroutput>vbox.home</computeroutput> property must be set to
+            location where the VirtualBox binaries are. Please make sure that
+            the JVM bitness matches bitness of VirtualBox you use as the XPCOM
+            bridge relies on native libraries.</para>
+
+            <para>Start your application like this: <programlisting>
+ java -cp vboxjxpcom.jar -Dvbox.home=/opt/virtualbox MyProgram
+              </programlisting></para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">COM:</emphasis> - for Microsoft
+            Windows. We rely on <computeroutput>Jacob</computeroutput> - a
+            generic Java to COM bridge - which has to be installed seperately.
+            See <ulink
+            url="http://sourceforge.net/projects/jacob-project/">http://sourceforge.net/projects/jacob-project/</ulink>
+            for installation instructions. Also, the VirtualBox provided
+            <computeroutput>vboxjmscom.jar</computeroutput> must be in the
+            class path.</para>
+
+            <para>Start your application like this: <programlisting>
+ java -cp vboxjmscom.jar;c:\jacob\jacob.jar -Djava.library.path=c:\jacob MyProgram
+              </programlisting></para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">SOAP</emphasis> - all platforms. Java
+            6 is required, as it comes with builtin support for SOAP via the
+            JAX-WS library. Also, the VirtualBox provided
+            <computeroutput>vbojws.jar</computeroutput> must be in the class
+            path. In the SOAP case it's possible to create several
+            VirtualBoxManager instances to communicate with multiple
+            VirtualBox hosts.</para>
+
+            <para>Start your application like this: <programlisting>
+ java -cp vboxjws.jar MyProgram
+              </programlisting></para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>Exception handling is also generalized by the generic glue layer,
+      so that all methods could throw
+      <computeroutput>VBoxException</computeroutput> containing human-readable
+      text message (see <computeroutput>getMessage()</computeroutput> method)
+      along with wrapped original exception (see
+      <computeroutput>getWrapped()</computeroutput> method).</para>
+    </sect1>
+
+    <sect1>
+      <title>Example</title>
+
+      <para>This example shows a simple use case of the Java API. Differences
+      for SOAP vs. local version are minimal, and limited to the connection
+      setup phase (see <computeroutput>ws</computeroutput> variable). In the
+      SOAP case it's possible to create several VirtualBoxManager instances to
+      communicate with multiple VirtualBox hosts. <programlisting>
+          import org.virtualbox_3_3.*;
+          ....
+          VirtualBoxManager mgr = VirtualBoxManager.createInstance(null);
+          boolean ws = false; // or true, if we need the SOAP version
+          if (ws)
+          {
+              String url = "http://myhost:18034";
+              String user = "test";
+              String passwd = "test";
+              mgr.connect(url, user, passwd);
+          }
+          IVirtualBox vbox = mgr.getVBox();
+          System.out.println("VirtualBox version: " + vbox.getVersion() + "\n");
+          // get first VM name
+          String m =  vbox.getMachines().get(0).getName();
+          System.out.println("\nAttempting to start VM '" + m + "'");
+          // start it
+          mgr.startVm(m, null, 7000);
+
+          if (ws)
+              mgr.disconnect();
+
+          mgr.cleanup();
+        </programlisting> For more a complete example, see
+      <computeroutput>TestVBox.java</computeroutput>, shipped with the
+      SDK.</para>
+    </sect1>
+  </chapter>
+
+  <chapter>
+    <title>License information</title>
+
+    <para>The sample code files shipped with the SDK are generally licensed
+    liberally to make it easy for anyone to use this code for their own
+    application code.</para>
+
+    <para>The Java files under
+    <computeroutput>bindings/webservice/java/jax-ws/</computeroutput> (library
+    files for the object-oriented web service) are, by contrast, licensed
+    under the GNU Lesser General Public License (LGPL) V2.1.</para>
+
+    <para>See
+    <computeroutput>sdk/bindings/webservice/java/jax-ws/src/COPYING.LIB</computeroutput>
+    for the full text of the LGPL 2.1.</para>
+
+    <para>When in doubt, please refer to the individual source code files
+    shipped with this SDK.</para>
+  </chapter>
+
+  <chapter>
+    <title>Main API change log</title>
+
+    <para>Generally, VirtualBox will maintain API compatibility within a major
+    release; a major release occurs when the first or the second of the three
+    version components of VirtualBox change (that is, in the x.y.z scheme, a
+    major release is one where x or y change, but not when only z
+    changes).</para>
+
+    <para>In other words, updates like those from 2.0.0 to 2.0.2 will not come
+    with API breakages.</para>
+
+    <para>Migration between major releases most likely will lead to API
+    breakage, so please make sure you updated code accordingly. The OOWS Java
+    wrappers enforce that mechanism by putting VirtualBox classes into
+    version-specific packages such as
+    <computeroutput>org.virtualbox_2_2</computeroutput>. This approach allows
+    for connecting to multiple VirtualBox versions simultaneously from the
+    same Java application.</para>
+
+    <para>The following sections list incompatible changes that the Main API
+    underwent since the original release of this SDK Reference with VirtualBox
+    2.0. A change is deemed "incompatible" only if it breaks existing client
+    code (e.g. changes in method parameter lists, renamed or removed
+    interfaces and similar). In other words, the list does not contain new
+    interfaces, methods or attributes or other changes that do not affect
+    existing client code.</para>
+
+    <sect1>
+      <title>Incompatible API changes with version 4.0</title>
+
+      <itemizedlist>
+        <listitem>
+          <para>The confusingly named and impractical session APIs were
+          changed. In existing client code, the following changes need to be
+          made:<itemizedlist>
+              <listitem>
+                <para>Replace any
+                <computeroutput>IVirtualBox::openSession(uuidMachine,
+                ...)</computeroutput> API call with the machine's <xref
+                linkend="IMachine__lockMachine"
+                xreflabel="IMachine::lockMachine()" /> call and a
+                <computeroutput>LockType.Write</computeroutput> argument. The
+                functionality is unchanged, but instead of "opening a direct
+                session on a machine" all documentation now refers to
+                "obtaining a write lock on a machine for the client
+                session".</para>
+              </listitem>
+
+              <listitem>
+                <para>Similarly, replace any
+                <computeroutput>IVirtualBox::openExistingSession(uuidMachine,
+                ...)</computeroutput> call with the machine's <xref
+                linkend="IMachine__lockMachine"
+                xreflabel="IMachine::lockMachine()" /> call and a
+                <computeroutput>LockType.Shared</computeroutput> argument.
+                Whereas it was previously impossible to connect a client
+                session to a running VM process in a race-free manner, the new
+                API will atomically either write-lock the machine for the
+                current session or establish a remote link to an existing
+                session. Existing client code which tried calling both
+                <computeroutput>openSession()</computeroutput> and
+                <computeroutput>openExistingSession()</computeroutput> can now
+                use this one call instead.</para>
+              </listitem>
+
+              <listitem>
+                <para>Third, replace any
+                <computeroutput>IVirtualBox::openRemoteSession(uuidMachine,
+                ...)</computeroutput> call with the machine's <xref
+                linkend="IMachine__launchVMProcess"
+                xreflabel="IMachine::launchVMProcess()" /> call. The
+                functionality is unchanged.</para>
+              </listitem>
+
+              <listitem>
+                <para>The <xref linkend="SessionState"
+                xreflabel="SessionState" /> enum was adjusted accordingly:
+                "Open" is now "Locked", "Closed" is now "Unlocked", "Closing"
+                is now "Unlocking".</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>Virtual machines created with VirtualBox 4.0 or later no
+          longer register their media in the global media registry in the
+          <computeroutput>VirtualBox.xml</computeroutput> file. Instead, such
+          machines list all their media in their own machine XML files. As a
+          result, a number of media-related APIs had to be modified again.
+          <itemizedlist>
+              <listitem>
+                <para>Neither <xref linkend="IVirtualBox__createHardDisk"
+                xreflabel="IVirtualBox::createHardDisk()" /> nor <xref
+                linkend="IVirtualBox__openMedium"
+                xreflabel="IVirtualBox::openMedium()" /> register media
+                automatically any more.</para>
+              </listitem>
+
+              <listitem>
+                <para><xref linkend="IMachine__attachDevice"
+                xreflabel="IMachine::attachDevice()" /> and <xref
+                linkend="IMachine__mountMedium"
+                xreflabel="IMachine::mountMedium()" /> now take an IMedium
+                object instead of a UUID as an argument. It is these two calls
+                which add media to a registry now (either a machine registry
+                for machines created with VirtualBox 4.0 or later or the
+                global registry otherwise). As a consequence, if a medium is
+                opened but never attached to a machine, it is no longer added
+                to any registry any more.</para>
+              </listitem>
+
+              <listitem>
+                <para>To reduce code duplication, the APIs
+                IVirtualBox::findHardDisk(), getHardDisk(), findDVDImage(),
+                getDVDImage(), findFloppyImage() and getFloppyImage() have all
+                been merged into <xref linkend="IVirtualBox__findMedium"
+                xreflabel="IVirtualBox::findMedium()" />, and
+                IVirtualBox::openHardDisk(), openDVDImage() and
+                openFloppyImage() have all been merged into <xref
+                linkend="IVirtualBox__openMedium"
+                xreflabel="IVirtualBox::openMedium()" />.</para>
+              </listitem>
+
+              <listitem>
+                <para>The rare use case of changing the UUID and parent UUID
+                of a medium previously handled by openHardDisk() is now in a
+                separate <xref linkend="IMedium__setIDs"
+                xreflabel="IMedium::setIDs" /> method.</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>To reduce code duplication and for consistency with the
+          aforementioned changes, IVirtualBox::getMachine() has been merged
+          with <xref linkend="IVirtualBox__findMachine"
+          xreflabel="IVirtualBox::findMachine()" />, and
+          IMachine::getSnapshot() has been merged with <xref
+          linkend="IMachine__findSnapshot"
+          xreflabel="IMachine::findSnapshot()" />.</para>
+        </listitem>
+
+        <listitem>
+          <para>IVirtualBox::unregisterMachine() was replaced with <xref
+          linkend="IMachine__unregister" xreflabel="IMachine::unregister()" />
+          with additional functionality.</para>
+        </listitem>
+
+        <listitem>
+          <para><xref linkend="IVirtualBox__createMachine"
+          xreflabel="IVirtualBox::createMachine()" /> is no longer restricted
+          to creating machines in the default "Machines" folder, but can now
+          create machines at arbitrary locations. For this to work, the
+          parameter list had to be changed.</para>
+        </listitem>
+
+        <listitem>
+          <para>IConsole::forgetSavedState has been renamed to <xref
+          linkend="IConsole__discardSavedState"
+          xreflabel="IConsole::discardSavedState()" />.</para>
+        </listitem>
+
+        <listitem>
+          <para>All event callbacks APIs were replaced with a new, generic
+          event mechanism that can be used both locally (COM, XPCOM) and
+          remotely (web services). Also, the new mechanism is usable from
+          scripting languages and a local Java. See <xref linkend="IEvent"
+          xreflabel="events" /> for details. The new concept will require
+          changes to all clients that used event callbacks.</para>
+        </listitem>
+
+        <listitem>
+          <para><xref linkend="IGuest__additionsVersion"
+          xreflabel="IGuest::additionsVersion()" /> no longer returns the
+          Guest Additions interface version but the installed Guest Additions
+          version and revision in form of
+          <computeroutput>3.3.0r12345</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>additionsActive() was replaced with <xref
+          linkend="IGuest__additionsRunLevel"
+          xreflabel="additionsRunLevel()" /> and <xref
+          linkend="IGuest__getAdditionsStatus"
+          xreflabel="getAdditionsStatus()" /> in order to support a more
+          detailed status of the current Guest Additions loading/readiness
+          state.</para>
+        </listitem>
+
+        <listitem>
+          <para>To address shared folders auto-mounting support, the following
+          APIs were extended to require an additional
+          <computeroutput>automount</computeroutput> parameter: <itemizedlist>
+              <listitem>
+                <para><xref linkend="IVirtualBox__createSharedFolder"
+                xreflabel="IVirtualBox::createSharedFolder()" /></para>
+              </listitem>
+
+              <listitem>
+                <para><xref linkend="IMachine__createSharedFolder"
+                xreflabel="IMachine::createSharedFolder()" /></para>
+              </listitem>
+
+              <listitem>
+                <para><xref linkend="IConsole__createSharedFolder"
+                xreflabel="IConsole::createSharedFolder()" /></para>
+              </listitem>
+            </itemizedlist> Also, a new property named
+          <computeroutput>autoMount</computeroutput> was added to the <xref
+          linkend="ISharedFolder" xreflabel="ISharedFolder" />
+          interface.</para>
+        </listitem>
+
+        <listitem>
+          <para><xref linkend="IMachine__export"
+          xreflabel="IMachine::export()" /> received an extra parameter
+          <computeroutput>location</computeroutput>, which is used to decide
+          for the disk naming.</para>
+        </listitem>
+
+        <listitem>
+          <para><xref linkend="IAppliance__write"
+          xreflabel="IAppliance::write()" /> received an extra parameter
+          <computeroutput>manifest</computeroutput>, which can suppress
+          creating the manifest file on export.</para>
+        </listitem>
+
+        <listitem>
+          <para><xref linkend="IVFSExplorer__entryList"
+          xreflabel="IVFSExplorer::entryList()" /> received two extra
+          parameters <computeroutput>sizes</computeroutput> and
+          <computeroutput>modes</computeroutput>, which contains the sizes (in
+          bytes) and the file access modes (in octal form) of the returned
+          files.</para>
+        </listitem>
+
+        <listitem>
+          <para>The long-deprecated IVirtualBox::createLegacyMachine() API has
+          been removed.</para>
+        </listitem>
+
+        <listitem>
+          <para>ISystemProperties::get/setDefaultHardDiskFolder() have been
+          removed.</para>
+        </listitem>
+
+        <listitem>
+          <para>ISystemProperties::getMaxVDISize() is now <xref
+          linkend="ISystemProperties__getMaxVDSize"
+          xreflabel="ISystemProperties::getMaxVDSize()" /> and the returned
+          unit has changed from megabytes to bytes.</para>
+        </listitem>
+
+        <listitem>
+          <para>A new Java glue layer replacing the previous OOWS JAX-WS
+          bindings was introduced. The new library allows for uniform code
+          targeting both local (COM/XPCOM) and remote (SOAP) transports. Now,
+          instead of <computeroutput>IWebsessionManager</computeroutput>, the
+          new class <computeroutput>VirtualBoxManager</computeroutput> must be
+          used. See <xref linkend="javaapi" xreflabel="Java API chapter" />
+          for details.</para>
+        </listitem>
+      </itemizedlist>
+    </sect1>
+
+    <sect1>
+      <title>Incompatible API changes with version 3.2</title>
+
+      <itemizedlist>
+        <listitem>
+          <para>The following interfaces were renamed for consistency:
+          <itemizedlist>
+              <listitem>
+                <para>IMachine::getCpuProperty() is now <xref
+                linkend="IMachine__getCPUProperty"
+                xreflabel="IMachine::getCPUProperty()" />;</para>
+              </listitem>
+
+              <listitem>
+                <para>IMachine::setCpuProperty() is now <xref
+                linkend="IMachine__setCPUProperty"
+                xreflabel="IMachine::setCPUProperty()" />;</para>
+              </listitem>
+
+              <listitem>
+                <para>IMachine::getCpuIdLeaf() is now <xref
+                linkend="IMachine__getCPUIDLeaf"
+                xreflabel="IMachine::getCPUIDLeaf()" />;</para>
+              </listitem>
+
+              <listitem>
+                <para>IMachine::setCpuIdLeaf() is now <xref
+                linkend="IMachine__setCPUIDLeaf"
+                xreflabel="IMachine::setCPUIDLeaf()" />;</para>
+              </listitem>
+
+              <listitem>
+                <para>IMachine::removeCpuIdLeaf() is now <xref
+                linkend="IMachine__removeCPUIDLeaf"
+                xreflabel="IMachine::removeCPUIDLeaf()" />;</para>
+              </listitem>
+
+              <listitem>
+                <para>IMachine::removeAllCpuIdLeafs() is now <xref
+                linkend="IMachine__removeAllCPUIDLeaves"
+                xreflabel="IMachine::removeAllCPUIDLeaves()" />;</para>
+              </listitem>
+
+              <listitem>
+                <para>the CpuPropertyType enum is now <xref
+                linkend="CPUPropertyType"
+                xreflabel="CPUPropertyType" />.</para>
+              </listitem>
+
+              <listitem>
+                <para>IVirtualBoxCallback::onSnapshotDiscarded() is now
+                IVirtualBoxCallback::onSnapshotDeleted.</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>When creating a VM configuration with <xref
+          linkend="IVirtualBox__createMachine"
+          xreflabel="IVirtualBox::createMachine" />) it is now possible to
+          ignore existing configuration files which would previously have
+          caused a failure. For this the
+          <computeroutput>override</computeroutput> parameter was
+          added.</para>
+        </listitem>
+
+        <listitem>
+          <para>Deleting snapshots via <xref
+          linkend="IConsole__deleteSnapshot"
+          xreflabel="IConsole::deleteSnapshot()" /> is now possible while the
+          associated VM is running in almost all cases. The API is unchanged,
+          but client code that verifies machine states to determine whether
+          snapshots can be deleted may need to be adjusted.</para>
+        </listitem>
+
+        <listitem>
+          <para>The IoBackendType enumeration was replaced with a boolean flag
+          (see <xref linkend="IStorageController__useHostIOCache"
+          xreflabel="IStorageController::useHostIOCache" />).</para>
+        </listitem>
+
+        <listitem>
+          <para>To address multi-monitor support, the following APIs were
+          extended to require an additional
+          <computeroutput>screenId</computeroutput> parameter: <itemizedlist>
+              <listitem>
+                <para><xref linkend="IMachine__querySavedThumbnailSize"
+                xreflabel="IMachine::querySavedThumbnailSize()" /></para>
+              </listitem>
+
+              <listitem>
+                <para><xref linkend="IMachine__readSavedThumbnailToArray"
+                xreflabel="IMachine::readSavedThumbnailToArray()" /></para>
+              </listitem>
+
+              <listitem>
+                <para><xref linkend="IMachine__querySavedScreenshotPNGSize"
+                xreflabel="IMachine::querySavedScreenshotPNGSize()" /></para>
+              </listitem>
+
+              <listitem>
+                <para><xref linkend="IMachine__readSavedScreenshotPNGToArray"
+                xreflabel="IMachine::readSavedScreenshotPNGToArray()" /></para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>The <computeroutput>shape</computeroutput> parameter of
+          IConsoleCallback::onMousePointerShapeChange was changed from a
+          implementation-specific pointer to a safearray, enabling scripting
+          languages to process pointer shapes.</para>
+        </listitem>
+      </itemizedlist>
+    </sect1>
+
+    <sect1>
+      <title>Incompatible API changes with version 3.1</title>
+
+      <itemizedlist>
+        <listitem>
+          <para>Due to the new flexibility in medium attachments that was
+          introduced with version 3.1 (in particular, full flexibility with
+          attaching CD/DVD drives to arbitrary controllers), we seized the
+          opportunity to rework all interfaces dealing with storage media to
+          make the API more flexible as well as logical. The <xref
+          linkend="IStorageController" xreflabel="IStorageController" />,
+          <xref linkend="IMedium" xreflabel="IMedium" />, <xref
+          linkend="IMediumAttachment" xreflabel="IMediumAttachment" /> and,
+          <xref linkend="IMachine" xreflabel="IMachine" /> interfaces were
+          affected the most. Existing code using them to configure storage and
+          media needs to be carefully checked.</para>
+
+          <para>All media (hard disks, floppies and CDs/DVDs) are now
+          uniformly handled through the <xref linkend="IMedium"
+          xreflabel="IMedium" /> interface. The device-specific interfaces
+          (<code>IHardDisk</code>, <code>IDVDImage</code>,
+          <code>IHostDVDDrive</code>, <code>IFloppyImage</code> and
+          <code>IHostFloppyDrive</code>) have been merged into IMedium; CD/DVD
+          and floppy media no longer need special treatment. The device type
+          of a medium determines in which context it can be used. Some
+          functionality was moved to the other storage-related
+          interfaces.</para>
+
+          <para><code>IMachine::attachHardDisk</code> and similar methods have
+          been renamed and generalized to deal with any type of drive and
+          medium. <xref linkend="IMachine__attachDevice"
+          xreflabel="IMachine::attachDevice()" /> is the API method for adding
+          any drive to a storage controller. The floppy and DVD/CD drives are
+          no longer handled specially, and that means you can have more than
+          one of them. As before, drives can only be changed while the VM is
+          powered off. Mounting (or unmounting) removable media at runtime is
+          possible with <xref linkend="IMachine__mountMedium"
+          xreflabel="IMachine::mountMedium()" />.</para>
+
+          <para>Newly created virtual machines have no storage controllers
+          associated with them. Even the IDE Controller needs to be created
+          explicitly. The floppy controller is now visible as a separate
+          controller, with a new storage bus type. For each storage bus type
+          you can query the device types which can be attached, so that it is
+          not necessary to hardcode any attachment rules.</para>
+
+          <para>This required matching changes e.g. in the callback interfaces
+          (the medium specific change notification was replaced by a generic
+          medium change notification) and removing associated enums (e.g.
+          <code>DriveState</code>). In many places the incorrect use of the
+          plural form "media" was replaced by "medium", to improve
+          consistency.</para>
+        </listitem>
+
+        <listitem>
+          <para>Reading the <xref linkend="IMedium__state"
+          xreflabel="IMedium::state" xrefstyle="" /> attribute no longer
+          automatically performs an accessibility check; a new method <xref
+          linkend="IMedium__refreshState"
+          xreflabel="IMedium::refreshState()" /> does this. The attribute only
+          returns the state any more.</para>
+        </listitem>
+
+        <listitem>
+          <para>There were substantial changes related to snapshots, triggered
+          by the "branched snapshots" functionality introduced with version
+          3.1. IConsole::discardSnapshot was renamed to <xref
+          linkend="IConsole__deleteSnapshot"
+          xreflabel="IConsole::deleteSnapshot()" />.
+          IConsole::discardCurrentState and
+          IConsole::discardCurrentSnapshotAndState were removed; corresponding
+          new functionality is in <xref linkend="IConsole__restoreSnapshot"
+          xreflabel="IConsole::restoreSnapshot()" />. Also, when <xref
+          linkend="IConsole__takeSnapshot"
+          xreflabel="IConsole::takeSnapshot()" /> is called on a running
+          virtual machine, a live snapshot will be created. The old behavior
+          was to temporarily pause the virtual machine while creating an
+          online snapshot.</para>
+        </listitem>
+
+        <listitem>
+          <para>The <xref linkend="IVRDPServer" xreflabel="IVRDPServer" />,
+          <xref linkend="IRemoteDisplayInfo" xreflabel="IRemoteDisplayInfo" />
+          and IConsoleCallback interfaces were changed to reflect VRDP server
+          ability to bind to one of available ports from a list of
+          ports.</para>
+
+          <para>The <computeroutput>IVRDPServer::port</computeroutput>
+          attribute has been replaced with <xref linkend="IVRDPServer__ports"
+          xreflabel="IVRDPServer::ports" />, which is a comma-separated list
+          of ports or ranges of ports.</para>
+
+          <para>An <xref linkend="IRemoteDisplayInfo__port"
+          xreflabel="IRemoteDisplayInfo::port" /> attribute has been added for
+          querying the actual port VRDP server listens on.</para>
+
+          <para>An IConsoleCallback::onRemoteDisplayInfoChange() notification
+          callback has been added.</para>
+        </listitem>
+
+        <listitem>
+          <para>The parameter lists for the following functions were
+          modified:<itemizedlist>
+              <listitem>
+                <para><xref linkend="IHost__removeHostOnlyNetworkInterface"
+                xreflabel="IHost::removeHostOnlyNetworkInterface()" /></para>
+              </listitem>
+
+              <listitem>
+                <para><xref linkend="IHost__removeUSBDeviceFilter"
+                xreflabel="IHost::removeUSBDeviceFilter()" /></para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>In the OOWS bindings for JAX-WS, the behavior of structures
+          changed: for one, we implemented natural structures field access so
+          you can just call a "get" method to obtain a field. Secondly,
+          setters in structures were disabled as they have no expected effect
+          and were at best misleading.</para>
+        </listitem>
+      </itemizedlist>
+    </sect1>
+
+    <sect1>
+      <title>Incompatible API changes with version 3.0</title>
+
+      <itemizedlist>
+        <listitem>
+          <para>In the object-oriented web service bindings for JAX-WS, proper
+          inheritance has been introduced for some classes, so explicit
+          casting is no longer needed to call methods from a parent class. In
+          particular, IHardDisk and other classes now properly derive from
+          <xref linkend="IMedium" xreflabel="IMedium" />.</para>
+        </listitem>
+
+        <listitem>
+          <para>All object identifiers (machines, snapshots, disks, etc)
+          switched from GUIDs to strings (now still having string
+          representation of GUIDs inside). As a result, no particular internal
+          structure can be assumed for object identifiers; instead, they
+          should be treated as opaque unique handles. This change mostly
+          affects Java and C++ programs; for other languages, GUIDs are
+          transparently converted to strings.</para>
+        </listitem>
+
+        <listitem>
+          <para>The uses of NULL strings have been changed greatly. All out
+          parameters now use empty strings to signal a null value. For in
+          parameters both the old NULL and empty string is allowed. This
+          change was necessary to support more client bindings, especially
+          using the webservice API. Many of them either have no special NULL
+          value or have trouble dealing with it correctly in the respective
+          library code.</para>
+        </listitem>
+
+        <listitem>
+          <para>Accidentally, the <code>TSBool</code> interface still appeared
+          in 3.0.0, and was removed in 3.0.2. This is an SDK bug, do not use
+          the SDK for VirtualBox 3.0.0 for developing clients.</para>
+        </listitem>
+
+        <listitem>
+          <para>The type of <xref linkend="IVirtualBoxErrorInfo__resultCode"
+          xreflabel="IVirtualBoxErrorInfo::resultCode" /> changed from
+          <computeroutput>result</computeroutput> to
+          <computeroutput>long</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>The parameter list of IVirtualBox::openHardDisk was
+          changed.</para>
+        </listitem>
+
+        <listitem>
+          <para>The method IConsole::discardSavedState was renamed to
+          IConsole::forgetSavedState, and a parameter was added.</para>
+        </listitem>
+
+        <listitem>
+          <para>The method IConsole::powerDownAsync was renamed to <xref
+          linkend="IConsole__powerDown" xreflabel="IConsole::powerDown" />,
+          and the previous method with that name was deleted. So effectively a
+          parameter was added.</para>
+        </listitem>
+
+        <listitem>
+          <para>In the <xref linkend="IFramebuffer"
+          xreflabel="IFramebuffer" /> interface, the following were
+          removed:<itemizedlist>
+              <listitem>
+                <para>the <computeroutput>operationSupported</computeroutput>
+                attribute;</para>
+
+                <para>(as a result, the
+                <computeroutput>FramebufferAccelerationOperation</computeroutput>
+                enum was no longer needed and removed as well);</para>
+              </listitem>
+
+              <listitem>
+                <para>the <computeroutput>solidFill()</computeroutput>
+                method;</para>
+              </listitem>
+
+              <listitem>
+                <para>the <computeroutput>copyScreenBits()</computeroutput>
+                method.</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>In the <xref linkend="IDisplay" xreflabel="IDisplay" />
+          interface, the following were removed:<itemizedlist>
+              <listitem>
+                <para>the
+                <computeroutput>setupInternalFramebuffer()</computeroutput>
+                method;</para>
+              </listitem>
+
+              <listitem>
+                <para>the <computeroutput>lockFramebuffer()</computeroutput>
+                method;</para>
+              </listitem>
+
+              <listitem>
+                <para>the <computeroutput>unlockFramebuffer()</computeroutput>
+                method;</para>
+              </listitem>
+
+              <listitem>
+                <para>the
+                <computeroutput>registerExternalFramebuffer()</computeroutput>
+                method.</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+      </itemizedlist>
+    </sect1>
+
+    <sect1>
+      <title>Incompatible API changes with version 2.2</title>
+
+      <itemizedlist>
+        <listitem>
+          <para>Added explicit version number into JAX-WS Java package names,
+          such as <computeroutput>org.virtualbox_2_2</computeroutput>,
+          allowing connect to multiple VirtualBox clients from single Java
+          application.</para>
+        </listitem>
+
+        <listitem>
+          <para>The interfaces having a "2" suffix attached to them with
+          version 2.1 were renamed again to have that suffix removed. This
+          time around, this change involves only the name, there are no
+          functional differences.</para>
+
+          <para>As a result, IDVDImage2 is now IDVDImage; IHardDisk2 is now
+          IHardDisk; IHardDisk2Attachment is now IHardDiskAttachment.</para>
+
+          <para>Consequentially, all related methods and attributes that had a
+          "2" suffix have been renamed; for example, IMachine::attachHardDisk2
+          now becomes IMachine::attachHardDisk().</para>
+        </listitem>
+
+        <listitem>
+          <para>IVirtualBox::openHardDisk has an extra parameter for opening a
+          disk read/write or read-only.</para>
+        </listitem>
+
+        <listitem>
+          <para>The remaining collections were replaced by more performant
+          safe-arrays. This affects the following collections:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>IGuestOSTypeCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>IHostDVDDriveCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>IHostFloppyDriveCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>IHostUSBDeviceCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>IHostUSBDeviceFilterCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>IProgressCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>ISharedFolderCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>ISnapshotCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>IUSBDeviceCollection</para>
+            </listitem>
+
+            <listitem>
+              <para>IUSBDeviceFilterCollection</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>Since "Host Interface Networking" was renamed to "bridged
+          networking" and host-only networking was introduced, all associated
+          interfaces needed renaming as well. In detail:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>The HostNetworkInterfaceType enum has been renamed to
+              <xref linkend="HostNetworkInterfaceMediumType"
+              xreflabel="HostNetworkInterfaceMediumType" /></para>
+            </listitem>
+
+            <listitem>
+              <para>The IHostNetworkInterface::type attribute has been renamed
+              to <xref linkend="IHostNetworkInterface__mediumType"
+              xreflabel="IHostNetworkInterface::mediumType" /></para>
+            </listitem>
+
+            <listitem>
+              <para>INetworkAdapter::attachToHostInterface() has been renamed
+              to <xref linkend="INetworkAdapter__attachToBridgedInterface"
+              xreflabel="INetworkAdapter::attachToBridgedInterface()" /></para>
+            </listitem>
+
+            <listitem>
+              <para>In the IHost interface, createHostNetworkInterface() has
+              been renamed to <xref
+              linkend="IHost__createHostOnlyNetworkInterface"
+              xreflabel="createHostOnlyNetworkInterface()" /></para>
+            </listitem>
+
+            <listitem>
+              <para>Similarly, removeHostNetworkInterface() has been renamed
+              to <xref linkend="IHost__removeHostOnlyNetworkInterface"
+              xreflabel="removeHostOnlyNetworkInterface()" /></para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </itemizedlist>
+    </sect1>
+
+    <sect1>
+      <title>Incompatible API changes with version 2.1</title>
+
+      <itemizedlist>
+        <listitem>
+          <para>With VirtualBox 2.1, error codes were added to many error
+          infos that give the caller a machine-readable (numeric) feedback in
+          addition to the error string that has always been available. This is
+          an ongoing process, and future versions of this SDK reference will
+          document the error codes for each method call.</para>
+        </listitem>
+
+        <listitem>
+          <para>The hard disk and other media interfaces were completely
+          redesigned. This was necessary to account for the support of VMDK,
+          VHD and other image types; since backwards compatibility had to be
+          broken anyway, we seized the moment to redesign the interfaces in a
+          more logical way.</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>Previously, the old IHardDisk interface had several
+              derivatives called IVirtualDiskImage, IVMDKImage, IVHDImage,
+              IISCSIHardDisk and ICustomHardDisk for the various disk formats
+              supported by VirtualBox. The new IHardDisk2 interface that comes
+              with version 2.1 now supports all hard disk image formats
+              itself.</para>
+            </listitem>
+
+            <listitem>
+              <para>IHardDiskFormat is a new interface to describe the
+              available back-ends for hard disk images (e.g. VDI, VMDK, VHD or
+              iSCSI). The IHardDisk2::format attribute can be used to find out
+              the back-end that is in use for a particular hard disk image.
+              ISystemProperties::hardDiskFormats[] contains a list of all
+              back-ends supported by the system. <xref
+              linkend="ISystemProperties__defaultHardDiskFormat"
+              xreflabel="ISystemProperties::defaultHardDiskFormat" /> contains
+              the default system format.</para>
+            </listitem>
+
+            <listitem>
+              <para>In addition, the new <xref linkend="IMedium"
+              xreflabel="IMedium" /> interface is a generic interface for hard
+              disk, DVD and floppy images that contains the attributes and
+              methods shared between them. It can be considered a parent class
+              of the more specific interfaces for those images, which are now
+              IHardDisk2, IDVDImage2 and IFloppyImage2.</para>
+
+              <para>In each case, the "2" versions of these interfaces replace
+              the earlier versions that did not have the "2" suffix.
+              Previously, the IDVDImage and IFloppyImage interfaces were
+              entirely unrelated to IHardDisk.</para>
+            </listitem>
+
+            <listitem>
+              <para>As a result, all parts of the API that previously
+              referenced IHardDisk, IDVDImage or IFloppyImage or any of the
+              old subclasses are gone and will have replacements that use
+              IHardDisk2, IDVDImage2 and IFloppyImage2; see, for example,
+              IMachine::attachHardDisk2.</para>
+            </listitem>
+
+            <listitem>
+              <para>In particular, the IVirtualBox::hardDisks2 array replaces
+              the earlier IVirtualBox::hardDisks collection.</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para><xref linkend="IGuestOSType" xreflabel="IGuestOSType" /> was
+          extended to group operating systems into families and for 64-bit
+          support.</para>
+        </listitem>
+
+        <listitem>
+          <para>The <xref linkend="IHostNetworkInterface"
+          xreflabel="IHostNetworkInterface" /> interface was completely
+          rewritten to account for the changes in how Host Interface
+          Networking is now implemented in VirtualBox 2.1.</para>
+        </listitem>
+
+        <listitem>
+          <para>The IVirtualBox::machines2[] array replaces the former
+          IVirtualBox::machines collection.</para>
+        </listitem>
+
+        <listitem>
+          <para>Added <xref linkend="IHost__getProcessorFeature"
+          xreflabel="IHost::getProcessorFeature()" /> and <xref
+          linkend="ProcessorFeature" xreflabel="ProcessorFeature" />
+          enumeration.</para>
+        </listitem>
+
+        <listitem>
+          <para>The parameter list for <xref
+          linkend="IVirtualBox__createMachine"
+          xreflabel="IVirtualBox::createMachine()" /> was modified.</para>
+        </listitem>
+
+        <listitem>
+          <para>Added IMachine::pushGuestProperty.</para>
+        </listitem>
+
+        <listitem>
+          <para>New attributes in IMachine: <xref
+          linkend="IMachine__accelerate3DEnabled"
+          xreflabel="accelerate3DEnabled" />, HWVirtExVPIDEnabled, <xref
+          linkend="IMachine__guestPropertyNotificationPatterns"
+          xreflabel="guestPropertyNotificationPatterns" />, <xref
+          linkend="IMachine__CPUCount" xreflabel="CPUCount" />.</para>
+        </listitem>
+
+        <listitem>
+          <para>Added <xref linkend="IConsole__powerUpPaused"
+          xreflabel="IConsole::powerUpPaused()" /> and <xref
+          linkend="IConsole__getGuestEnteredACPIMode"
+          xreflabel="IConsole::getGuestEnteredACPIMode()" />.</para>
+        </listitem>
+
+        <listitem>
+          <para>Removed ResourceUsage enumeration.</para>
+        </listitem>
+      </itemizedlist>
+    </sect1>
+  </chapter>
+</book>
+<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->
Index: trunk/doc/manual/fr_FR/UserManual.xml
===================================================================
--- trunk/doc/manual/fr_FR/UserManual.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/UserManual.xml	(revision 33555)
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<book>
+  <bookinfo>
+    <title>$VBOX_PRODUCT<superscript>®</superscript></title>
+
+    <subtitle>Manuel de l'utilisateur</subtitle>
+
+    <edition>Version
+    $VBOX_VERSION_STRING</edition>
+
+    <corpauthor>$VBOX_VENDOR</corpauthor>
+
+    <address>http://www.virtualbox.org</address>
+
+    <copyright>
+      <year>2004-$VBOX_C_YEAR</year>
+
+      <holder>$VBOX_VENDOR</holder>
+    </copyright>
+  </bookinfo>
+
+  <xi:include href="user_Introduction.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_Installation.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_BasicConcepts.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_GuestAdditions.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_Storage.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_Networking.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_Frontends.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_VBoxManage.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_AdvancedTopics.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_Technical.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_VirtualBoxAPI.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_Troubleshooting.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_KnownIssues.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_ChangeLog.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_ThirdParty.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_PrivacyPolicy.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_Glossary.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+</book>
Index: trunk/doc/manual/fr_FR/user_AdvancedTopics.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_AdvancedTopics.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_AdvancedTopics.xml	(revision 33555)
@@ -0,0 +1,1507 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="AdvancedTopics">
+  <title>Advanced topics</title>
+
+  <sect1 id="vboxconfigdata">
+    <title>VirtualBox configuration data</title>
+
+    <para>For each system user, VirtualBox stores configuration data in the
+    user's home directory, as per the conventions of the host operating
+    system:<itemizedlist>
+        <listitem>
+          <para>On Windows, this is
+          <computeroutput>%HOMEDRIVE%%HOMEPATH%\.VirtualBox</computeroutput>;
+          typically something like <computeroutput>C:\Documents and
+          Settings\Username\.VirtualBox</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>On Mac OS X, this is
+          <computeroutput>$HOME/Library/VirtualBox</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>On Unix-like systems (Linux, Solaris), this is
+          <computeroutput>$HOME/.VirtualBox</computeroutput>.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>VirtualBox creates this configuration directory automatically, if
+    necessary. Optionally, you can supply an alternate configuration directory
+    by setting the
+    <computeroutput><literal>VBOX_USER_HOME</literal></computeroutput>
+    environment variable. You can globally change some of the locations where
+    VirtualBox keeps extra configuration and data by selecting "Global
+    settings" from the "File" menu in the VirtualBox main window. Then, in the
+    window that pops up, click on the "General" tab.</para>
+
+    <para>VirtualBox stores all its global and machine-specific configuration
+    data in XML documents. We intentionally do not document the specifications
+    of these files, as we must reserve the right to modify them in the future.
+    We therefore strongly suggest that you do not edit these files manually.
+    VirtualBox provides complete access to its configuration data through its
+    the <computeroutput>VBoxManage</computeroutput> command line tool (see
+    <xref linkend="vboxmanage" />) and its API (see <xref
+    linkend="VirtualBoxAPI" />).</para>
+
+    <para>The XML files are versioned. When a new settings file is created
+    (e.g. because a new virtual machine is created), VirtualBox automatically
+    uses the settings format of the current VirtualBox version. These files
+    may not be readable if you downgrade to an earlier version of VirtualBox.
+    However, when VirtualBox encounters a settings file from an earlier
+    version (e.g. after upgrading VirtualBox), it attempts to preserve the
+    settings format as much as possible. It will only silently upgrade the
+    settings format if the current settings cannot be expressed in the old
+    format, for example because you enabled a feature that was not present in
+    an earlier version of VirtualBox.<footnote>
+        <para>As an example, before VirtualBox 3.1, it was only possible to
+        enable or disable a single DVD drive in a virtual machine. If it was
+        enabled, then it would always be visible as the secondary master of
+        the IDE controller. With VirtualBox 3.1, DVD drives can be attached to
+        arbitrary slots of arbitrary controllers, so they could be the
+        secondary slave of an IDE controller or in a SATA slot. If you have a
+        machine settings file from an earlier version and upgrade VirtualBox
+        to 3.1 and then move the DVD drive from its default position, this
+        cannot be expressed in the old settings format; the XML machine file
+        would get written in the new format, and a backup file of the old
+        format would be kept.</para>
+      </footnote> In such cases, VirtualBox backs up the old settings file in
+    the virtual machine's configuration directory. If you need to go back to
+    the earlier version of VirtualBox, then you will need to manually copy
+    these backup files back.</para>
+
+    <para>In detail, the following settings files are in use:</para>
+
+    <para><itemizedlist>
+        <listitem>
+          <para>In the configuration directory,
+          <computeroutput>VirtualBox.xml</computeroutput> is the main
+          configuration file. This includes global configuration options and
+          the media and virtual machine registry. The media registry links to
+          all CD/DVD, floppy and disk images that have been added to the
+          Virtual Media Manager. For each registered VM, there is one entry
+          which points to the VM configuration file, also in XML
+          format.</para>
+        </listitem>
+
+        <listitem>
+          <para>Virtual machine settings and files are, by default, saved as
+          XML files in a subdirectory of the
+          <computeroutput>Machines</computeroutput> directory, which
+          VirtualBox creates under the main configuration directory (see
+          above). You can change the location of this main "Machines" folder
+          in the "Global settings" dialog.</para>
+
+          <para>By default, for each virtual machine, VirtualBox uses another
+          subdirectory of the "Machines" directory that carries the same name
+          as the virtual machine. As a result, your virtual machine names must
+          conform to the conventions of your operating system for valid file
+          names. For example, a machine called "Fedora 6" would, by default,
+          have its settings saved in
+          <computeroutput>.VirtualBox/Machines/Fedora 6/Fedora
+          6.xml</computeroutput> (on a Linux or Solaris host).</para>
+
+          <para>If you would like more control over the file names used, you
+          can create the machine using <computeroutput>VBoxManage
+          createvm</computeroutput> with the
+          <computeroutput>--settingsfile</computeroutput> option; see <xref
+          linkend="vboxmanage-createvm" />.</para>
+
+          <para>The virtual machine directory will be renamed if you change
+          the machine name. If you do not wish this to happen, you can create
+          the machine using <computeroutput>VBoxManage
+          createvm</computeroutput> with the
+          <computeroutput>--basefolder</computeroutput> option. In this case,
+          the folder name will never change.</para>
+        </listitem>
+
+        <listitem>
+          <para>VirtualBox keeps snapshots and saved states in another special
+          folder for each virtual machine. By default, this is a subfolder of
+          the virtual machine folder called
+          <computeroutput>Snapshots</computeroutput> -- in our example,
+          <computeroutput>.VirtualBox/Machines/Fedora
+          6/Snapshots</computeroutput>. You can change this setting for each
+          machine using <computeroutput>VBoxManage</computeroutput> as
+          well.</para>
+        </listitem>
+
+        <listitem>
+          <para>VDI container files are, by default, created in the
+          <computeroutput>HardDisks</computeroutput> directory under the main
+          configuration directory (see above). In particular, this directory
+          is used when the "Create new virtual disk" wizard is started to
+          create a new VDI file. Changing this default is probably most useful
+          if the disk containing your home directory does not have enough room
+          to hold your VDI files, which can grow very large.</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+
+  <sect1 id="vboxsdl">
+    <title>VBoxSDL, the simplified VM displayer</title>
+
+    <sect2>
+      <title>Introduction</title>
+
+      <para>VBoxSDL is a simple graphical user interface (GUI) that lacks the
+      nice point-and-click support which VirtualBox, our main GUI, provides.
+      VBoxSDL is currently primarily used internally for debugging VirtualBox
+      and therefore not officially supported. Still, you may find it useful
+      for environments where the virtual machines are not necessarily
+      controlled by the same person that uses the virtual machine.<note>
+          <para>VBoxSDL is not available on the Mac OS X host platform.</para>
+        </note></para>
+
+      <para>As you can see in the following screenshot, VBoxSDL does indeed
+      only provide a simple window that contains only the "pure" virtual
+      machine, without menus or other controls to click upon and no additional
+      indicators of virtual machine activity:</para>
+
+      <para><mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/vbox-sdl.png"
+                       width="10cm" />
+          </imageobject>
+        </mediaobject></para>
+
+      <para>To start a virtual machine with VBoxSDL instead of the VirtualBox
+      GUI, enter the following on a command line:<screen>VBoxSDL --startvm &lt;vm&gt;</screen></para>
+
+      <para>where <computeroutput>&lt;vm&gt;</computeroutput> is, as usual
+      with VirtualBox command line parameters, the name or UUID of an existing
+      virtual machine.</para>
+    </sect2>
+
+    <sect2>
+      <title>Secure labeling with VBoxSDL</title>
+
+      <para>When running guest operating systems in fullscreen mode, the guest
+      operating system usually has control over the whole screen. This could
+      present a security risk as the guest operating system might fool the
+      user into thinking that it is either a different system (which might
+      have a higher security level) or it might present messages on the screen
+      that appear to stem from the host operating system.</para>
+
+      <para>In order to protect the user against the above mentioned security
+      risks, the secure labeling feature has been developed. Secure labeling
+      is currently available only for VBoxSDL. When enabled, a portion of the
+      display area is reserved for a label in which a user defined message is
+      displayed. The label height in set to 20 pixels in VBoxSDL. The label
+      font color and background color can be optionally set as hexadecimal RGB
+      color values. The following syntax is used to enable secure
+      labeling:</para>
+
+      <screen>VBoxSDL --startvm "VM name"
+      --securelabel --seclabelfnt ~/fonts/arial.ttf
+      --seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF</screen>
+
+      <para>In addition to enabling secure labeling, a TrueType font has to be
+      supplied. To use another font size than 12 point use the parameter
+      <computeroutput>--seclabelsiz</computeroutput>.</para>
+
+      <para>The label text can be set with <screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>
+      Changing this label will take effect immediately.</para>
+
+      <para>Typically, full screen resolutions are limited to certain
+      "standard" geometries such as 1024 x 768. Increasing this by twenty
+      lines is not usually feasible, so in most cases, VBoxSDL will chose the
+      next higher resolution, e.g. 1280 x 1024 and the guest's screen will not
+      cover the whole display surface. If VBoxSDL is unable to choose a higher
+      resolution, the secure label will be painted on top of the guest's
+      screen surface. In order to address the problem of the bottom part of
+      the guest screen being hidden, VBoxSDL can provide custom video modes to
+      the guest that are reduced by the height of the label. For Windows
+      guests and recent Solaris and Linux guests, the VirtualBox Guest
+      Additions automatically provide the reduced video modes. Additionally,
+      the VESA BIOS has been adjusted to duplicate its standard mode table
+      with adjusted resolutions. The adjusted mode IDs can be calculated using
+      the following formula:</para>
+
+      <screen>reduced_modeid = modeid + 0x30</screen>
+
+      <para>For example, in order to start Linux with 1024 x 748 x 16, the
+      standard mode 0x117 (1024 x 768 x 16) is used as a base. The Linux video
+      mode kernel parameter can then be calculated using:</para>
+
+      <screen>vga = 0x200 | 0x117 + 0x30
+vga = 839</screen>
+
+      <para>The reason for duplicating the standard modes instead of only
+      supplying the adjusted modes is that most guest operating systems
+      require the standard VESA modes to be fixed and refuse to start with
+      different modes.</para>
+
+      <para>When using the X.org VESA driver, custom modelines have to be
+      calculated and added to the configuration (usually in
+      <literal>/etc/X11/xorg.conf</literal>. A handy tool to determine
+      modeline entries can be found at <literal><ulink
+      url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink></literal>.)</para>
+    </sect2>
+
+    <sect2>
+      <title>Releasing modifiers with VBoxSDL on Linux</title>
+
+      <para>When switching from a X virtual terminal (VT) to another VT using
+      Ctrl-Alt-Fx while the VBoxSDL window has the input focus, the guest will
+      receive Ctrl and Alt keypress events without receiving the corresponding
+      key release events. This is an architectural limitation of Linux. In
+      order to reset the modifier keys, it is possible to send
+      <computeroutput>SIGUSR1</computeroutput> to the VBoxSDL main thread
+      (first entry in the <computeroutput>ps</computeroutput> list). For
+      example, when switching away to another VT and saving the virtual
+      machine from this terminal, the following sequence can be used to make
+      sure the VM is not saved with stuck modifiers:</para>
+
+      <para><screen>kill -usr1 &lt;pid&gt;
+VBoxManage controlvm "Windows 2000" savestate</screen></para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title id="autologon">Automated guest logons</title>
+
+    <para>VirtualBox provides Guest Addition modules for Windows, Linux and
+    Solaris to enable automated logons on the guest.</para>
+
+    <para>When a guest operating system is running in a virtual machine, it
+    might be desirable to perform coordinated and automated logons using
+    credentials from a master logon system. (With "credentials", we are
+    referring to logon information consisting of user name, password and
+    domain name, where each value might be empty.)</para>
+
+    <sect2 id="autologon_win">
+      <title>Automated Windows guest logons</title>
+
+      <para>Since Windows NT, Windows has provided a modular system logon
+      subsystem ("Winlogon") which can be customized and extended by means of
+      so-called GINA modules (Graphical Identification and Authentication).
+      With Windows Vista and Windows 7, the GINA modules were replaced with a
+      new mechanism called "credential providers". The VirtualBox Guest
+      Additions for Windows come with both, a GINA and a credential provider
+      module, and therefore enable any Windows guest to perform automated
+      logons.</para>
+
+      <para>To activate the VirtualBox GINA or credential provider module,
+      install the Guest Additions with using the command line switch
+      <computeroutput>/with_autologon</computeroutput>. All the following
+      manual steps required for installing these modules will be then done by
+      the installer.</para>
+
+      <para>To manually install the VirtualBox GINA module, extract the Guest
+      Additions (see <xref linkend="windows-guest-file-extraction" />) and
+      copy the file <computeroutput>VBoxGINA.dll</computeroutput> to the
+      Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, in
+      the registry, create the following key: <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
+      with a value of <computeroutput>VBoxGINA.dll</computeroutput>.</para>
+
+      <para><note>
+          The VirtualBox GINA is implemented as a wrapper around the standard Windows
+          GINA (<computeroutput>MSGINA.DLL</computeroutput>),
+          therefore it will most likely not work correctly with 3rd party GINA modules. 
+        </note></para>
+
+      <para>To manually install the VirtualBox credential module, extract the
+      Guest Additions (see <xref linkend="windows-guest-file-extraction" />)
+      and copy the file <computeroutput>VBoxCredProv.dll</computeroutput> to
+      the Windows <computeroutput>SYSTEM32</computeroutput> directory. Then,
+      in the registry, create the following keys:<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
+           Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
+
+HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
+
+HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen></para>
+
+      <para>with all default values (the key named
+      <computeroutput>(Default)</computeroutput> in each key) set to
+      <computeroutput>VBoxCredProv</computeroutput>. After that a new string
+      named <screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
+      with a value of <computeroutput>Apartment</computeroutput> has to be
+      created.</para>
+
+      <para>To set credentials, use the following command on a
+      <emphasis>running</emphasis> VM:</para>
+
+      <screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>
+
+      <para>While the VM is running, the credentials can be queried by the
+      VirtualBox logon modules (GINA or credential provider) using the
+      VirtualBox Guest Additions device driver. When Windows is in "logged
+      out" mode, the logon modules will constantly poll for credentials and if
+      they are present, a logon will be attempted. After retrieving the
+      credentials, the logon modules will erase them so that the above command
+      will have to be repeated for subsequent logons.</para>
+
+      <para>For security reasons, credentials are not stored in any persistent
+      manner and will be lost when the VM is reset. Also, the credentials are
+      "write-only", i.e. there is no way to retrieve the credentials from the
+      host side. Credentials can be reset from the host side by setting empty
+      values.</para>
+
+      <para>Depending on the particular variant of the Windows guest, the
+      following restrictions apply: <orderedlist>
+          <listitem>
+            <para>For <emphasis role="bold">Windows XP guests,</emphasis> the
+            logon subsystem needs to be configured to use the classic logon
+            dialog as the VirtualBox GINA module does not support the XP-style
+            welcome dialog.</para>
+          </listitem>
+
+          <listitem>
+            <para>For <emphasis role="bold">Windows Vista and Windows 7
+            guests,</emphasis> the logon subsystem does not support the
+            so-called Secure Attention Sequence
+            (<computeroutput>CTRL+ALT+DEL</computeroutput>). As a result, the
+            guest's group policy settings need to be changed to not use the
+            Secure Attention Sequence. Also, the user name given is only
+            compared to the true user name, not the user friendly name. This
+            means that when you rename a user, you still have to supply the
+            original user name (internally, Windows never renames user
+            accounts).</para>
+          </listitem>
+        </orderedlist></para>
+
+      <para>The following command forces VirtualBox to keep the credentials
+      after they were read by the guest and on VM reset: <screen>VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>Note
+      that this is a potential security risk as a malicious application
+      running on the guest could request this information using the proper
+      interface.</para>
+    </sect2>
+
+    <sect2 id="autologon_unix">
+      <title>Automated Linux/Unix guest logons</title>
+
+      <para>Starting with version 3.2, VirtualBox provides a custom PAM module
+      (Pluggable Authentication Module) which can be used to perform automated
+      guest logons on platforms which support this framework. Virtually all
+      modern Linux/Unix distributions rely on PAM.</para>
+
+      <para>The <computeroutput>pam_vbox.so</computeroutput> module itself
+      <emphasis role="bold">does not</emphasis> do an actual verification of
+      the credentials passed to the guest OS; instead it relies on other
+      modules such as <computeroutput>pam_unix.so</computeroutput> or
+      <computeroutput>pam_unix2.so</computeroutput> down in the PAM stack to
+      do the actual validation using the credentials retrieved by
+      <computeroutput>pam_vbox.so</computeroutput>. Therefore
+      <computeroutput>pam_vbox.so</computeroutput> has to be on top of the
+      authentication PAM service list.</para>
+
+      <note>
+        <para>The <computeroutput>pam_vbox.so</computeroutput> only supports
+        the <computeroutput>auth</computeroutput> primitive. Other primitives
+        such as <computeroutput>account</computeroutput>,
+        <computeroutput>session</computeroutput> or
+        <computeroutput>password</computeroutput> are not supported.</para>
+      </note>
+
+      <para>The <computeroutput>pam_vbox.so</computeroutput> module is shipped
+      as part of the Guest Additions but it is not installed and/or activated
+      on the guest OS by default. In order to install it, it has to be copied
+      from
+      <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/lib/VBoxGuestAdditions/</computeroutput>
+      to the security modules directory, usually
+      <computeroutput>/lib/security/</computeroutput>. Please refer to your
+      guest OS documentation for the correct PAM module directory.</para>
+
+      <para>For example, to use <computeroutput>pam_vbox.so</computeroutput>
+      with a Ubuntu Linux guest OS and GDM (the GNOME Desktop Manager) to
+      logon users automatically with the credentials passed by the host, the
+      guest OS has to be configured like the following:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>The <computeroutput>pam_vbox.so</computeroutput> module has to
+          be copied to the security modules directory, in this case it is
+          <computeroutput>/lib/security</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>Edit the PAM configuration file for GDM found at
+          <computeroutput>/etc/pam.d/gdm</computeroutput>, adding the line
+          <computeroutput>auth requisite pam_vbox.so</computeroutput> at the
+          top. Additionaly, in most Linux distributions there is a file called
+          <computeroutput>/etc/pam.d/common-auth</computeroutput>. This file
+          is included in many other services (like the GDM file mentioned
+          above). There you also have to add add the line <computeroutput>auth
+          requisite pam_vbox.so</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>If authentication against the shadow database using
+          <computeroutput>pam_unix.so</computeroutput> or
+          <computeroutput>pam_unix2.so</computeroutput> is desired, the
+          argument <computeroutput>try_first_pass</computeroutput> is needed
+          in order to pass the credentials from the VirtualBox module to the
+          shadow database authentication module. For Ubuntu, this needs to be
+          added to <computeroutput>/etc/pam.d/common-auth</computeroutput>, to
+          the end of the line referencing
+          <computeroutput>pam_unix.so</computeroutput>. This argument tells
+          the PAM module to use credentials already present in the stack, i.e.
+          the ones provided by the VirtualBox PAM module.</para>
+        </listitem>
+      </orderedlist>
+
+      <para><warning>
+          <para>An incorrectly configured PAM stack can effectively prevent
+          you from logging into your guest system!</para>
+        </warning></para>
+
+      <para>To make deployment easier, you can pass the argument
+      <computeroutput>debug</computeroutput> right after the
+      <computeroutput>pam_vbox.so</computeroutput> statement. Debug log output
+      will then be recorded using syslog.</para>
+
+      <para><warning>
+          <para>At present, the GDM display manager only retrieves credentials
+          at startup so unless the credentials have been supplied to the guest
+          before GDM starts, automatic logon will not work. This limitation
+          needs to be addressed by the GDM developers or another display
+          manager must be used.</para>
+        </warning></para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Advanced configuration for Windows guests</title>
+
+    <sect2 id="sysprep">
+      <title>Automated Windows system preparation</title>
+
+      <para>Beginning with Windows NT 4.0, Microsoft offers a "system
+      preparation" tool (in short: Sysprep) to prepare a Windows system for
+      deployment or redistribution. Whereas Windows 2000 and XP ship with
+      Sysprep on the installation medium, the tool also is available for
+      download on the Microsoft web site. In a standard installation of
+      Windows Vista and 7, Sysprep is already included. Sysprep mainly
+      consists of an executable called
+      <computeroutput>sysprep.exe</computeroutput> which is invoked by the
+      user to put the Windows installation into preparation mode.</para>
+
+      <para>Starting with VirtualBox 3.2.2, the Guest Additions offer a way to
+      launch a system preparation on the guest operating system in an
+      automated way, controlled from the host system. To achieve that, see
+      <xref linkend="guestadd-guestcontrol" /> for using the feature with the
+      special identifier <computeroutput>sysprep</computeroutput> as the
+      program to execute, along with the user name
+      <computeroutput>sysprep</computeroutput> and password
+      <computeroutput>sysprep</computeroutput> for the credentials. Sysprep
+      then gets launched with the required system rights.</para>
+
+      <note>
+        <para>Specifying the location of "sysprep.exe" is <emphasis
+        role="bold">not possible</emphasis> -- instead the following paths are
+        used (based on the operating system): <itemizedlist>
+            <listitem>
+              <para><computeroutput>C:\sysprep\sysprep.exe</computeroutput>
+              for Windows NT 4.0, 2000 and XP</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput>
+              for Windows Vista, 2008 Server and 7</para>
+            </listitem>
+          </itemizedlist> The Guest Additions will automatically use the
+        appropriate path to execute the system preparation tool.</para>
+      </note>
+    </sect2>
+  </sect1>
+
+  <sect1 id="cpuhotplug">
+    <title>CPU hot-plugging</title>
+
+    <para>With virtual machines running modern server operating systems,
+    VirtualBox supports CPU hot-plugging.<footnote>
+        <para>Support for CPU hot-plugging was introduced with VirtualBox
+        3.2.</para>
+      </footnote> Whereas on a physical computer this would mean that a CPU
+    can be added or removed while the machine is running, VirtualBox supports
+    adding and removing virtual CPUs while a virtual machine is
+    running.</para>
+
+    <para>CPU hot-plugging works only with guest operating systems that
+    support it. So far this applies only to Linux and Windows Server 2008 x64
+    Data Center Edition. Windows supports only hot-add while Linux supports
+    hot-add and hot-remove but to use this feature with more than 8 CPUs a
+    64bit Linux guest is required.</para>
+
+    <para>At this time, CPU hot-plugging requires using the VBoxManage
+    command-line interface. First, hot-plugging needs to be enabled for a
+    virtual machine:<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen></para>
+
+    <para>After that, the --cpus option specifies the maximum number of CPUs
+    that the virtual machine can have:<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>When
+    the VM is off, you can then add and remove virtual CPUs with the modifyvm
+    --plugcpu and --unplugcpu subcommands, which take the number of the
+    virtual CPU as a parameter, like this:<screen>VBoxManage modifyvm "VM name" --plugcpu 3
+VBoxManage modifyvm "VM name" --unplugcpu 3</screen>Note that CPU 0 can never
+    be removed.</para>
+
+    <para>While the VM is running, CPUs can be added with the
+    <computeroutput>controlvm plugcpu/unplugcpu</computeroutput> commands
+    instead:<screen>VBoxManage controlvm "VM name" plugcpu 3
+VBoxManage controlvm "VM name" unplugcpu 3</screen></para>
+
+    <para>See <xref linkend="vboxmanage-modifyvm" /> and <xref
+    linkend="vboxmanage-controlvm" /> for details.</para>
+
+    <para>With Linux guests, the following applies: To prevent ejection while
+    the CPU is still used it has to be ejected from within the guest before.
+    The Linux Guest Additions contain a service which receives hot-remove
+    events and ejects the CPU. Also, after a CPU is added to the VM it is not
+    automatically used by Linux. The Linux Guest Additions service will take
+    care of that if installed. If not a CPU can be started with the following
+    command:<screen>echo 1 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/online</screen></para>
+  </sect1>
+
+  <sect1>
+    <title>Advanced display configuration</title>
+
+    <sect2>
+      <title>Custom VESA resolutions</title>
+
+      <para>Apart from the standard VESA resolutions, the VirtualBox VESA BIOS
+      allows you to add up to 16 custom video modes which will be reported to
+      the guest operating system. When using Windows guests with the
+      VirtualBox Guest Additions, a custom graphics driver will be used
+      instead of the fallback VESA solution so this information does not
+      apply.</para>
+
+      <para>Additional video modes can be configured for each VM using the
+      extra data facility. The extra data key is called
+      <literal>CustomVideoMode&lt;x&gt;</literal> with <literal>x</literal>
+      being a number from 1 to 16. Please note that modes will be read from 1
+      until either the following number is not defined or 16 is reached. The
+      following example adds a video mode that corresponds to the native
+      display resolution of many notebook computers:</para>
+
+      <screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>
+
+      <para>The VESA mode IDs for custom video modes start at
+      <literal>0x160</literal>. In order to use the above defined custom video
+      mode, the following command line has be supplied to Linux:</para>
+
+      <screen>vga = 0x200 | 0x160
+vga = 864</screen>
+
+      <para>For guest operating systems with VirtualBox Guest Additions, a
+      custom video mode can be set using the video mode hint feature.</para>
+    </sect2>
+
+    <sect2>
+      <title>Configuring the maximum resolution of guests when using the
+      graphical frontend</title>
+
+      <para>When guest systems with the Guest Additions installed are started
+      using the graphical frontend (the normal VirtualBox application), they
+      will not be allowed to use screen resolutions greater than the host's
+      screen size unless the user manually resizes them by dragging the
+      window, switching to fullscreen or seamless mode or sending a video mode
+      hint using VBoxManage. This behavior is what most users will want, but
+      if you have different needs, it is possible to change it by issuing one
+      of the following commands from the command line:</para>
+
+      <screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>
+
+      <para>will remove all limits on guest resolutions.</para>
+
+      <screen>VBoxManage setextradata global GUI/MaxGuestResolution &gt;width,height&lt;</screen>
+
+      <para>manually specifies a maximum resolution.</para>
+
+      <screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>
+
+      <para>restores the default settings. Note that these settings apply
+      globally to all guest systems, not just to a single machine.</para>
+    </sect2>
+
+    <sect2 id="vbox-authenticate-sdk">
+      <title>Custom external authentication modules</title>
+
+      <para>As described in <xref linkend="vbox-auth" />, VirtualBox supports
+      arbitrary external modules to perform authentication. When the
+      authentication method is set to "external" for a
+      particular VM, VirtualBox calls the library that was specified with
+      <computeroutput>VBoxManage setproperty vrdeauthlibrary</computeroutput>.
+      This library will be loaded by the VM process on demand, i.e. when the
+      first RDP connection is made by an external client.</para>
+
+      <para>External authentication is the most flexible as the external
+      handler can both choose to grant access to everyone (like the "null"
+      authentication method would) and delegate the request to the guest
+      authentication component. When delegating the request to the guest
+      component, it will still be called afterwards with the option to
+      override the result.</para>
+
+      <para>An authentication library is required to implement exactly one
+      entry point:</para>
+
+      <screen>#include "VRDPAuth.h"
+
+/**
+ * Authentication library entry point. Decides whether to allow
+ * a client connection.
+ *
+ * Parameters:
+ *
+ *   pUuid            Pointer to the UUID of the virtual machine
+ *                    which the client connected to.
+ *   guestJudgement   Result of the guest authentication.
+ *   szUser           User name passed in by the client (UTF8).
+ *   szPassword       Password passed in by the client (UTF8).
+ *   szDomain         Domain passed in by the client (UTF8).
+ *   fLogon           Boolean flag. Indicates whether the entry point is called
+ *                    for a client logon or the client disconnect.
+ *   clientId         Server side unique identifier of the client.
+ *
+ * Return code:
+ *
+ *   VRDPAuthAccessDenied    Client access has been denied.
+ *   VRDPAuthAccessGranted   Client has the right to use the
+ *                           virtual machine.
+ *   VRDPAuthDelegateToGuest Guest operating system must
+ *                           authenticate the client and the
+ *                           library must be called again with
+ *                           the result of the guest
+ *                           authentication.
+ */
+VRDPAuthResult VRDPAUTHCALL VRDPAuth2(
+    PVRDPAUTHUUID pUuid,
+    VRDPAuthGuestJudgement guestJudgement,
+    const char *szUser,
+    const char *szPassword
+    const char *szDomain
+    int fLogon,
+    unsigned clientId)
+{
+    /* process request against your authentication source of choice */
+    return VRDPAuthAccessGranted;
+}</screen>
+
+      <para>A note regarding the UUID implementation of the first argument:
+      VirtualBox uses a consistent binary representation of UUIDs on all
+      platforms. For this reason the integer fields comprising the UUID are
+      stored as little endian values. If you want to pass such UUIDs to code
+      which assumes that the integer fields are big endian (often also called
+      network byte order), you need to adjust the contents of the UUID to e.g.
+      achieve the same string representation. The required changes
+      are:<itemizedlist>
+          <listitem>
+            <para>reverse the order of byte 0, 1, 2 and 3</para>
+          </listitem>
+
+          <listitem>
+            <para>reverse the order of byte 4 and 5</para>
+          </listitem>
+
+          <listitem>
+            <para>reverse the order of byte 6 and 7.</para>
+          </listitem>
+        </itemizedlist>Using this conversion you will get identical results
+      when converting the binary UUID to the string representation.</para>
+
+      <para>The second arguments contains information about the guest
+      authentication status. For the first call, it is always set to
+      <computeroutput>VRDPAuthGuestNotAsked</computeroutput>. In case the
+      function returns
+      <computeroutput>VRDPAuthDelegateToGuest</computeroutput>, a guest
+      authentication will be attempted and another call to the method is made
+      with its result. This can be either granted / denied or no judgement
+      (the guest component chose for whatever reason to not make a decision).
+      In case there is a problem with the guest authentication module (e.g.
+      the Additions are not installed or not running or the guest did not
+      respond within a timeout), the "not reacted" status will be
+      returned.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Advanced storage configuration</title>
+
+    <sect2 id="rawdisk">
+      <title>Using a raw host hard disk from a guest</title>
+
+      <para>Starting with version 1.4, as an alternative to using virtual disk
+      images (as described in detail in <xref linkend="storage" />),
+      VirtualBox can also present either entire physical hard disks or
+      selected partitions thereof as virtual disks to virtual machines.</para>
+
+      <para>With VirtualBox, this type of access is called "raw hard disk
+      access"; it allows a guest operating system to access its virtual hard
+      disk without going through the host OS file system. The actual
+      performance difference for image files vs. raw disk varies greatly
+      depending on the overhead of the host file system, whether dynamically
+      growing images are used and on host OS caching strategies. The caching
+      indirectly also affects other aspects such as failure behavior, i.e.
+      whether the virtual disk contains all data written before a host OS
+      crash. Consult your host OS documentation for details on this.</para>
+
+      <para><warning>
+          <para>Raw hard disk access is for expert users only. Incorrect use
+          or use of an outdated configuration can lead to <emphasis
+          role="bold">total loss of data </emphasis>on the physical disk. Most
+          importantly, <emphasis>do not</emphasis> attempt to boot the
+          partition with the currently running host operating system in a
+          guest. This will lead to severe data corruption.</para>
+        </warning></para>
+
+      <para>Raw hard disk access -- both for entire disks and individual
+      partitions -- is implemented as part of the VMDK image format support.
+      As a result, you will need to create a special VMDK image file which
+      defines where the data will be stored. After creating such a special
+      VMDK image, you can use it like a regular virtual disk image. For
+      example, you can use the Virtual Media Manager (<xref linkend="vdis" />)
+      or <computeroutput>VBoxManage</computeroutput> to assign the image to a
+      virtual machine.</para>
+
+      <sect3>
+        <title>Access to entire physical hard disk</title>
+
+        <para>While this variant is the simplest to set up, you must be aware
+        that this will give a guest operating system direct and full access to
+        an <emphasis>entire physical disk</emphasis>. If your
+        <emphasis>host</emphasis> operating system is also booted from this
+        disk, please take special care to not access the partition from the
+        guest at all. On the positive side, the physical disk can be
+        repartitioned in arbitrary ways without having to recreate the image
+        file that gives access to the raw disk.</para>
+
+        <para>To create an image that represents an entire physical hard disk
+        (which will not contain any actual data, as this will all be stored on
+        the physical disk), on a Linux host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda</screen>This creates the image
+        <code>/path/to/file.vmdk</code> (must be absolute), and all data will
+        be read and written from <code>/dev/sda</code>.</para>
+
+        <para>On a Windows host, instead of the above device specification,
+        use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
+        of the above device specification use e.g. <code>/dev/disk1</code>.
+        Note that on OS X you can only get access to an entire disk if no
+        volume is mounted from it.</para>
+
+        <para>Creating the image requires read/write access for the given
+        device. Read/write access is also later needed when using the image
+        from a virtual machine.</para>
+
+        <para>Just like with regular disk images, this does not automatically
+        register the newly created image in the internal registry of hard
+        disks. If you want this done automatically, add
+        <code>-register</code>: <screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda -register</screen>After registering, you can assign
+        the newly created image to a virtual machine with e.g. <screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
+      --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>When
+        this is done the selected virtual machine will boot from the specified
+        physical disk.</para>
+      </sect3>
+
+      <sect3>
+        <title>Access to individual physical hard disk partitions</title>
+
+        <para>This "raw partition support" is quite similar to the "full hard
+        disk" access described above. However, in this case, any partitioning
+        information will be stored inside the VMDK image, so you can e.g.
+        install a different boot loader in the virtual hard disk without
+        affecting the host's partitioning information. While the guest will be
+        able to <emphasis>see</emphasis> all partitions that exist on the
+        physical disk, access will be filtered in that reading from partitions
+        for which no access is allowed the partitions will only yield zeroes,
+        and all writes to them are ignored.</para>
+
+        <para>To create a special image for raw partition support (which will
+        contain a small amount of data, as already mentioned), on a Linux
+        host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda -partitions 1,5</screen></para>
+
+        <para>As you can see, the command is identical to the one for "full
+        hard disk" access, except for the additional
+        <computeroutput>-partitions</computeroutput> parameter. This example
+        would create the image <code>/path/to/file.vmdk</code> (which, again,
+        must be absolute), and partitions 1 and 5 of <code>/dev/sda</code>
+        would be made accessible to the guest.</para>
+
+        <para>VirtualBox uses the same partition numbering as your Linux host.
+        As a result, the numbers given in the above example would refer to the
+        first primary partition and the first logical drive in the extended
+        partition, respectively.</para>
+
+        <para>On a Windows host, instead of the above device specification,
+        use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
+        of the above device specification use e.g. <code>/dev/disk1</code>.
+        Note that on OS X you can only use partitions which are not mounted
+        (eject the respective volume first). Partition numbers are the same on
+        Linux, Windows and Mac OS X hosts.</para>
+
+        <para>The numbers for the list of partitions can be taken from the
+        output of<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>The
+        output lists the partition types and sizes to give the user enough
+        information to identify the partitions necessary for the guest.</para>
+
+        <para>Images which give access to individual partitions are specific
+        to a particular host disk setup. You cannot transfer these images to
+        another host; also, whenever the host partitioning changes, the image
+        <emphasis>must be recreated</emphasis>.</para>
+
+        <para>Creating the image requires read/write access for the given
+        device. Read/write access is also later needed when using the image
+        from a virtual machine. If this is not feasible, there is a special
+        variant for raw partition access (currently only available on Linux
+        hosts) that avoids having to give the current user access to the
+        entire disk. To set up such an image, use<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda -partitions 1,5 -relative</screen>When used from a
+        virtual machine, the image will then refer not to the entire disk, but
+        only to the individual partitions (in the example
+        <code>/dev/sda1</code> and <code>/dev/sda5</code>). As a consequence,
+        read/write access is only required for the affected partitions, not
+        for the entire disk. During creation however, read-only access to the
+        entire disk is required to obtain the partitioning information.</para>
+
+        <para>In some configurations it may be necessary to change the MBR
+        code of the created image, e.g. to replace the Linux boot loader that
+        is used on the host by another boot loader. This allows e.g. the guest
+        to boot directly to Windows, while the host boots Linux from the
+        "same" disk. For this purpose the
+        <computeroutput>-mbr</computeroutput> parameter is provided. It
+        specifies a file name from which to take the MBR code. The partition
+        table is not modified at all, so a MBR file from a system with totally
+        different partitioning can be used. An example of this is<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>The modified
+        MBR will be stored inside the image, not on the host disk.</para>
+
+        <para>For each of the above variants, you can register the resulting
+        image for immediate use in VirtualBox by adding
+        <computeroutput>-register</computeroutput> to the respective command
+        line. The image will then immediately appear in the list of registered
+        disk images. An example is<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda -partitions 1,5 -relative -register</screen> which
+        creates an image referring to individual partitions, and registers it
+        when the image is successfully created.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="changevpd">
+      <title>Configuring the hard disk vendor product data (VPD)</title>
+
+      <para>VirtualBox reports vendor product data for its virtual hard disks
+      which consist of hard disk serial number, firmware revision and model
+      number. These can be changed using the following commands:</para>
+
+      <screen>VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</screen>
+
+      <para>The serial number is a 20 byte alphanumeric string, the firmware
+      revision an 8 byte alphanumeric string and the model number a 40 byte
+      alphanumeric string. Instead of "Port0" (referring to the first port),
+      specify the desired SATA hard disk port.</para>
+
+      <para>Additional three parameters are needed for CD/DVD drives to report
+      the vendor product data:</para>
+
+      <screen>VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</screen>
+
+      <para>The vendor id is an 8 byte alphanumeric string, the product id an
+      16 byte alphanumeric string and the revision a 4 byte alphanumeric
+      string. Instead of "Port0" (referring to the first port), specify the
+      desired SATA hard disk port.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Launching more than 120 VMs on Solaris hosts</title>
+
+    <para>Solaris hosts have a fixed number of IPC semaphores IDs per process
+    preventing users from starting more than 120 VMs. While trying to launch
+    more VMs you would be shown a "Cannot create IPC semaphore" error.</para>
+
+    <para>In order to run more VMs, you will need to bump the semaphore ID
+    limit of the VBoxSVC process. Execute as root the
+    <computeroutput>prctl</computeroutput> command as shown below. The process
+    ID of VBoxSVC can be obtained using the
+    <computeroutput>ps</computeroutput> list command.</para>
+
+    <para><screen>prctl -r -n project.max-sem-ids -v 2048 &lt;pid-of-VBoxSVC&gt;</screen></para>
+  </sect1>
+
+  <sect1>
+    <title>Legacy commands for using serial ports</title>
+
+    <para>Starting with version 1.4, VirtualBox provided support for virtual
+    serial ports, which, at the time, was rather complicated to set up with a
+    sequence of <computeroutput>VBoxManage setextradata</computeroutput>
+    statements. Since version 1.5, that way of setting up serial ports is no
+    longer necessary and <emphasis>deprecated.</emphasis> To set up virtual
+    serial ports, use the methods now described in <xref
+    linkend="serialports" />.<note>
+        <para>For backwards compatibility, the old
+        <computeroutput>setextradata</computeroutput> statements, whose
+        description is retained below from the old version of the manual, take
+        <emphasis>precedence</emphasis> over the new way of configuring serial
+        ports. As a result, if configuring serial ports the new way doesn't
+        work, make sure the VM in question does not have old configuration
+        data such as below still active.</para>
+      </note></para>
+
+    <para>The old sequence of configuring a serial port used the following 6
+      commands:</para><screen>VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/serial/0/Config/IRQ" 4
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/serial/0/Config/IOBase" 0x3f8
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/serial/0/LUN#0/Driver" Char
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Driver" NamedPipe
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/Location" "\\.\pipe\vboxCOM1"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/IsServer" 1</screen>
+    <para>This sets up a serial port in the guest with the default
+    settings for COM1 (IRQ 4, I/O address 0x3f8) and the
+    <computeroutput>Location</computeroutput> setting assumes that this
+    configuration is used on a Windows host, because the Windows named pipe
+    syntax is used. Keep in mind that on Windows hosts a named pipe must
+    always start with <computeroutput>\\.\pipe\</computeroutput>. On Linux the
+    same config settings apply, except that the path name for the
+    <computeroutput>Location</computeroutput> can be chosen more freely. Local
+    domain sockets can be placed anywhere, provided the user running
+    VirtualBox has the permission to create a new file in the directory. The
+    final command above defines that VirtualBox acts as a server, i.e. it
+    creates the named pipe itself instead of connecting to an already existing
+    one.</para>
+  </sect1>
+
+  <sect1 id="changenat">
+    <title>Fine-tuning the VirtualBox NAT engine</title>
+
+    <sect2>
+      <title>Configuring the address of a NAT network interface</title>
+
+      <para>In NAT mode, the guest network interface is assigned to the IPv4
+      range <computeroutput>10.0.x.0/24</computeroutput> by default where
+      <computeroutput>x</computeroutput> corresponds to the instance of the
+      NAT interface +2. So <computeroutput>x</computeroutput> is 2 when there
+      is only one NAT instance active. In that case the guest is assigned to
+      the address <computeroutput>10.0.2.15</computeroutput>, the gateway is
+      set to <computeroutput>10.0.2.2</computeroutput> and the name server can
+      be found at <computeroutput>10.0.2.3</computeroutput>.</para>
+
+      <para>If, for any reason, the NAT network needs to be changed, this can
+      be achieved with the following command:</para>
+
+      <screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen>
+
+      <para>This command would reserve the network addresses from
+      <computeroutput>192.168.0.0</computeroutput> to
+      <computeroutput>192.168.254.254</computeroutput> for the first NAT
+      network instance of "VM name". The guest IP would be assigned to
+      <computeroutput>192.168.0.15</computeroutput> and the default gateway
+      could be found at <computeroutput>192.168.0.2</computeroutput>.</para>
+    </sect2>
+
+    <sect2 id="nat-adv-tftp">
+      <title>Configuring the boot server (next server) of a NAT network
+      interface</title>
+
+      <para>For network booting in NAT mode, by default VirtualBox uses a
+      built-in TFTP server at the IP address 10.0.2.3. This default behavior
+      should work fine for typical remote-booting scenarios. However, it is
+      possible to change the boot server IP and the location of the boot image
+      with the following commands: <screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
+VBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen></para>
+    </sect2>
+
+    <sect2 id="nat-adv-settings">
+      <title>Tuning TCP/IP buffers for NAT</title>
+
+      <para>The VirtualBox NAT stack performance is often determined by its
+      interaction with the host's TCP/IP stack and the size of several buffers
+      (<computeroutput>SO_RCVBUF</computeroutput> and
+      <computeroutput>SO_SNDBUF</computeroutput>). For certain setups users
+      might want to adjust the buffer size for a better performance. This can
+      by achieved using the following commands (values are in kilobytes and
+      can range from 8 to 1024): <screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
+      This example illustrates tuning the NAT settings. The first parameter is
+      the MTU, then the size of the socket's send buffer and the size of the
+      socket's receive buffer, the initial size of the TCP send window, and
+      lastly the initial size of the TCP receive window. Note that specifying
+      zero means fallback to the default value.</para>
+
+      <para>Each of these buffers has a default size of 64KB and default MTU
+      is 1500.</para>
+    </sect2>
+
+    <sect2>
+      <title>Binding NAT sockets to a specific interface</title>
+
+      <para>By default, VirtualBox's NAT engine will route TCP/IP packets
+      through the default interface assigned by the host's TCP/IP stack. (The
+      technical reason for this is that the NAT engine uses sockets for
+      communication.) If, for some reason, you want to change this behavior,
+      you can tell the NAT engine to bind to a particular IP address instead.
+      Use the following command: <screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen></para>
+
+      <para>After this, all outgoing traffic will be sent through the
+      interface with the IP address 10.45.0.2. Please make sure that this
+      interface is up and running prior to this assignment.</para>
+    </sect2>
+
+    <sect2 id="nat-adv-dns">
+      <title>Enabling DNS proxy in NAT mode</title>
+
+      <para>The NAT engine by default offers the same DNS servers to the guest
+      that are configured on the host. In some scenarios, it can be desirable
+      to hide the DNS server IPs from the guest, for example when this
+      information can change on the host due to expiring DHCP leases. In this
+      case, you can tell the NAT engine to act as DNS proxy using the
+      following command: <screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen></para>
+    </sect2>
+
+    <sect2 id="nat_host_resolver_proxy">
+      <title>Using the host's resolver as a DNS proxy in NAT mode</title>
+
+      <para>For resolving network names, the DHCP server of the NAT engine
+      offers a list of registered DNS servers of the host. If for some reason
+      you need to hide this DNS server list and use the host's resolver
+      settings, thereby forcing the VirtualBox NAT engine to intercept DNS
+      requests and forward them to host's resolver, use the following command:
+      <screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
+      Note that this setting is similar to the DNS proxy mode, however whereas
+      the proxy mode just forwards DNS requests to the appropriate servers,
+      the resolver mode will interpret the DNS requests and use the host's DNS
+      API to query the information and return it to the guest.</para>
+    </sect2>
+
+    <sect2 id="nat-adv-alias">
+      <title>Configuring aliasing of the NAT engine</title>
+
+      <para>By default, the NAT core uses aliasing and uses random ports when
+      generating an alias for a connection. This works well for the most
+      protocols like SSH, FTP and so on. Though some protocols might need a
+      more transparent behavior or may depend on the real port number the
+      packet was sent from. It is possible to change the NAT mode via the
+      VBoxManage frontend with the following commands: <screen>VBoxManage modifyvm "VM name" --nataliasmode proxyonly</screen>
+      and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode sameports</screen>
+      The first example disables aliasing and switches NAT into transparent
+      mode, the second example enforces preserving of port values. These modes
+      can be combined if necessary.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="changedmi">
+    <title>Configuring the BIOS DMI information</title>
+
+    <para>The DMI data VirtualBox provides to guests can be changed for a
+    specific VM. Use the following commands to configure the DMI BIOS
+    information:</para>
+
+    <screen>VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor"        "BIOS Vendor"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion"       "BIOS Version"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate"   "BIOS Release Date"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor"  1
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor"  2
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor"      "System Vendor"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct"     "System Product"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion"     "System Version"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "System Serial"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU"         "System SKU"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily"      "System Family"
+VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid"
+                                               "9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
+
+    <para>If a DMI string is not set, the default value of VirtualBox is used.
+    To set an empty string use
+    <computeroutput>"&lt;EMPTY&gt;"</computeroutput>.</para>
+
+    <para>Note that in the above list, all quoted parameters (DmiBIOSVendor,
+    DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be strings. If
+    such a string is a valid number, the parameter is treated as number and
+    the VM will most probably refuse to start with an
+    <computeroutput>VERR_CFGM_NOT_STRING</computeroutput> error. In that case,
+    use <computeroutput>"string:&lt;value&gt;"</computeroutput>, for instance
+    <screen>VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "string:1234"</screen></para>
+
+    <para>Changing this information can be necessary to provide the DMI
+    information of the host to the guest to prevent Windows from asking for a
+    new product key. On Linux hosts the DMI BIOS information can be obtained
+    with <screen>dmidecode -t0</screen>and the DMI system information can be
+    obtained with <screen>dmidecode -t1</screen></para>
+  </sect1>
+
+  <sect1>
+    <title>Fine-tuning timers and time synchronization</title>
+
+    <sect2 id="changetscmode">
+      <title>Configuring the guest time stamp counter (TSC) to reflect guest
+      execution</title>
+
+      <para>By default, VirtualBox keeps all sources of time visible to the
+      guest synchronized to a single time source, the monotonic host time.
+      This reflects the assumptions of many guest operating systems, which
+      expect all time sources to reflect "wall clock" time. In special
+      circumstances it may be useful however to make the TSC (time stamp
+      counter) in the guest reflect the time actually spent executing the
+      guest.</para>
+
+      <para>This special TSC handling mode can be enabled on a per-VM basis,
+      and for best results must be used only in combination with hardware
+      virtualization. To enable this mode use the following command:</para>
+
+      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen>
+
+      <para>To revert to the default TSC handling mode use:</para>
+
+      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen>
+
+      <para>Note that if you use the special TSC handling mode with a guest
+      operating system which is very strict about the consistency of time
+      sources you may get a warning or error message about the timing
+      inconsistency. It may also cause clocks to become unreliable with some
+      guest operating systems depending on they use the TSC.</para>
+    </sect2>
+
+    <sect2 id="warpguest">
+      <title>Accelerate or slow down the guest clock</title>
+
+      <para>For certain purposes it can be useful to accelerate or to slow
+      down the (virtual) guest clock. This can be achieved as follows:</para>
+
+      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen>
+
+      <para>The above example will double the speed of the guest clock
+      while</para>
+
+      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen>
+
+      <para>will halve the speed of the guest clock. Note that changing the
+      rate of the virtual clock can confuse the guest and can even lead to
+      abnormal guest behavior. For instance, a higher clock rate means shorter
+      timeouts for virtual devices with the result that a slightly increased
+      response time of a virtual device due to an increased host load can
+      cause guest failures. Note further that any time synchronization
+      mechanism will frequently try to resynchronize the guest clock with the
+      reference clock (which is the host clock if the VirtualBox Guest
+      Additions are active). Therefore any time synchronization should be
+      disabled if the rate of the guest clock is changed as described above
+      (see <xref linkend="changetimesync" />).</para>
+    </sect2>
+
+    <sect2 id="changetimesync">
+      <title>Tuning the Guest Additions time synchronization
+      parameters</title>
+
+      <para>The VirtualBox Guest Additions ensure that the guest's system time
+      is synchronized with the host time. There are several parameters which
+      can be tuned. The parameters can be set for a specific VM using the
+      following command:</para>
+
+      <screen>VBoxManage guestproperty set VM_NAME "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>
+
+      <para>where <computeroutput>PARAMETER</computeroutput> is one of the
+      following:</para>
+
+      <para><glosslist>
+          <glossentry>
+            <glossterm><computeroutput>--timesync-interval</computeroutput></glossterm>
+
+            <glossdef>
+              <para>Specifies the interval at which to synchronize the time
+              with the host. The default is 10000 ms (10 seconds).</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm><computeroutput>--timesync-min-adjust</computeroutput></glossterm>
+
+            <glossdef>
+              <para>The minimum absolute drift value measured in milliseconds
+              to make adjustments for. The default is 1000 ms on OS/2 and 100
+              ms elsewhere.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm><computeroutput>--timesync-latency-factor</computeroutput></glossterm>
+
+            <glossdef>
+              <para>The factor to multiply the time query latency with to
+              calculate the dynamic minimum adjust time. The default is 8
+              times, that means in detail: Measure the time it takes to
+              determine the host time (the guest has to contact the VM host
+              service which may take some time), multiply this value by 8 and
+              do an adjustment only if the time difference between host and
+              guest is bigger than this value. Don't do any time adjustment
+              otherwise.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm><computeroutput>--timesync-max-latency</computeroutput></glossterm>
+
+            <glossdef>
+              <para>The max host timer query latency to accept. The default is
+              250 ms.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm><computeroutput>--timesync-set-threshold</computeroutput></glossterm>
+
+            <glossdef>
+              <para>The absolute drift threshold, given as milliseconds where
+              to start setting the time instead of trying to smoothly adjust
+              it. The default is 20 minutes.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm><computeroutput>--timesync-set-start</computeroutput></glossterm>
+
+            <glossdef>
+              <para>Set the time when starting the time sync service.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm><computeroutput>--timesync-set-on-restore 0|1</computeroutput></glossterm>
+
+            <glossdef>
+              <para>Set the time after the VM was restored from a saved state
+                when passing 1 as parameter (default). Disable by passing 0.
+                In the latter case, the time will be adjusted smoothly which
+                can take a long time.</para>
+            </glossdef>
+          </glossentry>
+        </glosslist></para>
+
+      <para>All these parameters can be specified as command line parameters
+      to VBoxService as well.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="addhostonlysolaris">
+    <title>Configuring multiple host-only network interfaces on Solaris
+    hosts</title>
+
+    <para>By default VirtualBox provides you with one host-only network
+    interface. Adding more host-only network interfaces on Solaris hosts
+    requires manual configuration. Here's how to add two more host-only
+    network interfaces.</para>
+
+    <para>You first need to stop all running VMs and unplumb all existing
+    "vboxnet" interfaces. Execute the following commands as root:</para>
+
+    <screen>ifconfig vboxnet0 unplumb</screen>
+
+    <para>Once you make sure all vboxnet interfaces are unplumbed, remove the
+    driver using:</para>
+
+    <para><screen>rem_drv vboxnet</screen>then edit the file
+    <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
+    and add a line for the new interfaces:</para>
+
+    <para><screen>name="vboxnet" parent="pseudo" instance=1;
+name="vboxnet" parent="pseudo" instance=2;</screen>Add as many of these lines
+    as required and make sure "instance" number is uniquely incremented. Next
+    reload the vboxnet driver using:</para>
+
+    <para><screen>add_drv vboxnet</screen>Now plumb all the interfaces using
+    <computeroutput>ifconfig vboxnetX plumb</computeroutput> (where X can be
+    0, 1 or 2 in this case) and once plumbed you can then configure the
+    interface like any other network interface.</para>
+
+    <para>To make your newly added interfaces' settings persistent across
+    reboots you will need to edit the files
+    <computeroutput>/etc/netmasks</computeroutput>, and if you are using NWAM
+    <computeroutput>/etc/nwam/llp</computeroutput> and add the appropriate
+    entries to set the netmask and static IP for each of those interfaces. The
+    VirtualBox installer only updates these configuration files for the one
+    "vboxnet0" interface it creates by default.</para>
+  </sect1>
+
+  <sect1 id="solariscodedumper">
+    <title>Configuring VirtualBox CoreDumper on Solaris hosts</title>
+
+    <para>VirtualBox is capable of producing its own core files when things go
+    wrong and for more extensive debugging. Currently this is only available
+    on Solaris hosts.</para>
+
+    <para>The VirtualBox CoreDumper can be enabled using the following
+    command:</para>
+
+    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen></para>
+
+    <para>You can specify which directory to use for core dumps with this
+    command:</para>
+
+    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir &lt;path-to-directory&gt;</screen>Make
+    sure the directory you specify is on a volume with sufficient free space
+    and that the VirtualBox process has sufficient permissions to write files
+    to this directory. If you skip this command and don't specify any core
+    dump directory, the current directory of the VirtualBox executable will be
+    used (which would most likely fail when writing cores as they are
+    protected with root permissions). It is recommended you explicity set a
+    core dump directory.</para>
+
+    <para>You must specify when the VirtualBox CoreDumper should be triggered.
+    This is done using the following commands:</para>
+
+    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
+VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>At
+    least one of the above two commands will have to be provided if you have
+    enabled the VirtualBox CoreDumper.</para>
+
+    <para>Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
+    sets up the VM to override the host's core dumping mechanism and in the
+    event of any crash only the VirtualBox CoreDumper would produce the core
+    file.</para>
+
+    <para>Setting <computeroutput>CoreDumpLive</computeroutput> sets up the VM
+    to produce cores whenever the VM receives a
+    <computeroutput>SIGUSR2</computeroutput> signal. After producing the core
+    file, the VM will not be terminated and will continue to run. You can then
+    take cores of the VM process using:</para>
+
+    <para><screen>kill -s SIGUSR2 &lt;VM-process-id&gt;</screen></para>
+
+    <para>Core files produced by the VirtualBox CoreDumper are of the form
+    <computeroutput>core.vb.&lt;ProcessName&gt;.&lt;ProcessID&gt;</computeroutput>,
+    e.g.<computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para>
+  </sect1>
+
+  <sect1 id="guitweaks">
+    <title>Locking down the GUI</title>
+
+    <para>There are several advanced customization settings for locking down
+    the GUI, that is, removing some features that the user should not
+    see.<screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen></para>
+
+    <para>where <computeroutput>OPTION</computeroutput> is one of the
+    following keywords:<glosslist>
+        <glossentry>
+          <glossterm><computeroutput>noSelector</computeroutput></glossterm>
+
+          <glossdef>
+            <para>Don't allow to start the VM selector GUI. Trying to do so
+            will show a window containing a proper error message.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm><computeroutput>noMenuBar</computeroutput></glossterm>
+
+          <glossdef>
+            <para>The VM windows will not contain a menu bar.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm><computeroutput>noStatusBar</computeroutput></glossterm>
+
+          <glossdef>
+            <para>The VM windows will not contain a status bar.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+
+    <para>To disable any GUI customization do <screen>VBoxManage setextradata global GUI/Customizations</screen></para>
+
+    <para>To disable all host key combinations, open the global settings and
+    change the host key to <emphasis>None</emphasis>. This might be useful
+    when using VirtualBox in a kiosk mode.</para>
+
+    <para>Furthermore, you can disallow certain actions when terminating a VM
+    from the GUI. To disallow specific actions, type:</para>
+
+    <para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para>
+
+    <para>where <computeroutput>OPTION</computeroutput> is one of the
+    following keywords:<glosslist>
+        <glossentry>
+          <glossterm><computeroutput>SaveState</computeroutput></glossterm>
+
+          <glossdef>
+            <para>Don't allow the user to save the VM state plus terminate the
+            VM.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
+
+          <glossdef>
+            <para>Don't allow the user to shutdown the VM by sending the ACPI
+            power off event to the guest.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
+
+          <glossdef>
+            <para>Don't allow the user to power off the VM.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm><computeroutput>Restore</computeroutput></glossterm>
+
+          <glossdef>
+            <para>Don't allow the user to return to the last snapshot when
+            powering off the VM.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+
+    <para>Combinations of all of these options are allowed. If all options are
+    specified, the VM cannot be shut down from the GUI.</para>
+  </sect1>
+
+  <sect1 id="vboxwebsrv-daemon">
+    <title>Starting <computeroutput>vboxwebsrv</computeroutput>
+    automatically</title>
+
+    <para><computeroutput>vboxwebsrv</computeroutput> is used for controlling
+    VirtualBox remotely. As the client base using this interface is growing,
+    we added start scripts for the various operation systems we support. The
+    following describes how to use them. <itemizedlist>
+        <listitem>
+          <para>On Mac OS X, launchd is used. An example configuration file
+          can be found in
+          <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
+          It has to be enabled by changing the
+          <computeroutput>Disabled</computeroutput> key from
+          <computeroutput>true</computeroutput> to
+          <computeroutput>false</computeroutput>. To manually start the
+          service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
+          For additional information on how launchd services could be
+          configured see <literal><ulink
+          url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink></literal>.</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_BasicConcepts.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_BasicConcepts.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_BasicConcepts.xml	(revision 33555)
@@ -0,0 +1,1237 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="BasicConcepts">
+  <title>Configuring virtual machines</title>
+
+  <para>Whereas <xref linkend="Introduction" /> gave you a quick introduction
+  to VirtualBox and how to get your first virtual machine running, the
+  following chapter describe in detail how to configure virtual
+  machines.</para>
+
+  <para>You have considerable latitude in deciding what virtual hardware will
+  be provided to the guest. The virtual hardware can be used for communicating
+  with the host system or with other guests. For instance, if you provide
+  VirtualBox with the image of a CD-ROM in an ISO file, VirtualBox can present
+  this image to a guest system as if it were a physical CD-ROM. Similarly, you
+  can give a guest system access to the real network via its virtual network
+  card, and, if you choose, give the host system, other guests, or computers
+  on the Internet access to the guest system.</para>
+
+  <sect1>
+    <title id="guestossupport">Supported guest operating systems</title>
+
+    <para>Since VirtualBox is designed to provide a generic virtualization
+    environment for x86 systems, it may run operating systems of any kind,
+    even those that are not officially supported by $VBOX_VENDOR. However, our
+    focus is to optimize the product's performance for a select list of guest
+    systems:</para>
+
+    <para><glosslist>
+        <glossentry>
+          <glossterm>Windows NT 4.0</glossterm>
+
+          <glossdef>
+            <para>All versions/editions and service packs are fully supported;
+            however, there are some issues with older service packs. We
+            recommend to install service pack 6a. Guest Additions are
+            available with a limited feature set.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Windows 2000 / XP / Server 2003 / Vista / Server 2008 /
+          Windows 7</glossterm>
+
+          <glossdef>
+            <para>All versions/editions and service packs are fully supported
+            (including 64-bit versions, under the preconditions listed below).
+            Guest Additions are available.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>DOS / Windows 3.x / 95 / 98 / ME</glossterm>
+
+          <glossdef>
+            <para>Limited testing has been performed. Use beyond legacy
+            installation mechanisms not recommended. No Guest Additions
+            available.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Linux 2.4</glossterm>
+
+          <glossdef>
+            <para>Limited support.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Linux 2.6</glossterm>
+
+          <glossdef>
+            <para>All versions/editions are fully supported (32 bits and 64
+            bits). Guest Additions are available.</para>
+
+            <para>We strongly recommend using a Linux kernel version 2.6.13 or
+            higher for better performance.<note>
+                <para>Certain Linux kernel releases have bugs that prevent
+                them from executing in a virtual environment; please see <xref
+                linkend="trouble-linux-buggy" /> for details.</para>
+              </note></para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Solaris 10, OpenSolaris</glossterm>
+
+          <glossdef>
+            <para>Fully supported (32 bits and 64 bits). Guest Additions are
+            available.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>FreeBSD</glossterm>
+
+          <glossdef>
+            <para>Requires hardware virtualization to be enabled. Limited
+            support. Guest Additions are not available yet.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>OpenBSD</glossterm>
+
+          <glossdef>
+            <para>Requires hardware virtualization to be enabled. Versions 3.7
+            and later are supported. Guest Additions are not available
+            yet.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>OS/2 Warp 4.5</glossterm>
+
+          <glossdef>
+            <para>Requires hardware virtualization to be enabled. We
+            officially support MCP2 only; other OS/2 versions may or may not
+            work. Guest Additions are available with a limited feature
+            set.<footnote>
+                <para>See <xref linkend="KnownIssues" />.</para>
+              </footnote></para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Mac OS X Server</glossterm>
+
+          <glossdef>
+            <para>VirtualBox 3.2 added experimental support for Mac OS X
+            Server guests, but this comes with restrictions. Please see the
+            following section as well as <xref
+            linkend="KnownIssues" />.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+
+    <sect2 id="intro-macosxguests">
+      <title>Mac OS X Server guests</title>
+
+      <para>Starting with version 3.2, VirtualBox has experimental support for
+      Mac OS X Server guests. This allows you to install and execute
+      unmodified versions of Mac OS X Server on supported host
+      hardware.</para>
+
+      <para>Whereas competing solutions perform modifications to the Mac OS X
+      Server install DVDs (e.g. different boot loader and replaced files),
+      VirtualBox is the first product to provide the modern PC architecture
+      expected by OS X without requiring any "hacks".</para>
+
+      <para>You should be aware of a number of <emphasis role="bold">important
+      issues</emphasis> before attempting to install a Mac OS X Server
+      guest:<orderedlist>
+          <listitem>
+            <para>Mac OS X is commercial, licensed software and contains both
+            license and technical restrictions that limit its use to certain
+            hardware and usage scenarios. It is important that you understand
+            and obey these restrictions. Only the Mac OS X Server is designed
+            to be used in a virtual environment and therefore, VirtualBox does
+            not support Mac OS X client as a guest.</para>
+
+            <para>As a result, before attempting to install Mac OS X Server in
+            a virtual machine, make sure you understand the <emphasis
+            role="bold">license restrictions</emphasis> of the Mac OS X
+            version you want to use. For most versions of Mac OS X Server,
+            Apple prohibits installing them on non-Apple hardware.</para>
+
+            <para>These license restrictions are also enforced on a technical
+            level: Mac OS X Server verifies whether it is running on Apple
+            hardware, and most DVDs that that come with Apple hardware even
+            check for an exact model. These restrictions are
+            <emphasis>not</emphasis> circumvented by VirtualBox and continue
+            to apply.</para>
+          </listitem>
+
+          <listitem>
+            <para>Only <emphasis role="bold">CPUs</emphasis> known and tested
+            by Apple are supported. As a result, if the Intel CPU is newer
+            than the build of Mac OS X Server, it will most likely panic
+            during bootup with an "Unsupported CPU" exception. It is generally
+            best to use the Mac OS X Server DVD that came with your Apple
+            hardware.</para>
+          </listitem>
+
+          <listitem>
+            <para>The Mac OS X Server installer expects the harddisk to be
+            <emphasis role="bold">partitioned</emphasis> so when it does not
+            offer a selection, you have to launch the Disk Utility from the
+            "Tools" menu and partition the hard disk. Then close the Disk
+            Utility and proceed with the installation.</para>
+          </listitem>
+
+          <listitem>
+            <para>In addition, as Mac OS X Server support in VirtualBox is
+            currently still experimental, please refer also to <xref
+            linkend="KnownIssues" />.</para>
+          </listitem>
+        </orderedlist></para>
+    </sect2>
+
+    <sect2 id="intro-64bitguests">
+      <title>64-bit guests</title>
+
+      <para>Starting with version 2.0, VirtualBox supports 64-bit guest
+      operating systems. Starting with version 2.1, you can even run 64-bit
+      guests on a 32-bit host operating system. The hardware prerequisites are
+      identical for both cases.</para>
+
+      <para>In particular, 64-bit guests are supported under the following
+      conditions:<orderedlist>
+          <listitem>
+            <para>You need a 64-bit processor with hardware virtualization
+            support (see <xref linkend="hwvirt" />).</para>
+          </listitem>
+
+          <listitem>
+            <para>You must enable hardware virtualization for the particular
+            VM for which you want 64-bit support; software virtualization is
+            not supported for 64-bit VMs.</para>
+          </listitem>
+
+          <listitem>
+            <para>If you want to use 64-bit guest support on a 32-bit host
+            operating system, you must also select a 64-bit operating system
+            for the particular VM. Since supporting 64 bits on 32-bit hosts
+            incurs additional overhead, VirtualBox only enables this support
+            upon explicit request.</para>
+
+            <para>On 64-bit hosts, 64-bit guest support is always enabled, so
+            you can simply install a 64-bit operating system in the
+            guest.</para>
+          </listitem>
+        </orderedlist></para>
+
+      <para><warning>
+          <para>On any host, you should enable the <emphasis role="bold">I/O
+          APIC</emphasis> for virtual machines that you intend to use in
+          64-bit mode. This is especially true for 64-bit Windows VMs. See
+          <xref linkend="settings-general-advanced" />. In addition, for
+          64-bit Windows guests, you should make sure that the VM uses the
+          <emphasis role="bold">Intel networking device</emphasis>, since
+          there is no 64-bit driver support for the AMD PCNet card; see <xref
+          linkend="nichardware" />.</para>
+        </warning></para>
+
+      <para>If you use the "Create VM" wizard of the VirtualBox graphical user
+      interface (see <xref linkend="gui-createvm" />), VirtualBox will
+      automatically use the correct settings for each selected 64-bit
+      operating system type.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Emulated hardware</title>
+
+    <para>VirtualBox virtualizes nearly all hardware of the host. Depending on
+    a VM's configuration, the guest will see the following virtual
+    hardware:<itemizedlist>
+        <listitem>
+          <para><emphasis role="bold">Input devices.</emphasis> By default,
+          VirtualBox emulates a standard PS/2 keyboard and mouse. These
+          devices are supported by almost all past and present operating
+          systems. In addition, VirtualBox can provide virtual USB input
+          devices.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Graphics.</emphasis> the VirtualBox
+          graphics device (sometimes referred to as VGA device) is, unlike
+          nearly all other emulated devices, not based on any physical
+          counterpart. It is a simple, synthetic device which provides
+          compatibility with standard VGA and several extended registers used
+          by VESA BIOS Extensions (VBE).</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Storage.</emphasis> VirtualBox currently
+          emulates the standard ATA interface found on Intel PIIX3/PIIX4
+          chips, SATA (AHCI) interface, and two SCSI adapters (LSI Logic and
+          BusLogic); see <xref linkend="harddiskcontrollers" /> for details.
+          Whereas providing one of these would be enough for VirtualBox by
+          itself, this multitude of storage adapters is required for
+          compatibility with other hypervisors. Windows is particularly picky
+          about its boot devices, and migrating VMs between hypervisors is
+          very difficult or impossible if the storage controllers are
+          different.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Networking.</emphasis> See <xref
+          linkend="nichardware" />.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">USB.</emphasis> VirtualBox emulates two
+          USB host controllers, EHCI and OHCI. There is a need for two host
+          controllers because OHCI only handles USB low- and full-speed
+          devices (both USB 1.x and 2.0), while EHCI only handles high-speed
+          devices (USB 2.0 only). The emulated USB controllers do not
+          communicate directly with devices on the host but rather with the
+          VUSB layer (see below), which abstracts the USB protocol and allows
+          the use of remote USB devices (with VRDP).</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Audio.</emphasis> Two audio devices are
+          emulated, an AC97 controller plus codec, and a classic SoundBlaster
+          16 (digital audio only).</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+
+  <sect1 id="generalsettings">
+    <title>General settings</title>
+
+    <para>In the Settings window, under "General", you can configure the most
+    fundamental aspects of the virtual machine such as memory and essential
+    hardware. There are three tabs, "Basic", "Advanced" and
+    "Description".</para>
+
+    <sect2>
+      <title>"Basic" tab</title>
+
+      <para>Under the "Basic" tab of the "General" settings category, you can
+      find these settings:</para>
+
+      <glosslist>
+        <glossentry>
+          <glossterm>Name</glossterm>
+
+          <glossdef>
+            <para>The name under which the VM is shown in the list of VMs in
+            the main window. Under this name, VirtualBox also saves the VM's
+            configuration files. By changing the name, VirtualBox renames
+            these files as well. As a result, you can only use characters
+            which are allowed in your host operating system's file
+            names.</para>
+
+            <para>Note that internally, VirtualBox uses unique identifiers
+            (UUIDs) to identify virtual machines. You can display these with
+            <computeroutput>VBoxManage</computeroutput>.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Operating System / Version</glossterm>
+
+          <glossdef>
+            <para>The type of the guest operating system that is (or will be)
+            installed in the VM. This is the same setting that was specified
+            in the "New Virtual Machine" wizard, as described with <xref
+            linkend="gui-createvm" /> above.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist>
+    </sect2>
+
+    <sect2 id="settings-general-advanced">
+      <title>"Advanced" tab</title>
+
+      <para><glosslist>
+          <glossentry>
+            <glossterm>Snapshot folder</glossterm>
+
+            <glossdef>
+              <para>By default, VirtualBox saves snapshot data together with
+              your other VirtualBox configuration data; see <xref
+              linkend="vboxconfigdata" />. With this setting, you can specify
+              any other folder for each VM.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Shared Clipboard</glossterm>
+
+            <glossdef>
+              <para>If the virtual machine has Guest Additions installed, you
+              can select here whether the clipboard of the guest operating
+              system should be shared with that of your host. If you select
+              "Bidirectional", then VirtualBox will always make sure that both
+              clipboards contain the same data. If you select "Host to guest"
+              or "Guest to host", then VirtualBox will only ever copy
+              clipboard data in one direction.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Removable Media: Remember Runtime Changes</glossterm>
+
+            <glossdef>
+              <para>If this is checked, VirtualBox will save the state of what
+              media has been mounted between several runs of a virtual
+              machine.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Mini Toolbar</glossterm>
+
+            <glossdef>
+              <para>In full screen or seamless mode, VirtualBox can display a
+              small toolbar that contains some of the items that are normally
+              available from the virtual machine's menu bar. This toolbar
+              reduces itself to a small gray line unless you move the mouse
+              over it. With the toolbar, you can return from full screen or
+              seamless mode, control machine execution or enable certain
+              devices. If you don't want to see the toolbar, disable this
+              setting.</para>
+            </glossdef>
+          </glossentry>
+        </glosslist></para>
+    </sect2>
+
+    <sect2>
+      <title>"Description" tab</title>
+
+      <para>Here you can enter any description for your virtual machine, if
+      you want. This has no effect of the functionality of the machine, but
+      you may find this space useful to note down things like the
+      configuration of a virtual machine and the software that has been
+      installed into it.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="settings-system">
+    <title>System settings</title>
+
+    <para>The "System" category groups various settings that are related to
+    the basic hardware that is presented to the virtual machine.<note>
+        <para>As the activation mechanism of Microsoft Windows is sensitive to
+        hardware changes, if you are changing hardware settings for a Windows
+        guest, some of these changes may trigger a request for another
+        activation with Microsoft.</para>
+      </note></para>
+
+    <sect2 id="settings-motherboard">
+      <title>"Motherboard" tab</title>
+
+      <para>On the "Motherboard" tab, you can influence virtual hardware that
+      would normally be on the motherboard of a real computer.<glosslist>
+          <glossentry>
+            <glossterm>Base memory</glossterm>
+
+            <glossdef>
+              <para>This sets the amount of RAM that is allocated and given to
+              the VM when it is running. The specified amount of memory will
+              be requested from the host operating system, so it must be
+              available or made available as free memory on the host when
+              attempting to start the VM and will not be available to the host
+              while the VM is running. This is the same setting that was
+              specified in the "New Virtual Machine" wizard, as described with
+              guidelines under <xref linkend="gui-createvm" /> above.</para>
+
+              <para>Generally, it is possible to change the memory size after
+              installing the guest operating system (provided you do not
+              reduce the memory to an amount where the operating system would
+              no longer boot).</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Boot order</glossterm>
+
+            <glossdef>
+              <para>This setting determines the order in which the guest
+              operating system will attempt to boot from the various virtual
+              boot devices. Analogous to a real PC's BIOS setting, VirtualBox
+              can tell a guest OS to start from the virtual floppy, the
+              virtual CD/DVD drive, the virtual hard drive (each of these as
+              defined by the other VM settings), the network, or none of
+              these.</para>
+
+              <para>If you select "Network", the VM will attempt to boot from
+              a network via the PXE mechanism. This needs to be configured in
+              detail on the command line; please see <xref
+              linkend="vboxmanage-modifyvm" />.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Enable I/O APIC</glossterm>
+
+            <glossdef>
+              <para>Advanced Programmable Interrupt Controllers (APICs) are a
+              newer x86 hardware feature that have replaced old-style
+              Programmable Interrupt Controllers (PICs) in recent years. With
+              an I/O APIC, operating systems can use more than 16 interrupt
+              requests (IRQs) and therefore avoid IRQ sharing for improved
+              reliability.<note>
+                  <para>Enabling the I/O APIC is <emphasis>required</emphasis>
+                  for 64-bit guest operating systems, especially Windows
+                  Vista; it is also required if you want to use more than one
+                  virtual CPU in a virtual machine.</para>
+                </note></para>
+
+              <para>However, software support for I/O APICs has been
+              unreliable with some operating systems other than Windows. Also,
+              the use of an I/O APIC slightly increases the overhead of
+              virtualization and therefore slows down the guest OS a
+              little.<warning>
+                  <para>All Windows operating systems starting with Windows
+                  2000 install different kernels depending on whether an I/O
+                  APIC is available. As with ACPI, the I/O APIC therefore
+                  <emphasis>must not be turned off after
+                  installation</emphasis> of a Windows guest OS. Turning it on
+                  after installation will have no effect however.</para>
+                </warning></para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Enable EFI</glossterm>
+
+            <glossdef>
+              <para>This enables Extensible Firmware Interface (EFI), which
+              replaces the legacy BIOS, which may be useful for certain
+              advanced use cases. Please refer to <xref linkend="efi" /> for
+              details.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Hardware clock in UTC time</glossterm>
+
+            <glossdef>
+              <para>If checked, VirtualBox will report the system time in UTC
+              format to the guest instead of local (host) time. This affects
+              how the virtual real-time clock (RTC) operates and may be useful
+              for Unix-like guest operating systems, which typically expect
+              the hardware clock to be set to UTC.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Enable absolute pointing device</glossterm>
+
+            <glossdef>
+              <para>If enabled, VirtualBox reports to the virtual machine that
+              a USB tablet device is present and communicates mouse events to
+              the virtual machine through this device. If disabled, mouse
+              events are communicated through a traditional PS/2 virtual mouse
+              device.</para>
+
+              <para>Using the virtual USB tablet has the advantage that
+              movements are reported in absolute coordinates (instead of as
+              relative position changes), which allows VirtualBox to translate
+              mouse events over the VM window into tablet events without
+              having to "capture" the mouse in the guest as described in <xref
+              linkend="keyb_mouse_normal" />. This makes using the VM less
+              tedious even if Guest Additions are not installed.<footnote>
+                  <para>The virtual USB tablet was added with VirtualBox 3.2.
+                  Depending on the guest operating system selected, this is
+                  now enabled by default for new virtual machines.</para>
+                </footnote></para>
+            </glossdef>
+          </glossentry>
+        </glosslist></para>
+
+      <para>In addition, you can turn off the <emphasis role="bold">Advanced
+      Configuration and Power Interface (ACPI)</emphasis> which VirtualBox
+      presents to the guest operating system by default. ACPI is the current
+      industry standard to allow operating systems to recognize hardware,
+      configure motherboards and other devices and manage power. As all modern
+      PCs contain this feature and Windows and Linux have been supporting it
+      for years, it is also enabled by default in VirtualBox. It can only be
+      turned off on the command line; see <xref
+      linkend="vboxmanage-modifyvm" />.<warning>
+          <para>All Windows operating systems starting with Windows 2000
+          install different kernels depending on whether ACPI is available, so
+          ACPI <emphasis>must not be turned off</emphasis> after installation
+          of a Windows guest OS. Turning it on after installation will have no
+          effect however.</para>
+        </warning></para>
+    </sect2>
+
+    <sect2 id="settings-processor">
+      <title>"Processor" tab</title>
+
+      <para>On the "Processor" tab, you can set how many virtual <emphasis
+      role="bold">CPU cores</emphasis> the guest operating systems should see.
+      Starting with version 3.0, VirtualBox supports symmetrical
+      multiprocessing (SMP) and can present up to 32 virtual CPU cores to each
+      virtual machine.</para>
+
+      <para>You should not, however, configure virtual machines to use more
+      CPU cores than you have available physically.</para>
+
+      <para>In addition, the <emphasis role="bold">"Enable PAE/NX"</emphasis>
+      setting determines whether the PAE and NX capabilities of the host CPU
+      will be exposed to the virtual machine. PAE stands for "Physical Address
+      Extension". Normally, if enabled and supported by the operating system,
+      then even a 32-bit x86 CPU can access more than 4 GB of RAM. This is
+      made possible by adding another 4 bits to memory addresses, so that with
+      36 bits, up to 64 GB can be addressed. Some operating systems (such as
+      Ubuntu Server) require PAE support from the CPU and cannot be run in a
+      virtual machine without it.</para>
+
+      <para>With virtual machines running modern server operating systems,
+      VirtualBox also supports CPU hot-plugging. For details about this,
+      please refer to <xref linkend="cpuhotplug" />.</para>
+    </sect2>
+
+    <sect2>
+      <title>"Acceleration" tab</title>
+
+      <para>On this page, you can determine whether and how VirtualBox should
+      use hardware virtualization extensions that your host CPU may support.
+      This is the case with most CPUs built after 2006.</para>
+
+      <para>You can select for each virtual machine individually whether
+      VirtualBox should use software or hardware virtualization.<footnote>
+          <para>Prior to VirtualBox version 2.2, software virtualization was
+          the default; starting with version 2.2, VirtualBox will enable
+          hardware virtualization by default for new virtual machines that you
+          create. (Existing virtual machines are not automatically changed for
+          compatibility reasons, and the default can of course be changed for
+          each virtual machine.)</para>
+        </footnote></para>
+
+      <para>In most cases, the default settings will be fine; VirtualBox will
+      have picked sensible defaults depending on the operating system that you
+      selected when you created the virtual machine. In certain situations,
+      however, you may want to change these preconfigured defaults.</para>
+
+      <para>Advanced users may be interested in technical details about
+      software vs. hardware virtualization; please see <xref
+      linkend="hwvirt" />.</para>
+
+      <para>If your host's CPU supports the <emphasis role="bold">nested
+      paging</emphasis> (AMD-V) or <emphasis role="bold">EPT</emphasis> (Intel
+      VT-x) features, then you can expect a significant performance increase
+      by enabling nested paging in addition to hardware virtualization. Nested
+      paging is still disabled by default even for new machines, but it can be
+      enabled for each virtual machine individually. For technical details,
+      see <xref linkend="nestedpaging" />.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="settings-display">
+    <title>Display settings</title>
+
+    <glosslist>
+      <glossentry>
+        <glossterm>Video memory size</glossterm>
+
+        <glossdef>
+          <para>This sets the size of the memory provided by the virtual
+          graphics card available to the guest, in MB. As with the main
+          memory, the specified amount will be allocated from the host's
+          resident memory. Based on the amount of video memory, higher
+          resolutions and color depths may be available.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>Monitor count</glossterm>
+
+        <glossdef>
+          <para>With this setting VirtualBox can provide more than one virtual
+          monitor to a virtual machine. If a guest operating system (such as
+          Windows) supports multiple attached monitors, VirtualBox can pretend
+          that multiple virtual monitors are present.<footnote>
+              <para>Multiple monitor support was added with VirtualBox
+              3.2.</para>
+            </footnote> Up to 8 such virtual monitors are supported.</para>
+
+          <para>The output of the multiple monitors will be displayed on the
+          host in multiple VM windows which are running side by side.</para>
+
+          <para>However, in fullscreen and seamless mode, they will use the
+          available physical monitors attached to the host. As a result, for
+          fullscreen and seamless modes to work with multiple monitors, you
+          will need at least as many physical monitors as you have virtual
+          monitors configured, or VirtualBox will report an error. You can
+          configure the relationship between guest and host monitors using the
+          view menu by pressing Host key + Home when you are in fullscreen or
+          seamless mode.</para>
+
+          <para>Please see <xref linkend="KnownIssues" /> also.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>Enable 3D acceleration</glossterm>
+
+        <glossdef>
+          <para>If a virtual machine has Guest Additions installed, you can
+          select here whether the guest should support accelerated 3D
+          graphics. Please refer to <xref linkend="guestadd-3d" /> for
+          details.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>Enable 2D video acceleration</glossterm>
+
+        <glossdef>
+          <para>If a virtual machine with Microsoft Windows has Guest
+          Additions installed, you can select here whether the guest should
+          support accelerated 2D video graphics. Please refer to <xref
+          linkend="guestadd-2d" /> for details.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>Remote display</glossterm>
+
+        <glossdef>
+          <para>Under the "Remote display" tab, you can enable the VRDP server
+          that is built into VirtualBox to allow you to connect to the virtual
+          machine remotely. For this, you can use any standard RDP viewer,
+          such as <computeroutput>mstsc.exe</computeroutput> that comes with
+          Microsoft Windows or, on Linux systems, the standard open-source
+          <computeroutput>rdesktop</computeroutput> program. These features
+          are described in detail in <xref linkend="vrdp" />.</para>
+        </glossdef>
+      </glossentry>
+    </glosslist>
+  </sect1>
+
+  <sect1 id="settings-storage">
+    <title>Storage settings</title>
+
+    <para>In the VM Settings window, the "Storage" section allows you to
+    connect virtual hard disk, CD/DVD and floppy images and drives to your
+    virtual machine:<mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/vm-settings-harddisk.png"
+                     width="10cm" />
+        </imageobject>
+      </mediaobject></para>
+
+    <para>In a real PC, so-called "storage controllers" connect physical disk
+    drives to the rest of the computer. Similarly, VirtualBox presents virtual
+    storage controllers to a virtual machine. Under each controller, the
+    virtual devices (hard disks, CD/DVD or floppy drives) are shown that are
+    attached to the controller.</para>
+
+    <para>If you have used the "Create VM" wizard to create a machine, you
+    will normally see the following devices:<itemizedlist>
+        <listitem>
+          <para>You will see an IDE controller, under which there are two
+          devices:<itemizedlist>
+              <listitem>
+                <para>one virtual hard disk connected to the IDE slot called
+                "primary master"; this is represented by the disk images that
+                you created with the machine;</para>
+              </listitem>
+
+              <listitem>
+                <para>one virtual CD/DVD drive connected to the "secondary
+                master".</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>In addition, there is a floppy controller to which a virtual
+          floppy drive is attached.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>You can modify these media attachments freely. For example, if you
+    wish to copy some files from another virtual disk that you created, you
+    can connect that disk as a second hard disk. You could also add a second
+    virtual CD/DVD drive, or change where these items are attached.</para>
+
+    <para>In addition to the IDE controller, VirtualBox can also present an
+    SATA controller and a SCSI controller to the guest, which gives you 30 or
+    16 additional slots to attach devices to, respectively. This, however, may
+    require that you run a modern guest operating system. See <xref
+    linkend="harddiskcontrollers" /> for details.</para>
+
+    <para>To <emphasis role="bold">add another virtual hard disk or CD/DVD
+    drive,</emphasis> select the storage controller to which it should be
+    added (IDE, SATA or SCSI) and then click on the "add disk" button below
+    the tree. You can then either select "Add CD/DVD device" or "Add Hard
+    Disk". Alternatively, right-click on the storage controller and select a
+    menu item there.</para>
+
+    <para>On the right part of the window, you can then select where the
+    virtual disk should be connected to on the controller and which image file
+    to use.<itemizedlist>
+        <listitem>
+          <para>For virtual hard disks, a drop-down list appears on the right,
+          listing all the hard disk images that VirtualBox currently knows
+          about. If you click on the "Open Virtual Media Manager" icon to the
+          right, this will bring up a window in which you can select or create
+          a different hard disk image (see <xref linkend="vdis" /> for
+          details).</para>
+        </listitem>
+
+        <listitem>
+          <para>For virtual CD/DVD drives, there are two kinds of options in
+          the drop-down list.<itemizedlist>
+              <listitem>
+                <para>If you select "Empty", then VirtualBox will present a
+                virtual CD/DVD drive to the guest which has no media
+                inserted.</para>
+              </listitem>
+
+              <listitem>
+                <para>If you select "Host drive" from the list, then the
+                physical device of the host computer is connected to the VM,
+                so that the guest operating system can read from and write to
+                your physical device. This is, for instance, useful if you
+                want to install Windows from a real installation CD. In this
+                case, select your host drive from the drop-down list
+                presented.<note>
+                    <para>If you want to write CDs or DVDs using the host
+                    drive, you need to enable a special setting first; see
+                    <xref linkend="storage-write-cds" />.</para>
+                  </note></para>
+              </listitem>
+
+              <listitem>
+                <para>The other items in the list, like virtual hard disk
+                images, will be image files on your host. The file format here
+                is the ISO format. Most commonly, you will select this option
+                when installing an operating system from an ISO file that you
+                have obtained from the Internet. For example, most Linux
+                distributions are available in this way.</para>
+              </listitem>
+            </itemizedlist></para>
+
+          <note>
+            <para>The identification string of the drive provided to the guest
+            (which, in the guest, would be displayed by configuration tools
+            such as the Windows Device Manager) is always "VBOX CD-ROM",
+            irrespective of the current configuration of the virtual drive.
+            This is to prevent hardware detection from being triggered in the
+            guest operating system every time the configuration is
+            changed.</para>
+          </note>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>Note that the floppy controller is special: you cannot add devices
+    other than floppy drives to it. Virtual floppy drives, like virtual CD/DVD
+    drives, can be connected to either a host floppy drive (if you have one)
+    or a disk image, which in this case must be in RAW format.</para>
+
+    <para>To <emphasis role="bold">remove a virtual disk or drive,</emphasis>
+    select it and click on the "remove" icon at the bottom (or right-click on
+    it and select the menu item).</para>
+
+    <para>Removable media (CD/DVDs and floppies) can be changed while the
+    guest is running. Since the "Settings" dialog is not available at that
+    time, you can also access these settings from the "Devices" menu of your
+    virtual machine window.</para>
+
+    <para>We have dedicated an entire chapter of this User Manual to virtual
+    storage: please see <xref linkend="storage" /> for every single detail
+    about storage configuration.</para>
+  </sect1>
+
+  <sect1>
+    <title>Audio settings</title>
+
+    <para>The "Audio" section in a virtual machine's Settings window
+    determines whether the VM will see a sound card connected, and whether the
+    audio output should be heard on the host system.</para>
+
+    <para>If audio is enabled for a guest, you can choose between the
+    emulation of an Intel AC'97 controller or a SoundBlaster 16 card. In any
+    case, you can select what audio driver VirtualBox will use on the
+    host.</para>
+
+    <para>On a Linux host, depending on your host configuration, you can also
+    select between the OSS, ALSA or the PulseAudio subsystem. On newer Linux
+    distributions (Fedora 8 and above, Ubuntu 8.04 and above) the PulseAudio
+    subsystem should be preferred.<note>
+        <para>Newer Windows versions do not ship with drivers for the virtual
+        audio hardware emulated by VirtualBox. This applies to Windows 7
+        (32-bit and 64-bit versions) as well as 64-bit Windows Vista. See
+        <xref linkend="win7_audio" /> for instructions how to solve this
+        problem.</para>
+      </note></para>
+  </sect1>
+
+  <sect1 id="settings-network">
+    <title>Network settings</title>
+
+    <para>The "Network" section in a virtual machine's Settings window allows
+    you to configure how VirtualBox presents virtual network cards to your VM,
+    and how they operate.</para>
+
+    <para>When you first create a virtual machine, VirtualBox by default
+    enables one virtual network card and selects the "Network Address
+    Translation" (NAT) mode for it. This way the guest can connect to the
+    outside world using the host's networking and the outside world can
+    connect to services on the guest which you choose to make visible outside
+    of the virtual machine. In most cases, this default setup will work fine
+    for you.</para>
+
+    <para>However, VirtualBox is extremely flexible in how it can virtualize
+    networking. It supports up to eight virtual network cards per virtual
+    machine, the first four of which can be configured in detail in the
+    graphical user interface. All eight network cards can be configured on the
+    command line with VBoxManage. Because of this, we have dedicated an entire
+    chapter of this manual to discussing networking configuration; please see
+    <xref linkend="networkingdetails" />.</para>
+  </sect1>
+
+  <sect1 id="serialports">
+    <title>Serial ports</title>
+
+    <para>VirtualBox fully supports virtual serial ports in a virtual machine
+    in an easy-to-use manner.<footnote>
+        <para>Serial port support was added with VirtualBox 1.5.</para>
+      </footnote></para>
+
+    <para>Ever since the original IBM PC, personal computers have been
+    equipped with one or two serial ports (also called COM ports by DOS and
+    Windows). While these are no longer as important as they were until a few
+    years ago (especially since mice are no longer connected to serial ports
+    these days), there are still some important uses left for them. For
+    example, serial ports can be used to set up a primitive network over a
+    null-modem cable, in case Ethernet is not available. Also, serial ports
+    are indispensable for system programmers needing to do kernel debugging,
+    since kernel debugging software usually interacts with developers over a
+    serial port. In other words, with virtual serial ports, system programmers
+    can do kernel debugging on a virtual machine instead of needing a real
+    computer to connect to.</para>
+
+    <para>If a virtual serial port is enabled, the guest operating system sees
+    it a standard 16450-type serial port. Both receiving and transmitting data
+    is supported. How this virtual serial port is then connected to the host
+    is configurable, and details depend on your host operating system.</para>
+
+    <para>You can use either the graphical user interface or the command-line
+    <computeroutput>VBoxManage</computeroutput> tool to set up virtual serial
+    ports. For the latter, please refer to <xref
+    linkend="vboxmanage-modifyvm" />; in that section, look for the
+    <computeroutput>--uart</computeroutput> and
+    <computeroutput>--uartmode</computeroutput> options.</para>
+
+    <para>In either case, you can configure up to two virtual serial ports
+    simultaneously. For each such device, you will need to
+    determine<orderedlist>
+        <listitem>
+          <para>what kind of serial port the virtual machine should see by
+          selecting an I/O base address and interrupt (IRQ). For these, we
+          recommend to use the traditional values<footnote>
+              <para>See, for example, <ulink
+              url="http://en.wikipedia.org/wiki/COM_(hardware_interface)">http://en.wikipedia.org/wiki/COM_(hardware_interface)</ulink>.</para>
+            </footnote>, which are:</para>
+
+          <para><orderedlist>
+              <listitem>
+                <para>COM1: I/O base 0x3F8, IRQ 4</para>
+              </listitem>
+
+              <listitem>
+                <para>COM2: I/O base 0x2F8, IRQ 3</para>
+              </listitem>
+
+              <listitem>
+                <para>COM3: I/O base 0x3E8, IRQ 4</para>
+              </listitem>
+
+              <listitem>
+                <para>COM4: I/O base 0x2E8, IRQ 3</para>
+              </listitem>
+            </orderedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>Then, you will need to determine what this virtual port should
+          be connected to. For each virtual serial port, you have the
+          following options:</para>
+
+          <para><itemizedlist>
+              <listitem>
+                <para>You can elect to have the virtual serial port
+                "disconnected", which means that the guest will see it as
+                hardware, but it will behave as if no cable had been connected
+                to it.</para>
+              </listitem>
+
+              <listitem>
+                <para>You can connect the virtual serial port to a physical
+                serial port on your host. (On a Windows host, this will be a
+                name like <computeroutput>COM1</computeroutput>; on Linux or
+                OpenSolaris hosts, it will be a device node like
+                <computeroutput>/dev/ttyS0</computeroutput>). VirtualBox will
+                then simply redirect all data received from and sent to the
+                virtual serial port to the physical device.</para>
+              </listitem>
+
+              <listitem>
+                <para>You can tell VirtualBox to connect the virtual serial
+                port to a software pipe on the host. This depends on your host
+                operating system:<itemizedlist>
+                    <listitem>
+                      <para>On a Windows host, data will be sent and received
+                      through a named pipe. You can use a helper program
+                      called VMware Serial Line Gateway, available for
+                      download at <literal> <ulink
+                      url="http://www.l4ka.org/tools/vmwaregateway.php">http://www.l4ka.org/tools/vmwaregateway.php</ulink>
+                      </literal>. This tool provides a fixed server mode named
+                      pipe at
+                      <computeroutput>\\.\pipe\vmwaredebug</computeroutput>
+                      and connects incoming TCP connections on port 567 with
+                      the named pipe.</para>
+                    </listitem>
+
+                    <listitem>
+                      <para>On a Mac, Linux or OpenSolaris host, a local
+                      domain socket is used instead. On Linux there are
+                      various tools which can connect to a local domain socket
+                      or create one in server mode. The most flexible tool is
+                      <computeroutput>socat</computeroutput> and is available
+                      as part of many distributions.</para>
+                    </listitem>
+                  </itemizedlist></para>
+
+                <para>In this case, you can configure whether VirtualBox
+                should create the named pipe (or, on non-Windows hosts, the
+                local domain socket) itself or whether VirtualBox should
+                assume that the pipe (or socket) exists already. With the
+                <computeroutput>VBoxManage</computeroutput> command-line
+                options, this is referred to as "server" or "client" mode,
+                respectively.</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+      </orderedlist>Up to two serial ports can be configured simultaneously
+    per virtual machine, but you can pick any port numbers out of the above.
+    For example, you can configure two serial ports to be able to work with
+    COM2 and COM4 in the guest.</para>
+  </sect1>
+
+  <sect1>
+    <title>USB support</title>
+
+    <sect2 id="settings-usb">
+      <title>USB settings</title>
+
+      <para>The "USB" section in a virtual machine's Settings window allows
+      you to configure VirtualBox's sophisticated USB support.</para>
+
+      <para>VirtualBox can allow virtual machines to access the USB devices on
+      your host directly. To achieve this, VirtualBox presents the guest
+      operating system with a virtual USB controller. As soon as the guest
+      system starts using a USB device, it will appear as unavailable on the
+      host.<note>
+          <orderedlist>
+            <listitem>
+              <para>Be careful with USB devices that are currently in use on
+              the host! For example, if you allow your guest to connect to
+              your USB hard disk that is currently mounted on the host, when
+              the guest is activated, it will be disconnected from the host
+              without a proper shutdown. This may cause data loss.</para>
+            </listitem>
+
+            <listitem>
+              <para>Solaris hosts have a few known limitations regarding USB
+              support; please see <xref linkend="KnownIssues" />.</para>
+            </listitem>
+          </orderedlist>
+        </note></para>
+
+      <para>In addition to allowing a guest access to your local USB devices,
+      VirtualBox even allows your guests to connect to remote USB devices by
+      use of the VRDP protocol. For details about this, see <xref
+      linkend="usb-over-rdp" />.</para>
+
+      <para>In the Settings dialog, you can first configure whether USB is
+      available in the guest at all, and in addition also optionally enable
+      the USB 2.0 (EHCI) controller for the guest. If so, you can determine in
+      detail which devices are available. For this, you must create so-called
+      "filters" by specifying certain properties of the USB device.</para>
+
+      <para>Clicking on the "+" button to the right of the "USB Device
+      Filters" window creates a <emphasis role="bold">new filter.</emphasis>
+      You can give the filter a name (for referencing it later) and specify
+      the filter criteria. The more criteria you specify, the more precisely
+      devices will be selected. For instance, if you specify only a vendor ID
+      of 046d, all devices produced by Logitech will be available to the
+      guest. If you fill in all fields, on the other hand, the filter will
+      only apply to a particular device model from a particular vendor, and
+      not even to other devices of the same type with a different revision and
+      serial number.</para>
+
+      <para>In detail, the following criteria are available:</para>
+
+      <orderedlist>
+        <listitem>
+          <para><emphasis role="bold">Vendor and product ID.</emphasis> With
+          USB, each vendor of USB products carries an identification number
+          that is unique world-wide, the "vendor ID". Similarly, each line of
+          products is assigned a "product ID" number. Both numbers are
+          commonly written in hexadecimal (that is, they are composed of the
+          numbers 0-9 and the letters A-F), and a colon separates the vendor
+          from the product ID. For example,
+          <computeroutput>046d:c016</computeroutput> stands for Logitech as a
+          vendor, and the "M-UV69a Optical Wheel Mouse" product.</para>
+
+          <para>Alternatively, you can also specify <emphasis
+          role="bold">"Manufacturer"</emphasis> and <emphasis
+          role="bold">"Product"</emphasis> by name.</para>
+
+          <para>To list all the USB devices that are connected to your host
+          machine with their respective vendor and product IDs, you can use
+          the following command (see <xref linkend="vboxmanage" />): <screen>VBoxManage list usbhost</screen></para>
+
+          <para>On Windows, you can also see all USB devices that are attached
+          to your system in the Device Manager. On Linux, you can use the
+          <computeroutput>lsusb</computeroutput> command.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Serial number.</emphasis> While vendor
+          and product ID are already quite specific to identify USB devices,
+          if you have two identical devices of the same brand and product
+          line, you will also need their serial numbers to filter them out
+          correctly.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Remote.</emphasis> This setting
+          specifies whether the device will be local only, or remote only
+          (over VRDP), or either.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>On a Windows host, you will need to unplug and reconnect a USB
+      device to use it after creating a filter for it.</para>
+
+      <para>As an example, you could create a new USB filter and specify a
+      vendor ID of 046d (Logitech, Inc), a manufacturer index of 1, and "not
+      remote". Then any USB devices on the host system produced by Logitech,
+      Inc with a manufacturer index of 1 will be visible to the guest
+      system.</para>
+
+      <para>Several filters can select a single device -- for example, a
+      filter which selects all Logitech devices, and one which selects a
+      particular webcam.</para>
+
+      <para>You can <emphasis role="bold">deactivate</emphasis> filters
+      without deleting them by clicking in the checkbox next to the filter
+      name.</para>
+    </sect2>
+
+    <sect2>
+      <title>Implementation notes for Windows and Linux hosts</title>
+
+      <para>On Windows hosts, a kernel mode device driver provides USB proxy
+      support. It implements both a USB monitor, which allows VirtualBox to
+      capture devices when they are plugged in, and a USB device driver to
+      claim USB devices for a particular virtual machine. As opposed to
+      VirtualBox versions before 1.4.0, system reboots are no longer necessary
+      after installing the driver. Also, you no longer need to replug devices
+      for VirtualBox to claim them.</para>
+
+      <para>On newer Linux hosts, VirtualBox accesses USB devices through
+      special files in the file system. When VirtualBox is installed, these
+      are made available to all users in the
+      <computeroutput>vboxusers</computeroutput> system group. In order to be
+      able to access USB from guest systems, make sure that you are a member
+      of this group.</para>
+
+      <para>On older Linux hosts, USB devices are accessed using the
+      <computeroutput>usbfs</computeroutput> file system. Therefore, the user
+      executing VirtualBox needs read and write permission to the USB file
+      system. Most distributions provide a group (e.g.
+      <computeroutput>usbusers</computeroutput>) which the VirtualBox user
+      needs to be added to. Also, VirtualBox can only proxy to virtual
+      machines USB devices which are not claimed by a Linux host USB driver.
+      The <computeroutput>Driver=</computeroutput> entry in
+      <computeroutput>/proc/bus/usb/devices</computeroutput> will show you
+      which devices are currently claimed. Please refer to <xref
+      linkend="usb_linux" /> also for details about
+      <computeroutput>usbfs</computeroutput>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Shared folders</title>
+
+    <para>Shared folders allow you to easily exchange data between a virtual
+    machine and your host. This feature requires that the VirtualBox Guest
+    Additions be installed in a virtual machine and is described in detail in
+    <xref linkend="sharedfolders" />.</para>
+  </sect1>
+
+  <sect1 id="efi">
+    <title>Alternative firmware (EFI)</title>
+
+    <para>Starting with release 3.1, VirtualBox includes experimental support
+    for the Extensible Firmware Interface (EFI), which is a new industry
+    standard intended to eventually replace the legacy BIOS as the primary
+    interface for bootstrapping computers and certain system services
+    later.</para>
+
+    <para>By default, VirtualBox uses the BIOS firmware for virtual machines.
+    To use EFI for a given virtual machine, you can enable EFI in the
+    machine's "Settings" dialog (see <xref linkend="settings-motherboard" />).
+    Alternatively, use the <computeroutput>VBoxManage</computeroutput> command
+    line interface like this: <screen>VBoxManage modifyvm "VM name" --firmware efi</screen>
+    To switch back to using the BIOS, use: <screen>VBoxManage modifyvm "VM name" --firmware bios</screen>One
+    notable user of EFI is Apple's Mac OS X, but recent Linuxes (such as
+    Fedora 11) and Windows (starting with Vista) can be booted using EFI as
+    well.</para>
+
+    <para>Another possible use of EFI in VirtualBox is development and testing
+    of EFI applications, without booting any OS.</para>
+
+    <para>Note that the VirtualBox EFI support is experimental and will be
+    enhanced as EFI matures and becomes more widespread. While Mac OS X and
+    Linux guests are known to work fine, Windows guests are currently unable
+    to boot using EFI.</para>
+
+    <sect2 id="efividmode">
+      <title>Video modes in EFI</title>
+
+      <para>EFI provides two distinct video interfaces: GOP (Graphics Output
+      Protocol) and UGA (Universal Graphics Adapter). Mac OS X uses GOP, while
+      Linux tends to use UGA. VirtualBox provides a configuration option to
+      control the framebuffer size for both interfaces.</para>
+
+      <para>To control GOP, use the following
+      <computeroutput>VBoxManage</computeroutput> command: <screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiGopMode N</screen>
+      Where N can be one of 0,1,2,3,4 referring to the 640x480, 800x600,
+      1024x768, 1280x1024, 1440x900 screen resolution respectively.</para>
+
+      <para>To change the UGA resolution: <screen>VBoxManage setextradata "VM name" VBoxInternal2/UgaHorizontalResolution 1440
+VBoxManage setextradata "VM name" VBoxInternal2/UgaVerticalResolution    900</screen></para>
+
+      <para>The video mode for both GOP and UGA can only be changed when the
+      VM is powered off and remains persistent until changed.</para>
+    </sect2>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_ChangeLog.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_ChangeLog.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_ChangeLog.xml	(revision 33555)
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="ChangeLog">
+  <title>Change log</title>
+
+  <para>This section summarizes the changes between VirtualBox versions. Note
+  that this change log is not exhaustive; not all changes are listed.</para>
+
+  <para>VirtualBox version numbers consist of three numbers separated by dots
+  where the first and second number represent the major version and the 3rd number
+  the minor version. Minor version numbers of official releases are always even.
+  An odd minor version number represents an internal development or test build.
+  In addition, each build contains a revision number.</para>
+
+  <xi:include href="../user_ChangeLogImpl.xml" xpointer="element(/1)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</chapter>
Index: trunk/doc/manual/fr_FR/user_Frontends.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_Frontends.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_Frontends.xml	(revision 33555)
@@ -0,0 +1,641 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter>
+  <title>Remote virtual machines</title>
+
+  <sect1>
+    <title id="vrdp">Remote display (VRDP support)</title>
+
+    <para>VirtualBox, the graphical user interface, has a built-in server for
+    the VirtualBox Remote Desktop Protocol (VRDP). This allows you to see the
+    output of a virtual machine's window remotely on any other computer and
+    control the virtual machine from there, as if the virtual machine was
+    running locally.</para>
+
+    <para>VRDP is a backwards-compatible extension to Microsoft's Remote
+    Desktop Protocol (RDP). Typically graphics updates and audio are sent from
+    the remote machine to the client, while keyboard and mouse events are sent
+    back. As a result, you can use any standard RDP client to control the
+    remote VM.</para>
+
+    <para>With <computeroutput>VirtualBox</computeroutput>, the graphical user
+    interface, the VRDP server is disabled by default, but can easily be
+    enabled on a per-VM basis either in the "Display" settings (see <xref
+    linkend="settings-display" />) or with
+    <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrdp on</screen></para>
+
+    <para>If you use <computeroutput>VBoxHeadless</computeroutput> (described
+    further below), VRDP support will be automatically enabled since
+    VBoxHeadless has no other means of output.</para>
+
+    <sect2 id="rdp-viewers">
+      <title>Common third-party RDP viewers</title>
+
+      <para>You can use any standard RDP viewer to connect to such a remote
+      virtual machine (examples follow below). For this to work, you must
+      specify the <emphasis role="bold">IP address</emphasis> of your
+      <emphasis>host</emphasis> system (not of the virtual machine!) as the
+      server address to connect to, as well as the <emphasis role="bold">port
+      number</emphasis> that the RDP server is using.</para>
+
+      <para>By default, the VRDP server uses the standard RDP TCP port
+      <computeroutput>3389</computeroutput>. You will need to change the
+      default port if you run more than one VRDP server, since the port can
+      only be used by one server at a time; you might also need to change it
+      on Windows hosts since the default port might already be used by the RDP
+      server that is built into Windows itself. Ports 5000 through 5050 are
+      typically not used and might be a good choice.</para>
+
+      <para>The port can be changed either in the "Display" settings of the
+      graphical user interface or with
+      <computeroutput>--vrdpport</computeroutput> option of the
+      <computeroutput>VBoxManage modifyvm</computeroutput> command. You can
+      specify a comma-separated list of ports or ranges of ports. Use a dash
+      between two port numbers to specify a range. The VRDP server will bind
+      to <emphasis role="bold">one</emphasis> of available ports from the
+      specified list. For example, <computeroutput>VBoxManage modifyvm "VM
+      name" --vrdpport 5000,5010-5012</computeroutput> will configure the
+      server to bind to one of the ports 5000, 5010, 5011 or 5012. See <xref
+      linkend="vboxmanage-modifyvm" /> for details.</para>
+
+      <para>The actual port used by a running VM can be either queried with
+      <computeroutput>VBoxManage showvminfo</computeroutput> command or seen
+      in the GUI on the <computeroutput>Runtime</computeroutput> tab of the
+      <computeroutput>Session Information Dialog</computeroutput>, which is
+      accessible via the <computeroutput>Machine</computeroutput> menu of the
+      VM window.</para>
+
+      <para>Here follow examples for the most common RDP viewers:<itemizedlist>
+          <listitem>
+            <para>On Windows, you can use the Microsoft Terminal Services
+            Connector (<computeroutput>mstsc.exe</computeroutput>) that ships
+            with Windows. You can start it by bringing up the "Run" dialog
+            (press the Windows key and "R") and typing "mstsc". You can also
+            find it under "Start" -&gt; "All Programs" -&gt; "Accessories"
+            -&gt; "Remote Desktop Connection". If you use the "Run" dialog,
+            you can type in options directly:<screen>mstsc 1.2.3.4[:3389]</screen></para>
+
+            <para>Replace "1.2.3.4" with the host IP address, and 3389 with a
+            different port if necessary.</para>
+
+            <note><para>When connecting to localhost in order to test the connection,
+            the addresses <computeroutput>localhost</computeroutput> and
+            <computeroutput>127.0.0.1</computeroutput> might not work using
+            <computeroutput>mstsc.exe</computeroutput>. Instead, the address
+            <computeroutput>127.0.0.2[:3389]</computeroutput> has to be used.</para></note>
+          </listitem>
+
+          <listitem>
+            <para>On other systems, you can use the standard open-source
+            <computeroutput>rdesktop</computeroutput> program. This ships with
+            most Linux distributions, but VirtualBox also comes with a
+            modified variant of rdesktop for remote USB support (see <xref
+            linkend="usb-over-rdp" /> below).</para>
+
+            <para>With rdesktop, use a command line such as the
+            following:<screen>rdesktop -a 16 -N 1.2.3.4:3389</screen></para>
+
+            <para>As said for the Microsoft viewer above, replace "1.2.3.4"
+            with the host IP address, and 3389 with a different port if
+            necessary. The <computeroutput>-a 16</computeroutput> option
+            requests a color depth of 16 bits per pixel, which we recommend.
+            (For best performance, after installation of the guest operating
+            system, you should set its display color depth to the same value).
+            The <computeroutput>-N</computeroutput> option enables use of the
+            NumPad keys.</para>
+          </listitem>
+
+          <listitem>
+            <para>If you run the KDE desktop, you might prefer
+            <computeroutput>krdc</computeroutput>, the KDE RDP viewer. The
+            command line would look like this:<screen>krdc --window --high-quality rdp:/1.2.3.4[:3389]</screen></para>
+
+            <para>Again, replace "1.2.3.4" with the host IP address, and 3389
+            with a different port if necessary. The "rdp:/" bit is required
+            with krdc to switch it into RDP mode.</para>
+          </listitem>
+        </itemizedlist></para>
+    </sect2>
+
+    <sect2 id="vboxheadless">
+      <title>VBoxHeadless, the VRDP-only server</title>
+
+      <para>While the VRDP server that is built into the
+      <computeroutput>VirtualBox</computeroutput> GUI is perfectly capable of
+      running virtual machines remotely, it is not convenient to have to run
+      <computeroutput>VirtualBox</computeroutput> if you never want to have
+      VMs displayed locally in the first place. In particular, if you are
+      running servers whose only purpose is to host VMs, and all your VMs are
+      supposed to run remotely over VRDP, then it is pointless to have a
+      graphical user interface on the server at all -- especially since, on a
+      Linux or Solaris host, <computeroutput>VirtualBox</computeroutput> comes
+      with dependencies on the Qt and SDL libraries, which is inconvenient if
+      you would rather not have the X Window system on your server at
+      all.</para>
+
+      <para>VirtualBox therefore comes with yet another front-end called
+      <computeroutput>VBoxHeadless</computeroutput>, which produces no visible
+      output on the host at all, but instead only delivers VRDP data.<footnote>
+          <para>Before VirtualBox 1.6, the headless server was called
+          <computeroutput>VBoxVRDP</computeroutput>. For the sake of backwards
+          compatibility, the VirtualBox installation still installs an
+          executable with that name as well.</para>
+        </footnote></para>
+
+      <para>To start a virtual machine with VBoxHeadless, you have two
+      options:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>You can use <screen>VBoxManage startvm "VM name" --type vrdp</screen>
+          The extra <computeroutput>--type</computeroutput> option causes the
+          VirtualBox core to use <computeroutput>VBoxHeadless</computeroutput>
+          as the front-end to the internal virtualization engine.</para>
+        </listitem>
+
+        <listitem>
+          <para>The alternative is to use
+          <computeroutput>VBoxHeadless</computeroutput> directly, as
+          follows:<screen>VBoxHeadless --startvm &lt;uuid|name&gt;</screen></para>
+
+          <para>This way of starting the VM has the advantage that you can see
+          more detailed error messages, especially for early failures before
+          the VM execution is started. If you have trouble with
+          <computeroutput>VBoxManage startvm</computeroutput>, it can help
+          greatly to start <computeroutput>VBoxHeadless</computeroutput>
+          directly to diagnose the problem cause.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Note that when you use
+      <computeroutput>VBoxHeadless</computeroutput> to start a VM, since the
+      headless server has no other means of output, the built-in VRDP server
+      will <emphasis>always</emphasis> be enabled, regardless of whether you
+      have enabled the VRDP server in the VM's settings. If this is
+      undesirable (for example because you want to access the VM via
+      <computeroutput>ssh</computeroutput> only), start the VM like
+      this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrdp=off</screen>To
+      have the VRDP server use the setting from the VM configuration, as the
+      other front-ends would, use this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrdp=config</screen></para>
+    </sect2>
+
+    <sect2>
+      <title>Step by step: creating a virtual machine on a headless
+      server</title>
+
+      <para>The following instructions may give you an idea how to create a
+      virtual machine on a headless server over a network connection. We will
+      create a virtual machine, establish a VRDP connection and install a
+      guest operating system -- all without having to touch the headless
+      server. All you need is the following:</para>
+
+      <para><orderedlist>
+          <listitem>
+            <para>VirtualBox on a server machine with a supported host
+            operating system; for the following example, we will assume a
+            Linux server;</para>
+          </listitem>
+
+          <listitem>
+            <para>an ISO file on the server, containing the installation data
+            for the guest operating system to install (we will assume Windows
+            XP in the following example);</para>
+          </listitem>
+
+          <listitem>
+            <para>a terminal connection to that host over which you can access
+            a command line (e.g. via <computeroutput>telnet</computeroutput>
+            or <computeroutput>ssh</computeroutput>);</para>
+          </listitem>
+
+          <listitem>
+            <para>an RDP viewer on the remote client; see <xref
+            linkend="rdp-viewers" /> above for examples.</para>
+          </listitem>
+        </orderedlist>Note again that on the server machine, since we will
+      only use the headless server, neither Qt nor SDL nor the X Window system
+      will be needed.</para>
+
+      <para><orderedlist>
+          <listitem>
+            <para>On the headless server, create a new virtual machine:</para>
+
+            <screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
+
+            <para>Note that if you do not specify
+            <computeroutput>--register</computeroutput>, you will have to
+            manually use the registervm command later.</para>
+
+            <para>Note further that you do not need to specify
+            <computeroutput>--ostype</computeroutput> but doing so selects
+            some sane default values for certain VM parameters, for example
+            the RAM size and the type of the virtual network device. To get a
+            complete list of supported operating systems you can use</para>
+
+            <screen>VBoxManage list ostypes</screen>
+          </listitem>
+
+          <listitem>
+            <para>Make sure the settings for this VM are appropriate for the
+            guest operating system that we will install. For example:<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen></para>
+          </listitem>
+
+          <listitem>
+            <para>Create a virtual hard disk for the VM (in this case, 10GB in
+            size) and register it with VirtualBox:<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000 --remember</screen></para>
+          </listitem>
+
+          <listitem>
+            <para>Add an IDE Controller to the new VM:<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
+      --add ide --controller PIIX4</screen></para>
+          </listitem>
+
+          <listitem>
+            <para>Set this newly created VDI file as the first virtual hard
+            disk of the new VM:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
+      --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen></para>
+          </listitem>
+
+          <listitem>
+            <para>Register the ISO file that contains the operating system
+            installation that you want to install later:<screen>VBoxManage openmedium dvd /full/path/to/iso.iso</screen></para>
+          </listitem>
+
+          <listitem>
+            <para>Attach this ISO to the virtual machine, so it can boot from
+            it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
+      --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para>
+          </listitem>
+
+          <listitem>
+            <para>Start the virtual machine using VBoxHeadless:<screen>VBoxHeadless --startvm "Windows XP"</screen></para>
+
+            <para>If everything worked, you should see a copyright notice. If,
+            instead, you are returned to the command line, then something went
+            wrong.</para>
+          </listitem>
+
+          <listitem>
+            <para>On the client machine, fire up the RDP viewer and try to
+            connect to the server (see <xref linkend="rdp-viewers" /> above
+            for how to use various common RDP viewers).</para>
+
+            <para>You should now be seeing the installation routine of your
+            guest operating system in the RDP viewer.</para>
+          </listitem>
+        </orderedlist></para>
+    </sect2>
+
+    <sect2 id="usb-over-rdp">
+      <title>Remote USB</title>
+
+      <para>As a special feature on top of the VRDP support, VirtualBox
+      supports remote USB devices over the wire as well. That is, the
+      VirtualBox guest that runs on one computer can access the USB devices of
+      the remote computer on which the RDP data is being displayed the same
+      way as USB devices that are connected to the actual host. This allows
+      for running virtual machines on a VirtualBox host that acts as a server,
+      where a client can connect from elsewhere that needs only a network
+      adapter and a display capable of running an RDP viewer. When USB devices
+      are plugged into the client, the remote VirtualBox server can access
+      them.</para>
+
+      <para>For these remote USB devices, the same filter rules apply as for
+      other USB devices, as described with <xref linkend="settings-usb" />.
+      All you have to do is specify "Remote" (or "Any") when setting up these
+      rules.</para>
+
+      <para>Accessing remote USB devices is only possible if the RDP client
+      supports this extension. On Linux and Solaris hosts, the VirtualBox
+      installation provides a suitable RDP client called
+      <computeroutput>rdesktop-vrdp</computeroutput>. RDP clients for other
+      platforms will be provided in future VirtualBox versions.</para>
+
+      <para>To make a remote USB device available to a VM, rdesktop-vrdp
+      should be started as follows:<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>Note
+      that <computeroutput>rdesktop-vrdp</computeroutput> can access USB
+      devices only through <computeroutput>/proc/bus/usb</computeroutput>.
+      Please refer to <xref linkend="usb_linux" /> for further details on how
+      to properly set up the permissions. Furthermore it is advisable to
+      disable automatic loading of any host driver on the remote host which
+      might work on USB devices to ensure that the devices are accessible by
+      the RDP client. If the setup was properly done on the remote host,
+      plug/unplug events are visible on the VBox.log file of the VM.</para>
+    </sect2>
+
+    <sect2 id="vbox-auth">
+      <title>RDP authentication</title>
+
+      <para>For each virtual machine that is remotely accessible via RDP, you
+      can individually determine if and how RDP connections are
+      authenticated.</para>
+
+      <para>For this, use <computeroutput>VBoxManage modifyvm</computeroutput>
+      command with the <computeroutput>--vrdeauthtype</computeroutput> option;
+      see <xref linkend="vboxmanage-modifyvm" /> for a general introduction.
+      Three methods of authentication are available:<itemizedlist>
+          <listitem>
+            <para>The "null" method means that there is no authentication at
+            all; any client can connect to the VRDP server and thus the
+            virtual machine. This is, of course, very insecure and only to be
+            recommended for private networks.</para>
+          </listitem>
+
+          <listitem>
+            <para>The "external" method provides external authentication
+            through a special authentication library.</para>
+
+            <para>VirtualBox comes with three default libraries for external
+            authentication:<itemizedlist>
+                <listitem>
+                  <para>On Linux hosts,
+                  <computeroutput>VBoxAuth.so</computeroutput> authenticates
+                  users against the host's PAM system.</para>
+                </listitem>
+
+                <listitem>
+                  <para>On Windows hosts,
+                  <computeroutput>VBoxAuth.dll</computeroutput> authenticates
+                  users against the host's WinLogon system.</para>
+                </listitem>
+
+                <listitem>
+                  <para>On Mac OS X hosts,
+                  <computeroutput>VBoxAuth.dylib</computeroutput>
+                  authenticates users against the host's directory
+                  service.<footnote>
+                      <para>Support for Mac OS X was added in version
+                      3.2.</para>
+                    </footnote></para>
+                </listitem>
+              </itemizedlist></para>
+
+            <para>In other words, the "external" method per default performs
+            authentication with the user accounts that exist on the host
+            system. Any user with valid authentication credentials is
+            accepted, i.e. the username does not have to correspond to the
+            user running the VM.</para>
+          </listitem>
+          
+          <listitem>
+            <para>An additional library called
+            <computeroutput>VBoxAuthSimple</computeroutput> performs authentication
+            against credentials configured in the VM's extra data section. This is
+            probably the simplest way to get authentication that does not depend
+            on a running and supported guest (see below). In order to enable
+            VBoxAuthSimple, issue
+            <computeroutput>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</computeroutput>.
+            To enable the library for a VM, switch authentication to external using
+            <computeroutput>VBoxManage modifyvm "VM name" --vrdpauthtype external</computeroutput>.
+            Last but not least, you have to configure users and passwords. Here is an example
+            for the user "john" with the password "secret":
+            <computeroutput>VBoxManage internalcommands passwordhash "secret"</computeroutput>
+            This will give you the hash value "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"
+            which you set using
+            <computeroutput>VBoxManage setextradata "VM name" "VBoxAuthSimple/users/john"
+            "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"</computeroutput>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>Finally, the "guest" authentication method performs
+            authentication with a special component that comes with the Guest
+            Additions; as a result, authentication is not performed with the
+            host users, but with the guest user accounts. This method is
+            currently still in testing and not yet supported.</para>
+          </listitem>
+        </itemizedlist></para>
+        
+        <para>In addition to the methods described above, you can replace the
+        default "external authentication module with any other module. For this,
+        VirtualBox provides a well-defined interface that allows you to write your
+        own authentication module; see <xref linkend="vbox-authenticate-sdk" />
+        for details.</para>
+    </sect2>
+
+    <sect2 id="vrdp-crypt">
+      <title>RDP encryption</title>
+
+      <para>RDP features data stream encryption, which is based on the RC4
+      symmetric cipher (with keys up to 128bit). The RC4 keys are being
+      replaced in regular intervals (every 4096 packets).</para>
+
+      <para>RDP provides three different authentication methods:<orderedlist>
+          <listitem>
+            <para>Historically, RDP4 authentication was used, with which the
+            RDP client does not perform any checks in order to verify the
+            identity of the server it connects to. Since user credentials can
+            be obtained using a man in the middle (MITM) attack, RDP4
+            authentication is insecure and should generally not be
+            used.</para>
+          </listitem>
+
+          <listitem>
+            <para>RDP5.1 authentication employs a server certificate for which
+            the client possesses the public key. This way it is guaranteed
+            that the server possess the corresponding private key. However, as
+            this hard-coded private key became public some years ago, RDP5.1
+            authentication is also insecure and cannot be recommended.</para>
+          </listitem>
+
+          <listitem>
+            <para>RDP5.2 authentication is based on TLS 1.0 with
+            customer-supplied certificates. The server supplies a certificate
+            to the client which must be signed by a certificate authority (CA)
+            that the client trusts (for the Microsoft RDP Client 5.2, the CA
+            has to be added to the Windows Trusted Root Certificate
+            Authorities database). VirtualBox allows you to supply your own CA
+            and server certificate and uses OpenSSL for encryption.</para>
+          </listitem>
+        </orderedlist></para>
+
+      <para>While VirtualBox supports all of the above, only RDP5.2
+      authentication should be used in environments where security is a
+      concern. As the client that connects to the server determines what type
+      of encryption will be used, with rdesktop, the Linux RDP viewer, use the
+      <computeroutput>-4</computeroutput> or
+      <computeroutput>-5</computeroutput> options.</para>
+    </sect2>
+
+    <sect2 id="vrdp-multiconnection">
+      <title>Multiple VRDP connections</title>
+
+      <para>The built-in RDP server of VirtualBox supports simultaneous
+      connections to the same running VM from different clients. All connected
+      clients see the same screen output and share a mouse pointer and
+      keyboard focus. This is similar to several people using the same
+      computer at the same time, taking turns at the keyboard.</para>
+
+      <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdpmulticon on</screen></para>
+    </sect2>
+
+    <sect2 id="vrdp-multimonitor">
+      <title>Multiple remote monitors</title>
+
+      <para>
+      To access two or more remote VM displays you have to enable the
+      VRDP multiconnection mode (see <xref linkend="vrdp-multiconnection" />).</para>
+
+      <para>The RDP client can select the virtual monitor number to connect to
+        using the <computeroutput>domain</computeroutput> logon parameter
+        (<computeroutput>-d</computeroutput>). If
+      the parameter ends with <computeroutput>@</computeroutput> followed by a
+      number, the VirtualBox RDP server interprets this number as the screen index.
+      The primary guest screen is selected with
+      <computeroutput>@1</computeroutput>, the first secondary screen is
+      <computeroutput>@2</computeroutput>, etc.</para>
+
+      <para>The MS RDP6 client does not let you specify a separate domain
+      name. Instead, use <computeroutput>domain\username</computeroutput> in
+      the <computeroutput>Username:</computeroutput> field -- for example,
+      <computeroutput>@2\name</computeroutput>.
+      <computeroutput>name</computeroutput> must be supplied, and must be the
+      name used to log in if the VRDP server is set up to require credentials.
+      If it is not, you may use any text as the username.</para>
+    </sect2>
+
+    <sect2 id="vrdp-videochannel">
+      <title>VRDP video redirection</title>
+
+      <para>Starting with VirtualBox 3.2, the VRDP server can redirect video
+      streams from the guest to the RDP client. Video frames are compressed
+      using the JPEG algorithm allowing a higher compression ratio than
+      standard RDP bitmap compression methods. It is possible to increase the
+      compression ratio by lowering the video quality.</para>
+
+      <para>Video streams in a guest are detected by the VRDP server
+      automatically as frequently updated rectangular areas. Therefore, this
+      method works with any guest operating system without having to install
+      additional software in the guest.</para>
+
+      <para>On the client side, however, currently only the Windows 7 Remote
+      Desktop Connection client supports this feature. If a client does not
+      support video redirection, the VRDP server uses regular bitmap
+      updates.</para>
+
+      <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdpvideochannel on</screen></para>
+
+      <para>The quality of the video is defined as a value from 10 to 100
+      percent, as is common with JPEG compression. The quality can be changed
+      using the following command: <screen>VBoxManage modifyvm "VM name" --vrdpvideochannelquality 75</screen></para>
+    </sect2>
+
+    <sect2 id="vrdp-customization">
+      <title>VRDP customization</title>
+
+      <para>Starting with VirtualBox 3.2.10, it is possible to disable display output,
+      mouse and keyboard input, audio, remote USB or clipboard in the VRDP server.</para>
+
+      <para>The following commands change corresponding server settings:</para>
+
+      <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1
+VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1
+VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1
+VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableAudio" 1
+VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1</screen>
+
+      <para>To reenable a feature use a similar command without the trailing 1. For example:
+      <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="teleporting">
+    <title>Teleporting</title>
+
+    <para>Starting with version 3.1, VirtualBox supports "teleporting" -- that
+    is, moving a virtual machine over a network from one VirtualBox host to
+    another, while the virtual machine is running. This works regardless of
+    the host operating system that is running on the hosts: you can teleport
+    virtual machines between Solaris and Mac hosts, for example.</para>
+
+    <para>Teleporting requires that a machine be currently running on one
+    host, which is then called the <emphasis role="bold">"source"</emphasis>.
+    The host to which the virtual machine will be teleported will then be
+    called the <emphasis role="bold">"target"</emphasis>; the machine on the
+    target is then configured to wait for the source to contact the target.
+    The machine's running state will then be transferred from the source to
+    the target with minimal downtime.</para>
+
+    <para>Teleporting happens over any TCP/IP network; the source and the
+    target only need to agree on a TCP/IP port which is specified in the
+    teleporting settings.</para>
+
+    <para>At this time, there are a few prerequisites for this to work,
+    however:<orderedlist>
+        <listitem>
+          <para>On the target host, you must configure a virtual machine in
+          VirtualBox with exactly the same hardware settings as the machine on
+          the source that you want to teleport. This does not apply to
+          settings which are merely descriptive, such as the VM name, but
+          obviously for teleporting to work, the target machine must have the
+          same amount of memory and other hardware settings. Otherwise
+          teleporting will fail with an error message.</para>
+        </listitem>
+
+        <listitem>
+          <para>The two virtual machines on the source and the target must
+          share the same storage (hard disks as well as floppy and CD/DVD
+          images). This means that they either use the same iSCSI targets or
+          that the storage resides somewhere on the network and both hosts
+          have access to it via NFS or SMB/CIFS.</para>
+
+          <para>This also means that neither the source nor the target machine
+          can have any snapshots.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>Then perform the following steps:<orderedlist>
+        <listitem>
+          <para>On the <emphasis>target</emphasis> host, configure the virtual
+          machine to wait for a teleport request to arrive when it is started,
+          instead of actually attempting to start the machine. This is done
+          with the following VBoxManage command:<screen>VBoxManage modifyvm &lt;targetvmname&gt; --teleporter on --teleporterport &lt;port&gt;</screen></para>
+
+          <para>where <computeroutput>&lt;targetvmname&gt;</computeroutput> is
+          the name of the virtual machine on the target host and
+          <computeroutput>&lt;port&gt;</computeroutput> is a TCP/IP port
+          number to be used on both the source and the target hosts. For
+          example, use 6000. For details, see <xref
+          linkend="vboxmanage-modifyvm-teleport" />.</para>
+        </listitem>
+
+        <listitem>
+          <para>Start the VM on the target host. You will see that instead of
+          actually running, it will show a progress dialog. indicating that it
+          is waiting for a teleport request to arrive.</para>
+        </listitem>
+
+        <listitem>
+          <para>Start the machine on the <emphasis>source</emphasis> host as
+          usual. When it is running and you want it to be teleported, issue
+          the following command on the source host:<screen>VBoxManage controlvm &lt;sourcevmname&gt; teleport --host &lt;targethost&gt; --port &lt;port&gt;</screen></para>
+
+          <para>where <computeroutput>&lt;sourcevmname&gt;</computeroutput> is
+          the name of the virtual machine on the source host (the machine that
+          is currently running),
+          <computeroutput>&lt;targethost&gt;</computeroutput> is the host or
+          IP name of the target host on which the machine is waiting for the
+          teleport request, and <computeroutput>&lt;port&gt;</computeroutput>
+          must be the same number as specified in the command on the target
+          host. For details, see <xref
+          linkend="vboxmanage-controlvm" />.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>For testing, you can also teleport machines on the same host; in
+    that case, use "localhost" as the hostname on both the source and the
+    target host.<note>
+        <para>In rare cases, if the CPUs of the source and the target are very
+        different, teleporting can fail with an error message, or the target
+        may hang. This may happen especially if the VM is running application
+        software that is highly optimized to run on a particular CPU without
+        correctly checking that certain CPU features are actually present.
+        VirtualBox filters what CPU capabilities are presented to the guest
+        operating system. Advanced users can attempt to restrict these virtual
+        CPU capabilities with the <computeroutput>VBoxManage --modifyvm
+        --cpuid</computeroutput> command; see <xref
+        linkend="vboxmanage-modifyvm-teleport" />.</para>
+      </note></para>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_Glossary.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_Glossary.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_Glossary.xml	(revision 33555)
@@ -0,0 +1,433 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<glossary id="Glossary">
+  <glossdiv>
+    <title>A</title>
+
+    <glossentry>
+      <glossterm>ACPI</glossterm>
+
+      <glossdef>
+        <para>Advanced Configuration and Power Interface, an industry
+        specification for BIOS and hardware extensions to configure PC
+        hardware and perform power management. Windows 2000 and higher as well
+        as Linux 2.4 and higher support ACPI. Windows can only enable or
+        disable ACPI support at installation time.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>AHCI</glossterm>
+
+      <glossdef>
+        <para>Advanced Host Controller Interface, the interface that supports
+        SATA devices such as hard disks. See <xref
+        linkend="harddiskcontrollers" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>AMD-V</glossterm>
+
+      <glossdef>
+        <para>The hardware virtualization features built into modern AMD
+        processors. See <xref linkend="hwvirt" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>API</glossterm>
+
+      <glossdef>
+        <para>Application Programming Interface.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>APIC</glossterm>
+
+      <glossdef>
+        <para>Advanced Programmable Interrupt Controller, a newer version of
+        the original PC PIC (programmable interrupt controller). Most modern
+        CPUs contain an on-chip APIC ("local APIC"). Many systems also contain
+        an I/O APIC (input output APIC) as a separate chip which provides more
+        than 16 IRQs. Windows 2000 and higher use a different kernel if they
+        detect an I/O APIC during installation. Therefore an I/O APIC must not
+        be removed after installation.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>ATA</glossterm>
+
+      <glossdef>
+        <para>Advanced Technology Attachment, an industry standard for hard
+        disk interfaces (synonymous with IDE). See <xref
+        linkend="harddiskcontrollers" />.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>B</title>
+
+    <glossentry>
+      <glossterm>BIOS</glossterm>
+
+      <glossdef>
+        <para>Basic Input/Output System, the firmware built into most personal
+        computers which is responsible of initializing the hardware after the
+        computer has been turned on and then booting an operating system.
+        VirtualBox ships with its own virtual BIOS that runs when a virtual
+        machine is started.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>C</title>
+
+    <glossentry>
+      <glossterm>COM</glossterm>
+
+      <glossdef>
+        <para>Microsoft Component Object Model, a programming infrastructure
+        for modular software. COM allows applications to provide application
+        programming interfaces which can be accessed from various other
+        programming languages and applications. VirtualBox makes use of COM
+        both internally and externally to provide a comprehensive API to 3rd
+        party developers.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>D</title>
+
+    <glossentry>
+      <glossterm>DHCP</glossterm>
+
+      <glossdef>
+        <para>Dynamic Host Configuration Protocol. This allows a networking
+        device in a network to acquire its IP address (and other networking
+        details) automatically, in order to avoid having to configure all
+        devices in a network with fixed IP addresses. VirtualBox has a
+        built-in DHCP server that delivers an IP addresses to a virtual
+        machine when networking is configured to NAT; see <xref
+        linkend="networkingdetails" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>DKMS</glossterm>
+
+      <glossdef>
+        <para>Dynamic Kernel Module Support. A framework that simplifies
+        installing and updating external kernel modules on Linux machines; see
+        <xref linkend="externalkernelmodules" />.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>E</title>
+
+    <glossentry>
+      <glossterm>EFI</glossterm>
+
+      <glossdef>
+        <para>Extensible Firmware Interface, a firmware built into computers
+        which is designed to replace the aging BIOS. Originally designed by
+        Intel, most modern operating systems can now boot on computers which
+        have EFI instead of a BIOS built into them; see <xref
+        linkend="efi" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>EHCI</glossterm>
+
+      <glossdef>
+        <para>Enhanced Host Controller Interface, the interface that
+        implements the USB 2.0 standard.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>G</title>
+
+    <glossentry>
+      <glossterm>GUI</glossterm>
+
+      <glossdef>
+        <para>Graphical User Interface. Commonly used as an antonym to a
+        "command line interface", in the context of VirtualBox, we sometimes
+        refer to the main graphical
+        <computeroutput>VirtualBox</computeroutput> program as the "GUI", to
+        differentiate it from the <computeroutput>VBoxManage</computeroutput>
+        interface.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>GUID</glossterm>
+
+      <glossdef>
+        <para>See UUID.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>I</title>
+
+    <glossentry>
+      <glossterm>IDE</glossterm>
+
+      <glossdef>
+        <para>Integrated Drive Electronics, an industry standard for hard disk
+        interfaces. See <xref linkend="harddiskcontrollers" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>I/O APIC</glossterm>
+
+      <glossdef>
+        <para>See APIC.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>iSCSI</glossterm>
+
+      <glossdef>
+        <para>Internet SCSI; see <xref linkend="storage-iscsi" />.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>M</title>
+
+    <glossentry>
+      <glossterm>MAC</glossterm>
+
+      <glossdef>
+        <para>Media Access Control, a part of an Ethernet network card. A MAC
+        address is a 6-byte number which identifies a network card. It is
+        typically written in hexadecimal notation where the bytes are
+        separated by colons, such as
+        <computeroutput>00:17:3A:5E:CB:08</computeroutput>.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>N</title>
+
+    <glossentry>
+      <glossterm>NAT</glossterm>
+
+      <glossdef>
+        <para>Network Address Translation. A technique to share networking
+        interfaces by which an interface modifies the source and/or target IP
+        addresses of network packets according to specific rules. Commonly
+        employed by routers and firewalls to shield an internal network from
+        the Internet, VirtualBox can use NAT to easily share a host's physical
+        networking hardware with its virtual machines. See <xref
+        linkend="network_nat" />.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>O</title>
+
+    <glossentry>
+      <glossterm>OVF</glossterm>
+
+      <glossdef>
+        <para>Open Virtualization Format, a cross-platform industry standard
+        to exchange virtual appliances between virtualization products; see
+        <xref linkend="ovf" />.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>P</title>
+
+    <glossentry>
+      <glossterm>PAE</glossterm>
+
+      <glossdef>
+        <para>Physical Address Extension. This allows accessing more than 4 GB
+        of RAM even in 32-bit environments; see <xref
+        linkend="settings-general-advanced" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>PIC</glossterm>
+
+      <glossdef>
+        <para>See APIC.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>PXE</glossterm>
+
+      <glossdef>
+        <para>Preboot Execution Environment, an industry standard for booting
+        PC systems from remote network locations. It includes DHCP for IP
+        configuration and TFTP for file transfer. Using UNDI, a hardware
+        independent driver stack for accessing the network card from bootstrap
+        code is available.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>R</title>
+
+    <glossentry>
+      <glossterm>RDP</glossterm>
+
+      <glossdef>
+        <para>Remote Desktop Protocol, a protocol developed by Microsoft as an
+        extension to the ITU T.128 and T.124 video conferencing protocol. With
+        RDP, a PC system can be controlled from a remote location using a
+        network connection over which data is transferred in both directions.
+        Typically graphics updates and audio are sent from the remote machine
+        and keyboard and mouse input events are sent from the client.
+        VirtualBox contains an enhanced implementation of the relevant
+        standards called "VirtualBox RDP" (VRDP), which is largely compatible
+        with Microsoft's RDP implementation. See <xref linkend="vrdp" /> for
+        details.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>S</title>
+
+    <glossentry>
+      <glossterm>SAS</glossterm>
+
+      <glossdef>
+        <para>Serial Attached SCSI, an industry standard for hard disk
+        interfaces. See <xref linkend="harddiskcontrollers" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>SATA</glossterm>
+
+      <glossdef>
+        <para>Serial ATA, an industry standard for hard disk interfaces. See
+        <xref linkend="harddiskcontrollers" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>SCSI</glossterm>
+
+      <glossdef>
+        <para>Small Computer System Interface. An industry standard for data
+        transfer between devices, especially for storage. See <xref
+        linkend="harddiskcontrollers" />.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>SMP</glossterm>
+
+      <glossdef>
+        <para>Symmetrical Multiprocessing, meaning that the resources of a
+        computer are shared between several processors. These can either be
+        several processor chips or, as is more common with modern hardware,
+        multiple CPU cores in one processor.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>U</title>
+
+    <glossentry>
+      <glossterm>UUID</glossterm>
+
+      <glossdef>
+        <para>A Universally Unique Identifier -- often also called GUID
+        (Globally Unique Identifier) -- is a string of numbers and letters
+        which can be computed dynamically and is guaranteed to be unique.
+        Generally, it is used as a global handle to identify entities.
+        VirtualBox makes use of UUIDs to identify VMs, Virtual Disk Images
+        (VDI files) and other entities.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>V</title>
+
+    <glossentry>
+      <glossterm>VM</glossterm>
+
+      <glossdef>
+        <para>Virtual Machine -- a virtual computer that VirtualBox allows you
+        to run on top of your actual hardware. See <xref
+        linkend="virtintro" /> for details.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>VRDP</glossterm>
+
+      <glossdef>
+        <para>See RDP.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>VT-x</glossterm>
+
+      <glossdef>
+        <para>The hardware virtualization features built into modern Intel
+        processors. See <xref linkend="hwvirt" />.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
+  <glossdiv>
+    <title>X</title>
+
+    <glossentry>
+      <glossterm>XML</glossterm>
+
+      <glossdef>
+        <para>The eXtensible Markup Language, a metastandard for all kinds of
+        textual information. XML only specifies how data in the document is
+        organized generally and does not prescribe how to semantically
+        organize content.</para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry>
+      <glossterm>XPCOM</glossterm>
+
+      <glossdef>
+        <para>Mozilla Cross Platform Component Object Model, a programming
+        infrastructure developed by the Mozilla browser project which is
+        similar to Microsoft COM and allows applications to provide a modular
+        programming interface. VirtualBox makes use of XPCOM on Linux both
+        internally and externally to provide a comprehensive API to
+        third-party developers.</para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+</glossary>
Index: trunk/doc/manual/fr_FR/user_GuestAdditions.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_GuestAdditions.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_GuestAdditions.xml	(revision 33555)
@@ -0,0 +1,1533 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter>
+  <title id="guestadditions">Guest Additions</title>
+
+  <para>The previous chapter covered getting started with VirtualBox and
+  installing operating systems in a virtual machine. For any serious and
+  interactive use, the VirtualBox Guest Additions will make your life much
+  easier by providing closer integration between host and guest and improving
+  the interactive performance of guest systems. This chapter describes the
+  Guest Additions in detail.</para>
+
+  <sect1>
+    <title>Introduction</title>
+
+    <para>As said in <xref linkend="virtintro" />, the Guest Additions are
+    designed to be installed <emphasis>inside</emphasis> a virtual machine
+    after the guest operating system has been installed. They consist of
+    device drivers and system applications that optimize the guest operating
+    system for better performance and usability. Please see <xref
+    linkend="guestossupport" /> for details on what guest operating systems
+    are fully supported with Guest Additions by VirtualBox.</para>
+
+    <para>The VirtualBox Guest Additions for all supported guest operating
+    systems are provided as a single CD-ROM image file which is called
+    <computeroutput>VBoxGuestAdditions.iso</computeroutput>. This image file
+    is located in the installation directory of VirtualBox. To install the
+    Guest Additions for a particular VM, you mount this ISO file in your VM as
+    a virtual CD-ROM and install from there.</para>
+
+    <para>The Guest Additions offer the following features:<glosslist>
+        <glossentry>
+          <glossterm>Mouse pointer integration</glossterm>
+
+          <glossdef>
+            <para>To overcome the limitations for mouse support that were
+            described in <xref linkend="keyb_mouse_normal" />, this provides
+            you with seamless mouse support. You will only have one mouse
+            pointer and pressing the Host key is no longer required to "free"
+            the mouse from being captured by the guest OS. To make this work,
+            a special mouse driver is installed in the guest that communicates
+            with the "real" mouse driver on your host and moves the guest
+            mouse pointer accordingly.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Better video support</glossterm>
+
+          <glossdef>
+            <para>While the virtual graphics card which VirtualBox emulates
+            for any guest operating system provides all the basic features,
+            the custom video drivers that are installed with the Guest
+            Additions provide you with extra high and non-standard video modes
+            as well as accelerated video performance.</para>
+
+            <para>In addition, with Windows and recent Linux, Solaris and
+            OpenSolaris guests, if the Guest Additions are installed, you can
+            resize the virtual machine's window, and the video resolution in
+            the guest will be automatically adjusted (as if you had manually
+            entered an arbitrary resolution in the guest's display
+            settings).</para>
+
+            <para>Finally, if the Guest Additions are installed, 3D graphics
+            for guest applications can be accelerated; see <xref
+            linkend="guestadd-3d" />.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Time synchronization</glossterm>
+
+          <glossdef>
+            <para>With the Guest Additions installed, VirtualBox can ensure
+            that the guest's system time is better synchronized with that of
+            the host.</para>
+
+            <para>For various reasons, the time in the guest might run at a
+            slightly different rate than the time on the host. The host could
+            be receiving updates via NTP and its own time might not run
+            linearly. A VM could also be paused, which stops the flow of time
+            in the guest for a shorter or longer period of time. When the wall
+            clock time between the guest and host only differs slightly, the
+            time synchronization service attempts to gradually and smoothly
+            adjust the guest time in small increments to either "catch up" or
+            "lose" time. When the difference is too great (e.g., a VM paused
+            for hours or restored from saved state), the guest time is changed
+            immediately, without a gradual adjustment.</para>
+
+            <para>The Guest Additions will re-synchronize the time regularly.
+            See <xref linkend="changetimesync" /> for how to configure the
+            parameters of the time synchronization mechanism.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Shared folders</glossterm>
+
+          <glossdef>
+            <para>These provide an easy way to exchange files between the host
+            and the guest. Much like ordinary Windows network shares, you can
+            tell VirtualBox to treat a certain host directory as a shared
+            folder, and VirtualBox will make it available to the guest
+            operating system as a network share. For details, please refer to
+            <xref linkend="sharedfolders" />.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Seamless windows</glossterm>
+
+          <glossdef>
+            <para>With this feature, the individual windows that are displayed
+            on the desktop of the virtual machine can be mapped on the host's
+            desktop, as if the underlying application was actually running on
+            the host. See <xref linkend="seamlesswindows" /> for
+            details.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Shared clipboard</glossterm>
+
+          <glossdef>
+            <para>With the Guest Additions installed, the clipboard of the
+            guest operating system can optionally be shared with your host
+            operating system; see <xref linkend="generalsettings" />.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Automated logons (credentials passing)</glossterm>
+
+          <glossdef>
+            <para>For details, please see <xref linkend="autologon" />.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+
+    <para>Each version of VirtualBox, even minor releases, ship with their own
+    version of the Guest Additions. While the interfaces through which the
+    VirtualBox core communicates with the Guest Additions are kept stable so
+    that Guest Additions already installed in a VM should continue to work
+    when VirtualBox is upgraded on the host, for best results, it is
+    recommended to keep the Guest Additions at the same version.</para>
+
+    <para>Starting with VirtualBox 3.1, the Windows and Linux Guest Additions
+    therefore check automatically whether they have to be updated. If the host
+    is running a newer VirtualBox version than the Guest Additions, a
+    notification with further instructions is displayed in the guest.</para>
+
+    <para>To disable this update check for the Guest Additions of a given
+    virtual machine, set the value of its
+    <computeroutput>/VirtualBox/GuestAdd/CheckHostVersion</computeroutput>
+    guest property to <computeroutput>0</computeroutput>; see <xref
+    linkend="guestadd-guestprops" /> for details.</para>
+  </sect1>
+
+  <sect1>
+    <title>Installing and Maintaining Guest Additions</title>
+
+    <para>Guest Additions are available for virtual machines running Windows,
+    Linux, Solaris or OS/2. The following sections describe the specifics of
+    each variant in detail.</para>
+
+    <sect2 id="additions-windows">
+      <title>Guest Additions for Windows</title>
+
+      <para>The VirtualBox Windows Guest Additions are designed to be
+      installed in a virtual machine running a Windows operating system. The
+      following versions of Windows guests are supported:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Microsoft Windows NT 4.0 (any service pack)</para>
+        </listitem>
+
+        <listitem>
+          <para>Microsoft Windows 2000 (any service pack)</para>
+        </listitem>
+
+        <listitem>
+          <para>Microsoft Windows XP (any service pack)</para>
+        </listitem>
+
+        <listitem>
+          <para>Microsoft Windows Server 2003 (any service pack)</para>
+        </listitem>
+
+        <listitem>
+          <para>Microsoft Windows Server 2008</para>
+        </listitem>
+
+        <listitem>
+          <para>Microsoft Windows Vista (all editions)</para>
+        </listitem>
+
+        <listitem>
+          <para>Microsoft Windows 7 (all editions)</para>
+        </listitem>
+      </itemizedlist>
+
+      <sect3 id="mountingadditionsiso">
+        <title>Installation</title>
+
+        <para>In the "Devices" menu in the virtual machine's menu bar,
+        VirtualBox has a handy menu item named "Install guest additions",
+        which mounts the Guest Additions ISO file inside your virtual machine.
+        A Windows guest should then automatically start the Guest Additions
+        installer, which installs the Guest Additions into your Windows
+        guest.</para>
+
+        <note>
+          <para>For Direct 3D acceleration to work in a Windows Guest, you
+          must install the Guest Additions in "Safe Mode"; see <xref
+          linkend="KnownIssues" /> for details.</para>
+        </note>
+
+        <para>If you prefer to mount the additions manually, you can perform
+        the following steps:</para>
+
+        <orderedlist>
+          <listitem>
+            <para>Start the virtual machine in which you have installed
+            Windows.</para>
+          </listitem>
+
+          <listitem>
+            <para>Select "Mount CD/DVD-ROM" from the "Devices" menu in the
+            virtual machine's menu bar and then "CD/DVD-ROM image". This
+            brings up the Virtual Media Manager described in <xref
+            linkend="vdis" />.</para>
+          </listitem>
+
+          <listitem>
+            <para>In the Virtual Media Manager, press the "Add" button and
+            browse your host file system for the
+            <computeroutput>VBoxGuestAdditions.iso</computeroutput>
+            file:<itemizedlist>
+                <listitem>
+                  <para>On a Windows host, you can find this file in the
+                  VirtualBox installation directory (usually under
+                  <computeroutput>C:\Program
+                  files\Oracle\VirtualBox</computeroutput> ).</para>
+                </listitem>
+
+                <listitem>
+                  <para>On Mac OS X hosts, you can find this file in the
+                  application bundle of VirtualBox. (Right click on the
+                  VirtualBox icon in Finder and choose <emphasis>Show Package
+                  Contents</emphasis>. There it is located in the
+                  <computeroutput>Contents/MacOS</computeroutput>
+                  folder.)</para>
+                </listitem>
+
+                <listitem>
+                  <para>On a Linux host, you can find this file in the
+                  <computeroutput>additions</computeroutput> folder under
+                  where you installed VirtualBox (normally
+                  <computeroutput>/opt/VirtualBox/</computeroutput>).</para>
+                </listitem>
+
+                <listitem>
+                  <para>On Solaris hosts, you can find this file in the
+                  <computeroutput>additions</computeroutput> folder under
+                  where you installed VirtualBox (normally
+                  <computeroutput>/opt/VirtualBox</computeroutput>).</para>
+                </listitem>
+              </itemizedlist></para>
+          </listitem>
+
+          <listitem>
+            <para>Back in the Virtual Media Manager, select that ISO file and
+            press the "Select" button. This will mount the ISO file and
+            present it to your Windows guest as a CD-ROM.</para>
+          </listitem>
+        </orderedlist>
+
+        <para>Unless you have the Autostart feature disabled in your Windows
+        guest, Windows will now autostart the VirtualBox Guest Additions
+        installation program from the Additions ISO. If the Autostart feature
+        has been turned off, choose
+        <computeroutput>VBoxWindowsAdditions.exe</computeroutput> from the
+        CD/DVD drive inside the guest to start the installer.</para>
+
+        <para>The installer will add several device drivers to the Windows
+        driver database and then invoke the hardware detection wizard.</para>
+
+        <para>Depending on your configuration, it might display warnings that
+        the drivers are not digitally signed. You must confirm these in order
+        to continue the installation and properly install the
+        Additions.</para>
+
+        <para>After installation, reboot your guest operating system to
+        activate the Additions.</para>
+      </sect3>
+
+      <sect3>
+        <title>Updating the Windows Guest Additions</title>
+
+        <para>Windows Guest Additions can be updated by running the
+        installation program again, as previously described. This will then
+        replace the previous Additions drivers with updated versions.</para>
+
+        <para>Alternatively, you may also open the Windows Device Manager and
+        select "Update driver..." for two devices:</para>
+
+        <orderedlist>
+          <listitem>
+            <para>the VirtualBox Graphics Adapter and</para>
+          </listitem>
+
+          <listitem>
+            <para>the VirtualBox System Device.</para>
+          </listitem>
+        </orderedlist>
+
+        <para>For each, choose to provide your own driver and use "Have Disk"
+        to point the wizard to the CD-ROM drive with the Guest
+        Additions.</para>
+      </sect3>
+
+      <sect3>
+        <title>Unattended Installation</title>
+
+        <para>In order to allow for completely unattended guest installations,
+        you can specify a command line parameter to the install
+        launcher:</para>
+
+        <screen>VBoxWindowsAdditions.exe /S</screen>
+
+        <para>This automatically installs the right files and drivers for the
+        corresponding platform (32- or 64-bit).</para>
+
+        <note>
+          <para>Because of the drivers are not yet WHQL certified, you still
+          might get some driver installation popups, depending on the Windows
+          guest version.</para>
+        </note>
+
+        <para>For more options regarding unattended guest installations,
+        consult the command line help by using the command:</para>
+
+        <screen>VBoxWindowsAdditions.exe /?</screen>
+      </sect3>
+
+      <sect3 id="windows-guest-file-extraction">
+        <title>Manual file extraction</title>
+
+        <para>If you would like to install the files and drivers manually, you
+        can extract the files from the Windows Guest Additions setup by
+        typing:</para>
+
+        <screen>VBoxWindowsAdditions.exe /extract</screen>
+
+        <para>To explicitly extract the Windows Guest Additions for another
+        platform than the current running one (e.g. 64-bit files on a 32-bit
+        system), you have to execute the appropriate platform installer
+        (<computeroutput>VBoxWindowsAdditions-x86.exe</computeroutput> or
+        <computeroutput>VBoxWindowsAdditions-amd64.exe</computeroutput>) with
+        the <computeroutput>/extract</computeroutput> parameter.</para>
+      </sect3>
+
+      <sect3 id="vista_networking">
+        <title>Windows Vista networking</title>
+
+        <para>Earlier versions of VirtualBox provided a virtual AMD PCNet
+        Ethernet card to guests by default. Since Microsoft no longer ships a
+        driver for that card with Windows (starting with Windows Vista), if
+        you select Windows Vista or newer as the guest operating system for a
+        virtual machine, VirtualBox will instead present a virtual Intel
+        network controller to the guest (see <xref
+        linkend="nichardware" />).</para>
+
+        <para>However, if for any reason you have a 32-bit Windows Vista VM
+        that is configured to use an AMD PCNet card, you will have no
+        networking in the guest initially.</para>
+
+        <para>As a convenience, VirtualBox ships with a 32-bit driver for the
+        AMD PCNet card, which comes with the Windows Guest Additions. If you
+        install these in a 32-bit Vista guest, the driver will automatically
+        be installed as well. If, for some reason, you would like to install
+        the driver manually, you can extract the required files from the
+        Windows Guest Additions setup. Please consult <xref
+        linkend="windows-guest-file-extraction" /> on how to achieve this. You
+        will then find the AMD PCNet driver files in the
+        <computeroutput>x86\Network\AMD\netamd.inf</computeroutput>
+        subdirectory of the default install directory.</para>
+
+        <para>Alternatively, change the Vista guest's VM settings to use an
+        Intel networking card instead of the default AMD PCNet card; see <xref
+        linkend="settings-network" /> for details.</para>
+
+        <para>Unfortunately, there is no 64-bit driver available for the AMD
+        PCNet card. So for 64-bit Windows VMs, you should always use the Intel
+        networking devices.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Guest Additions for Linux</title>
+
+      <para>Like the Windows Guest Additions, the VirtualBox Guest Additions
+      for Linux take the form of a set of device drivers and system
+      applications which may be installed in the guest operating
+      system.</para>
+
+      <para>The following Linux distributions are officially supported:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Fedora as of Fedora Core 4;</para>
+        </listitem>
+
+        <listitem>
+          <para>Redhat Enterprise Linux as of version 3;</para>
+        </listitem>
+
+        <listitem>
+          <para>SUSE and openSUSE Linux as of version 9;</para>
+        </listitem>
+
+        <listitem>
+          <para>Ubuntu as of version 5.10.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Many other distributions are known to work with the Guest
+      Additions.</para>
+
+      <para>The version of the Linux kernel supplied by default in SUSE and
+      openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06 (server
+      edition) contains a bug which can cause it to crash during startup when
+      it is run in a virtual machine. The Guest Additions work in those
+      distributions.</para>
+
+      <para>Note that some Linux distributions already come with VirtualBox
+      Guest Additions or a part thereof. You may keep the distribution's
+      version of the Guest Additions but often, these are not up to date
+      and limited in functionality. Therefore, you can choose the install
+      the Guest Additions that come with VirtualBox, overriding the already
+      installed version. The VirtualBox Linux Guest Additions installer tries
+      to detect existing installation and replace them but depending on how
+      the distribution integrates the Guest Additions, they may require some
+      manual interaction. It is highly recommended to take a snapshot of the
+      virtual machine before overriding the installation.</para>
+
+      <sect3>
+        <title>Installing the Linux Guest Additions</title>
+
+        <para>The VirtualBox Guest Additions for Linux are provided on the
+        same ISO CD-ROM as the Additions for Windows described above. They
+        also come with an installation program guiding you through the setup
+        process, although, due to the significant differences between Linux
+        distributions, installation may be slightly more complex.</para>
+
+        <para>Installation generally involves the following steps:</para>
+
+        <orderedlist>
+          <listitem>
+            <para>Before installing the Guest Additions, you will have to
+            prepare your guest system for building external kernel modules.
+            This works similarly as described in <xref
+            linkend="externalkernelmodules" />, except that this step must now
+            be performed in your Linux <emphasis>guest</emphasis> instead of
+            on a Linux host system, as described there.</para>
+
+            <para>Again, as with Linux hosts, we recommend using DKMS for
+            Linux guests as well. If it is not installed, use this
+            command for Ubuntu/Debian systems:<screen>sudo apt-get install dkms</screen>
+            or for Fedora systems: <screen>yum install dkms</screen></para>
+
+            <para>Make sure to nstall DKMS <emphasis>before</emphasis> installing the
+            Linux Guest Additions.</para>
+          </listitem>
+
+          <listitem>
+            <para>Mount the
+            <computeroutput>VBoxGuestAdditions.iso</computeroutput> file as
+            your Linux guest's virtual CD-ROM drive, exactly the same way as
+            described for a Windows guest in <xref
+            linkend="mountingadditionsiso" />.</para>
+          </listitem>
+
+          <listitem>
+            <para>Change to the directory where your CD-ROM drive is mounted
+            and execute as root:</para>
+
+            <screen>sh ./VBoxLinuxAdditions-x86.run</screen>
+
+            <para>In a 64-bit Linux guest, use
+            <computeroutput>VBoxLinuxAdditions-amd64.run</computeroutput>
+            instead.</para>
+          </listitem>
+        </orderedlist>
+
+        <para>For your convenience, the following step-by-step instructions
+        have been verified to work for freshly installed copies of the most
+        popular Linux distributions. After these preparational steps, you
+        can execute the VirtualBox Guest Additions installer as described
+        above.</para>
+
+        <sect4><title>Ubuntu 10.04 ("Lucid Lynx")</title><para>
+        <orderedlist>
+          <listitem>
+            <para>In order to update your system to the latest version
+            of the packets, open a terminal and as root, execute
+            <screen>apt-get update</screen>
+            followed by
+            <screen>apt-get upgrade</screen></para>
+          </listitem>
+          <listitem>
+            <para>Install DKMS using
+            <screen>apt-get install dkms</screen></para>
+          </listitem>
+          <listitem>
+            <para>Reboot your guest system in order to activate the
+            updates and then proceed as described above.</para>
+          </listitem>
+        </orderedlist></para></sect4>
+
+        <sect4><title>Fedora 13 ("Goddard")</title><para>
+        <orderedlist>
+          <listitem>
+            <para>In order to update your system to the latest version
+            of the packets, open a terminal and as root, execute
+            <screen>yum update</screen></para>
+          </listitem>
+          <listitem>
+            <para>Install DKMS and the GNU C compiler using
+            <screen>yum install dkms</screen>
+            followed by
+            <screen>yum install gcc</screen></para>
+          </listitem>
+          <listitem>
+            <para>Reboot your guest system in order to activate the
+            updates and then proceed as described above.</para>
+          </listitem>
+        </orderedlist></para></sect4>
+
+        <sect4><title>openSUSE 11.2</title><para>
+        <orderedlist>
+          <listitem>
+            <para>In order to update your system to the latest version
+            of the packets, open a terminal and as root, execute
+            <screen>zypper update</screen></para>
+          </listitem>
+          <listitem>
+            <para>Install the make tool and the GNU C compiler using
+            <screen>zypper install make gcc</screen></para>
+          </listitem>
+          <listitem>
+            <para>Reboot your guest system in order to activate the
+            updates.</para>
+          </listitem>
+          <listitem>
+            <para>Find out which kernel you are running using
+            <screen>uname -a</screen>
+            An example would be <computeroutput>2.6.31.12-0.2-default</computeroutput>
+            which refers to the "default" kernel. Then install the correct kernel
+            development package. In the above example this would be
+            <screen>zypper install kernel-default-devel</screen></para>
+          </listitem>
+          <listitem>
+            <para>Make sure that your running kernel
+            (<computeroutput>uname -a</computeroutput>) and the kernel packages
+            you have installed (<computeroutput>rpm -qa kernel\*</computeroutput>)
+            have the exact same version number. Proceed with the installation as described
+            above.</para>
+          </listitem>
+        </orderedlist></para></sect4>
+
+        <sect4><title>SuSE Linux Enterprise Desktop (SLED) 11</title><para>
+        <orderedlist>
+          <listitem>
+            <para>In order to update your system to the latest version
+            of the packets, open a terminal and as root, execute
+            <screen>zypper update</screen></para>
+          </listitem>
+          <listitem>
+            <para>Install the GNU C compiler using
+            <screen>zypper install gcc</screen></para>
+          </listitem>
+          <listitem>
+            <para>Reboot your guest system in order to activate the
+            updates.</para>
+          </listitem>
+          <listitem>
+            <para>Find out which kernel you are running using
+            <screen>uname -a</screen>
+            An example would be <computeroutput>2.6.27.19-5.1-default</computeroutput>
+            which refers to the "default" kernel. Then install the correct kernel
+            development package. In the above example this would be
+            <screen>zypper install kernel-syms kernel-source</screen></para>
+          </listitem>
+          <listitem>
+            <para>Make sure that your running kernel
+            (<computeroutput>uname -a</computeroutput>) and the kernel packages
+            you have installed (<computeroutput>rpm -qa kernel\*</computeroutput>)
+            have the exact same version number. Proceed with the installation as described
+            above.</para>
+          </listitem>
+        </orderedlist></para></sect4>
+
+        <sect4><title>Mandrake 2010</title><para>
+        <orderedlist>
+          <listitem>
+            <para>Mandrake ships with the VirtualBox Guest Additions which
+            will be replaced if you follow these steps.</para>
+          </listitem>
+          <listitem>
+            <para>In order to update your system to the latest version
+            of the packets, open a terminal and as root and execute
+            <screen>urpmi --auto-update</screen></para>
+          </listitem>
+          <listitem><para>Reboot your system in order to activate the updates.</para>
+          </listitem>
+          <listitem><para>Install DKMS using
+            <screen>urpmi dkms</screen>
+            and make sure the choose the correct kernel-devel package when asked
+            by the installer (use <computeroutput>uname -a</computeroutput> to compare).</para>
+          </listitem>
+        </orderedlist></para></sect4>
+
+        <sect4><title>CentOS 5.5, Red Hat Enterprise Linux 5.5 and Oracle Enterprise
+            Linux 5.5</title><para>
+        <orderedlist>
+          <listitem>
+            <para>Add <computeroutput>divider=10</computeroutput> to the kernel boot options
+            in <computeroutput>/etc/grub.conf</computeroutput> to reduce the idle CPU load.</para>
+          </listitem>
+          <listitem>
+            <para>To update your system to the latest version
+            of the packets, open a terminal and as root, execute
+            <screen>yum update</screen></para>
+          </listitem>
+          <listitem>
+            <para>Install the GNU C compiler and the kernel development packages using
+            <screen>yum install gcc</screen>
+            followed by
+            <screen>yum install kernel-devel</screen></para>
+          </listitem>
+          <listitem>
+            <para>Reboot your guest system in order to activate the
+            updates and then proceed as described above.</para>
+          </listitem>
+          <listitem>
+            <para>Note that OpenGL support is not available unless you update to a later Linux kernel.</para>
+            <para>In case Oracle Enterprise Linux does not find the required packages, you either have to
+            install them from a different source (e.g. DVD) or use Oracle's public Yum server located at
+            <ulink url="http://public-yum.oracle.com/">http://public-yum.oracle.com</ulink>.</para>
+          </listitem>
+        </orderedlist></para></sect4>
+
+        <sect4><title>Debian 5 ("Lenny")</title><para>
+        <orderedlist>
+          <listitem>
+            <para>In order to update your system to the latest version
+            of the packets, open a terminal and as root, execute
+            <screen>apt-get update</screen>
+            followed by
+            <screen>apt-get upgrade</screen></para>
+          </listitem>
+          <listitem>
+            <para>Install the make tool and the GNU C compiler using
+            <screen>apt-get install make gcc</screen></para>
+          </listitem>
+          <listitem>
+            <para>Reboot your guest system in order to activate the
+            updates.</para>
+          </listitem>
+          <listitem>
+            <para>Determine the exact version of your kernel using
+            <computeroutput>uname -a</computeroutput> and install the correct version
+            of the linux-headers package, e.g. using
+            <screen>apt-get install linux-headers-2.6.26-2-686</screen></para>
+
+          <listitem>
+            <para>Note that OpenGL support is not available unless you update to a later Linux kernel.</para>
+          </listitem>
+          </listitem>
+        </orderedlist></para></sect4>
+        </sect3>
+
+        <sect3><title>Manual setup of selected guest services</title>
+        <para>The VirtualBox Guest Additions contain several different
+        drivers. If for any reason you do not wish to set them all up, you can
+        install the Guest Additions using the following command:</para>
+
+        <screen>  sh ./VBoxLinuxAdditions-x86.run no_setup</screen>
+
+        <para>(substituting <computeroutput>VBoxLinuxAdditions-amd64
+        </computeroutput> on a 64-bit guest).</para>
+
+        <para>After this, you will need to at least compile the kernel modules
+        by running the command <screen>  /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
+        as root (you will need to replace <emphasis>lib</emphasis> by
+        <emphasis>lib64</emphasis>
+        on some 64bit guests), and on older guests without the udev service
+        you will need to add the <emphasis>vboxadd</emphasis> service to the
+        default runlevel to ensure that the modules get loaded.</para>
+
+        <para>To setup the time synchronization service, run the command
+        <screen>  /usr/lib/VBoxGuestAdditions/vboxadd-service setup</screen>
+        and add the service vboxadd-service to the default runlevel. To set up
+        the X11 and OpenGL part of the Guest Additions, run the command
+        <screen>  /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup</screen> (you
+        do not need to enable any services for this).</para>
+
+        <para>To recompile the guest kernel modules, use this command:
+        <screen>  /usr/lib/VBoxGuestAdditions/vboxadd setup</screen> After
+        compilation you should reboot your guest to ensure that the new
+        modules are actually used.</para>
+      </sect3>
+
+      <sect3>
+        <title>Video acceleration and high resolution graphics modes</title>
+
+        <para>In Linux guests, VirtualBox video acceleration is available
+        through the X Window System. Typically, in today's Linux
+        distributions, this will be the X.Org server. During the installation
+        process, X will be set up to use the VirtualBox video driver shipped
+        with the Guest Additions.</para>
+
+        <para>For Linux and Solaris guests, the X.org server version 1.3 or
+        later is required for automatic resizing (the feature has been
+        disabled on Fedora 9 guests due to a bug in the X server they supply).
+        The server version can be checked with <computeroutput>Xorg
+        -version</computeroutput>.</para>
+
+        <para>You can also send video mode hints using the
+        <computeroutput>VBoxManage</computeroutput> tool.</para>
+
+        <para>If you are only using recent Linux guests systems, you can skip
+        the rest of this section. On older guest systems, whatever graphics
+        modes were set up before the installation will be used. If these modes
+        do not suit your requirements, you can change your setup by editing
+        the configuration file of the X server, usually found in
+        <computeroutput>/etc/X11/xorg.conf</computeroutput>.</para>
+
+        <para>VirtualBox can use any default X graphics mode which fits into
+        the virtual video memory allocated to the virtual machine, as
+        described in <xref linkend="generalsettings" />. You can also add your
+        own modes to the X server configuration file. You simply need to add
+        them to the "Modes" list in the "Display" subsection of the "Screen"
+        section. For example, the section shown here has a custom 2048x800
+        resolution mode added:</para>
+
+        <screen>Section "Screen"
+        Identifier    "Default Screen"
+        Device        "VirtualBox graphics card"
+        Monitor       "Generic Monitor"
+        DefaultDepth  24
+        SubSection "Display"
+                Depth         24
+                Modes         "2048x800" "800x600" "640x480"
+        EndSubSection
+EndSection</screen>
+      </sect3>
+
+      <sect3>
+        <title>Updating the Linux Guest Additions</title>
+
+        <para>The Guest Additions can simply be updated by going through the
+        installation procedure again with an updated CD-ROM image. This will
+        replace the drivers with updated versions. You should reboot after
+        updating the Guest Additions.</para>
+      </sect3>
+
+      <sect3>
+        <title>Uninstalling the Linux Guest Additions</title>
+
+        <para>If you have a version of the Guest Additions installed on your
+        virtual machine and wish to remove it without installing new ones,
+        you can do so by inserting the Guest Additions CD image into the
+        virtual CD-ROM drive as described above and running the installer for
+        the current Guest Additions with the "uninstall" parameter from the
+        path that the CD image is mounted on in the guest:
+        <screen>sh ./VBoxLinuxAdditions-x86.run uninstall</screen>
+        <para>(substituting <computeroutput>VBoxLinuxAdditions-amd64</computeroutput>
+          on a 64-bit guest).  While this will normally work
+        without issues, you may need to do some manual clean up of the guest
+        (particularly of the XFree86Config or xorg.conf file) in some cases,
+        particularly if the Additions version installed or the guest
+        operating system were very old, or if you made your own changes to
+        the Guest Additions setup after you installed them.</para>
+       </para>
+       <para>
+         Starting with version 3.1.0, you can uninstall the Additions
+         by invoking
+         <screen>/opt/VBoxGuestAdditions-$VBOX_VERSION_STRING/uninstall.sh</screen>
+         substituting <computeroutput>/opt/VBoxGuestAdditions-$VBOX_VERSION_STRING</computeroutput>
+         with the Guest Additions installation directory.
+       </para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Guest Additions for Solaris</title>
+
+      <para>Like the Windows Guest Additions, the VirtualBox Guest Additions
+      for Solaris take the form of a set of device drivers and system
+      applications which may be installed in the guest operating
+      system.</para>
+
+      <para>The following Solaris distributions are officially
+      supported:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>OpenSolaris Nevada (Build 82 and higher; this includes
+          OpenSolaris 2008.05, 2008.11 and 2009.06);</para>
+        </listitem>
+
+        <listitem>
+          <para>OpenSolaris Indiana (Developer Preview 2 and higher);</para>
+        </listitem>
+
+        <listitem>
+          <para>Solaris 10 (u5 and higher).</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Other distributions may work if they are based on comparable
+      software releases.</para>
+
+      <sect3>
+        <title>Installing the Solaris Guest Additions</title>
+
+        <para>The VirtualBox Guest Additions for Solaris are provided on the
+        same ISO CD-ROM as the Additions for Windows and Linux described
+        above. They also come with an installation program guiding you through
+        the setup process.</para>
+
+        <para>Installation involves the following steps:</para>
+
+        <orderedlist>
+          <listitem>
+            <para>Mount the
+            <computeroutput>VBoxGuestAdditions.iso</computeroutput> file as
+            your Solaris guest's virtual CD-ROM drive, exactly the same way as
+            described for a Windows guest in <xref
+            linkend="mountingadditionsiso" />.</para>
+
+            <para>If in case the CD-ROM drive on the guest doesn't get mounted
+            (observed on some versions of Solaris 10), execute as root:</para>
+
+            <screen>svcadm restart volfs</screen>
+          </listitem>
+
+          <listitem>
+            <para>Change to the directory where your CD-ROM drive is mounted
+            and execute as root:</para>
+
+            <screen>pkgadd -G -d ./VBoxSolarisAdditions.pkg</screen>
+          </listitem>
+
+          <listitem>
+            <para>Choose "1" and confirm installation of the Guest Additions
+            package. After the installation is complete, re-login to X server
+            on your guest to activate the X11 Guest Additions.</para>
+          </listitem>
+        </orderedlist>
+      </sect3>
+
+      <sect3>
+        <title>Uninstalling the Solaris Guest Additions</title>
+
+        <para>The Solaris Guest Additions can be safely removed by removing
+        the package from the guest. Open a root terminal session and
+        execute:</para>
+
+        <para><screen>pkgrm SUNWvboxguest</screen></para>
+      </sect3>
+
+      <sect3>
+        <title>Updating the Solaris Guest Additions</title>
+
+        <para>The Guest Additions should be updated by first uninstalling the
+        existing Guest Additions and then installing the new ones. Attempting
+        to install new Guest Additions without removing the existing ones is
+        not possible.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Guest Additions for OS/2</title>
+
+      <para>VirtualBox also ships with a set of drivers that improve running
+      OS/2 in a virtual machine. Due to restrictions of OS/2 itself, this
+      variant of the Guest Additions has a limited feature set; see <xref
+      linkend="KnownIssues" /> for details.</para>
+
+      <para>The OS/2 Guest Additions are provided on the same ISO CD-ROM as
+      those for the other platforms. As a result, mount the ISO in OS/2 as
+      described previously. The OS/2 Guest Additions are located in the
+      directory <computeroutput>\32bit\OS2</computeroutput>.</para>
+
+      <para>As we do not provide an automatic installer at this time, please
+      refer to the <computeroutput>readme.txt</computeroutput> file in that
+      directory, which describes how to install the OS/2 Guest Additions
+      manually.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="sharedfolders">
+    <title>Shared folders</title>
+
+    <para>With the "shared folders" feature of VirtualBox, you can access
+    files of your host system from within the guest system. This is similar
+    how you would use network shares in Windows networks -- except that shared
+    folders do not need require networking, so long as the Guest Additions are
+    installed. Shared Folders are supported with Windows (2000 or newer),
+    Linux and Solaris guests.</para>
+
+    <para>Shared folders must physically reside on the
+    <emphasis>host</emphasis> and are then shared with the guest; sharing is
+    accomplished using a special service on the host and a file system driver
+    for the guest, both of which are provided by VirtualBox. For Windows
+    guests, shared folders are implemented as a pseudo-network redirector; for
+    Linux and Solaris guests, the Guest Additions provide a virtual filesystem
+    driver which handles communication with the host.</para>
+
+    <para>To share a host folder with a virtual machine in VirtualBox, you
+    must specify the path of that folder and choose for it a "share name" that
+    the guest can use to access it. Hence, first create the shared folder on
+    the host; then, within the guest, connect to it.</para>
+
+    <para>There are several ways in which shared folders can be set up for a
+    particular virtual machine:<itemizedlist>
+        <listitem>
+          <para>In the graphical user interface of a running virtual machine,
+          you can select "Shared folders" from the "Devices" menu, or click on
+          the folder icon on the status bar in the bottom right corner of the
+          virtual machine window.</para>
+        </listitem>
+
+        <listitem>
+          <para>If a virtual machine is not currently running, you can
+          configure shared folders in each virtual machine's "Settings"
+          dialog.</para>
+        </listitem>
+
+        <listitem>
+          <para>From the command line, you can create shared folders using the
+          VBoxManage command line interface; see <xref
+          linkend="vboxmanage" />. The command is as follows: <screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen></para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>There are two types of shares:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>VM shares which are only available to the VM for which they have
+        been defined;</para>
+      </listitem>
+
+      <listitem>
+        <para>transient VM shares, which can be added and removed at runtime
+        and do not persist after a VM has stopped; for these, add the
+        <computeroutput>--transient</computeroutput> option to the above
+        command line.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>Shared folders have read/write access to the files at the host path
+    by default. To restrict the guest to have read-only access, create a
+    read-only shared folder. This can either be achieved using the GUI or by
+    appending the parameter <computeroutput>--readonly</computeroutput> when
+    creating the shared folder with VBoxManage.</para>
+
+    <sect2 id="sf_mount_manual">
+      <title>Manual mounting</title>
+
+        <para>You can mount the shared folder from inside a VM the same way
+        as you would mount an ordinary network share:</para>
+
+        <para><itemizedlist>
+        <listitem>
+          <para>In a Windows guest, starting with VirtualBox 1.5.0, shared
+          folders are browseable and are therefore visible in Windows
+          Explorer. So, to attach the host's shared folder to your Windows
+          guest, open Windows Explorer and look for it under "My Networking
+          Places" -&gt; "Entire Network" -&gt; "VirtualBox Shared Folders". By
+          right-clicking on a shared folder and selecting "Map network drive"
+          from the menu that pops up, you can assign a drive letter to that
+          shared folder.</para>
+
+          <para>Alternatively, on the Windows command line, use the
+          following:</para>
+
+          <screen>net use x: \\vboxsvr\sharename</screen>
+
+          <para>While <computeroutput>vboxsvr</computeroutput> is a fixed name
+          (note that <computeroutput>vboxsrv</computeroutput> would also
+          work), replace "x:" with the drive letter that you want to use for
+          the share, and <computeroutput>sharename</computeroutput> with the
+          share name specified with
+          <computeroutput>VBoxManage</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>In a Linux guest, use the following command:</para>
+
+          <screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen>
+
+          <para>To mount a shared folder during boot, add the following entry
+          to /etc/fstab:</para>
+
+          <screen>sharename   mountpoint   vboxsf   defaults  0   0</screen>
+        </listitem>
+
+        <listitem>
+          <para>In a Solaris guest, use the following command:</para>
+
+          <screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen>
+
+          <para>Replace <computeroutput>sharename</computeroutput> (use
+          lowercase) with the share name specified with
+          <computeroutput>VBoxManage</computeroutput> or the GUI, and
+          <computeroutput>mountpoint</computeroutput> with the path where you
+          want the share to be mounted on the guest (e.g.
+          <computeroutput>/mnt/share</computeroutput>). The usual mount rules
+          apply, that is, create this directory first if it does not exist
+          yet.</para>
+
+          <para>Here is an example of mounting the shared folder for the user
+          "jack" on OpenSolaris:</para>
+
+          <screen>$ id
+uid=5000(jack) gid=1(other)
+$ mkdir /export/home/jack/mount
+$ pfexec mount -F vboxfs -o uid=5000,gid=1 jackshare /export/home/jack/mount
+$ cd ~/mount
+$ ls
+sharedfile1.mp3 sharedfile2.txt
+$</screen>
+          <para>Beyond the standard options supplied by the
+          <computeroutput>mount</computeroutput> command, the following are
+          available:</para>
+
+          <screen>iocharset CHARSET</screen>
+
+          <para>to set the character set used for I/O operations (utf8 by
+          default) and</para>
+
+          <screen>convertcp CHARSET</screen>
+
+          <para>to specify the character set used for the shared folder name
+          (utf8 by default).</para>
+
+          <para>The generic mount options (documented in the mount manual
+          page) apply also. Especially useful are the options
+          <computeroutput>uid</computeroutput>,
+          <computeroutput>gid</computeroutput> and
+          <computeroutput>mode</computeroutput>, as they allow access by
+          normal users (in read/write mode, depending on the settings) even if
+          root has mounted the filesystem.</para>
+        </listitem>
+      </itemizedlist></para>
+    </sect2>
+
+    <sect2 id="sf_mount_auto">
+      <title>Automatic mounting</title>
+
+      <para>Starting with version 3.3.0, VirtualBox supports automatic mounting
+      support for shared folders. The installed Guest Additions will then take
+      care of all shared folders which are marked as being auto-mounted as soon
+      as a user is logged in to the guest OS. This makes it more convenient
+      instead of mounting shared folders manually described in <xref
+      linkend="sf_mount_manual" />.</para>
+      <note>
+        <para>Auto-mounting currently is only supported on Windows, Linux and
+        Solaris guests.</para>
+      </note>
+
+      <para>On Windows guests an auto-mounted shared folder will be represented by an own
+      drive letter (e.g. <computeroutput>E:</computeroutput>), depending on the
+      remaining free drive letters of the system.</para>
+
+      <para>On Linux and Solaris guests auto-mounted shared folders get mounted into
+      the <computeroutput>/media</computeroutput> directory, along with the prefix
+      <computeroutput>sf_</computeroutput>, so the shared folder <computeroutput>myfiles</computeroutput>
+      would be mounted to <computeroutput>/media/sf_myfiles</computeroutput> on Linux
+      and <computeroutput>/mnt/sf_myfiles</computeroutput> on Solaris.</para>
+
+      <para>To change the prefix <computeroutput>sf_</computeroutput> of a given
+      virtual machine, set the value of its <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</computeroutput>
+      guest property to another value; see <xref linkend="guestadd-guestprops" /> for details.</para>
+
+      <para>To get a user full access to the auto-mounted shared folders on the guest
+      this user needs to be part of the newly create group "vboxsf", which is created by the
+      VirtualBox Guest Additions installer. Without being in that group read-only access
+      is provided.</para>
+
+      <para>To get changes applied, for example by adding new or deleting auto-mounted
+      shared folders while a VM is running, the guest OS needs to be rebooted. However,
+      this does not affect <xref linkend="sf_mount_manual" />.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="seamlesswindows">
+    <title>Seamless windows</title>
+
+    <para>With the "seamless windows" feature of VirtualBox, you can have the
+    windows that are displayed within a virtual machine appear side by side
+    next to the windows of your host. This feature is supported for the
+    following guest operating systems (provided that the Guest Additions are
+    installed):<itemizedlist>
+        <listitem>
+          <para>Windows guests (support added with VirtualBox 1.5);</para>
+        </listitem>
+
+        <listitem>
+          <para>Linux or Solaris/OpenSolaris guests with an X.org server
+          version 1.3 or higher<footnote>
+              <para>The X server version is not the same as the version of the
+              entire X.org suite. You can type <computeroutput>X
+              -version</computeroutput> in a terminal to find out about the
+              X.org server version level that is currently installed.</para>
+            </footnote> (support added with VirtualBox 1.6). The exception is
+          Fedora 9, due to a bug in its X server.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>After seamless windows are enabled (see below), VirtualBox
+    suppresses the display of the Desktop background of your guest, allowing
+    you to run the windows of your guest operating system seamlessly next to
+    the windows of your host:</para>
+
+    <para><mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/seamless.png" width="10cm" />
+        </imageobject>
+      </mediaobject>To enable seamless mode, after starting the virtual
+    machine, press the Host key (normally the right control key) together with
+    "L". This will enlarge the size of the VM's display to the size of your
+    host screen and mask out the guest operating system's background. To go
+    back to the "normal" VM display (i.e. to disable seamless windows), press
+    the Host key and "L" again.</para>
+  </sect1>
+
+  <sect1>
+    <title>Hardware-accelerated graphics</title>
+
+    <sect2 id="guestadd-3d">
+      <title>Hardware 3D acceleration (OpenGL and Direct3D 8/9)</title>
+
+      <para>The VirtualBox Guest Additions contain experimental hardware 3D
+      support for Windows, Linux and Solaris guests.<footnote>
+          <para>OpenGL support for Windows guests was added with VirtualBox
+          2.1; support for Linux and Solaris followed with VirtualBox 2.2.
+          With VirtualBox 3.0, Direct3D 8/9 support was added for Windows
+          guests. OpenGL 2.0 is now supported as well.</para>
+        </footnote></para>
+
+      <para>With this feature, if an application inside your virtual machine
+      uses 3D features through the OpenGL or Direct3D 8/9 programming
+      interfaces, instead of emulating them in software (which would be slow),
+      VirtualBox will attempt to use your host's 3D hardware. This works for
+      all supported host platforms (Windows, Mac, Linux, Solaris), provided
+      that your host operating system can make use of your accelerated 3D
+      hardware in the first place.</para>
+
+      <para>The 3D acceleration currently has the following
+      preconditions:<orderedlist>
+          <listitem>
+            <para>It is only available for certain Windows, Linux and Solaris
+            guests. In particular:<itemizedlist>
+                <listitem>
+                  <para>For Windows guests, support is restricted to 32-bit
+                  versions of XP and Vista. Both OpenGL and Direct3D 8/9 are
+                  supported (experimental).</para>
+                </listitem>
+
+                <listitem>
+                  <para>OpenGL on Linux requires kernel 2.6.27 and higher as
+                  well as X.org server version 1.5 and higher. Ubuntu 8.10 and
+                  Fedora 10 have been tested and confirmed as working.</para>
+                </listitem>
+
+                <listitem>
+                  <para>OpenGL on Solaris guests requires X.org server version
+                  1.5 and higher.</para>
+                </listitem>
+              </itemizedlist></para>
+          </listitem>
+
+          <listitem>
+            <para>The Guest Additions must be installed.<note>
+                <para>For Direct 3D acceleration to work in a Windows Guest,
+                VirtualBox needs to replace Windows system files in the
+                virtual machine. As a result, the Guest Additions installation
+                program offers Direct 3D acceleration as an option that must
+                be explicitly enabled.</para>
+
+                <para>Also, you must install the Guest Additions in "Safe
+                Mode"; see <xref linkend="KnownIssues" /> for details.</para>
+              </note></para>
+          </listitem>
+
+          <listitem>
+            <para>Because 3D support is still experimental at this time, it is
+            disabled by default and must be <emphasis role="bold">manually
+            enabled</emphasis> in the VM settings (see <xref
+            linkend="generalsettings" />).<note>
+                <para>Enabling 3D acceleration may expose security holes to
+                malicious software running the guest. The third-party code
+                that VirtualBox uses for this purpose (Chromium) is not
+                hardened enough to prevent every risky 3D operation on the
+                host.</para>
+              </note></para>
+          </listitem>
+        </orderedlist></para>
+
+      <para>Technically, VirtualBox implements this by installing an
+      additional hardware 3D driver inside your guest when the Guest Additions
+      are installed. This driver acts as a hardware 3D driver and reports to
+      the guest operating system that the (virtual) hardware is capable of 3D
+      hardware acceleration. When an application in the guest then requests
+      hardware acceleration through the OpenGL or Direct3D programming
+      interfaces, these are sent to the host through a special communication
+      tunnel implemented by VirtualBox, and then the host performs the
+      requested 3D operation via the host's programming interfaces.</para>
+    </sect2>
+
+    <sect2 id="guestadd-2d">
+      <title>Hardware 2D video acceleration for Windows guests</title>
+
+      <para>Starting with version 3.1, the VirtualBox Guest Additions contain
+      experimental hardware 2D video acceleration support for Windows
+      guests.</para>
+
+      <para>With this feature, if an application (e.g. a video player) inside
+      your Windows VM uses 2D video overlays to play a movie clip, then
+      VirtualBox will attempt to use your host's video acceleration hardware
+      instead of performing overlay stretching and color conversion in
+      software (which would be slow). This currently works for Windows, Linux
+      and Mac host platforms, provided that your host operating system can
+      make use of 2D video acceleration in the first place.</para>
+
+      <para>The 2D video acceleration currently has the following
+      preconditions:<orderedlist>
+          <listitem>
+            <para>It is only available for Windows guests (XP or
+            later).</para>
+          </listitem>
+
+          <listitem>
+            <para>The Guest Additions must be installed.</para>
+          </listitem>
+
+          <listitem>
+            <para>Because 2D support is still experimental at this time, it is
+            disabled by default and must be <emphasis role="bold">manually
+            enabled</emphasis> in the VM settings (see <xref
+            linkend="generalsettings" />).</para>
+          </listitem>
+        </orderedlist></para>
+
+      <para>Technically, VirtualBox implements this by exposing video overlay
+      DirectDraw capabilities in the Guest Additions video driver. The driver
+      sends all overlay commands to the host through a special communication
+      tunnel implemented by VirtualBox. On the host side, OpenGL is then used
+      to implement color space transformation and scaling</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="guestadd-guestprops">
+    <title>Guest properties</title>
+
+    <para>Starting with version 2.1, VirtualBox allows for requesting certain
+    properties from a running guest, provided that the VirtualBox Guest
+    Additions are installed and the VM is running. This is good for two
+    things:<orderedlist>
+        <listitem>
+          <para>A number of predefined VM characteristics are automatically
+          maintained by VirtualBox and can be retrieved on the host, e.g. to
+          monitor VM performance and statistics.</para>
+        </listitem>
+
+        <listitem>
+          <para>In addition, arbitrary string data can be exchanged between
+          guest and host. This works in both directions.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>To accomplish this, VirtualBox establishes a private communication
+    channel between the VirtualBox Guest Additions and the host, and software
+    on both sides can use this channel to exchange string data for arbitrary
+    purposes. Guest properties are simply string keys to which a value is
+    attached. They can be set (written to) by either the host and the guest,
+    and they can also be read from both sides.</para>
+
+    <para>In addition to establishing the general mechanism of reading and
+    writing values, a set of predefined guest properties is automatically
+    maintained by the VirtualBox Guest Additions to allow for retrieving
+    interesting guest data such as the guest's exact operating system and
+    service pack level, the installed version of the Guest Additions, users
+    that are currently logged into the guest OS, network statistics and more.
+    These predefined properties are all prefixed with
+    <computeroutput>/VirtualBox/</computeroutput> and organized into a
+    hierarchical tree of keys.</para>
+
+    <para>Some of this runtime information is shown when you select "Session
+    Information Dialog" from a virtual machine's "Machine" menu.</para>
+
+    <para>A more flexible way to use this channel is via the
+    <computeroutput>VBoxManage guestproperty</computeroutput> command set; see
+    <xref linkend="vboxmanage-guestproperty" /> for details. For example, to
+    have <emphasis>all</emphasis> the available guest properties for a given
+    running VM listed with their respective values, use this:<screen>$ VBoxManage guestproperty enumerate "Windows Vista III"
+VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
+(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
+All rights reserved.
+
+Name: /VirtualBox/GuestInfo/OS/Product, value: Windows Vista Business Edition,
+    timestamp: 1229098278843087000, flags:
+Name: /VirtualBox/GuestInfo/OS/Release, value: 6.0.6001,
+    timestamp: 1229098278950553000, flags:
+Name: /VirtualBox/GuestInfo/OS/ServicePack, value: 1,
+    timestamp: 1229098279122627000, flags:
+Name: /VirtualBox/GuestAdd/InstallDir,
+    value: C:/Program Files/Oracle/VirtualBox
+    Guest Additions, timestamp: 1229098279269739000, flags:
+Name: /VirtualBox/GuestAdd/Revision, value: 40720,
+    timestamp: 1229098279345664000, flags:
+Name: /VirtualBox/GuestAdd/Version, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD,
+    timestamp: 1229098279479515000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279651731000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279804835000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279880611000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279882618000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279883195000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279885027000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279886838000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279890600000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279893056000, flags:
+Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
+    timestamp: 1229098279895767000, flags:
+Name: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1,
+    timestamp: 1229099826317660000, flags:
+Name: /VirtualBox/GuestInfo/OS/NoLoggedInUsers, value: false,
+    timestamp: 1229098455580553000, flags:
+Name: /VirtualBox/GuestInfo/Net/Count, value: 1,
+    timestamp: 1229099826299785000, flags:
+Name: /VirtualBox/HostInfo/GUI/LanguageID, value: C,
+    timestamp: 1229098151272771000, flags:
+Name: /VirtualBox/GuestInfo/Net/0/V4/IP, value: 192.168.2.102,
+    timestamp: 1229099826300088000, flags:
+Name: /VirtualBox/GuestInfo/Net/0/V4/Broadcast, value: 255.255.255.255,
+    timestamp: 1229099826300220000, flags:
+Name: /VirtualBox/GuestInfo/Net/0/V4/Netmask, value: 255.255.255.0,
+    timestamp: 1229099826300350000, flags:
+Name: /VirtualBox/GuestInfo/Net/0/Status, value: Up,
+    timestamp: 1229099826300524000, flags:
+Name: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username,
+    timestamp: 1229099826317386000, flags:</screen></para>
+
+    <para>To query the value of a single property, use the "get" subcommand
+    like this:<screen>$ VBoxManage guestproperty get "Windows Vista III"
+         "/VirtualBox/GuestInfo/OS/Product"
+VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
+(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
+All rights reserved.
+
+Value: Windows Vista Business Edition
+</screen></para>
+
+    <para>To add or change guest properties from the guest, use the tool
+    <computeroutput>VBoxControl</computeroutput>. This tool is included in the
+    Guest Additions of VirtualBox 2.2 or later. When started from a Linux
+    guest, this tool requires root privileges for security reasons:<screen>$ sudo VBoxControl guestproperty enumerate
+VirtualBox Guest Additions Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
+(C) 2009-$VBOX_C_YEAR $VBOX_VENDOR
+All rights reserved.
+
+Name: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic,
+    timestamp: 1265813265835667000, flags: &lt;NULL&gt;
+Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010,
+    timestamp: 1265813265836305000, flags: &lt;NULL&gt;
+      ...</screen></para>
+
+    <para>For more complex needs, you can use the VirtualBox programming
+    interfaces; see <xref linkend="VirtualBoxAPI" />.</para>
+  </sect1>
+
+  <sect1 id="guestadd-guestcontrol">
+    <title>Guest control</title>
+
+    <para>Starting with version 3.2, the Guest Additions of VirtualBox allow
+    starting applications inside a VM from the host system.</para>
+
+    <para>For this to work, the application needs to be installed inside the
+    guest; no additional software needs to be installed on the host.
+    Additionally, text mode output (to stdout and stderr) can be shown on the
+    host for further processing along with options to specify user
+    credentials and a timeout value (in milliseconds) to limit time the
+    application is able to run.</para>
+
+    <para>This feature can be used to automate deployment of software within
+    the guest.</para>
+
+    <para>To use this feature, use the VirtualBox command line. See <xref
+    linkend="vboxmanage-guestcontrol" /> for details.</para>
+  </sect1>
+
+  <sect1 id="guestadd-balloon">
+    <title>Memory ballooning</title>
+
+    <para>Starting with version 3.2, the Guest Additions of VirtualBox can
+    change the amount of memory of a virtual machine while the machine is
+    running. Because of how this is implemented, this feature is called
+    "memory ballooning".</para>
+
+    <para>Normally, to change the amount of memory allocated to a virtual
+    machine, one has to shut down the virtual machine entirely and change the
+    virtual machine's settings. With memory ballooning, memory that was
+    allocated for a virtual machine can be given to another virtual machine
+    without having to shut the machine down. This can be useful to temporarily
+    start another virtual machine, or in more complicated environments for
+    sophisticated memory management of many virtual machines that may be
+    running in parallel depending on how memory is used by the guests.</para>
+
+    <para>When memory ballooning is requested, the VirtualBox Guest Additions
+    (which run inside the guest) allocate physical memory from the guest
+    operating system on the kernel level and lock this memory down in the
+    guest. This ensures that the guest will not use that memory any longer: no
+    guest applications can allocate it, and the guest operating system will
+    not use it either. VirtualBox can then re-use this memory and give it to a
+    second virtual machine.</para>
+
+    <para>The memory made available through the ballooning mechanism is only
+    available for re-use by VirtualBox. It is <emphasis>not</emphasis>
+    returned as free memory to the host. Requesting balloon memory from a
+    running guest will therefore not increase the amount of free, unallocated
+    memory on the host.</para>
+
+    <para>Effectively, memory ballooning is therefore a memory overcommitment
+    mechanism for multiple virtual machines while they are running.</para>
+
+    <para>At this time, memory ballooning is only supported in VBoxManage, the
+    VirtualBox command-line utility. Use the following command to increase or
+    decrease the size of the memory balloon within a running virtual machine
+    that has Guest Additions installed: <screen>VBoxManage controlvm "VM name" guestmemoryballoon &lt;n&gt;</screen>
+    where <computeroutput>"VM name"</computeroutput> is the name or UUID of
+    the virtual machine in question and
+    <computeroutput>&lt;n&gt;</computeroutput> is the amount of memory to
+    allocate from the guest in megabytes; see <xref
+    linkend="vboxmanage-controlvm" /> for more information.</para>
+
+    <para>You can also set a default balloon that will automatically be
+    requested from the VM every time after it has started up with the
+    following command: <screen>VBoxManage modifyvm "VM name" --guestmemoryballoon &lt;n&gt;</screen></para>
+
+    <para>By default, no balloon memory is allocated. This is a VM setting,
+    like other <computeroutput>modifyvm</computeroutput> settings, and
+    therefore can only be set while the machine is shut down; see <xref
+    linkend="vboxmanage-modifyvm" />.</para>
+
+    <para><note>
+        <para>VirtualBox supports memory ballooning only on 64-bit hosts,
+        memory ballooning is <emphasis>not</emphasis> supported on Mac OS X
+        hosts.</para>
+      </note></para>
+  </sect1>
+
+  <sect1 id="guestadd-pagefusion">
+    <title>Page Fusion</title>
+
+    <para>Page Fusion is a novel technique to further improve VM density on the host,
+    i.e. a way of overcommitting resources. It was first introduced with VirtualBox 3.2
+    and is currently limited to VMs running Windows 2000 and later. In a typical scenario,
+    dozens, up to hundreds of very similar VMs are consolidated on a powerful host
+    computer and the level of consolidation is most often limited by the amount of RAM
+    that can be installed in a system at reasonable cost. Often, due to RAM exhaustion,
+    additional VMs cannot be started even though the host's CPUs still provide capacity.
+    To circumvent this restriction, hypervisors can benefit from the fact that often, VMs
+    are very similar (e.g. multiple VMs running Windows XP Service Pack 2) and therefore
+    contain a number of identical RAM cells. The hypervisor can look for such duplicate
+    data in memory, eliminate the redundancy (deduplication) and thereby free additional
+    memory.</para>
+
+    <para>Traditional hypervisors use a technique often called "page sharing" or
+    "same page merging" where they go through all memory and compute checksums (hashes)
+    for each memory page. Then, they look for pages with identical hashes and compare
+    the content of the pages (if two pages produce the same hash, it is very likely that
+    the pages are identical in content). Identical pages get eliminated so that all VMs
+    point to the same page as long as none of the VMs tries to modify the page. If such
+    a page gets modified, the previously eliminated duplicates get allocated again. All
+    this is fully transparent to the virtual machine. However, the classical algorithm
+    has several drawbacks. First of all, it takes rather long to scan the complete
+    memory (esp. when the system is not idling) so the additional memory only becomes
+    available after some time (this can be hours or even days!). Also, the whole page
+    sharing algorithm generally consumes significant CPU resources and increases the
+    virtualization overhead by 10-20%.</para>
+
+    <para>Page Fusion in VirtualBox uses the VirtualBox Guest Additions to identify
+    memory cells that are most likely identical across VMs and therefore achieves
+    most of the possible savings of page sharing almost immediately and with almost no
+    overhead. Page Fusion is also much less likely to be tricked by identical memory
+    that it will eliminate just to learn seconds later that the memory will now change
+    and having to perform a highly expensive and often service disrupting reallocation.
+    </para>
+
+    <para>Page Fusion can be enabled for a VM using:
+    <screen>VBoxManage modifyvm "VM name" --pagefusion on</screen>
+    </para>
+
+    <para>You can observe Page Fusion operation using some metrics.
+    <computeroutput>RAM/VMM/Shared</computeroutput> shows the total amount of fused
+    pages whereas the per VM metric <computeroutput>Guest/RAM/Usage/Shared</computeroutput>
+    will return the amount of fused memory for a given VM. Please refer to
+    <xref linkend="metrics" /> for information on how to query metrics.</para>
+
+    <para><note>
+      <para>VirtualBox supports Page Fusion only on 64-bit host operating systems.
+      Mac OS X hosts are currently not supported. Page Fusion is only available for
+      Windows 2000 and later guests with current Guest Additions.</para>
+    </note></para>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_Installation.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_Installation.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_Installation.xml	(revision 33555)
@@ -0,0 +1,870 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="installation">
+  <title>Installation details</title>
+
+  <para>As installation of VirtualBox varies depending on your host operating
+  system, we provide installation instructions in four separate chapters for
+  Windows, Mac OS X, Linux and Solaris, respectively.</para>
+
+  <sect1>
+    <title>Installing on Windows hosts</title>
+
+    <sect2>
+      <title>Prerequisites</title>
+
+      <para>For the various versions of Windows that we support as host
+      operating systems, please refer to <xref
+      linkend="hostossupport" />.</para>
+
+      <para>In addition, Windows Installer 1.1 or higher must be present on
+      your system. This should be the case if you have all recent Windows
+      updates installed.</para>
+    </sect2>
+
+    <sect2>
+      <title>Performing the installation</title>
+
+      <para>The VirtualBox installation can be started <itemizedlist>
+          <listitem>
+            <para>either by double-clicking on its executable file (contains
+            both 32- and 64-bit architectures)</para>
+          </listitem>
+
+          <listitem>
+            <para>or by entering <screen>VirtualBox.exe -extract</screen></para>
+
+            <para>on the command line. This will extract both installers into
+            a temporary directory in which you'll then find the usual .MSI
+            files. Then you can do a <screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi</screen>
+            to perform the installation.</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>In either case, this will display the installation welcome dialog
+      and allow you to choose where to install VirtualBox to and which
+      components to install. In addition to the VirtualBox application, the
+      following components are available:<glosslist>
+          <glossentry>
+            <glossterm>USB support</glossterm>
+
+            <glossdef>
+              <para>This package contains special drivers for your Windows
+              host that VirtualBox requires to fully support USB devices
+              inside your virtual machines.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Networking</glossterm>
+
+            <glossdef>
+              <para>This package contains extra networking drivers for your
+              Windows host that VirtualBox needs to support Host Interface
+              Networking (to make your VM's virtual network cards accessible
+              from other machines on your physical network).</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>Python Support</glossterm>
+
+            <glossdef>
+              <para>This package contains Python scripting support for the
+              VirtualBox API (see <xref linkend="VirtualBoxAPI" />). To get this
+              feature installed an already working Python installation on the
+              system is required.</para>
+            </glossdef>
+          </glossentry>
+        </glosslist></para>
+
+      <para>Depending on your Windows configuration, you may see warnings
+      about "unsigned drivers" or similar. Please select "Continue" on these
+      warnings as otherwise VirtualBox might not function correctly after
+      installation.</para>
+
+      <para>The installer will create a "VirtualBox" group in the programs
+      startup folder which allows you to launch the application and access its
+      documentation.</para>
+
+      <para>With standard settings, VirtualBox will be installed for all users
+      on the local system. In case this is not wanted, you have to invoke the
+      installer by first extracting it by using <screen>VirtualBox.exe -extract</screen>
+      and then do as follows: <screen>VirtualBox.exe -msiparams ALLUSERS=2</screen>
+      or <screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi ALLUSERS=2</screen>
+      on the extracted .MSI files. This will install VirtualBox only for the
+      current user.</para>
+
+      <para>To not install certain features of VirtualBox there is an <computeroutput>ADDLOCAL</computeroutput>
+      parameter that can be specified additionally to explicitly name the features
+      to be installed. The following features are available:
+
+        <glosslist>
+          <glossentry>
+            <glossterm>VBoxApplication</glossterm>
+
+            <glossdef>
+              <para>Main binaries of VirtualBox.
+                <note>This feature never can be absent,
+                since it contains the minimum set of files to have working VirtualBox installation!</note>
+              </para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>VBoxUSB</glossterm>
+
+            <glossdef>
+              <para>USB support.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>VBoxNetwork</glossterm>
+
+            <glossdef>
+              <para>All networking support; includes the VBoxNetworkFlt and VBoxNetworkAdp features (see below).</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>VBoxNetworkFlt</glossterm>
+
+            <glossdef>
+              <para>Bridged networking support.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>VBoxNetworkAdp</glossterm>
+
+            <glossdef>
+              <para>Host-only networking support.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>VBoxPython</glossterm>
+
+            <glossdef>
+              <para>Python support.</para>
+            </glossdef>
+          </glossentry>
+        </glosslist>
+
+      To only install USB support along with the main binaries, do a:
+      <screen>VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</screen>
+      or <screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen></para>
+
+    </sect2>
+
+    <sect2>
+      <title>Uninstallation</title>
+
+      <para>As we use the Microsoft Installer, VirtualBox can be safely
+      uninstalled at any time by choosing the program entry in the "Add/Remove
+      Programs" applet in the Windows Control Panel.</para>
+    </sect2>
+
+    <sect2>
+      <title>Unattended installation</title>
+
+      <para>Unattended installations can be performed using the standard MSI
+      support.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Installing on Mac OS X hosts</title>
+
+    <sect2>
+      <title>Performing the installation</title>
+
+      <para>For Mac OS X hosts, VirtualBox ships in a disk image (dmg) file.
+      Perform the following steps: <orderedlist>
+          <listitem>
+            <para>Double-click on that file to have its contents
+            mounted.</para>
+          </listitem>
+
+          <listitem>
+            <para>A window will open telling you to double click on the
+            <computeroutput>VirtualBox.mpkg</computeroutput> installer file
+            displayed in that window.</para>
+          </listitem>
+
+          <listitem>
+            <para>This will start the installer, which will allow you to
+            select where to install VirtualBox to.</para>
+          </listitem>
+        </orderedlist></para>
+
+      <para>After installation, you can find a VirtualBox icon in the
+      "Applications" folder in the Finder.</para>
+    </sect2>
+
+    <sect2>
+      <title>Uninstallation</title>
+
+      <para>To uninstall VirtualBox, open the disk image (dmg) file again and
+      double-click on the uninstall icon contained therein.</para>
+    </sect2>
+
+    <sect2>
+      <title>Unattended installation</title>
+
+      <para>To perform a non-interactive installation of VirtualBox you can
+      use the command line version of the installer application.</para>
+
+      <para>Mount the disk image (dmg) file as described in the normal
+      installation. Then open a terminal session and execute:</para>
+
+      <screen>sudo installer -pkg /Volumes/VirtualBox/VirtualBox.mpkg \
+      -target /Volumes/Macintosh\ HD</screen>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title id="install-linux-host">Installing on Linux hosts</title>
+
+    <sect2>
+      <title>Prerequisites</title>
+
+      <para>For the various versions of Linux that we support as host
+      operating systems, please refer to <xref
+      linkend="hostossupport" />.</para>
+
+      <para>You will need to install the following packages on your Linux
+      system before starting the installation (some systems will do this for
+      you automatically when you install VirtualBox):</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Qt 4.4.0 or higher;</para>
+        </listitem>
+
+        <listitem>
+          <para>SDL 1.2.7 or higher (this graphics library is typically called
+          <computeroutput>libsdl</computeroutput> or similar).</para>
+        </listitem>
+      </itemizedlist>
+
+      <note>
+        <para>To be precise, these packages are only required if you want to
+        run the VirtualBox graphical user interfaces. In particular,
+        <computeroutput>VirtualBox</computeroutput>, our main graphical user
+        interface, requires both Qt and SDL;
+        <computeroutput>VBoxSDL</computeroutput>, our simplified GUI, requires
+        only SDL. By contrast, if you only want to run the headless VRDP
+        server that comes with VirtualBox, neither Qt nor SDL are
+        required.</para>
+      </note>
+    </sect2>
+
+    <sect2 id="externalkernelmodules">
+      <title>The VirtualBox kernel module</title>
+
+      <para>VirtualBox uses a special kernel module to perform physical memory
+      allocation and to gain control of the processor for guest system
+      execution. Without this kernel module, you will still be able to work
+      with virtual machines in the configuration interface, but you will not
+      be able to start any virtual machines.</para>
+
+      <para>The VirtualBox kernel module is automatically installed on your
+      system when you install VirtualBox. To maintain it with future kernel
+      updates, for recent Linux distributions -- for example Fedora Core 5 and
+      later, Ubuntu 7.10 (Gutsy) and later and Mandriva 2007.1 and later --,
+      generally we recommend installing Dynamic Kernel Module Support
+      (DKMS)<footnote>
+          <para>See <ulink
+          url="http://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support">http://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support</ulink>
+          for an introduction.</para>
+        </footnote>. This framework helps to build kernel modules and to deal
+      with kernel upgrades.</para>
+
+      <para>If DKMS is not already installed, execute one of the following:
+      <itemizedlist>
+          <listitem>
+            <para>On an Ubuntu system:</para>
+
+            <screen>sudo apt-get install dkms</screen>
+          </listitem>
+
+          <listitem>
+            <para>On a Fedora system:<screen>yum install dkms</screen></para>
+          </listitem>
+
+          <listitem>
+            <para>On a Mandriva system:<screen>urpmi dkms</screen></para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>If DKMS is available and installed, the VirtualBox kernel module
+      should always work automatically, and it will be automatically rebuilt
+      if your host kernel is updated.</para>
+
+      <para>Otherwise, there are only two situations in which you will need to
+      worry about the kernel module:<orderedlist>
+          <listitem>
+            <para>The original installation fails. This probably means that
+            your Linux system is not prepared for building external kernel
+            modules.</para>
+
+            <para>Most Linux distributions can be set up simply by installing
+            the right packages - normally, these will be the GNU compiler
+            (GCC), GNU Make (make) and packages containing header files for
+            your kernel - and making sure that all system updates are
+            installed and that the system is running the most up-to-date
+            kernel included in the distribution. <emphasis>The version numbers
+            of the header file packages must be the same as that of the kernel
+            you are using.</emphasis></para>
+
+            <itemizedlist>
+              <listitem>
+                <para>With Debian and Ubuntu releases, you must install the
+                right version of the
+                <computeroutput>linux-headers</computeroutput> and if it
+                exists the <computeroutput>linux-kbuild</computeroutput>
+                package. Current Ubuntu releases should have the right
+                packages installed by default.</para>
+              </listitem>
+
+              <listitem>
+                <para>In even older Debian and Ubuntu releases, you must
+                install the right version of the
+                <computeroutput>kernel-headers</computeroutput>
+                package.</para>
+              </listitem>
+
+              <listitem>
+                <para>On Fedora and Redhat systems, the package is
+                <computeroutput>kernel-devel</computeroutput>.</para>
+              </listitem>
+
+              <listitem>
+                <para>On SUSE and openSUSE Linux, you must install the right
+                versions of the <computeroutput>kernel-source</computeroutput>
+                and <computeroutput>kernel-syms</computeroutput>
+                packages.</para>
+              </listitem>
+
+              <listitem>
+                <para>Alternatively, if you have built your own kernel,
+                <computeroutput>/usr/src/linux</computeroutput> should point
+                to your kernel sources. If you have not removed the files
+                created during the build process, then your system will
+                already be set up correctly.</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+
+          <listitem>
+            <para>The kernel of your Linux host got updated. In that case, the
+            kernel module will need to be reinstalled by executing (as
+            root):</para>
+
+            <screen>/etc/init.d/vboxdrv setup</screen>
+          </listitem>
+        </orderedlist></para>
+    </sect2>
+
+    <sect2>
+      <title>USB and advanced networking support</title>
+
+      <para>In order to use VirtualBox's USB support, the user account under
+      which you intend to run VirtualBox must have read and write access to
+      the USB filesystem (<computeroutput>usbfs</computeroutput>).</para>
+
+      <para>In addition, access to
+      <computeroutput>/dev/net/tun</computeroutput> will be required if you
+      want to use Host Interface Networking, which is described in detail in
+      <xref linkend="network_bridged" />.</para>
+
+      <!--TODO Write a couple of notes about hardened kernels. If PaX is installed, VBox presently doesn't start. I tried with a
+gentoo hardened kernel that had PaX enabled, and VBoxHeadless failed with really funny VERR_NO_MEMORY messages. Discussing
+it with Knut revealed that PaX might be the problem, and running paxctl to disable these protections actually
+helped. For reference:
+First run paxctl -C VBoxVDRP to have the executable modified to support PaX flags in the first place.
+Then paxctl -pemrxs VBoxHeadless to disable all protections. TODO: Figure out which ones are really needed.-->
+    </sect2>
+
+    <sect2>
+      <title>Performing the installation</title>
+
+      <para>VirtualBox is available in a number of package formats native to
+      various common Linux distributions (see <xref linkend="hostossupport" />
+      for details). In addition, there is an alternative generic installer
+      (.run) which should work on most Linux distributions.</para>
+
+      <sect3>
+        <title>Installing VirtualBox from a Debian/Ubuntu package</title>
+
+        <para>First, download the appropriate package for your distribution.
+        The following examples assume that you are installing to a 32-bit Ubuntu
+        Karmic system. Use <computeroutput>dpkg</computeroutput> to install the
+        Debian package:</para>
+
+        <screen>sudo dpkg -i VirtualBox-3.2_$VBOX_VERSION_STRING_Ubuntu_karmic_i386.deb</screen>
+
+        <para>You will be asked to accept the VirtualBox Personal Use and
+        Evaluation License. Unless you answer "yes" here, the installation
+        will be aborted.</para>
+
+        <para>The group <computeroutput>vboxusers</computeroutput> will be
+        created during installation. Note that a user who is going to run
+        VirtualBox must be member of that group. A user can be made member of
+        the group <computeroutput>vboxusers</computeroutput> through the GUI
+        user/group management or at the command line with</para>
+
+        <screen>sudo usermod -a -G vboxusers username</screen>
+
+        <para>Also note that adding an active user to that group will require
+        that user to log out and back in again. This should be done manually
+        after successful installation of the package.</para>
+
+        <para>The installer will also search for a VirtualBox kernel module
+        suitable for your kernel. The package includes pre-compiled modules
+        for the most common kernel configurations. If no suitable kernel
+        module is found, the installation script tries to build a module
+        itself. If the build process is not successful you will be shown a
+        warning and the package will be left unconfigured. Please have a look
+        at <computeroutput>/var/log/vbox-install.log</computeroutput> to find
+        out why the compilation failed. You may have to install the
+        appropriate Linux kernel headers (see <xref
+        linkend="externalkernelmodules" />). After correcting any problems, do
+        <screen>sudo /etc/init.d/vboxdrv setup</screen>This will start a
+        second attempt to build the module.</para>
+
+        <para>If a suitable kernel module was found in the package or the
+        module was successfully built, the installation script will attempt to
+        load that module. If this fails, please see <xref
+        linkend="linuxkernelmodulefailstoload" /> for further
+        information.</para>
+
+        <para>Once VirtualBox has been successfully installed and configured,
+        you can start it by selecting "VirtualBox" in your start menu or from
+        the command line (see <xref linkend="startingvboxonlinux" />).</para>
+      </sect3>
+
+      <sect3>
+        <title>Using the alternative installer (VirtualBox.run)</title>
+
+        <para>The alternative installer performs the following steps:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>It unpacks the application files to a target directory of
+            choice. By default, <screen>/opt/VirtualBox/</screen> will be
+            used.</para>
+          </listitem>
+
+          <listitem>
+            <para>It builds the VirtualBox kernel module
+            (<computeroutput>vboxdrv</computeroutput>) and installs it.</para>
+          </listitem>
+
+          <listitem>
+            <para>It creates
+            <computeroutput>/etc/init.d/vboxdrv</computeroutput>, an init
+            script to start the VirtualBox kernel module.</para>
+          </listitem>
+
+          <listitem>
+            <para>It creates a new system group called
+            <computeroutput>vboxusers</computeroutput>.</para>
+          </listitem>
+
+          <listitem>
+            <para>It creates symbolic links to
+            <computeroutput>VirtualBox</computeroutput>,
+            <computeroutput>VBoxSDL</computeroutput>,
+            <computeroutput>VBoxVRDP</computeroutput>,
+            <computeroutput>VBoxHeadless</computeroutput> and
+            <computeroutput>VBoxManage</computeroutput> in
+            <computeroutput>/usr/bin</computeroutput>.</para>
+          </listitem>
+
+          <listitem>
+            <para>It creates
+            <computeroutput>/etc/udev/60-vboxdrv.rules</computeroutput>, a
+            description file for udev, if that is present, which makes the
+            module accessible to anyone in the group
+            <computeroutput>vboxusers</computeroutput>.</para>
+          </listitem>
+
+          <listitem>
+            <para>It writes the installation directory to
+            <computeroutput>/etc/vbox/vbox.cfg</computeroutput>.</para>
+          </listitem>
+        </itemizedlist>
+
+        <para>The installer must be executed as root with either
+        <computeroutput>install</computeroutput> or
+        <computeroutput>uninstall</computeroutput> as the first parameter. If
+        you do not want the installer to ask you whether you wish to accept
+        the license agreement (for example, for performing unattended
+        installations), you can add the parameter
+        <computeroutput>license_accepted_unconditionally</computeroutput>.
+        Finally, if you want to use a directory other than the default
+        installation directory, add the desired path as an extra
+        parameter.</para>
+
+        <screen>sudo ./VirtualBox.run install /opt/VirtualBox</screen>
+
+        <para>Or if you do not have the "sudo" command available, run the
+        following as root instead:<screen>./VirtualBox.run install /opt/VirtualBox</screen></para>
+
+        <para>After that you need to put every user which should be able to
+        use VirtualBox in the group
+        <computeroutput>vboxusers</computeroutput>, either through the GUI
+        user management tools or by running the following command as
+        root:</para>
+
+        <screen>sudo usermod -a -G vboxusers username</screen>
+
+        <para><note>
+            <para>The <computeroutput>usermod</computeroutput> command of some
+            older Linux distributions does not support the
+            <computeroutput>-a</computeroutput> option (which adds the user to
+            the given group without affecting membership of other groups). In
+            this case, find out the current group memberships with the
+            <computeroutput>groups</computeroutput> command and add all these
+            groups in a comma-separated list to the command line after the
+            <computeroutput>-G</computeroutput> option, e.g. like this:
+            <computeroutput>usermod -G group1,group2,vboxusers
+            username</computeroutput>.</para>
+          </note>If any users on your system should be able to access host USB
+        devices from within VirtualBox guests, you should also add them to the
+        appropriate user group that your distribution uses for USB access,
+        e.g. <computeroutput>usb</computeroutput> or
+        <computeroutput>usbusers</computeroutput>.</para>
+      </sect3>
+
+      <sect3>
+        <title>Performing a manual installation</title>
+
+        <para>If, for any reason, you cannot use the shell script installer
+        described previously, you can also perform a manual installation.
+        Invoke the installer like this:</para>
+
+        <screen>./VirtualBox.run --keep --noexec</screen>
+
+        <para>This will unpack all the files needed for installation in the
+        directory <computeroutput>install</computeroutput> under the current
+        directory. The VirtualBox application files are contained in
+        <computeroutput>VirtualBox.tar.bz2</computeroutput> which you can
+        unpack to any directory on your system. For example:</para>
+
+        <screen>sudo mkdir /opt/VirtualBox
+sudo tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen>
+
+        <para>or as root:<screen>mkdir /opt/VirtualBox
+tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen></para>
+
+        <para>The sources for VirtualBox's kernel module are provided in the
+        <computeroutput>src</computeroutput> directory. To build the module,
+        change to the directory and issue</para>
+
+        <screen>make</screen>
+
+        <para>If everything builds correctly, issue the following command to
+        install the module to the appropriate module directory:</para>
+
+        <screen>sudo make install</screen>
+
+        <para>In case you do not have sudo, switch the user account to root
+        and perform<screen>make install</screen></para>
+
+        <para>The VirtualBox kernel module needs a device node to operate. The
+        above make command will tell you how to create the device node,
+        depending on your Linux system. The procedure is slightly different
+        for a classical Linux setup with a
+        <computeroutput>/dev</computeroutput> directory, a system with the now
+        deprecated <computeroutput>devfs</computeroutput> and a modern Linux
+        system with <computeroutput>udev</computeroutput>.</para>
+
+        <para>On certain Linux distributions, you might experience
+        difficulties building the module. You will have to analyze the error
+        messages from the build system to diagnose the cause of the problems.
+        In general, make sure that the correct Linux kernel sources are used
+        for the build process.</para>
+
+        <para>Note that the user who is going to run VirtualBox needs read and
+        write permission on the VirtualBox kernel module device node
+        <computeroutput>/dev/vboxdrv</computeroutput>. You can either define a
+        <computeroutput>vboxusers</computeroutput> group by entering<screen>groupadd vboxusers
+chgrp vboxusers /dev/vboxdrv
+chmod 660 /dev/vboxdrv</screen>or, alternatively, simply give all users access
+        (insecure, not recommended!)<screen>chmod 666 /dev/vboxdrv</screen>You
+        should also add any users who will be allowed to use host USB devices
+        in VirtualBox guests to the appropriate USB users group for your
+        distribution. This group is often called
+        <computeroutput>usb</computeroutput> or
+        <computeroutput>usbusers</computeroutput>.</para>
+
+        <para>Next, you will have to install the system initialization script
+        for the kernel module:<screen>cp /opt/VirtualBox/vboxdrv.sh /etc/init.d/vboxdrv</screen>(assuming
+        you installed VirtualBox to the
+        <computeroutput>/opt/VirtualBox</computeroutput> directory) and
+        activate the initialization script using the right method for your
+        distribution. You should create VirtualBox's configuration
+        file:<screen>mkdir /etc/vbox
+echo INSTALL_DIR=/opt/VirtualBox &gt; /etc/vbox/vbox.cfg</screen>and, for
+        convenience, create the following symbolic links:</para>
+
+        <screen>ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VirtualBox
+ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxSVC
+ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxManage
+ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxHeadless
+ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxSDL</screen>
+      </sect3>
+
+      <sect3>
+        <title>Updating and uninstalling VirtualBox</title>
+
+        <para>Before updating or uninstalling VirtualBox, you must terminate
+        any virtual machines which are currently running and exit the
+        VirtualBox or VBoxSVC applications. To update VirtualBox, simply run
+        the installer of the updated version. To uninstall VirtualBox, invoke
+        the installer like this: <screen>sudo ./VirtualBox.run uninstall</screen>
+        or as root<screen>./VirtualBox.run uninstall</screen>. Starting with
+        version 2.2.2, you can uninstall the .run package by invoking <screen>/opt/VirtualBox/uninstall.sh</screen>To
+        manually uninstall VirtualBox, simply undo the steps in the manual
+        installation in reverse order.</para>
+      </sect3>
+
+      <sect3>
+        <title>Automatic installation of Debian packages</title>
+
+        <para>The Debian packages will request some user feedback when
+        installed for the first time. The debconf system is used to perform
+        this task. To prevent any user interaction during installation,
+        default values can be defined. A file
+        <computeroutput>vboxconf</computeroutput> can contain the following
+        debconf settings: <screen>virtualbox virtualbox/module-compilation-allowed boolean true
+virtualbox virtualbox/delete-old-modules boolean true</screen>The first line
+        allows compilation of the vboxdrv kernel module if no module was found
+        for the current kernel. The second line allows the package to delete
+        any old vboxdrv kernel modules compiled by previous
+        installations.</para>
+
+        <para>These default settings can be applied with <screen>debconf-set-selections vboxconf</screen>
+        prior to the installation of the VirtualBox Debian package.</para>
+
+        <para>In addition there are some common configuration options that can be set prior to
+        the installation, described in <xref linkend="linux_install_opts" />.</para>
+      </sect3>
+
+      <sect3>
+        <title>Automatic installation of .rpm packages</title>
+
+        <para>The .rpm format does not provide a configuration system
+        comparable to the debconf system. See <xref linkend="linux_install_opts" />
+        for how to set some common installation options provided by VirtualBox.</para>
+      </sect3>
+
+      <sect3>
+        <title id="linux_install_opts">Automatic installation options</title>
+        <para>To configure the installation process of our .deb and .rpm packages, a file
+        <computeroutput>/etc/default/virtualbox</computeroutput> is interpreted.
+        The automatic generation of the udev rule can be prevented by the following setting:
+        <screen>INSTALL_NO_UDEV=1</screen> The creation of the group vboxusers can be prevented
+        by <screen>INSTALL_NO_GROUP=1</screen> If the line <screen>INSTALL_NO_VBOXDRV=1</screen>
+        is specified, the package installer will not try to build the
+        <computeroutput>vboxdrv</computeroutput> kernel module if no module according to the
+        current kernel was found.</para>
+      </sect3>
+
+    </sect2>
+
+    <sect2 id="startingvboxonlinux">
+      <title>Starting VirtualBox on Linux</title>
+
+      <para>The easiest way to start a VirtualBox program is by running the
+      program of your choice (<computeroutput>VirtualBox</computeroutput>,
+      <computeroutput>VBoxManage</computeroutput>,
+      <computeroutput>VBoxSDL</computeroutput> or
+      <computeroutput>VBoxHeadless</computeroutput>) from a terminal. These
+      are symbolic links to <computeroutput>VBox.sh</computeroutput> that
+      start the required program for you.</para>
+
+      <para>The following detailed instructions should only be of interest if
+      you wish to execute VirtualBox without installing it first. You should
+      start by compiling the <computeroutput>vboxdrv</computeroutput> kernel
+      module (see above) and inserting it into the Linux kernel. VirtualBox
+      consists of a service daemon (<computeroutput>VBoxSVC</computeroutput>)
+      and several application programs. The daemon is automatically started if
+      necessary. All VirtualBox applications will communicate with the daemon
+      through Unix local domain sockets. There can be multiple daemon
+      instances under different user accounts and applications can only
+      communicate with the daemon running under the user account as the
+      application. The local domain socket resides in a subdirectory of your
+      system's directory for temporary files called
+      <computeroutput>.vbox-&lt;username&gt;-ipc</computeroutput>. In case of
+      communication problems or server startup problems, you may try to remove
+      this directory.</para>
+
+      <para>All VirtualBox applications
+      (<computeroutput>VirtualBox</computeroutput>,
+      <computeroutput>VBoxSDL</computeroutput>,
+      <computeroutput>VBoxManage</computeroutput> and
+      <computeroutput>VBoxHeadless</computeroutput>) require the VirtualBox
+      directory to be in the library path:</para>
+
+      <screen>LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</screen>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title id="install-solaris-host">Installing on Solaris hosts</title>
+
+    <para>For the various versions of Solaris that we support as host
+    operating systems, please refer to <xref
+    linkend="hostossupport" />.</para>
+
+    <para>If you have a previously installed instance of VirtualBox on your
+    Solaris host, please uninstall it first before installing a new instance.
+    Refer to <xref linkend="uninstallsolhost" /> for uninstall
+    instructions.</para>
+
+    <sect2>
+      <title>Performing the installation</title>
+
+      <para>VirtualBox is available as a standard Solaris package. Download
+      the VirtualBox SunOS package which includes both the 32-bit and 64-bit
+      versions of VirtualBox. <emphasis>The installation must be performed as
+      root and from the global zone</emphasis> as the VirtualBox installer
+      loads kernel drivers which cannot be done from non-global zones. To
+      verify which zone you are currently in, execute the
+      <computeroutput>zonename</computeroutput> command. Execute the following
+      commands:</para>
+
+      <screen>gunzip -cd VirtualBox-$VBOX_VERSION_STRING-SunOS.tar.gz | tar xvf -</screen>
+
+      <para>Starting with VirtualBox 3.1 the VirtualBox kernel package is no
+      longer a separate package and has been integrated into the main package.
+      Install the VirtualBox package using:</para>
+
+      <screen>pkgadd -d VirtualBox-$VBOX_VERSION_STRING-SunOS.pkg</screen>
+
+      <note>
+        <para>If you are using Solaris Zones, to install VirtualBox only into
+        the current zone and not into any other zone, use
+        <computeroutput>pkgadd -G</computeroutput>. For more information refer
+        to the <computeroutput>pkgadd</computeroutput> manual; see also <xref
+        linkend="solariszones" />.</para>
+      </note>
+
+      <para>The installer will then prompt you to enter the package you wish
+      to install. Choose "1" or "all" and proceed. Next the installer will ask
+      you if you want to allow the postinstall script to be executed. Choose
+      "y" and proceed as it is essential to execute this script which installs
+      the VirtualBox kernel module. Following this confirmation the installer
+      will install VirtualBox and execute the postinstall setup script.</para>
+
+      <para>Once the postinstall script has been executed your installation is
+      now complete. You may now safely delete the uncompressed package and
+      <computeroutput>autoresponse</computeroutput> files from your system.
+      VirtualBox would be installed in
+      <computeroutput>/opt/VirtualBox</computeroutput>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Starting VirtualBox on Solaris</title>
+
+      <para>The easiest way to start a VirtualBox program is by running the
+      program of your choice (<computeroutput>VirtualBox</computeroutput>,
+      <computeroutput>VBoxManage</computeroutput>,
+      <computeroutput>VBoxSDL</computeroutput> or
+      <computeroutput>VBoxHeadless</computeroutput>) from a terminal. These
+      are symbolic links to <computeroutput>VBox.sh</computeroutput> that
+      start the required program for you.</para>
+
+      <para>Alternatively, you can directly invoke the required programs from
+      <computeroutput>/opt/VirtualBox</computeroutput>. Using the links
+      provided is easier as you do not have to type the full path.</para>
+
+      <para>You can configure some elements of the
+      <computeroutput>VirtualBox</computeroutput> Qt GUI such as fonts and
+      colours by executing <computeroutput>VBoxQtconfig</computeroutput> from
+      the terminal.</para>
+    </sect2>
+
+    <sect2>
+      <title id="uninstallsolhost">Uninstallation</title>
+
+      <para>Uninstallation of VirtualBox on Solaris requires root permissions.
+      To perform the uninstallation, start a root terminal session and
+      execute:</para>
+
+      <screen>pkgrm SUNWvbox</screen>
+
+      <para>After confirmation, this will remove VirtualBox from your
+      system.</para>
+
+      <para>If you are uninstalling VirtualBox version 3.0 or lower, you need
+      to remove the VirtualBox kernel interface package, execute:</para>
+
+      <para><screen>pkgrm SUNWvboxkern</screen></para>
+    </sect2>
+
+    <sect2>
+      <title>Unattended installation</title>
+
+      <para>To perform a non-interactive installation of VirtualBox we have
+      provided a response file named
+      <computeroutput>autoresponse</computeroutput> that the installer will
+      use for responses to inputs rather than ask them from you.</para>
+
+      <para>Extract the tar.gz package as described in the normal
+      installation. Then open a root terminal session and execute:</para>
+
+      <screen>pkgadd -d VirtualBox-$VBOX_VERSION_STRING-SunOS-x86 -n -a autoresponse SUNWvbox</screen>
+
+      <para>To perform a non-interactive uninstallation, open a root terminal
+      session and execute:</para>
+
+      <screen>pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</screen>
+    </sect2>
+
+    <sect2>
+      <title id="solariszones">Configuring a zone for running
+      VirtualBox</title>
+
+      <para>Starting with VirtualBox 1.6 it is possible to run VirtualBox from
+      within Solaris zones. For an introduction of Solaris zones, please refer
+      to <ulink
+      url="http://www.sun.com/bigadmin/features/articles/solaris_zones.jsp">http://www.sun.com/bigadmin/features/articles/solaris_zones.jsp</ulink>.</para>
+
+      <para>Assuming that VirtualBox has already been installed into your
+      zone, you need to give the zone access to VirtualBox's device node. This
+      is done by performing the following steps. Start a root terminal and
+      execute:</para>
+
+      <screen>zonecfg -z vboxzone</screen>
+
+      <para>Inside the <computeroutput>zonecfg</computeroutput> prompt add the
+      <computeroutput>device</computeroutput> resource and
+      <computeroutput>match</computeroutput> properties to the zone. Here's
+      how it can be done:</para>
+
+      <screen>zonecfg:vboxzone&gt;add device
+zonecfg:vboxzone:device&gt;set match=/dev/vboxdrv
+zonecfg:vboxzone:device&gt;end
+zonecfg:vboxzone&gt;verify
+zonecfg:vboxzone&gt;exit</screen>
+
+      <para>If you are running VirtualBox 2.2.0 or above on OpenSolaris or
+      Nevada hosts, you should add a device for
+      <computeroutput>/dev/vboxusbmon</computeroutput> too, similar to what
+      was shown above. This does not apply to Solaris 10 hosts due to lack of
+      USB support.</para>
+
+      <para>Replace "vboxzone" with the name of the zone in which you intend
+      to run VirtualBox. Next reboot the zone using
+      <computeroutput>zoneadm</computeroutput> and you should be able to run
+      VirtualBox from within the configured zone.</para>
+    </sect2>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_Introduction.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_Introduction.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_Introduction.xml	(revision 33555)
@@ -0,0 +1,1527 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter>
+  <title id="Introduction">Premières étapes</title>
+
+  <para>Bienvenu sur $VBOX_PRODUCT!</para>
+
+  <para>VirtualBox est une application de virtualisation de machines
+  inter-plateformes. Qu'est-ce que cela veut dire&nbsp;? Premièrement, il 
+  s'installe sur vos ordinateurs existants basés sur Intel ou AMD, qu'ils 
+  exécutent les systèmes d'exploitation Windows, Mac, Linux ou Solaris. 
+  Deuxièmement, il étend augmente les capacités de votre ordinateur existant de
+  telle sorte qu'il puisse exécuter plusieurs systèmes d'exploitation à la fois
+  (au sein de plusieurs machines virtuelles). Donc, par exemple, vous pouvez 
+  lancer Windows et Linux sur votre Mac, lancer Windows Server 2008 sur votre 
+  serveur Linux, lancer Linux sur votre PC Windows, etc., tout en laissant 
+  ouvertes vos applications existantes. Vous pouvez installer et exécuter 
+  autant de machines virtuelles que vous le voulez&nbsp;; les seules limites 
+  pratiques sont l'espace disque et la mémoire.</para>
+
+  <para>VirtualBox est tout autant simple que puissant. Il peut se lancer 
+  depuis n'importe où, sur de petits systèmes embarqués ou des machines de 
+  bureau jusqu'au déploiement tout autant que sur des centres de données de 
+  développement et mêmes dans des environnements <quote>Cloud</quote> dit en 
+  nuages.</para>
+
+  <para>L'aperçu suivant vous montre comment VirtualBox, installé sur une machine
+  Linux, lance Windows 7 dans une fenêtre de machine virtuelle&nbsp;:</para>
+
+  <para><mediaobject>
+      <imageobject>
+        <imagedata align="center" fileref="../en_US/images/vm-vista-running.png"
+                   width="10cm" />
+      </imageobject>
+    </mediaobject></para>
+
+  <para>Dans ce manuel de l'utilisateur, nous allons simplement commencer par une
+  rapide introduction à la virtualisation et sur la façon de lancer votre 
+  première machine virtuelle avec l'interface graphique VirtualBox facile à 
+  utiliser. Les chapitres suivants donneront beaucoup plus de détails 
+  concernant des outils et des fonctionnalités plus puissants, mais heureusement,
+  il n'est pas nécessaire de lire tout le manuel de l'utilisateur avant de 
+  pouvoir utiliser VirtualBox.</para>
+
+  <para>Vous pouvez trouver un résumé des possibilités de VirtualBox au <xref
+  linkend="features-overview" />. Pour les utilisateurs qui ont déjà VirtualBox
+  et qui veulent seulement savoir ce qu'il y a de nouveau dans cette version, il 
+  y a une liste détaillée au <xref linkend="ChangeLog" />.</para>
+
+  <sect1>
+    <title>Pourquoi la virtualisation est-elle utile&nbsp;?</title>
+
+    <para>Les techniques et les fonctionnalités fournies par VirtualBox sont 
+    utiles pour plusieurs scénarii&nbsp;:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Support du système d'exploitation.</emphasis>
+        Avec VirtualBox, on peut lancer un logiciel écrit pour un système 
+        d'exploitation sur un autre (par exemple, un logiciel Windows sur Linux
+        ou un Mac) sans avoir à redémarrer pour l'utiliser. Comme vous pouvez 
+        configurer les types de matériel qui devraient être présentés à chaque 
+        machine virtuelle, vous pouvez même installer un vieux système 
+        d'exploitation comme DOS ou OS/2 dans une machine virtuelle si le 
+        matériel de votre ordinateur n'est plus supporté par ce système 
+        d'exploitation.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Tester et réparer un dommage.</emphasis>
+        Une fois installée, on peut considérer une machine virtuelle et ses 
+        disques virtuels comme un <quote>container</quote> que vous pouvez de 
+        façon arbitraire figer, réveiller, copier, sauvegarder et transporter 
+        entre les hôtes.</para>
+        
+        <para>Au surplus, avec l'utilisation d'une autre 
+        caractéristique de VirtualBox appelée <quote>prise</quote>, vous pouvez
+        sauvegarder un état particulier de la machine virtuelle et revenir vers
+        à cet état si nécessaire. De cette façon, vous pouvez expérimenter 
+        librement en divers environnements de travail. Si quelque chose ne va 
+        pas (comme un logiciel qui ne se comporte pas bien après avoir été 
+        installé ou un virus qui a infecté la machine invité), vous pouvez 
+        facilement revenir à un dépôt précédent et éviter de devoir sauvegarder
+        et restaurer souvent.</para>
+        
+        <para>Vous pouvez créer n'importe quel nombre de dépôts,
+        ce qui vous permet de voyager en arrière et dans le temps des machines 
+        virtuelles. Vous pouvez effacer des dépôts alors qu'une VM est en 
+        fonction pour récupérer de l'espace disque.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Consolidation de l'infrastructure..</emphasis>
+        La virtualisation peut réduire significativement les coûts de matériel 
+        et d'électricité. Aujourd'hui, les serveurs tournent se lancent 
+        typiquement avec des charges système très faibles et sont rarement 
+        utilisés dans leur plein potentiel. Beaucoup de potentiel du matériel et
+        d'électricité est ainsi gaspillé. Alors, au lieu de lancer plusieurs 
+        ordinateurs physiques qui ne sont que partiellement utilisés, vous pouvez
+        englober beaucoup de machines virtuelles au sein de quelques hôtes 
+        puissants et équilibrer les charges entre eux.</para>
+        
+        <para>Avec VirtualBox, vous 
+        pouvez même lancer des machines virtuelles en tant que purs serveurs 
+        pour le VirtualBox Remote Desktop Protocol (VRDP) (protocole de bureau 
+        distant de VirtualBox), avec un support complet du client USB. Cela 
+        permet de consolider les machines de bureau dans une entreprise sur à 
+        peine quelques serveurs RDP, tandis que les clients finals ne doivent 
+        qu'être capables d'afficher des données VRDP.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Installations plus faciles de logiciels.</emphasis>
+        Les machines virtuelles peuvent être utilisées par des vendeurs de 
+        logiciels pour livrer porter des configurations globales entières de 
+        logiciels. Par exemple, la solution d'installer un serveur de messagerie
+        complet sur une machine réelle peut être une tâche ennuyeuse. Avec la 
+        virtualisation, il devient possible de livrer une solution logicielle 
+        globale entière, consistant éventuellement en plusieurs composants 
+        différents, dans une machine virtuelle, ce qui s'appelle alors le plus 
+        souvent l'<quote>appliance</quote>. Installer et lancer un serveur de 
+        messagerie devient aussi facile que d'importer un tel service (appliance)
+        dans VirtualBox.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title id="virtintro">Un peu de terminologie</title>
+
+    <para>Quand on parle de virtualisation (et aussi pour comprendre les 
+    chapitres suivants de cette documentation), il est utile de se familiariser
+    un peu avec une terminologie fondamentale, surtout les termes suivants&nbsp;:</para>
+
+    <glosslist>
+      <glossentry>
+        <glossterm>Système d'exploitation hôte (host OS)&nbsp;:</glossterm>
+
+        <glossdef>
+          <para>le système d'exploitation de l'ordinateur physique sur lequel 
+          VirtualBox a été installé. Il existe des versions de VirtualBox pour 
+          les hôtes Windows, Mac OS X, Linux et Solaris&nbsp;; pour plus de 
+          détails, merci de consulter le <xref linkend="hostossupport" />.
+          Tandis que les diverses versions de VirtualBox sont généralement 
+          traitées ensemble dans ce document, il peut y avoir des différences 
+          propres aux plateformes sur lesquelles nous reviendrons aux endroits 
+          adéquats.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>Système d'exploitation invité (guest OS)&nbsp;:</glossterm>
+
+        <glossdef>
+          <para>le système d'exploitation qui est exécuté à l'intérieur de la 
+          machine virtuelle. En théorie, VirtualBox peut exécuter n'importe quel
+          système d'exploitation x86 (DOS, Windows, OS/2, FreeBSD, OpenBSD), mais
+          pour obtenir du code invité les performances les plus proches d'une 
+          installation native sur votre machine, nous avons dû effectuer un grand
+          nombre d'optimisations spécifiques à certains systèmes d'exploitation.
+          Donc si votre système d'exploitation <emphasis>peut</emphasis>
+          s'exécuter comme un invité,
+          nous supportons et optimisons officiellement quelques uns qui sont 
+          sélectionnés (ce qui comprend néanmoins la plupart de ceux courants).</para>
+
+          <para>Voir <xref linkend="guestossupport" /> pour des détails.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>Machine virtuelle (VM).</glossterm>
+
+        <glossdef>
+          <para>Lorsqu'elle est exécutée, une VM est l'environnement spécial 
+          que VirtualBox crée pour votre système d'exploitation invité. Donc, en 
+          d'autres termes, vous lancez votre système d'exploitation invité
+          <quote>dans</quote> une VM. Normalement, une VM apparaîtra comme une 
+          fenêtre sur le bureau de votre ordinateur, mais selon le front-ends 
+          de VirtualBox que vous utilisez, il peut être affiché en mode plein 
+          écran ou à distance en utilisant le VirtualBox Remote Desktop Protocol
+          (VRDP).</para>
+          
+          <para>Parfois nous utilisons aussi le terme <quote>machine virtuelle</quote> d'une 
+          façon plus abstraite&nbsp;: en interne, VirtualBox considère comme une
+          VM  un ensemble de paramètres qui déterminent son comportement. Ils 
+          comprennent tant les réglages matériels (combien de mémoire doit avoir
+          la VM, quels disques durs VirtualBox doit virtualiser parmi les 
+          containers de fichiers, quel CDs sont montés etc.) que des informations
+          d'état (si la VM est actuellement en fonction, sauvegardée, ses prises
+          etc.).</para>
+          
+          <para>Ces paramètres se reflètent aussi bien dans l'interface graphique
+          que dans le programme <computeroutput>VBoxManage</computeroutput> en 
+          ligne de commande&nbsp;; voir le chapitre <xref linkend="vboxmanage" />. 
+          En d'autres termes, une VM est aussi ce que vous pouvez voir dans la 
+          boîte de dialogue de ses paramètres.</para>
+
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>Suppléments invité.</glossterm>
+
+        <glossdef>
+          <para>Avec les <quote>Suppléments invité</quote>, nous faisons 
+          référence à des paquets de logiciel spéciaux qui sont fournis avec 
+          VirtualBox. Même s'ils font partie de VirtualBox, ils sont faits pour
+          être installés à l'intérieur d'une VM pour améliorer la performance de
+           l'OS invité et pour ajouter des fonctionnalités supplémentaires. Ceci 
+           est décrit en détail au chapitre <xref linkend="guestadditions" />.</para>
+        </glossdef>
+      </glossentry>
+    </glosslist>
+  </sect1>
+
+  <sect1 id="features-overview">
+    <title>Aperçu des fonctionnalités</title>
+
+    <para>Voici un bref résumé des principales fonctionnalités de 
+    VirtualBox&nbsp;:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Portabilité.</emphasis> VirtualBox s'exécute
+        sur un grand nombre de systèmes d'exploitation hôtes 32 bits et 64 bits
+        (de nouveau, voir le <xref linkend="hostossupport" /> pour des détails).
+        VirtualBox est ce qu'on appelle un hyperviseur <quote>hébergé</quote> 
+        (parfois désigné comme un hyperviseur de <quote>type 2</quote>). Alors 
+        qu'un hyperviseur <quote>bare-metal</quote> ou de <quote>type 1</quote>
+        s'exécuterait directement sur du matériel, VirtualBox exige qu'un système
+        d'exploitation soit installé. Il peut ainsi s'exécuter avec aux côtés 
+        d'applications existantes sur cet hôte.</para>
+        
+        <para>Dans une large mesure, VirtualBox
+        est, au plan fonctionnel, identique sur toutes les plateformes hôtes et
+        les mêmes formats de fichiers et d'images sont utilisés. Cela vous permet
+        de lancer des machines virtuelles créées sur un hôte sur un autre hôte 
+        au système d'exploitation hôte différent&nbsp;; par exemple vous pouvez
+        créer une machine virtuelle sur Windows puis la lancer sous Linux.</para>
+        
+        <para>En outre, les machines virtuelles peuvent être importées et exportées 
+        facilement en utilisant l'Open Virtualization Format (OVF, voir 
+        <xref linkend="ovf" />), une technologie standard créée à cette fin. 
+        Vous pouvez même importer des OVFs qui ont été créés avec un logiciel de
+        virtualisation différent.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Pas besoin de virtualiser du matériel.</emphasis> 
+        Dans la plupart des scénarii, VirtualBox n'exige pas que les 
+        fonctionnalités du processeur soit construites dans le nouveau matériel
+         comme Intel VT-x ou AMD-V. Contrairement à bien d'autres solutions de 
+         virtualisation, vous pouvez ainsi utiliser VirtualBox même sur du 
+         matériel ancien où ces fonctionnalités ne sont pas présentes. Vous 
+         pouvez trouver plus de détails au chapitre <xref
+        linkend="hwvirt" />.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Suppléments invité&nbsp;: dossiers partagés,
+       fenêtres transparentes, virtualisation 3D.</emphasis> Les suppléments
+       invité de VirtualBox sont des paquets de logiciels qui peuvent être 
+       installés <emphasis>à l'intérieur</emphasis> des systèmes invité 
+       supportés pour améliorer leur performance et pour offrir une meilleure 
+       intégration supplémentaire et une communication avec le système hôte. 
+       Après avoir installé les suppléments invité, une machine virtuelle 
+       supportera l'ajustement automatique des résolutions graphiques, les 
+       fenêtres transparentes seamless, l'accélération 3D graphique et davantage.
+       Les suppléments invité sont décrits en détail au chapitre <xref
+       linkend="guestadditions" />.</para>
+       
+       <para>En particulier, les suppléments invité offrent les 
+       <quote>répertoires partagés</quote> qui vous permettent d'accéder à des 
+       fichiers à partir du système hôte à partir de l'intérieur de la machine 
+       invitée. Les dossiers partagés sont décrits au chapitre <xref 
+       linkend="sharedfolders" />.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Excellent support matériel.</emphasis> Entre
+        autres, VirtualBox supporte&nbsp;:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para><emphasis role="bold">Multitâches invité
+            (SMP).</emphasis> VirtualBox peut présenter jusqu'à 32 processeurs
+            virtuels à une machine virtuelle, indépendamment du nombre de cœurs
+            présents effectivement sur le processeur de votre hôte.</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">Support du périphérique USB 2.0.</emphasis>
+            VirtualBox implémente un contrôleur USB virtuel et vous permet de 
+            connecter à vos machines virtuelles des périphériques USB de votre 
+            choix sans devoir installer de pilotes spécifiques aux 
+            périphériques sur l'hôte. Le support USB n'est pas limité à certaines 
+            catégories de périphériques. Pour des détails, voir le <xref 
+            linkend="settings-usb" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">Compatibilité matérielle.</emphasis>
+            VirtualBox virtualise une large gamme de périphériques, dont beaucoup
+            de périphériques qui sont en général fournis par d'autres plateformes
+            de virtualisation. Cela inclut les contrôleurs de disque IDE, SCSI 
+            et SATA, plusieurs cartes réseau et cartes sons virtuelles, ports 
+            série et parallèle virtuels et Input/Output Advanced Programmable 
+            Interrupt Controller (I/O APIC) (contrôleur d'interruption 
+            programmable avancé entrée/sortie),  que l'on trouve dans beaucoup 
+            de systèmes PC modernes. Cela facilite le clonage d'images de PC à 
+            partir de machines réelles et l'importation de machines virtuelles 
+            tierces dans VirtualBox.</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">Support ACPI complet.</emphasis>
+            L'Advanced Configuration and Power Interface (ACPI) (interface de 
+            configuration et d'énergie avancée) est pleinement supportée par 
+            VirtualBox. Avec son <emphasis role="bold">support unique de statut
+            d'énergie ACPI</emphasis>, VirtualBox peut même signaler à des 
+            systèmes d'exploitation invités gérant l'ACPI le statut de l'énergie
+            de l'hôte. Pour les systèmes portables fonctionnant sur batterie, 
+            l'invité peut ainsi activer l'économie d'énergie et notifier 
+            l'utilisateur de la charge restante (par exemple en modes plein 
+            écran).</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">Résolutions de plusieurs écrans..</emphasis>
+            Les machines virtuelles de VirtualBox supportent les résolutions 
+            d'écran autant importantes qu'avec un écran physique, leur permettant
+            d'être étendus à un grand nombre d'écrans attachés au système hôte.</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">Support iSCSI inclu.</emphasis>
+            Cette fonctionnalité unique vous permet de connecter une machine 
+            virtuelle directement à un serveur de stockage iSCSI sans passer 
+            par le système hôte. La VM accède la cible iSCSI directement sans 
+            la charge intermédiaire requise pour des disques durs de 
+            virtualisation dans des fichiers de container. Pour des détails, 
+            voir chapitre <xref linkend="storage-iscsi" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">Amorçage par réseau PXE.</emphasis> 
+            Les cartes réseau virtuelles intégrées de VirtualBox supportent 
+            complètement l'amorçage à distance à travers le Preboot Execution 
+            Environment (PXE (environnement d'exécution préamorçage).</para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Multigénération de prises branchées.</emphasis> 
+        VirtualBox peut sauvegarder des prises de votre choix de l'état de la 
+        machine virtuelle. Vous pouvez revenir en arrière au moment voulu et 
+        rétablir la machine virtuelle dans n'importe quel des dépôts et démarrer
+        une configuration de VM alternative à partir de là, en créant de fait 
+        une arborescence de dépôts. Pour des détails, voir le <xref linkend="snapshots" />.
+        Vous pouvez supprimer un prise alors que la VM tourne.</para>
+      </listitem>
+
+      <listitem>
+$$        <para><emphasis role="bold">Clean architecture; unprecedented
+        modularity.</emphasis> VirtualBox has an extremely modular design with
+        well-defined internal programming interfaces and a clean separation of
+        client and server code. This makes it easy to control it from several
+        interfaces at once: for example, you can start a VM simply by clicking
+        on a button in the VirtualBox graphical user interface and then
+        control that machine from the command line, or even remotely. See
+        <xref linkend="frontends" /> for details.</para>
+
+        <para>Due to its modular architecture, VirtualBox can also expose its
+        full functionality and configurability through a comprehensive
+        <emphasis role="bold">software development kit (SDK),</emphasis> which
+        allows for integrating every aspect of VirtualBox with other software
+        systems. Please see <xref linkend="VirtualBoxAPI" /> for
+        details.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Remote machine display.</emphasis> You can
+        run any virtual machine in a special VirtualBox program that acts as a
+        server for the VirtualBox Remote Desktop Protocol (VRDP), a
+        backward-compatible extension of the standard Remote Desktop Protocol.
+        With this unique feature, VirtualBox provides high-performance remote
+        access to any virtual machine.</para>
+
+        <para>VirtualBox's VRDP support does not rely on the RDP server that
+        is built into Microsoft Windows. Instead, a custom VRDP server has
+        been built directly into the virtualization layer. As a result, it
+        works with any operating system (even in text mode) and does not
+        require application support in the virtual machine either.</para>
+
+        <para>VRDP support is described in detail in <xref
+        linkend="vrdp" />.</para>
+
+        <para>On top of this special capacity, VirtualBox offers you more
+        unique features:<itemizedlist>
+            <listitem>
+              <para><emphasis role="bold">Extensible RDP
+              authentication.</emphasis> VirtualBox already supports Winlogon
+              on Windows and PAM on Linux for RDP authentication. In addition,
+              it includes an easy-to-use SDK which allows you to create
+              arbitrary interfaces for other methods of authentication; see
+              <xref linkend="vbox-authenticate-sdk" /> for details.</para>
+            </listitem>
+
+            <listitem>
+              <para><emphasis role="bold">USB over RDP.</emphasis> Via RDP
+              virtual channel support, VirtualBox also allows you to connect
+              arbitrary USB devices locally to a virtual machine which is
+              running remotely on a VirtualBox RDP server; see <xref
+              linkend="usb-over-rdp" /> for details.</para>
+            </listitem>
+          </itemizedlist></para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title id="hostossupport">Supported host operating systems</title>
+
+    <para>Currently, VirtualBox runs on the following host operating
+    systems:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Windows</emphasis> hosts:<itemizedlist>
+            <listitem>
+              <para>Windows XP, all service packs (32-bit)</para>
+            </listitem>
+
+            <listitem>
+              <para>Windows Server 2003 (32-bit)</para>
+            </listitem>
+
+            <listitem>
+              <para>Windows Vista (32-bit and 64-bit<footnote>
+                  <para>Support for 64-bit Windows was added with VirtualBox
+                  1.5.</para>
+                </footnote>).</para>
+            </listitem>
+
+            <listitem>
+              <para>Windows Server 2008 (32-bit and 64-bit)</para>
+            </listitem>
+
+            <listitem>
+              <para>Windows 7 (32-bit and 64-bit)</para>
+            </listitem>
+          </itemizedlist></para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Mac OS X</emphasis> hosts:<footnote>
+            <para>Preliminary Mac OS X support (beta stage) was added with
+            VirtualBox 1.4, full support with 1.6. Mac OS X 10.4 (Tiger)
+            support was removed with VirtualBox 3.1.</para>
+          </footnote></para>
+
+        <itemizedlist>
+          <listitem>
+            <para>10.5 (Leopard, 32-bit)</para>
+          </listitem>
+
+          <listitem>
+            <para>10.6 (Snow Leopard, 32-bit and 64-bit)</para>
+          </listitem>
+        </itemizedlist>
+
+        <para>Intel hardware is required; please see <xref
+        linkend="KnownIssues" /> also.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Linux</emphasis> hosts (32-bit and
+        64-bit<footnote>
+            <para>Support for 64-bit Linux was added with VirtualBox
+            1.4.</para>
+          </footnote>). Among others, this includes:<itemizedlist>
+            <listitem>
+              <para>Ubuntu 6.06 ("Dapper Drake"), 6.10 ("Edgy Eft"), 7.04
+              ("Feisty Fawn"), 7.10 ("Gutsy Gibbon"), 8.04 ("Hardy Heron"),
+              8.10 ("Intrepid Ibex"), 9.04 ("Jaunty Jackalope"), 9.10 ("Karmic
+              Koala"), 10.04 ("Lucid Lynx").</para>
+            </listitem>
+
+            <listitem>
+              <para>Debian GNU/Linux 3.1 ("sarge"), 4.0 ("etch") and 5.0
+              ("lenny")</para>
+            </listitem>
+
+            <listitem>
+              <para>Oracle Enterprise Linux 4 and 5</para>
+            </listitem>
+
+            <listitem>
+              <para>Redhat Enterprise Linux 4 and 5</para>
+            </listitem>
+
+            <listitem>
+              <para>Fedora Core 4 to 12</para>
+            </listitem>
+
+            <listitem>
+              <para>Gentoo Linux</para>
+            </listitem>
+
+            <listitem>
+              <para>SUSE Linux 9 and 10, openSUSE 10.3, 11.0, 11.1,
+              11.2</para>
+            </listitem>
+
+            <listitem>
+              <para>Mandriva 2007.1, 2008.0, 2009.1, 2010.0</para>
+            </listitem>
+          </itemizedlist></para>
+
+        <para>It should be possible to use VirtualBox on most systems based on
+        Linux kernel 2.6 using either the VirtualBox installer or by doing a
+        manual installation; see <xref linkend="install-linux-host" />.</para>
+
+        <para>Note that starting with VirtualBox 2.1, Linux 2.4-based host
+        operating systems are no longer supported.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Solaris</emphasis> hosts (32-bit and
+        64-bit<footnote>
+            <para>Support for OpenSolaris was added with VirtualBox
+            1.6.</para>
+          </footnote>) are supported with the restrictions listed in <xref
+        linkend="KnownIssues" />:<itemizedlist>
+            <listitem>
+              <para>OpenSolaris (2008.05 and higher, "Nevada" build 86 and
+              higher)</para>
+            </listitem>
+
+            <listitem>
+              <para>Solaris 10 (u5 and higher)</para>
+            </listitem>
+          </itemizedlist></para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Installing and starting VirtualBox</title>
+
+    <para>VirtualBox comes in many different packages, and <emphasis
+    role="bold">installation</emphasis> depends on your host platform. If you
+    have installed software before, installation should be straightforward as
+    on each host platform, VirtualBox uses the installation method that is
+    most common and easy to use. If you run into trouble or have special
+    requirements, please refer to <xref linkend="installation" /> for details
+    about the various installation methods.</para>
+
+    <para>After installation, you can start VirtualBox as
+    follows:<itemizedlist>
+        <listitem>
+          <para>On a Windows host, in the standard "Programs" menu, click on
+          the item in the "VirtualBox" group. On Vista or Windows 7, you can
+          also type "VirtualBox" in the search box of the "Start" menu.</para>
+        </listitem>
+
+        <listitem>
+          <para>On a Mac OS X host, in the Finder, double-click on the
+          "VirtualBox" item in the "Applications" folder. (You may want to
+          drag this item onto your Dock.)</para>
+        </listitem>
+
+        <listitem>
+          <para>On a Linux or Solaris host, depending on your desktop
+          environment, a "VirtualBox" item may have been placed in either the
+          "System" or "System Tools" group of your "Applications" menu.
+          Alternatively, you can type
+          <computeroutput>VirtualBox</computeroutput> in a terminal.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>When you start VirtualBox for the first time, a window like the
+    following should come up:</para>
+
+    <para><mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/virtualbox-main-empty.png"
+                     width="10cm" />
+        </imageobject>
+      </mediaobject>On the left, you can see a pane that will later list all
+    your virtual machines. Since you have not created any, the list is empty.
+    A row of buttons above it allows you to create new VMs and work on
+    existing VMs, once you have some. The pane on the right displays the
+    properties of the virtual machine currently selected, if any. Again, since
+    you don't have any machines yet, the pane displays a welcome
+    message.</para>
+
+    <para>To give you an idea what VirtualBox might look like later, after you
+    have created many machines, here's another example:</para>
+
+    <para><mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/virtualbox-main.png"
+                     width="10cm" />
+        </imageobject>
+      </mediaobject></para>
+  </sect1>
+
+  <sect1 id="gui-createvm">
+    <title>Creating your first virtual machine</title>
+
+    <para>Click on the "New" button at the top of the VirtualBox window. A
+    wizard will pop up to guide you through setting up a new virtual machine
+    (VM):</para>
+
+    <para><mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/create-vm-1.png"
+                     width="10cm" />
+        </imageobject>
+      </mediaobject>On the following pages, the wizard will ask you for the
+    bare minimum of information that is needed to create a VM, in
+    particular:<orderedlist>
+        <listitem>
+          <para>A <emphasis role="bold">name</emphasis> for your VM, and the
+          <emphasis role="bold">type of operating system</emphasis> (OS) you
+          want to install.</para>
+
+          <para>The name is what you will later see in the VirtualBox main
+          window, and what your settings will be stored under. It is purely
+          informational, but once you have created a few VMs, you will
+          appreciate if you have given your VMs informative names. "My VM"
+          probably is therefore not as useful as "Windows XP SP2".</para>
+
+          <para>For "Operating System Type", select the operating system that
+          you want to install later. Depending on your selection, VirtualBox
+          will enable or disable certain VM settings that your guest operating
+          system may require. This is particularly important for 64-bit guests
+          (see <xref linkend="intro-64bitguests" />). It is therefore
+          recommended to always set it to the correct value.</para>
+        </listitem>
+
+        <listitem>
+          <para>The <emphasis role="bold">amount of memory (RAM)</emphasis>
+          that the virtual machine should have for itself. Every time a
+          virtual machine is started, VirtualBox will allocate this much
+          memory from your host machine and present it to the guest operating
+          system, which will report this size as the (virtual) computer's
+          installed RAM.</para>
+
+          <para><note>
+              <para>Choose this setting carefully! The memory you give to the
+              VM will not be available to your host OS while the VM is
+              running, so do not specify more than you can spare. For example,
+              if your host machine has 1 GB of RAM and you enter 512 MB as the
+              amount of RAM for a particular virtual machine, while that VM is
+              running, you will only have 512 MB left for all the other
+              software on your host. If you run two VMs at the same time, even
+              more memory will be allocated for the second VM (which may not
+              even be able to start if that memory is not available). On the
+              other hand, you should specify as much as your guest OS (and
+              your applications) will require to run properly.</para>
+            </note></para>
+
+          <para>A Windows XP guest will require at least a few hundred MB RAM
+          to run properly, and Windows Vista will even refuse to install with
+          less than 512 MB. Of course, if you want to run graphics-intensive
+          applications in your VM, you may require even more RAM.</para>
+
+          <para>So, as a rule of thumb, if you have 1 GB of RAM or more in
+          your host computer, it is usually safe to allocate 512 MB to each
+          VM. But, in any case, make sure you always have at least 256 to 512
+          MB of RAM left on your host operating system. Otherwise you may
+          cause your host OS to excessively swap out memory to your hard disk,
+          effectively bringing your host system to a standstill.</para>
+
+          <para><note>
+              <para>VirtualBox restricts the amount of guest RAM to 1500 MB on
+              32-bit Windows hosts and to 2560 MB on 32-bit Linux and Solaris
+              hosts due to address-space limitations. These restrictions do
+              not apply to 64-bit hosts.</para>
+            </note></para>
+
+          <para>As with the other settings, you can change this setting later,
+          after you have created the VM.</para>
+        </listitem>
+
+        <listitem>
+          <para>Next, you must specify a <emphasis role="bold">virtual hard
+          disk</emphasis> for your VM.</para>
+
+          <para>There are many and potentially complicated ways in which
+          VirtualBox can provide hard disk space to a VM (see <xref
+          linkend="storage" /> for details), but the most common way is to use
+          a large image file on your "real" hard disk, whose contents
+          VirtualBox presents to your VM as if it were a complete hard
+          disk.</para>
+
+          <para>The wizard shows you the following window:</para>
+
+          <para><mediaobject>
+              <imageobject>
+                <imagedata align="center" fileref="images/create-vm-2.png"
+                           width="10cm" />
+              </imageobject>
+            </mediaobject></para>
+
+          <para>The wizard allows you to create an image file or use an
+          existing one. Note also that the disk images can be separated from a
+          particular VM, so even if you delete a VM, you can keep the image,
+          or copy it to another host and create a new VM for it there.</para>
+
+          <para>In the wizard, you have the following options:</para>
+
+          <para><itemizedlist>
+              <listitem>
+                <para>If you have previously created any virtual hard disks
+                which have not been attached to other virtual machines, you
+                can select those from the drop-down list in the wizard
+                window.</para>
+              </listitem>
+
+              <listitem>
+                <para>Otherwise, to create a new virtual hard disk, press the
+                <emphasis role="bold">"New"</emphasis> button.</para>
+              </listitem>
+
+              <listitem>
+                <para>Finally, for more complicated operations with virtual
+                disks, the <emphasis role="bold">"Existing..."</emphasis>
+                button will bring up the Virtual Media Manager, which is
+                described in more detail in <xref linkend="vdis" />.</para>
+              </listitem>
+            </itemizedlist>Most probably, if you are using VirtualBox for the
+          first time, you will want to create a new disk image. Hence, press
+          the "New" button.</para>
+
+          <para>This brings up another window, the <emphasis
+          role="bold">"Create New Virtual Disk Wizard".</emphasis></para>
+
+          <para>VirtualBox supports two types of image files:<itemizedlist>
+              <listitem>
+                <para>A <emphasis role="bold">dynamically expanding
+                file</emphasis> will only grow in size when the guest actually
+                stores data on its virtual hard disk. It will therefore
+                initially be small on the host hard drive and only later grow
+                to the size specified as it is filled with data.</para>
+              </listitem>
+
+              <listitem>
+                <para>A <emphasis role="bold">fixed-size file</emphasis> will
+                immediately occupy the file specified, even if only a fraction
+                of the virtual hard disk space is actually in use. While
+                occupying much more space, a fixed-size file incurs less
+                overhead and is therefore slightly faster than a dynamically
+                expanding file.</para>
+              </listitem>
+            </itemizedlist></para>
+
+          <para>For details about the differences, please refer to <xref
+          linkend="vdidetails" />.</para>
+
+          <para>To prevent your physical hard disk from running full,
+          VirtualBox limits the size of the image file. Still, it needs to be
+          large enough to hold the contents of your operating system and the
+          applications you want to install -- for a modern Windows or Linux
+          guest, you will probably need several gigabytes for any serious
+          use:</para>
+
+          <mediaobject>
+            <imageobject>
+              <imagedata align="center" fileref="images/create-vdi-1.png"
+                         width="10cm" />
+            </imageobject>
+          </mediaobject>
+
+          <para>After having selected or created your image file, again press
+          <emphasis role="bold">"Next"</emphasis> to go to the next
+          page.</para>
+        </listitem>
+
+        <listitem>
+          <para>After clicking on <emphasis role="bold">"Finish"</emphasis>,
+          your new virtual machine will be created. You will then see it in
+          the list on the left side of the main window, with the name you have
+          entered.</para>
+        </listitem>
+      </orderedlist></para>
+  </sect1>
+
+  <sect1>
+    <title>Running your virtual machine</title>
+
+    <para>You will now see your new virtual machine in the list of virtual
+    machines, at the left of the VirtualBox main window. To start the virtual
+    machine, simply double-click on it, or select it and press the "Start"
+    button at the top.</para>
+
+    <para>This opens up a new window, and the virtual machine which you
+    selected will boot up. Everything which would normally be seen on the
+    virtual system's monitor is shown in the window, as can be seen with the
+    image in <xref linkend="virtintro" />.</para>
+
+    <para>Since this is the first time you are running this VM, another wizard
+    will show up to help you select an installation medium. Since the VM is
+    created empty, it would otherwise behave just like a real computer with no
+    operating system installed: it will do nothing and display an error
+    message that it cannot boot an operating system.</para>
+
+    <para>For this reason, the "First Start Wizard" helps you select an
+    operating system medium to install an operating system from. In most
+    cases, this will either be a real CD or DVD (VirtualBox can then configure
+    the virtual machine to use your host's drive), or you might have an ISO
+    image of a CD or DVD handy, which VirtualBox can then present to the
+    virtual machine.</para>
+
+    <para>In both cases, after making the choices in the wizard, you will be
+    able to install your operating system.</para>
+
+    <para>In general, you can use the virtual machine much like you would use
+    a real computer. There are couple of points worth mentioning
+    however.</para>
+
+    <sect2>
+      <title>Keyboard and mouse support in virtual machines</title>
+
+      <sect3>
+        <title id="keyb_mouse_normal">Capturing and releasing keyboard and
+        mouse</title>
+
+        <para>As of version 3.2, VirtualBox provides a virtual USB tablet
+        device to new virtual machines through which mouse events are
+        communicated to the guest operating system. As a result, if you are
+        running a fairly recent guest operating system that can handle such
+        devices, mouse support may work out of the box without the mouse being
+        "captured" as described below; see <xref
+        linkend="settings-motherboard" /> for more information.</para>
+
+        <para>Otherwise, if the virtual machine only sees standard PS/2 mouse
+        and keyboard devices, since the operating system in the virtual
+        machine does not "know" that it is not running on a real computer, it
+        expects to have exclusive control over your keyboard and mouse. This
+        is, however, not the case since, unless you are running the VM in
+        full-screen mode, your VM needs to share keyboard and mouse with other
+        applications and possibly other VMs on your host.</para>
+
+        <para>As a result, initially after installing a guest operating system
+        and before you install the Guest Additions (we will explain this in a
+        minute), only one of the two -- your VM or the rest of your computer
+        -- can "own" the keyboard and the mouse. You will see a
+        <emphasis>second</emphasis> mouse pointer which will always be
+        confined to the limits of the VM window. Basically, you activate the
+        VM by clicking inside it.</para>
+
+        <para>To return ownership of keyboard and mouse to your host operating
+        system, VirtualBox reserves a special key on your keyboard for itself:
+        the <emphasis role="bold">"host key".</emphasis> By default, this is
+        the <emphasis>right Control key</emphasis> on your keyboard; on a Mac
+        host, the default host key is the left Command key. You can change
+        this default in the VirtualBox Global Settings. In any case, the
+        current setting for the host key is always displayed <emphasis>at the
+        bottom right of your VM window,</emphasis> should you have forgotten
+        about it:</para>
+
+        <para><mediaobject>
+            <imageobject>
+              <imagedata align="center" fileref="images/vm-hostkey.png"
+                         width="7cm" />
+            </imageobject>
+          </mediaobject>In detail, all this translates into the
+        following:</para>
+
+        <para><itemizedlist>
+            <listitem>
+              <para>Your <emphasis role="bold">keyboard</emphasis> is owned by
+              the VM if the VM window on your host desktop has the keyboard
+              focus (and then, if you have many windows open in your guest
+              operating system as well, the window that has the focus in your
+              VM). This means that if you want to type within your VM, click
+              on the title bar of your VM window first.</para>
+
+              <para>To release keyboard ownership, press the Host key (as
+              explained above, typically the right Control key).</para>
+
+              <para>Note that while the VM owns the keyboard, some key
+              sequences (like Alt-Tab for example) will no longer be seen by
+              the host, but will go to the guest instead. After you press the
+              host key to re-enable the host keyboard, all key presses will go
+              through the host again, so that sequences like Alt-Tab will no
+              longer reach the guest.</para>
+            </listitem>
+
+            <listitem>
+              <para>Your <emphasis role="bold">mouse</emphasis> is owned by
+              the VM only after you have clicked in the VM window. The host
+              mouse pointer will disappear, and your mouse will drive the
+              guest's pointer instead of your normal mouse pointer.</para>
+
+              <para>Note that mouse ownership is independent of that of the
+              keyboard: even after you have clicked on a titlebar to be able
+              to type into the VM window, your mouse is not necessarily owned
+              by the VM yet.</para>
+
+              <para>To release ownership of your mouse by the VM, also press
+              the Host key.</para>
+            </listitem>
+          </itemizedlist></para>
+
+        <para>As this behavior can be inconvenient, VirtualBox provides a set
+        of tools and device drivers for guest systems called the "VirtualBox
+        Guest Additions" which make VM keyboard and mouse operation a lot more
+        seamless. Most importantly, the Additions will get rid of the second
+        "guest" mouse pointer and make your host mouse pointer work directly
+        in the guest.</para>
+
+        <para>This will be described later in <xref
+        linkend="guestadditions" />.</para>
+      </sect3>
+
+      <sect3>
+        <title>Typing special characters</title>
+
+        <para>Operating systems expect certain key combinations to initiate
+        certain procedures. Some of these key combinations may be difficult to
+        enter into a virtual machine, as there are three candidates as to who
+        receives keyboard input: the host operating system, VirtualBox, or the
+        guest operating system. Who of these three receives keypresses depends
+        on a number of factors, including the key itself.</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>Host operating systems reserve certain key combinations for
+            themselves. For example, it is impossible to enter the <emphasis
+            role="bold">Ctrl+Alt+Delete</emphasis> combination if you want to
+            reboot the guest operating system in your virtual machine, because
+            this key combination is usually hard-wired into the host OS (both
+            Windows and Linux intercept this), and pressing this key
+            combination will therefore reboot your
+            <emphasis>host</emphasis>.</para>
+
+            <para>Also, on Linux and Solairs hosts, which use the X Window
+            System, the key combination <emphasis
+            role="bold">Ctrl+Alt+Backspace</emphasis> normally resets the X
+            server (to restart the entire graphical user interface in case it
+            got stuck). As the X server intercepts this combination, pressing
+            it will usually restart your <emphasis>host</emphasis> graphical
+            user interface (and kill all running programs, including
+            VirtualBox, in the process).</para>
+
+            <para>Third, on Linux hosts supporting virtual terminals, the key
+            combination <emphasis role="bold">Ctrl+Alt+Fx</emphasis> (where Fx
+            is one of the function keys from F1 to F12) normally allows to
+            switch between virtual terminals. As with Ctrl+Alt+Delete, these
+            combinations are intercepted by the host operating system and
+            therefore always switch terminals on the
+            <emphasis>host</emphasis>.</para>
+
+            <para>If, instead, you want to send these key combinations to the
+            <emphasis>guest</emphasis> operating system in the virtual
+            machine, you will need to use one of the following methods:</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>Use the items in the "Machine" menu of the virtual
+                machine window. There you will find "Insert Ctrl+Alt+Delete"
+                and "Ctrl+Alt+Backspace"; the latter will only have an effect
+                with Linux or Solaris guests, however.</para>
+              </listitem>
+
+              <listitem>
+                <para>Press special key combinations with the Host key
+                (normally the right Control key), which VirtualBox will then
+                translate for the virtual machine:<itemizedlist>
+                    <listitem>
+                      <para><emphasis role="bold">Host key + Del</emphasis> to
+                      send Ctrl+Alt+Del (to reboot the guest);</para>
+                    </listitem>
+
+                    <listitem>
+                      <para><emphasis role="bold">Host key +
+                      Backspace</emphasis> to send Ctrl+Alt+Backspace (to
+                      restart the graphical user interface of a Linux or
+                      Solaris guest);</para>
+                    </listitem>
+
+                    <listitem>
+                      <para><emphasis role="bold">Host key + F1</emphasis> (or
+                      other function keys) to simulate Ctrl+Alt+F1 (or other
+                      function keys, i.e. to switch between virtual terminals
+                      in a Linux guest).</para>
+                    </listitem>
+                  </itemizedlist></para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+
+          <listitem>
+            <para>For some other keyboard combinations such as <emphasis
+            role="bold">Alt-Tab</emphasis> (to switch between open windows),
+            VirtualBox allows you to configure whether these combinations will
+            affect the host or the guest, if a virtual machine currently has
+            the focus. This is a global setting for all virtual machines and
+            can be found under "File" -&gt; "Preferences" -&gt; "Input" -&gt;
+            "Auto-capture keyboard".</para>
+          </listitem>
+        </itemizedlist>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Changing removable media</title>
+
+      <para>While a virtual machine is running, you can change removable media
+      in the "Devices" menu of the VM's window. Here you can select in detail
+      what VirtualBox presents to your VM as a CD, DVD, or floppy.</para>
+
+      <para>The settings are the same as would be available for the VM in the
+      "Settings" dialog of the VirtualBox main window, but since that dialog
+      is disabled while the VM is in the "running" or "saved" state, this
+      extra menu saves you from having to shut down and restart the VM every
+      time you want to change media.</para>
+
+      <para>Hence, in the "Devices" menu, VirtualBox allows you to attach the
+      host drive to the guest or select a floppy or DVD image using the Disk
+      Image Manager, all as described in <xref
+      linkend="configbasics" />.</para>
+    </sect2>
+
+    <sect2>
+      <title>Saving the state of the machine</title>
+
+      <para>When you click on the "Close" button of your virtual machine
+      window (at the top right of the window, just like you would close any
+      other window on your system) (or press the Host key together with "Q"),
+      VirtualBox asks you whether you want to "save" or "power off" the
+      VM.</para>
+
+      <para><mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/vm-close.png"
+                       width="7cm" />
+          </imageobject>
+        </mediaobject>The difference between these three options is crucial.
+      They mean:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><emphasis role="bold">Save the machine state:</emphasis> With
+          this option, VirtualBox "freezes" the virtual machine by completely
+          saving its state to your local disk. When you later resume the VM
+          (by again clicking the "Start" button in the VirtualBox main
+          window), you will find that the VM continues exactly where it was
+          left off. All your programs will still be open, and your computer
+          resumes operation.</para>
+
+          <para>Saving the state of a virtual machine is thus in some ways
+          similar to suspending a laptop computer (e.g. by closing its
+          lid).</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Send the shutdown signal.</emphasis>
+          This will send an ACPI shutdown signal to the virtual machine, which
+          has the same effect as if you had pressed the power button on a real
+          computer. So long as a fairly modern operating system is installed
+          and running in the VM, this should trigger a proper shutdown
+          mechanism in the VM.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Power off the machine:</emphasis> With
+          this option, VirtualBox also stops running the virtual machine, but
+          <emphasis>without</emphasis> saving its state.</para>
+
+          <para>This is equivalent to pulling the power plug on a real
+          computer without shutting it down properly. If you start the machine
+          again after powering it off, your operating system will have to
+          reboot completely and may begin a lengthy check of its (virtual)
+          system disks.</para>
+
+          <para>As a result, this should not normally be done, since it can
+          potentially cause data loss or an inconsistent state of the guest
+          system on disk.</para>
+
+          <para>As an exception, if your virtual machine has any snapshots
+          (see the next chapter), you can use this option to quickly <emphasis
+          role="bold">restore the current snapshot</emphasis> of the virtual
+          machine. Only in that case, powering off the machine is not
+          harmful.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>The <emphasis role="bold">"Discard"</emphasis> button in the main
+      VirtualBox window discards a virtual machine's saved state. This has the
+      same effect as powering it off, and the same warnings apply.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="snapshots">
+    <title>Snapshots</title>
+
+    <para>With snapshots, you can save a particular state of a virtual machine
+    for later use. At any later time, you can revert to that state, even
+    though you may have changed the VM considerably since then.</para>
+
+    <para>You can see the snapshots of a virtual machine by first selecting a
+    machine from the list on the left of the VirtualBox main window and then
+    selecting the "Snapshots" tab on the right. Initially, until you take a
+    snapshot of the machine, that list is empty except for the "Current state"
+    item, which represents the "Now" point in the lifetime of the virtual
+    machine.</para>
+
+    <para>There are three operations related to snapshots:<orderedlist>
+        <listitem>
+          <para>You can <emphasis role="bold">take a
+          snapshot</emphasis>.<itemizedlist>
+              <listitem>
+                <para>If your VM is currently running, select "Take snapshot"
+                from the "Machine" pull-down menu of the VM window.</para>
+              </listitem>
+
+              <listitem>
+                <para>If your VM is currently in either the "saved" or the
+                "powered off" state (as displayed next to the VM in the
+                VirtualBox main window), click on the "Snapshots" tab on the
+                top right of the main window, and then<itemizedlist>
+                    <listitem>
+                      <para>either on the small camera icon (for "Take
+                      snapshot") or</para>
+                    </listitem>
+
+                    <listitem>
+                      <para>right-click on the "Current State" item in the
+                      list and select "Take snapshot" from the menu.</para>
+                    </listitem>
+                  </itemizedlist></para>
+              </listitem>
+            </itemizedlist></para>
+
+          <para>In any case, a window will pop up and ask you for a snapshot
+          name. This name is purely for reference purposes to help you
+          remember the state of the snapshot. For example, a useful name would
+          be "Fresh installation from scratch, no external drivers". You can
+          also add a longer text in the "Description" field if you
+          want.</para>
+
+          <para>Your new snapshot will then appear in the list of snapshots
+          under the "Snapshots" tab. Underneath, you will see an item called
+          "Current state", signifying that the current state of your VM is a
+          variation based on the snapshot you took earlier. If you later take
+          another snapshot, you will see that they will be displayed in
+          sequence, and each subsequent snapshot is a derivation of the
+          earlier one:<mediaobject>
+              <imageobject>
+                <imagedata align="center" fileref="images/snapshots-1.png"
+                           width="10cm" />
+              </imageobject>
+            </mediaobject></para>
+
+          <para>VirtualBox allows you to take an unlimited number of snapshots
+          -- the only limitation is the size of your disks. Keep in mind that
+          each snapshot stores the state of the virtual machine and thus takes
+          some disk space.</para>
+        </listitem>
+
+        <listitem>
+          <para>You can <emphasis role="bold">restore a snapshot</emphasis> by
+          right-clicking on any snapshot you have taken in the list of
+          snapshots. By restoring a snapshot, you go back (or forward) in
+          time: the current state of the machine is lost, and the machine is
+          restored to exactly the same state as it was when then snapshot was
+          taken.<footnote>
+              <para>Both the terminology and the functionality of restoring
+              snapshots has changed with VirtualBox 3.1. Before that version,
+              it was only possible to go back to the very last snapshot taken
+              -- not earlier ones, and the operation was called "Discard
+              current state" instead of "Restore last snapshot". The
+              limitation has been lifted with version 3.1. It is now possible
+              to restore <emphasis>any</emphasis> snapshot, going backward and
+              forward in time.</para>
+            </footnote></para>
+
+          <note>
+            <para>Restoring a snapshot will affect the virtual hard drives
+            that are connected to your VM, as the entire state of the virtual
+            hard drive will be reverted as well. This means also that all
+            files that have been created since the snapshot and all other file
+            changes <emphasis>will be lost. </emphasis>In order to prevent
+            such data loss while still making use of the snapshot feature, it
+            is possible to add a second hard drive in "write-through" mode
+            using the <computeroutput>VBoxManage</computeroutput> interface
+            and use it to store your data. As write-through hard drives are
+            <emphasis>not</emphasis> included in snapshots, they remain
+            unaltered when a machine is reverted. See <xref
+            linkend="hdimagewrites" os="" /> for details.</para>
+          </note>
+
+          <para>By restoring an earlier snapshot and taking more snapshots
+          from there, it is even possible to create a kind of alternate
+          reality and to switch between these different histories of the
+          virtual machine. This can result in a whole tree of virtual machine
+          snapshots, as shown in the screenshot above.</para>
+        </listitem>
+
+        <listitem>
+          <para>You can also <emphasis role="bold">delete a
+          snapshot</emphasis>, which will not affect the state of the virtual
+          machine, but only release the files on disk that VirtualBox used to
+          store the snapshot data, thus freeing disk space. To delete a
+          snapshot, right-click on it in the snapshots tree and select
+          "Delete". As of VirtualBox 3.2, snapshots can be deleted even while
+          a machine is running.<note>
+              <para>Whereas taking and restoring snapshots are fairly quick
+              operations, deleting a snapshot can take a considerable amount
+              of time since large amounts of data may need to be copied
+              between several disk image files. Temporary disk files may also
+              need large amounts of disk space while the operation is in
+              progress.</para>
+            </note></para>
+
+          <para>There are some situations which cannot be handled while a VM
+          is running, and you will get an appropriate message that you need to
+          perform this snapshot deletion when the VM is shut down.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>Think of a snapshot as a point in time that you have preserved. More
+    formally, a snapshot consists of three things:<itemizedlist>
+        <listitem>
+          <para>It contains a complete copy of the VM settings, so that when
+          you restore a snapshot, the VM settings are restored as well. (For
+          example, if you changed the hard disk configuration, that change is
+          undone when you restore the snapshot.)</para>
+        </listitem>
+
+        <listitem>
+          <para>The state of all the virtual disks attached to the machine is
+          preserved. Going back to a snapshot means that all changes, bit by
+          bit, that had been made to the machine's disks will be undone as
+          well.</para>
+
+          <para>(Strictly speaking, this is only true for virtual hard disks
+          in "normal" mode. As mentioned above, you can configure disks to
+          behave differently with snapshots; see <xref
+          linkend="hdimagewrites" />. Even more formally and technically
+          correct, it is not the virtual disk itself that is restored when a
+          snapshot is restored. Instead, when a snapshot is taken, VirtualBox
+          creates differencing images which contain only the changes since the
+          snapshot were taken, and when the snapshot is restored, VirtualBox
+          throws away that differencing image, thus going back to the previous
+          state. This is both faster and uses less disk space. For the
+          details, which can be complex, please see <xref
+          linkend="diffimages" />.)</para>
+        </listitem>
+
+        <listitem>
+          <para>Finally, if you took a snapshot while the machine was running,
+          the memory state of the machine is also saved in the snapshot (the
+          same way the memory can be saved when you close the VM window) so
+          that when you restore the snapshot, execution resumes at exactly the
+          point when the snapshot was taken.</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+
+  <sect1>
+    <title id="configbasics">Virtual machine configuration</title>
+
+    <para>When you select a virtual machine from the list in the main
+    VirtualBox window, you will see a summary of that machine's settings on
+    the right of the window, under the "Details" tab.</para>
+
+    <para>Clicking on the "Settings" button in the toolbar at the top of
+    VirtualBox main window brings up a detailed window where you can configure
+    many of the properties of the VM that is currently selected. But be
+    careful: even though it is possible to change all VM settings after
+    installing a guest operating system, certain changes might prevent a guest
+    operating system from functioning correctly if done after
+    installation.</para>
+
+    <note>
+      <para>The "Settings" button is disabled while a VM is either in the
+      "running" or "saved" state. This is simply because the settings dialog
+      allows you to change fundamental characteristics of the virtual computer
+      that is created for your guest operating system, and this operating
+      system may not take it well when, for example, half of its memory is
+      taken away from under its feet. As a result, if the "Settings" button is
+      disabled, shut down the current VM first.</para>
+    </note>
+
+    <para>VirtualBox provides a plethora of parameters that can be changed for
+    a virtual machine. The various settings that can be changed in the
+    "Settings" window are described in detail in <xref
+    linkend="BasicConcepts" />. Even more parameters are available with the
+    command line interface; see <xref linkend="vboxmanage" />.</para>
+
+    <para>For now, if you have just created an empty VM, you will probably be
+    most interested in the settings presented by the "CD/DVD-ROM" section if
+    you want to make a CD or a DVD available the first time you start it, in
+    order to install your guest operating system.</para>
+
+    <para>For this, you have two options:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>If you have actual CD or DVD media from which you want to
+        install your guest operating system (e.g. in the case of a Windows
+        installation CD or DVD), put the media into your host's CD or DVD
+        drive.</para>
+
+        <para>Then, in the settings dialog, go to the "CD/DVD-ROM" section and
+        select "Host drive" with the correct drive letter (or, in the case of
+        a Linux host, device file).</para>
+
+        <para>This will allow your VM to access the media in your host drive,
+        and you can proceed to install from there.</para>
+      </listitem>
+
+      <listitem>
+        <para>If you have downloaded installation media from the Internet in
+        the form of an ISO image file (most probably in the case of a Linux
+        distribution), you would normally burn this file to an empty CD or DVD
+        and proceed as just described. With VirtualBox however, you can skip
+        this step and mount the ISO file directly. VirtualBox will then
+        present this file as a CD or DVD-ROM drive to the virtual machine,
+        much like it does with virtual hard disk images.</para>
+
+        <para>In this case, in the settings dialog, go to the "CD/DVD-ROM"
+        section and select "ISO image file". This brings up the Virtual Media
+        Manager, where you perform the following steps:</para>
+
+        <para><orderedlist>
+            <listitem>
+              <para>Press the "Add" button to add your ISO file to the list of
+              registered images. This will present an ordinary file dialog
+              that allows you to find your ISO file on your host
+              machine.</para>
+            </listitem>
+
+            <listitem>
+              <para>Back to the manager window, select the ISO file that you
+              just added and press the "Select" button. This selects the ISO
+              file for your VM.</para>
+            </listitem>
+          </orderedlist></para>
+
+        <para>The Virtual Media Manager is described in detail in <xref
+        linkend="vdis" />.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Deleting virtual machines</title>
+
+    <para>To remove a virtual machine which you no longer need, right-click on
+    it in the list of virtual machines in the main window and select "Delete"
+    from the context menu that comes up. All settings for that machine will be
+    lost.</para>
+
+    <para>The "Delete" menu item is disabled while a machine is in "Saved"
+    state. To delete such a machine, discard the saved state first by pressing
+    on the "Discard" button.</para>
+
+    <para>However, any hard disk images attached to the machine will be kept;
+    you can delete those separately using the Virtual Media Manager; see <xref
+    linkend="vdis" />.</para>
+
+    <para>You cannot delete a machine which has snapshots or is in a saved
+    state, so you must discard these first.</para>
+  </sect1>
+
+  <sect1 id="ovf">
+    <title>Importing and exporting virtual machines</title>
+
+    <para>Starting with version 2.2, VirtualBox can import and export virtual
+    machines in the industry-standard Open Virtualization Format (OVF).</para>
+
+    <para>OVF is a cross-platform standard supported by many virtualization
+    products which allows for creating ready-made virtual machines that can
+    then be imported into a virtualizer such as VirtualBox. As opposed to
+    other virtualization products, VirtualBox now supports OVF with an
+    easy-to-use graphical user interface as well as using the command line.
+    This allows for packaging so-called <emphasis role="bold">virtual
+    appliances</emphasis>: disk images together with configuration settings
+    that can be distributed easily. This way one can offer complete
+    ready-to-use software packages (operating systems with applications) that
+    need no configuration or installation except for importing into
+    VirtualBox.<note>
+        <para>The OVF standard is complex, and support in VirtualBox is an
+        ongoing process. In particular, no guarantee is made that VirtualBox
+        supports all appliances created by other virtualization software. For
+        a list of know limitations, please see <xref
+        linkend="KnownIssues" />.</para>
+      </note></para>
+
+    <para>An appliance in OVF format will typically consist of several
+    files:<orderedlist>
+        <listitem>
+          <para>one or several disk images, typically in the widely-used VMDK
+          format (see <xref linkend="vdidetails" />) and</para>
+        </listitem>
+
+        <listitem>
+          <para>a textual description file in an XML dialect with an
+          <computeroutput>.ovf</computeroutput> extension.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>These files must reside in the same directory for VirtualBox to be
+    able to import them.</para>
+
+    <para>A future version of VirtualBox will also support packages that
+    include the OVF XML file and the disk images packed together in a single
+    archive.</para>
+
+    <para>To <emphasis role="bold">import</emphasis> an appliance in OVF
+    format, select "File" -&gt; "Import appliance" from the main window of the
+    VirtualBox graphical user interface. Then open the file dialog and
+    navigate to the OVF text file with the
+    <computeroutput>.ovf</computeroutput> file extension.</para>
+
+    <para>If VirtualBox can handle the file, a dialog similar to the following
+    will appear:</para>
+
+    <para><mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/ovf-import.png"
+                     width="10cm" />
+        </imageobject>
+      </mediaobject>This presents the virtual machines described in the OVF
+    file and allows you to change the virtual machine settings by
+    double-clicking on the description items. Once you click on <emphasis
+    role="bold">"Import"</emphasis>, VirtualBox will copy the disk images and
+    create local virtual machines with the settings described in the dialog.
+    These will then show up in the list of virtual machines.</para>
+
+    <para>Note that since disk images tend to be big, and VMDK images that
+    come with virtual appliances are typically shipped in a special compressed
+    format that is unsuitable for being used by virtual machines directly, the
+    images will need to be unpacked and copied first, which can take a few
+    minutes.</para>
+
+    <para>For how to import an image at the command line, please see <xref
+    linkend="vboxmanage-import" />.</para>
+
+    <para>Conversely, to <emphasis role="bold">export</emphasis> virtual
+    machines that you already have in VirtualBox, select the machines and
+    "File" -&gt; "Export appliance". A different dialog window shows up that
+    allows you to combine several virtual machines into an OVF appliance.
+    Then, you select the target location where the OVF and VMDK files should
+    be stored, and the conversion process begins. This can again take a
+    while.</para>
+
+    <para>For how to export an image at the command line, please see <xref
+    linkend="vboxmanage-export" />.<note>
+        <para>OVF cannot describe snapshots that were taken for a virtual
+        machine. As a result, when you export a virtual machine that has
+        snapshots, only the current state of the machine will be exported, and
+        the disk images in the export will have a "flattened" state identical
+        to the current state of the virtual machine.</para>
+      </note></para>
+  </sect1>
+
+  <sect1 id="frontends">
+    <title>Alternative front-ends</title>
+
+    <para>As briefly mentioned in <xref linkend="features-overview" />,
+    VirtualBox has a very flexible internal design that allows you to use
+    different front-ends to control the same virtual machines. To illustrate,
+    you can, for example, start a virtual machine with VirtualBox's
+    easy-to-use graphical user interface and then stop it from the command
+    line. With VirtualBox's support for the Remote Desktop Protocol (VRDP),
+    you can even run virtual machines remotely on a headless server and have
+    all the graphical output redirected over the network.</para>
+
+    <para>In detail, the following front-ends are shipped in the standard
+    VirtualBox package:</para>
+
+    <para><orderedlist>
+        <listitem>
+          <para><computeroutput>VirtualBox</computeroutput> is our graphical
+          user interface (GUI), which most of this User Manual is dedicated to
+          describing, especially in <xref linkend="BasicConcepts" />. While
+          this is the easiest-to-use of our interfaces, it does not (yet)
+          cover all the features that VirtualBox provides. Still, this is the
+          best way to get to know VirtualBox initially.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxManage</computeroutput> is our
+          command-line interface for automated and very detailed control of
+          every aspect of VirtualBox. It is described in <xref
+          linkend="vboxmanage" />.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxSDL</computeroutput> is an alternative,
+          simple graphical front-end with an intentionally limited feature
+          set, designed to only display virtual machines that are controlled
+          in detail with <computeroutput>VBoxManage</computeroutput>. This is
+          interesting for business environments where displaying all the bells
+          and whistles of the full GUI is not feasible.
+          <computeroutput>VBoxSDL</computeroutput> is described in <xref
+          linkend="vboxsdl" />.</para>
+        </listitem>
+
+        <listitem>
+          <para>Finally, <computeroutput>VBoxHeadless</computeroutput> is yet
+          another front-end that produces no visible output on the host at
+          all, but merely acts as a VRDP server. Now, even though the other
+          graphical front-ends (VirtualBox and VBoxSDL) also have VRDP support
+          built-in and can act as a VRDP server, this particular front-end
+          requires no graphics support. This is useful, for example, if you
+          want to host your virtual machines on a headless Linux server that
+          has no X Window system installed. For details, see <xref
+          linkend="vboxheadless" />.</para>
+        </listitem>
+      </orderedlist>If the above front-ends still do not satisfy your
+    particular needs, it is relatively painless to create yet another
+    front-end to the complex virtualization engine that is the core of
+    VirtualBox, as the VirtualBox core neatly exposes all of its features in a
+    clean API; please refer to <xref linkend="VirtualBoxAPI" />.</para>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_KnownIssues.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_KnownIssues.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_KnownIssues.xml	(revision 33555)
@@ -0,0 +1,252 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="KnownIssues">
+  <title>Known limitations</title>
+
+  <para>This sections describes known problems with VirtualBox
+  $VBOX_VERSION_STRING. Unless marked otherwise, these issues are planned to
+  be fixed in later releases.</para>
+
+  <itemizedlist>
+    <listitem>
+      <para>The following <emphasis role="bold">Guest SMP (multiprocessor)
+      limitations</emphasis> exist:<itemizedlist>
+          <listitem>
+            <para><emphasis role="bold">Poor performance</emphasis> with
+            32-bit guests on AMD CPUs. This affects mainly Windows and Solaris
+            guests, but possibly also some Linux kernel revisions. Partially
+            solved in 3.0.6 for 32 bits Windows NT, 2000, XP and 2003 guests.
+            Requires 3.0.6 or higher Guest Additions to be installed.</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis role="bold">Poor performance</emphasis> with
+            32-bit guests on certain Intel CPU models that do not include
+            virtual APIC hardware optimization support. This affects mainly
+            Windows and Solaris guests, but possibly also some Linux kernel
+            revisions. Partially solved in 3.0.12 for 32 bits Windows NT,
+            2000, XP and 2003 guests. Requires 3.0.12 or higher Guest
+            Additions to be installed.</para>
+          </listitem>
+
+        </itemizedlist></para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">64-bit guests on some 32-bit host systems
+      with VT-x</emphasis> can cause instabilities to your system. If you
+      experience this, do not attempt to execute 64-bit guests. Refer to the
+      VirtualBox user forum for additional information.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Direct 3D support in Windows
+      guests.</emphasis> For this to work, the Guest Additions must be
+      installed in Windows "safe mode". Press F8 when the Windows guest is
+      booting and select "Safe mode", then install the Guest Additions.
+      Otherwise Windows' file protection mechanism will interfere with the
+      replacement DLLs installed by VirtualBox and keep restoring the original
+      Windows system DLLs.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Guest control.</emphasis> On
+      Windows guests, a process lauched via the guest control execute support is
+      only able to display a graphical user interface if the user account it is
+      started under, is currently logged in and has a desktop
+      session. Otherwise, the process will not be able to display its user
+      interface. </para>
+      <para>Also, for using accounts without or with an empty password specified,
+      the group policy needs to be changed on the guest. To do so, open the
+      group policy editor on the command line by typing
+      <computeroutput>gpedit.msc</computeroutput>, open the key
+      <emphasis>Computer Configuration\Windows Settings\Security Settings\Local Policies\Security Options</emphasis>
+      and change the value of <emphasis>Accounts: Limit local account use of blank passwords to console logon only</emphasis>
+      to <emphasis>Disabled</emphasis>.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Guest multi-monitor support.</emphasis> This
+      feature is currently only supported with Windows guests.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Deleting the only snapshot with a running VM
+      is not implemented.</emphasis> Trying to perform this operation will
+      result in an error message. This feature will be added in one of the
+      next maintenance releases. It is possible to delete the only snapshot
+      when the VM is not running, e.g. in "poweroff" or "saved" state.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Disabled host I/O caches.</emphasis>
+      Disabling the host I/O cache (see <xref linkend="iocaching" />) will
+      yield poor performance with VHD and sparse VMDK files as these do not
+      currently support asynchronous I/O. This does not apply to VDI files and
+      raw disk/partition VMDK files, which do support async I/O. This
+      restriction will be lifted in a future maintenance update.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Compacting virtual disk images is limited to
+      VDI files.</emphasis> The <code>VBoxManage modifyhd --compact</code>
+      command is currently only implemented for VDI files. At the moment the
+      only way to optimize the size of a virtual disk images in other formats
+      (VMDK, VHD) is to clone the image and then use the cloned image in the
+      VM configuration.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">OVF import/export:</emphasis><itemizedlist>
+          <listitem>
+            <para>When importing an OVF that was previously exported by
+            VirtualBox 3.2 or higher which contains a complete VirtualBox machine
+            configuration in the &lt;vbox:Machine&gt; element, some of the
+            import customizations that can be specified (in either the GUI or
+            on the VBoxManage command line) are presently ignored. In
+            particular, customizations of the imported storage configuration
+            are ignored. This will be fixed in the next release.</para>
+          </listitem>
+
+          <listitem>
+            <para>OVF localization (multiple languages in one OVF file) is not
+            yet supported.</para>
+          </listitem>
+
+          <listitem>
+            <para>Some OVF sections like StartupSection,
+            DeploymentOptionSection and InstallSection are ignored.</para>
+          </listitem>
+
+          <listitem>
+            <para>OVF environment documents, including their property sections
+            and appliance configuration with ISO images, are not yet
+            supported.</para>
+          </listitem>
+
+          <listitem>
+            <para>OVA archives (TAR containers) are not yet supported.</para>
+          </listitem>
+
+          <listitem>
+            <para>Remote files via HTTP or other mechanisms are not yet
+            supported.</para>
+          </listitem>
+        </itemizedlist></para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Seamless mode</emphasis> does not work
+      correctly with Linux guests that have 3D effects enabled (such as with
+      compiz-enabled window managers).</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Mac OS X hosts.</emphasis> The following
+      restrictions apply (all of which will be resolved in future
+      versions):<itemizedlist>
+          <listitem>
+            <para>The numlock emulation has not yet been implemented.</para>
+          </listitem>
+
+          <listitem>
+            <para>The CPU frequency metric is not supported.</para>
+          </listitem>
+
+          <listitem>
+            <para>3D OpenGL acceleration, in particular with Linux guests that
+            have 3D effects enabled (such as with compiz-enabled window
+            managers).</para>
+          </listitem>
+
+          <listitem>
+            <para>Memory ballooning is not supported.</para>
+          </listitem>
+        </itemizedlist></para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Mac OS X Server guests.</emphasis>
+      <itemizedlist>
+          <listitem>
+            <para>Mac OS X Server guests can only run on a certain host
+            hardware. For details about license and host hardware limitations,
+            please see <xref linkend="intro-macosxguests" />.</para>
+          </listitem>
+
+          <listitem>
+            <para>VirtualBox does not provide Guest Additions for Mac OS X
+            Server at this time.</para>
+          </listitem>
+
+          <listitem>
+            <para>The graphics resolution currently defaults to 1024x768 as
+            Mac OS X Server falls back to the built-in EFI display support.
+            See <xref linkend="efividmode" /> for more information on how to
+            change EFI video modes.</para>
+          </listitem>
+
+          <listitem>
+            <para>Even when idle, Mac OS X Server guests currently burn 100%
+            CPU. This is a power management issue that will be addressed in a
+            future release.</para>
+          </listitem>
+
+          <listitem>
+            <para>Mac OS X Server guests only work with one CPU assigned to
+            the VM. Support for SMP will be provided in a future
+            release.</para>
+          </listitem>
+
+          <listitem>
+            <para>Depending on your system and version of Mac OS X Server, you
+            might experience guest hangs after some time. This can be fixed by
+            turning off energy saving (set timeout to "Never") in the system
+            preferences.</para>
+          </listitem>
+
+          <listitem>
+            <para>By default, the VirtualBox EFI enables debug output of the
+            Mac OS X Server kernel to help you diagnose boot problems. Note
+            that there is a lot of output and not all errors are fatal (they
+            would also show on your physical Mac). You can turn off these
+            messages by issuing this command:<screen>VBoxManage setextradata "VM name" "VBoxInternal2/EfiBootArgs" "  "</screen>To
+            revert to the previous behavior, use:<screen>VBoxManage setextradata "VM name" "VBoxInternal2/EfiBootArgs" ""</screen></para>
+          </listitem>
+        </itemizedlist></para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Solaris hosts.</emphasis> The following
+      restrictions apply for OpenSolaris and Solaris 10:<itemizedlist>
+          <listitem>
+            <para>There is no support for USB devices connected to Solaris 10 hosts.</para>
+          </listitem>
+
+          <listitem>
+            <para>USB support on OpenSolaris hosts requires version snv_124 or
+            higher. Webcams and other isochronous devices are known to have
+            poor performance.</para>
+          </listitem>
+
+          <listitem>
+            <para>No ACPI information (battery status, power source) is
+            reported to the guest.</para>
+          </listitem>
+
+          <listitem>
+            <para>No support for using wireless adapters with bridged
+            networking.</para>
+          </listitem>
+        </itemizedlist></para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Guest Additions for OS/2.</emphasis> Shared
+      folders are not yet supported with OS/2 guests. In addition, seamless
+      windows and automatic guest resizing will probably never be implemented
+      due to inherent limitations of the OS/2 graphics system.</para>
+    </listitem>
+  </itemizedlist>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_Networking.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_Networking.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_Networking.xml	(revision 33555)
@@ -0,0 +1,605 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="networkingdetails">
+  <title>Virtual networking</title>
+
+  <para>As briefly mentioned in <xref linkend="settings-network" />,
+  VirtualBox provides up to eight virtual PCI Ethernet cards for each virtual
+  machine. For each such card, you can individually select<orderedlist>
+      <listitem>
+        <para>the hardware that will be virtualized as well as</para>
+      </listitem>
+
+      <listitem>
+        <para>the virtualization mode that the virtual card will be operating
+        in with respect to your physical networking hardware on the
+        host.</para>
+      </listitem>
+    </orderedlist></para>
+
+  <para>Four of the network cards can be configured in the "Network" section
+  of the settings dialog in the graphical user interface of VirtualBox. You
+  can configure all eight network cards on the command line via VBoxManage
+  modifyvm; see <xref linkend="vboxmanage-modifyvm" />.</para>
+
+  <para>This chapter explains the various networking settings in more
+  detail.</para>
+
+  <sect1 id="nichardware">
+    <title>Virtual networking hardware</title>
+
+    <para>For each card, you can individually select what kind of
+    <emphasis>hardware</emphasis> will be presented to the virtual machine.
+    VirtualBox can virtualize the following six types of networking
+    hardware:<itemizedlist>
+        <listitem>
+          <para>AMD PCNet PCI II (Am79C970A);</para>
+        </listitem>
+
+        <listitem>
+          <para>AMD PCNet FAST III (Am79C973, the default);</para>
+        </listitem>
+
+        <listitem>
+          <para>Intel PRO/1000 MT Desktop (82540OEM);</para>
+        </listitem>
+
+        <listitem>
+          <para>Intel PRO/1000 T Server (82543GC);</para>
+        </listitem>
+
+        <listitem>
+          <para>Intel PRO/1000 MT Server (82545EM);</para>
+        </listitem>
+
+        <listitem>
+          <para>Paravirtualized network adapter (virtio-net).</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>The PCNet FAST III is the default because it is supported by nearly
+    all operating systems out of the box, as well as the GNU GRUB boot
+    manager. As an exception, the Intel PRO/1000 family adapters are chosen
+    for some guest operating system types that no longer ship with drivers for
+    the PCNet card, such as Windows Vista; see <xref
+    linkend="vista_networking" /> for details.<footnote>
+        <para>Support for the Intel PRO/1000 MT Desktop type was added with
+        VirtualBox 1.6. The T Server variant of the Intel PRO/1000 card was
+        added with VirtualBox 1.6.2 because this one is recognized by Windows
+        XP guests without additional driver installation. The MT Server
+        variant was added with VirtualBox 2.2 to facilitate OVF imports from
+        other platforms.</para>
+      </footnote></para>
+
+    <para>The <emphasis role="bold">"Paravirtualized network adapter
+    (virtio-net)"</emphasis> is special. If you select this, then VirtualBox
+    does <emphasis>not</emphasis> virtualize common networking hardware (that
+    is supported by common guest operating systems out of the box). Instead,
+    VirtualBox then expects a special software interface for virtualized
+    environments to be provided by the guest, thus avoiding the complexity of
+    emulating networking hardware and improving network performance. Starting
+    with version 3.1, VirtualBox provides support for the industry-standard
+    "virtio" networking drivers, which are part of the open-source KVM
+    project.</para>
+
+    <para>The "virtio" networking drivers are available for the following
+    guest operating systems:</para>
+
+    <para><itemizedlist>
+        <listitem>
+          <para>Linux kernels version 2.6.25 or later can be configured to
+          provide virtio support; some distributions also back-ported virtio
+          to older kernels.</para>
+        </listitem>
+
+        <listitem>
+          <para>For Windows 2000, XP and Vista, virtio drivers can be
+          downloaded and installed from the KVM project web page.<footnote>
+              <para><ulink
+              url="http://www.linux-kvm.org/page/WindowsGuestDrivers">http://www.linux-kvm.org/page/WindowsGuestDrivers</ulink>.</para>
+            </footnote></para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>VirtualBox also has limited support for so-called <emphasis
+    role="bold">jumbo frames</emphasis>, i.e. networking packets with more
+    than 1500 bytes of data, provided that you use the Intel card
+    virtualization and bridged networking. In other words, jumbo frames are
+    not supported with the AMD networking devices; in those cases, jumbo
+    packets will silently be dropped for both the transmit and the receive
+    direction. Guest operating systems trying to use this feature will observe
+    this as a packet loss, which may lead to unexpected application behavior
+    in the guest. This does not cause problems with guest operating systems in
+    their default configuration, as jumbo frames need to be explicitly
+    enabled.</para>
+  </sect1>
+
+  <sect1 id="networkingmodes">
+    <title>Introduction to networking modes</title>
+
+    <para>Each of the eight networking adapters can be separately configured
+    to operate in one of the following five modes:<glosslist>
+        <glossentry>
+          <glossterm>Not attached</glossterm>
+
+          <glossdef>
+            <para>In this mode, VirtualBox reports to the guest that a network
+            card is present, but that there is no connection -- as if no
+            Ethernet cable was plugged into the card. This way it is possible
+            to "pull" the virtual Ethernet cable and disrupt the connection,
+            which can be useful to inform a guest operating system that no
+            network connection is available and enforce a
+            reconfiguration.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Network Address Translation (NAT)</glossterm>
+
+          <glossdef>
+            <para>If all you want is to browse the Web, download files and
+            view e-mail inside the guest, then this default mode should be
+            sufficient for you, and you can safely skip the rest of this
+            section. Please note that there are certain limitations when using
+            Windows file sharing (see <xref linkend="nat-limitations" /> for
+            details).</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Bridged networking</glossterm>
+
+          <glossdef>
+            <para>This is for more advanced networking needs such as network
+            simulations and running servers in a guest. When enabled,
+            VirtualBox connects to one of your installed network cards and
+            exchanges network packets directly, circumventing your host
+            operating system's network stack.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Internal networking</glossterm>
+
+          <glossdef>
+            <para>This can be used to create a different kind of
+            software-based network which is visible to selected virtual
+            machines, but not to applications running on the host or to the
+            outside world.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Host-only networking</glossterm>
+
+          <glossdef>
+            <para>This can be used to create a network containing the host and
+            a set of virtual machines, without the need for the host's
+            physical network interface. Instead, a virtual network interface
+            (similar to a loopback interface) is created on the host,
+            providing connectivity among virtual machines and the host.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>VDE (Virtual Distributed Ethernet) networking</glossterm>
+
+          <glossdef>
+            <para>This option can be used to connect to a Virtual Distributed
+            Ethernet switch on a Linux or a FreeBSD host. It is only available
+            if the VDE software and the VDE plugin library from the
+            VirtualSquare project are installed on the host system. For more
+            information on setting up VDE networks, please see the
+            documentation accompanying the software.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+
+    <para>The following sections describe the available network modes in more
+    detail.</para>
+  </sect1>
+
+  <sect1 id="network_nat">
+    <title>Network Address Translation (NAT)</title>
+
+    <para>Network Address Translation (NAT) is the simplest way of accessing
+    an external network from a virtual machine. Usually, it does not require
+    any configuration on the host network and guest system. For this reason,
+    it is the default networking mode in VirtualBox.</para>
+
+    <para>A virtual machine with NAT enabled acts much like a real computer
+    that connects to the Internet through a router. The "router", in this
+    case, is the VirtualBox networking engine, which maps traffic from and to
+    the virtual machine transparently. The disadvantage of NAT mode is that,
+    much like a private network behind a router, the virtual machine is
+    invisible and unreachable from the outside internet; you cannot run a
+    server this way unless you set up port forwarding (described
+    below).</para>
+
+    <para>The network frames sent out by the guest operating system are
+    received by VirtualBox's NAT engine, which extracts the TCP/IP data and
+    resends it using the host operating system. To an application on the host,
+    or to another computer on the same network as the host, it looks like the
+    data was sent by the VirtualBox application on the host, using an IP
+    address belonging to the host. VirtualBox listens for replies to the
+    packages sent, and repacks and resends them to the guest machine on its
+    private network.</para>
+
+    <para>The virtual machine receives its network address and configuration
+    on the private network from a DHCP server integrated into VirtualBox. The
+    IP address thus assigned to the virtual machine is usually on a completely
+    different network than the host. As more than one card of a virtual
+    machine can be set up to use NAT, the first card is connected to the
+    private network 10.0.2.0, the second card to the network 10.0.3.0 and so
+    on. If you need to change the guest-assigned IP range for some reason,
+    please refer to <xref linkend="changenat" />.</para>
+
+    <sect2 id="natforward">
+      <title>Configuring port forwarding with NAT</title>
+
+      <para>As the virtual machine is connected to a private network internal
+      to VirtualBox and invisible to the host, network services on the guest
+      are not accessible to the host machine or to other computers on the same
+      network. However, like a physical router, VirtualBox can make selected
+      services available to the world outside the guest through <emphasis
+      role="bold">port forwarding.</emphasis> This means that VirtualBox
+      listens to certain ports on the host and resends all packets which
+      arrive there to the guest, on the same or a different port.</para>
+
+      <para>To an application on the host or other physical (or virtual)
+      machines on the network, it looks as though the service being proxied is
+      actually running on the host. This also means that you cannot run the
+      same service on the same ports on the host. However, you still gain the
+      advantages of running the service in a virtual machine -- for example,
+      services on the host machine or on other virtual machines cannot be
+      compromised or crashed by a vulnerability or a bug in the service, and
+      the service can run in a different operating system than the host
+      system.</para>
+
+      <para>You can set up a guest service which you wish to proxy using the
+      command line tool <computeroutput>VBoxManage</computeroutput>; for
+      details, please refer to <xref linkend="vboxmanage-modifyvm" />.</para>
+
+      <para>You will need to know which ports on the guest the service uses
+      and to decide which ports to use on the host (often but not always you
+      will want to use the same ports on the guest and on the host). You can
+      use any ports on the host which are not already in use by a service. For
+      example, to set up incoming NAT connections to an
+      <computeroutput>ssh</computeroutput> server in the guest, use the
+      following command: <screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,,22"</screen>With
+      the above example, all TCP traffic arriving on port 2222 on any host
+      interface will be forwarded to port 22 in the guest. The protocol name
+      <computeroutput>tcp</computeroutput> is a mandatory attribute defining
+      which protocol should be used for forwarding
+      (<computeroutput>udp</computeroutput> could also be used). The name
+      <computeroutput>guestssh</computeroutput> is purely descriptive and will
+      be auto-generated if omitted. The number after
+      <computeroutput>--natpf</computeroutput> denotes the network card, like
+      in other parts of VBoxManage.</para>
+
+      <para>To remove this forwarding rule again, use the following command:
+      <screen>VBoxManage modifyvm "VM name" --natpf1 delete "guestssh"</screen></para>
+
+      <para>If for some reason the guest uses a static assigned IP address not
+      leased from the built-in DHCP server, it is required to specify the
+      guest IP when registering the forwarding rule: <screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,10.0.2.19,22"</screen>This
+      example is identical to the previous one, except that the NAT engine is
+      being told that the guest can be found at the 10.0.2.19 address.</para>
+
+      <para>To forward <emphasis>all</emphasis> incoming traffic from a
+      specific host interface to the guest, specify the IP of that host
+      interface like this:<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,127.0.0.1,2222,,22"</screen>This
+      forwards all TCP traffic arriving on the localhost interface (127.0.0.1)
+      via port 2222 to port 22 in the guest.</para>
+
+      <para>It is not possible to configure incoming NAT connections while the
+      VM is running. However, you can change the settings for a VM which is
+      currently saved (or powered off at a snapshot).</para>
+    </sect2>
+
+    <sect2 id="nat-tftp">
+      <title>PXE booting with NAT</title>
+
+      <para>PXE booting is now supported in NAT mode. The NAT DHCP server
+      provides a boot file name of the form
+      <computeroutput>vmname.pxe</computeroutput> if the directory
+      <computeroutput>TFTP</computeroutput> exists in the directory where the
+      user's <computeroutput>VirtualBox.xml</computeroutput> file is kept. It
+      is the responsibility of the user to provide
+      <computeroutput>vmname.pxe</computeroutput>.</para>
+    </sect2>
+
+    <sect2 id="nat-limitations">
+      <title>NAT limitations</title>
+
+      <para>There are four <emphasis role="bold">limitations</emphasis> of NAT
+      mode which users should be aware of:</para>
+
+      <glosslist>
+        <glossentry>
+          <glossterm>ICMP protocol limitations:</glossterm>
+
+          <glossdef>
+            <para>Some frequently used network debugging tools (e.g.
+            <computeroutput>ping</computeroutput> or tracerouting) rely on the
+            ICMP protocol for sending/receiving messages. While ICMP support
+            has been improved with VirtualBox 2.1
+            (<computeroutput>ping</computeroutput> should now work), some
+            other tools may not work reliably.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Receiving of UDP broadcasts is not reliable:</glossterm>
+
+          <glossdef>
+            <para>The guest does not reliably receive broadcasts, since, in
+            order to save resources, it only listens for a certain amount of
+            time after the guest has sent UDP data on a particular port. As a
+            consequence, NetBios name resolution based on broadcasts does not
+            always work (but WINS always works). As a workaround, you can use
+            the numeric IP of the desired server in the
+            <computeroutput>\\server\share</computeroutput> notation.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Protocols such as GRE are unsupported:</glossterm>
+
+          <glossdef>
+            <para>Protocols other than TCP and UDP are not supported. This
+            means some VPN products (e.g. PPTP from Microsoft) cannot be used.
+            There are other VPN products which use simply TCP and UDP.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Forwarding host ports &lt; 1024 impossible:</glossterm>
+
+          <glossdef>
+            <para>On Unix-based hosts (e.g. Linux, Solaris, Mac OS X) it is
+            not possible to bind to ports below 1024 from applications that
+            are not run by <computeroutput>root</computeroutput>. As a result,
+            if you try to configure such a port forwarding, the VM will refuse
+            to start.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist>
+
+      <para>These limitations normally don't affect standard network use. But
+      the presence of NAT has also subtle effects that may interfere with
+      protocols that are normally working. One example is NFS, where the
+      server is often configured to refuse connections from non-privileged
+      ports (i.e. ports not below 1024).</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title id="network_bridged">Bridged networking</title>
+
+    <para>With bridged networking, VirtualBox uses a device driver on your
+    <emphasis>host</emphasis> system that filters data from your physical
+    network adapter. This driver is therefore called a "net filter" driver.
+    This allows VirtualBox to intercept data from the physical network and
+    inject data into it, effectively creating a new network interface in
+    software. When a guest is using such a new software interface, it looks to
+    the host system as though the guest were physically connected to the
+    interface using a network cable: the host can send data to the guest
+    through that interface and receive data from it. This means that you can
+    set up routing or bridging between the guest and the rest of your
+    network.</para>
+
+    <para>For this to work, VirtualBox needs a device driver on your host
+    system. The way bridged networking works has been completely rewritten
+    with VirtualBox 2.0 and 2.1, depending on the host operating system. From
+    the user perspective, the main difference is that complex configuration is
+    no longer necessary on any of the supported host operating
+    systems.<footnote>
+        <para>For Mac OS X and Solaris hosts, net filter drivers were already
+        added in VirtualBox 2.0 (as initial support for Host Interface
+        Networking on these platforms). With VirtualBox 2.1, net filter
+        drivers were also added for the Windows and Linux hosts, replacing the
+        mechanisms previously present in VirtualBox for those platforms;
+        especially on Linux, the earlier method required creating TAP
+        interfaces and bridges, which was complex and varied from one
+        distribution to the next. None of this is necessary anymore. Bridged
+        network was formerly called "Host Interface Networking" and has been
+        renamed with version 2.2 without any change in functionality.</para>
+      </footnote></para>
+
+    <para><note>
+        <para>Even though TAP is no longer necessary on Linux with bridged
+        networking, you <emphasis>can</emphasis> still use TAP interfaces for
+        certain advanced setups, since you can connect a VM to any host
+        interface -- which could also be a TAP interface.</para>
+      </note>To enable bridged networking, all you need to do is to open the
+    Settings dialog of a virtual machine, go to the "Network" page and select
+    "Bridged network" in the drop down list for the "Attached to" field.
+    Finally, select desired host interface from the list at the bottom of the
+    page, which contains the physical network interfaces of your systems. On a
+    typical MacBook, for example, this will allow you to select between "en1:
+    AirPort" (which is the wireless interface) and "en0: Ethernet", which
+    represents the interface with a network cable.</para>
+
+    <para>Depending on your host operating system, the following limitations
+    should be kept in mind:<itemizedlist>
+        <listitem>
+          <para>On <emphasis role="bold">Macintosh</emphasis> hosts,
+          functionality is limited when using AirPort (the Mac's wireless
+          networking) for bridged networking. Currently, VirtualBox supports
+          only IPv4 over AirPort. For other protocols such as IPv6 and IPX,
+          you must choose a wired interface.</para>
+        </listitem>
+
+        <listitem>
+          <para>On <emphasis role="bold">Linux</emphasis> hosts, functionality
+          is limited when using wireless interfaces for bridged networking.
+          Currently, VirtualBox supports only IPv4 over wireless. For other
+          protocols such as IPv6 and IPX, you must choose a wired
+          interface.</para>
+
+          <para>Also, setting the MTU to less than 1500 bytes on wired
+          interfaces provided by the sky2 driver on the Marvell Yukon II EC
+          Ultra Ethernet NIC is known to cause packet losses under certain
+          conditions.</para>
+        </listitem>
+
+        <listitem>
+          <para>On <emphasis role="bold">Solaris</emphasis> hosts, there is no
+          support for using wireless interfaces. Filtering guest traffic using
+          IPFilter is also not completely supported due to technical
+          restrictions of the Solaris networking subsystem. These issues would
+          be addressed in a future release of OpenSolaris.</para>
+
+          <para>With VirtualBox 2.0.4 and above, it is possible to use
+          Crossbow Virtual Network Interfaces (VNICs) with bridged networking,
+          but with the following caveats:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>A VNIC cannot be shared between multiple guest network
+              interfaces, i.e. each guest network interface must have its own,
+              exclusive VNIC.</para>
+            </listitem>
+
+            <listitem>
+              <para>The VNIC and the guest network interface that uses the
+              VNIC must be assigned identical MAC addresses.</para>
+            </listitem>
+          </itemizedlist>
+
+          <para>When using VLAN interfaces with VirtualBox, they must be named
+          according to the PPA-hack naming scheme (e.g. "e1000g513001"), as
+          otherwise the guest may receive packets in an unexpected
+          format.</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+
+  <sect1 id="network_internal">
+    <title>Internal networking</title>
+
+    <para>Internal Networking is similar to bridged networking in that the VM
+    can directly communicate with the outside world. However, the "outside
+    world" is limited to other VMs on the same host which connect to the same internal
+    network.</para>
+
+    <para>Even though technically, everything that can be done using internal
+    networking can also be done using bridged networking, there are security
+    advantages with internal networking. In bridged networking mode, all traffic
+    goes through a physical interface of the host system. It is therefore possible
+    to attach a packet sniffer (such as Wireshark) to the host interface and log
+    all traffic that goes over it. If, for any reason, you prefer two or more VMs
+    on the same machine to communicate privately, hiding their data from both
+    the host system and the user, bridged networking therefore is not an option.</para>
+
+    <para>Internal networks are created automatically as needed, i.e. there is
+    no central configuration. Every internal network is identified simply by
+    its name. Once there is more than one active virtual network card with the
+    same internal network ID, the VirtualBox support driver will automatically
+    "wire" the cards and act as a network switch. The VirtualBox support
+    driver implements a complete Ethernet switch and supports both
+    broadcast/multicast frames and promiscuous mode.</para>
+
+    <para>In order to attach a VM's network card to an internal network, set
+    its networking mode to "internal networking". There are two ways to
+    accomplish this:</para>
+
+    <para><itemizedlist>
+        <listitem>
+          <para>You can use a VM's "Settings" dialog in the VirtualBox
+          graphical user interface. In the "Networking" category of the
+          settings dialog, select "Internal Networking" from the drop-down
+          list of networking modes. Now select the name of an existing
+          internal network from the drop-down below or enter a new name into
+          the entry field.</para>
+        </listitem>
+
+        <listitem>
+          <para>You can use <screen>VBoxManage modifyvm "VM name" --nic&lt;x&gt; intnet</screen>
+          Optionally, you can specify a network name with the command <screen>VBoxManage modifyvm "VM name" --intnet&lt;x&gt; "network name"</screen>
+          If you do not specify a network name, the network card will be
+          attached to the network <computeroutput>intnet</computeroutput> by
+          default.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>Unless you configure the (virtual) network cards in the guest
+    operating systems that are participating in the internal network to use
+    static IP addresses, you may want to use the DHCP server that is built
+    into VirtualBox to manage IP addresses for the internal network. Please
+    see <xref linkend="vboxmanage-dhcpserver" /> for details.</para>
+
+    <para>As a security measure, the Linux implementation of internal
+    networking only allows VMs running under the same user ID to establish an
+    internal network.</para>
+  </sect1>
+
+  <sect1 id="network_hostonly">
+    <title>Host-only networking</title>
+
+    <para>Host-only networking is another networking mode that was added with
+    version 2.2 of VirtualBox. It can be thought of as a hybrid between the
+    bridged and internal networking modes: as with bridged networking, the
+    virtual machines can talk to each other and the host as if they were
+    connected through a physical ethernet switch. Similarly, as with internal
+    networking however, a physical networking interface need not be present,
+    and the virtual machines cannot talk to the world outside the host since
+    they are not connected to a physical networking interface.</para>
+
+    <para>Instead, when host-only networking is used, VirtualBox creates a new
+    software interface on the host which then appears next to your existing
+    network interfaces. In other words, whereas with bridged networking an
+    existing physical interface is used to attach virtual machines to, with
+    host-only networking a new "loopback" interface is created on the host.
+    And whereas with internal networking, the traffic between the virtual
+    machines cannot be seen, the traffic on the "loopback" interface on the
+    host can be intercepted.</para>
+
+    <para>Host-only networking is particularly useful for preconfigured
+    virtual appliances, where multiple virtual machines are shipped together
+    and designed to cooperate. For example, one virtual machine may contain a
+    web server and a second one a database, and since they are intended to
+    talk to each other, the appliance can instruct VirtualBox to set up a
+    host-only network for the two. A second (bridged) network would then
+    connect the web server to the outside world to serve data to, but the
+    outside world cannot connect to the database.</para>
+
+    <para>To change a virtual machine's virtual network interface to "host
+    only" mode:<itemizedlist>
+        <listitem>
+          <para>either go to the "Network" page in the virtual machine's
+          settings notebook in the graphical user interface and select
+          "Host-only networking", or</para>
+        </listitem>
+
+        <listitem>
+          <para>on the command line, type <computeroutput>VBoxManage modifyvm
+          "VM name" --nic&lt;x&gt; hostonly</computeroutput>; see <xref
+          linkend="vboxmanage-modifyvm" /> for details.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>For host-only networking, like with internal networking, you may
+    find the DHCP server useful that is built into VirtualBox. This can be
+    enabled to then manage the IP addresses in the host-only network since
+    otherwise you would need to configure all IP addresses
+    statically.<itemizedlist>
+        <listitem>
+          <para>In the VirtualBox graphical user interface, you can configure
+          all these items in the global settings via "File" -&gt; "Settings"
+          -&gt; "Network", which lists all host-only networks which are
+          presently in use. Click on the network name and then on the "Edit"
+          button to the right, and you can modify the adapter and DHCP
+          settings.</para>
+        </listitem>
+
+        <listitem>
+          <para>Alternatively, you can use <computeroutput>VBoxManage
+          dhcpserver</computeroutput> on the command line; please see <xref
+          linkend="vboxmanage-dhcpserver" /> for details.</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_PrivacyPolicy.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_PrivacyPolicy.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_PrivacyPolicy.xml	(revision 33555)
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<appendix id="privacy">
+  <title>VirtualBox privacy policy</title>
+
+  <para>Policy version 4, Apr 22, 2010</para>
+
+  <para>This privacy policy sets out how Oracle Corporation ("Oracle") treats
+  personal information related to the virtualbox.org website and the
+  VirtualBox application.</para>
+
+  <para><emphasis role="bold">§ 1 virtualbox.org.</emphasis> The
+  "virtualbox.org" website logs anonymous usage information such as your IP
+  address, geographical location, browser type, referral source, length of
+  visit and number of page views while you visit (collectively, "anonymous
+  data"). In addition, but only if you choose to register, the website's bug
+  tracking and forum services store the data you choose to reveal upon
+  registration, such as your user name and contact information.</para>
+
+  <para><emphasis role="bold">§ 2 Cookies.</emphasis> The virtualbox.org
+  website, the bug tracker and the forum services use cookies to identify and
+  track the visiting web browser and, if you have registered, to facilitate
+  login. Most browsers allow you to refuse to accept cookies. While you can
+  still visit the website with cookies disabled, logging into the bug tracker
+  and forum services will most likely not work without them.</para>
+
+  <para><emphasis role="bold">§ 3 VirtualBox registration process.</emphasis>
+  The VirtualBox application may ask that the user optinoally register with
+  Oracle. in der If you choose to register, your name, e-mail address, country
+  and company will be submitted to Oracle and stored together with the IP
+  address of the submitter as well as product version and platform being used.
+  The standard Oracle Privacy Policies as posted on
+  http://www.oracle.com/html/privacy.html apply to this data.</para>
+
+  <para><emphasis role="bold">§ 4 Update notifications.</emphasis> The
+  VirtualBox application may contact Oracle to find out whether a new version
+  of VirtualBox has been released and notify the user if that is the case. In
+  the process, anonymous data such as your IP address and a non-identifying
+  counter, together with the product version and the platform being used, is
+  sent so that the server can find out whether an update is available. By
+  default, this check is performed once a day. You change this interval or
+  disable these checks altogether in the VirtualBox preferences.</para>
+
+  <para><emphasis role="bold">§ 5 Usage of personal information.</emphasis>
+  Oracle may use anonymous and personal data collected by the means above for
+  statistical purposes as well as to automatically inform you about new
+  notices related to your posts on the bug tracker and forum services, to
+  administer the website and to contact you due to technical issues. Oracle
+  may also inform you about new product releases related to VirtualBox.</para>
+
+  <para>In no event will personal data without your express consent be
+  provided to any third parties, unless Oracle may be required to do so by law
+  or in connection with legal proceedings.</para>
+
+  <para><emphasis role="bold">§ 6 Updates.</emphasis> Oracle may update this
+  privacy policy by posting a new version on the virtualbox.org website. You
+  should check this page occasionally to ensure you are happy with any
+  changes.</para>
+</appendix>
Index: trunk/doc/manual/fr_FR/user_Storage.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_Storage.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_Storage.xml	(revision 33555)
@@ -0,0 +1,944 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="storage">
+  <title>Virtual storage</title>
+
+  <para>As the virtual machine will most probably expect to see a hard disk
+  built into its virtual computer, VirtualBox must be able to present "real"
+  storage to the guest as a virtual hard disk. There are presently three
+  methods in which to achieve this:</para>
+
+  <orderedlist>
+    <listitem>
+      <para>Most commonly, VirtualBox will use large image files on a real
+      hard disk and present them to a guest as a virtual hard disk. This is
+      described in <xref linkend="vdidetails" />.</para>
+    </listitem>
+
+    <listitem>
+      <para>Alternatively, if you have iSCSI storage servers, you can attach
+      such a server to VirtualBox as well; this is described in <xref
+      linkend="storage-iscsi" />.</para>
+    </listitem>
+
+    <listitem>
+      <para>Finally, as an experimental feature, you can allow a virtual
+      machine to access one of your host disks directly; this advanced feature
+      is described in <xref linkend="rawdisk" />.</para>
+    </listitem>
+  </orderedlist>
+
+  <para>Each such virtual storage device (image file, iSCSI target or physical
+  hard disk) will need to be connected to the virtual hard disk controller
+  that VirtualBox presents to a virtual machine. This is explained in the next
+  section.</para>
+
+  <sect1 id="harddiskcontrollers">
+    <title>Hard disk controllers: IDE, SATA (AHCI), SCSI, SAS</title>
+
+    <para>In a real PC, hard disks and CD/DVD drives are connected to a device
+    called hard disk controller which drives hard disk operation and data
+    transfers. VirtualBox can emulate the three most common types of hard disk
+    controllers typically found in today's PCs: IDE, SATA (AHCI) and
+    SCSI.<footnote>
+        <para>SATA support was added with VirtualBox 1.6; experimental SCSI
+        support was added with 2.1 and fully implemented with 2.2. Generally,
+        storage attachments were made much more flexible with VirtualBox 3.1;
+        see below.</para>
+      </footnote><itemizedlist>
+        <listitem>
+          <para><emphasis role="bold">IDE (ATA)</emphasis> controllers have
+          been in use since the 1980s. Initially, this type of interface
+          worked only with hard disks, but was later extended to also support
+          CD-ROM drives and other types of removable media. In physical PCs,
+          this standard uses flat ribbon parallel cables with 40 or 80 wires.
+          Each such cable can connect two devices to a controller, which have
+          traditionally been called "master" and "slave". Typical hard disk
+          controllers have two connectors for such cables; as a result, most
+          PCs support up to four devices.</para>
+
+          <para>In VirtualBox, each virtual machine has one IDE controller
+          enabled by default, which gives you up to four virtual storage
+          devices that you can attach to the machine. (By default, one of
+          these four -- the secondary master -- is preconfigured to be the
+          machine's virtual CD/DVD drive, but this can be changed.<footnote>
+              <para>The assignment of the machine's CD/DVD drive to the
+              secondary master was fixed before VirtualBox 3.1; it is now
+              changeable, and the drive can be at other slots of the IDE
+              controller, and there can be more than one such drive.</para>
+            </footnote>)</para>
+
+          <para>So even if your guest operating system has no support for SCSI
+          or SATA devices, it should always be able to see the default IDE
+          controller that is enabled by default.</para>
+
+          <para>You can also select which exact type of IDE controller
+          hardware VirtualBox should present to the virtual machine (PIIX3,
+          PIIX4 or ICH6). This makes no difference in terms of performance,
+          but if you import a virtual machine from another virtualization
+          product, the operating system in that machine may expect a
+          particular controller and crash if it isn't found.</para>
+
+          <para>After you have created a new virtual machine with the "New
+          Virtual Machine" wizard of the graphical user interface, you will
+          typically see one IDE controller in the machine's "Storage"
+          settings where the virtual CD/DVD drive will be attached
+          to one of the four ports of this controller.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Serial ATA (SATA)</emphasis> is a newer
+          standard introduced in 2003. Compared to IDE, it supports both much
+          higher speeds and more devices per hard disk controller. Also, with
+          physical hardware, devices can be added and removed while the system
+          is running. The standard interface for SATA controllers is called
+          Advanced Host Controller Interface (<emphasis
+          role="bold">AHCI</emphasis>).</para>
+
+          <para>For compatibility reasons, AHCI controllers by default operate
+          the disks attached to it in a so-called "IDE compatibility mode",
+          unless SATA support is explicitly requested. "IDE compatibility
+          mode" only means that the drives can be seen and operated by the
+          computer's BIOS. Still, disks assigned to those slots will operate
+          in full-speed AHCI mode once the guest operating system has loaded
+          its AHCI device driver.</para>
+
+          <para>Like a real SATA controller, VirtualBox's virtual SATA
+          controller operates faster and also consumes less CPU resources than
+          the virtual IDE controller. Also, this allows you to connect up to
+          30 virtual hard disks to one machine instead of just three, as with
+          the VirtualBox IDE controller (with the DVD drive already attached).
+          Of these, the first four (numbered 0-3 in the graphical user
+          interface) are operated in IDE compatibility mode by default.</para>
+
+          <para>For this reason, starting with version 3.2 and depending on
+          the selected guest operating system, VirtualBox uses SATA as the
+          default for newly created virtual machines. One virtual SATA
+          controller is created by default, and the default disk that is
+          created with a new VM is attached to this controller.<warning>
+              <para>The entire SATA controller and the virtual disks attached
+              to it (including those in IDE compatibility mode) will not be
+              seen by operating systems that do not have device support for
+              AHCI. In particular, <emphasis role="bold">there is no support
+              for AHCI in Windows before Windows Vista</emphasis>, so Windows
+              XP (even SP2) will not see such disks unless you install
+              additional drivers. It is possible to switch from IDE to SATA
+              after installation by installing the SATA drivers and changing
+              the controller type in the VM settings dialog.
+              <footnote><para>VirtualBox recommends the Intel Matrix Storage
+              drivers which can be downloaded from
+              http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101
+              </para></footnote></para>
+            </warning></para>
+
+          <para>To add a SATA controller to a machine for which it has not
+          been enabled by default (either because it was created by an earlier
+          version of VirtualBox, or because SATA is not supported by default
+          by the selected guest operating system), go to the "Storage" page of
+          of the machine's settings dialog, click on the "Add Controller"
+          button under the "Storage Tree" box and then select "Add SATA
+          Controller". After this, the additional controller will appear as a
+          separate PCI device in the virtual machine, and you can add virtual
+          disks to it.</para>
+
+          <para>To change the IDE compatibility mode settings for the SATA
+          controller, please see <xref linkend="vboxmanage-storage" />.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">SCSI</emphasis> is another established
+          industry standard, standing for "Small Computer System Interface".
+          SCSI was standardized as early as 1986 as a generic interface for
+          data transfer between all kinds of devices, including storage
+          devices. Today SCSI is still used for connecting hard disks and tape
+          devices, but it has mostly been displaced in commodity hardware. It
+          is still in common use in high-performance workstations and
+          servers.</para>
+
+          <para>Primarily for compatibility with other virtualization
+          software, VirtualBox optionally supports LSI Logic and BusLogic SCSI
+          controllers, to each of which up to 15 virtual hard disks can be
+          attached.</para>
+
+          <para>To enable a SCSI controller, on the "Storage" page of a
+          virtual machine's settings dialog, click on the "Add Controller"
+          button under the "Storage Tree" box and then select "Add SCSI
+          Controller". After this, the additional controller will appear as a
+          separate PCI device in the virtual machine.<warning>
+              <para>As with the other controller types, a SCSI controller will 
+            only be seen by operating systems with device support for it. 
+            Windows 2003 and later ships with drivers for the LSI Logic 
+            controller, while Windows NT 4.0 and Windows 2000 ships with drivers 
+            for the BusLogic controller. Windows XP ships with drivers for 
+            neither.
+              </para>
+            </warning></para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Serial Attached SCSI (SAS)</emphasis> is
+          another bus standard which uses the SCSI command set. As opposed to
+          SCSI, however, with physical devices, serial cables are used instead
+          of parallel ones, which simplifies physical device connections. In
+          some ways, therefore, SAS is to SCSI what SATA is to IDE: it allows
+          for more reliable and faster connections. </para>
+
+          <para>To support high-end guests which require SAS controllers,
+          VirtualBox emulates a LSI Logic SAS controller, which can be enabled
+          much the same way as a SCSI controller. At this time, up to eight
+          devices can be connected to the SAS controller.<footnote>
+              <para>Support for the LSI Logic SAS controller was added with
+              VirtualBox 3.2.</para>
+            </footnote></para>
+
+          <warning>
+            <para>As with SATA, the SAS controller will only be seen by
+            operating systems with device support for it. In particular,
+            <emphasis role="bold">there is no support for SAS in Windows
+            before Windows Vista</emphasis>, so Windows XP (even SP2) will not
+            see such disks unless you install additional drivers.</para>
+          </warning>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>In summary, VirtualBox gives you the following categories of virtual
+    storage slots:<orderedlist>
+        <listitem>
+          <para>four slots attached to the traditional IDE controller, which
+          are always present (one of which typically is a virtual CD/DVD
+          drive);</para>
+        </listitem>
+
+        <listitem>
+          <para>30 slots attached to the SATA controller, if enabled and
+          provided that your guest operating system can see it; these slots
+          can either be<orderedlist>
+              <listitem>
+                <para>in IDE compatibility mode (by default, slots 0-3)
+                or</para>
+              </listitem>
+
+              <listitem>
+                <para>in SATA mode;</para>
+              </listitem>
+            </orderedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>15 slots attached to the SCSI controller, if enabled and
+          supported by the guest operating system;</para>
+        </listitem>
+
+        <listitem>
+          <para>eight slots attached to the SAS controller, if enabled and
+          supported by the guest operating system.</para>
+        </listitem>
+      </orderedlist></para>
+
+      <para>Given this large choice of storage controllers, you may ask yourself
+      which one to choose. In general, you should avoid IDE unless it is the only
+      controller supported by your guest. Whether you use SATA, SCSI or SAS does
+      not make any real difference.</para>
+  </sect1>
+
+  <sect1 id="vdidetails">
+    <title>Disk image files (VDI, VMDK, VHD, HDD)</title>
+
+    <para>Disk image files reside on the host system and are seen by the guest
+    systems as hard disks of a certain geometry. When a guest operating system
+    reads from or writes to a hard disk, VirtualBox redirects the request to
+    the image file.</para>
+
+    <para>Note that when you create an image file, its size needs to be
+    specified, which represents a fixed geometry of the virtual disk. It is
+    therefore not possible to change the size of the virtual hard disk
+    later.</para>
+
+    <para>VirtualBox supports four variants of disk image files:<itemizedlist>
+        <listitem>
+          <para>Normally, VirtualBox uses its own container format for guest
+          hard disks -- Virtual Disk Image (VDI) files. In particular, this
+          format will be used when you create a new virtual machine with a new
+          disk.</para>
+        </listitem>
+
+        <listitem>
+          <para>VirtualBox also fully supports the popular and open VMDK
+          container format that is used by many other virtualization products,
+          in particular, by VMware.<footnote>
+              <para>Initial support for VMDK was added with VirtualBox 1.4;
+              since version 2.1, VirtualBox supports VMDK fully, meaning that
+              you can create snapshots and use all the other advanced features
+              described above for VDI images with VMDK also.</para>
+            </footnote></para>
+        </listitem>
+
+        <listitem>
+          <para>VirtualBox also fully supports the VHD format used by
+          Microsoft.</para>
+        </listitem>
+
+        <listitem>
+          <para>Image files of Parallels version 2 (HDD format) are also
+          supported.<footnote>
+              <para>Support was added with VirtualBox 3.1.</para>
+            </footnote> For lack of documentation of the format, newer formats
+          (3 and 4) are not supported. You can however convert such image
+          files to version 2 format using tools provided by Parallels.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>Irrespective of the disk format, as briefly mentioned in <xref
+    linkend="gui-createvm" />, there are two options of how to create a disk
+    image: fixed-size or dynamically expanding.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>If you create a <emphasis role="bold">fixed-size
+        image</emphasis> of e.g. 10 GB, an image file of roughly the same size
+        will be created on your host system. Note that the creation of a
+        fixed-size image can take a long time depending on the size of the
+        image and the write performance of your hard disk.</para>
+      </listitem>
+
+      <listitem>
+        <para>For more flexible storage management, use a <emphasis
+        role="bold">dynamically expanding image</emphasis>. This will
+        initially be very small and not occupy any space for unused virtual
+        disk sectors, but the image file will grow every time a disk sector is
+        written to for the first time. While this format takes less space
+        initially, the fact that VirtualBox needs to constantly expand the
+        image file consumes additional computing resources, so until the disk
+        has fully expanded, write operations are slower than with fixed size
+        disks. However, after a dynamic disk has fully expanded, the
+        performance penalty for read and write operations is
+        negligible.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="vdis">
+    <title>The Virtual Media Manager</title>
+
+    <para>VirtualBox keeps an internal registry of all available hard disk,
+    CD/DVD-ROM and floppy disk images. This registry can be viewed and changed
+    in the <emphasis role="bold">Virtual Media Manager</emphasis>, which you
+    can access from the "File" menu in the VirtualBox main window:</para>
+
+    <para><mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/virtual-disk-manager.png"
+                     width="10cm" />
+        </imageobject>
+      </mediaobject>The window shows you all images that are currently
+    registered with VirtualBox, conveniently grouped in three tabs for the
+    three possible formats. These formats are:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Hard disk images, either in VirtualBox's own Virtual Disk Image
+        (VDI) format or in the third-party formats listed above;</para>
+      </listitem>
+
+      <listitem>
+        <para>CD/DVD images in standard ISO format;</para>
+      </listitem>
+
+      <listitem>
+        <para>floppy images in standard RAW format.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>As you can see in the screenshot above, for each image, the Virtual
+    Media Manager shows you the full path of the image file and other
+    information, such as the virtual machine the image is currently attached
+    to, if any.</para>
+
+    <para>The Virtual Media Manager allows you to</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>create new hard disk images using the <emphasis
+        role="bold">"New"</emphasis> button; this will bring up the "Create
+        Disk Image" wizard already described in <xref
+        linkend="gui-createvm" />;</para>
+      </listitem>
+
+      <listitem>
+        <para>import existing image files from your hard drive into VirtualBox
+        using the <emphasis role="bold">"Add"</emphasis> button;</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">remove</emphasis> an image from the
+        registry (and optionally delete the image file when doing so);</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">"release"</emphasis> an image, that is,
+        detach it from a virtual machine if it is currently attached to one as
+        a virtual hard disk.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>We recommend that you maintain two special folders on your system
+    for keeping images: one for hard disk image files (which can, in the case
+    of dynamically expanding images, grow to considerable sizes), and one for
+    ISO files (which were probably downloaded from the Internet).</para>
+
+    <para>Hard disk image files can be copied onto other host systems and
+    imported into virtual machines there, although certain guest systems
+    (notably Windows 2000 and XP) will require that the new virtual machine be
+    set up in a similar way to the old one.<note>
+        <para>Do not simply make copies of virtual disk images. If you import
+        such a second copy into a virtual machine, VirtualBox will complain
+        with an error, since VirtualBox assigns a unique identifier (UUID) to
+        each disk image to make sure it is only used once. See <xref
+        linkend="cloningvdis" /> for instructions on this matter. Also, if you
+        want to copy a virtual machine to another system, VirtualBox has an
+        import/export facility that might be better suited for your needs; see
+        <xref linkend="ovf" />.</para>
+      </note></para>
+  </sect1>
+
+  <sect1 id="hdimagewrites">
+    <title>Special image write modes</title>
+
+    <para>For each virtual disk image supported by VirtualBox, you can use
+    special commands how write operations from the virtual machine should
+    affect the image and how snapshots should affect it. This applies to all
+    of the aforementioned image formats (VDI, VMDK, VHD or HDD) and
+    irrespective of whether an image is fixed-size or dynamically
+    expanding.</para>
+
+    <orderedlist>
+      <listitem>
+        <para>With <emphasis role="bold">normal images</emphasis> (the default
+        setting), there are no restrictions on how guests can read from and
+        write to the disk.</para>
+
+        <para>When you take a snapshot of your virtual machine as described in
+        <xref linkend="snapshots" />, the state of such a "normal hard disk"
+        will be recorded together with the snapshot, and when reverting to the
+        snapshot, its state will be fully reset.</para>
+
+        <para>(Technically, strictly speaking, the image file itself is not
+        "reset". Instead, when a snapshot is taken, VirtualBox "freezes" the
+        image file and no longer writes to it. For the write operations from
+        the VM, a second, "differencing" image file is created which receives
+        only the changes to the original image; see the next section for
+        details.)</para>
+
+        <para>While you can attach the same "normal" image to more than one
+        virtual machine, only one of these virtual machines attached to the
+        same image file can be executed simultaneously, as otherwise there
+        would be conflicts if several machines write to the same image
+        file.<footnote>
+            <para>This restriction is more lenient now than it was before
+            VirtualBox 2.2. Previously, each "normal" disk image could only be
+            <emphasis>attached</emphasis> to one single machine. Now it can be
+            attached to more than one machine so long as only one of these
+            machines is running.</para>
+          </footnote></para>
+      </listitem>
+
+      <listitem>
+        <para>By contrast, <emphasis role="bold">write-through hard
+        disks</emphasis> are completely unaffected by snapshots: their state
+        is <emphasis>not</emphasis> saved when a snapshot is taken, and not
+        restored when a snapshot is restored.</para>
+
+        <para>To <emphasis>create</emphasis> a disk image in VDI format as
+        "write-through", use the <computeroutput>VBoxManage
+        createhd</computeroutput> command; see <xref
+        linkend="vboxmanage-createvdi" />. To mark an
+        <emphasis>existing</emphasis> image as write-through, use
+        <computeroutput>VBoxManage modifyhd</computeroutput>; see <xref
+        linkend="vboxmanage-modifyvdi" />.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">Shareable hard disks</emphasis> are a
+        variant of write-through hard disks. In principle they behave exactly
+        the same, i.e. their state is <emphasis>not</emphasis> saved when a
+        snapshot is taken, and not restored when a snapshot is restored. The
+        difference only shows if you attach such disks to several VMs.
+        Shareable VMs may be attached to several VMs which may run
+        concurrently. This makes them suitable for use by cluster filesystems
+        between VMs and similar applications which are explicitly prepared to
+        access a disk concurrently. Only fixed size images can be used in this
+        way, and dynamically growing images are rejected.</para>
+
+        <para>This is an expert feature, and misuse can lead to data loss --
+        regular filesystems are not prepared to handle simultaneous changes by
+        several parties.</para>
+
+        <para>To <emphasis>create</emphasis> a disk image in VDI format as
+        "shareable", use the <computeroutput>VBoxManage
+        createhd</computeroutput> command; see <xref
+        linkend="vboxmanage-createvdi" />. To mark an
+        <emphasis>existing</emphasis> image as shareable, use
+        <computeroutput>VBoxManage modifyhd</computeroutput>; see <xref
+        linkend="vboxmanage-modifyvdi" />.</para>
+      </listitem>
+
+      <listitem>
+        <para>Finally, <emphasis role="bold">immutable images</emphasis> only
+        remember write accesses temporarily while the virtual machine is
+        running; all changes are lost when the virtual machine is powered on
+        the next time. As a result, as opposed to "normal" images, the same
+        immutable image can be used with several virtual machines without
+        restrictions.</para>
+
+        <para><emphasis>Creating</emphasis> an immutable image makes little
+        sense since it would be initially empty and lose its contents with
+        every machine restart (unless you really want to have a disk that is
+        always unformatted when the machine starts up). As a result, normally,
+        you would first create a "normal" image and then, when you deem its
+        contents useful, later mark it immutable using
+        <computeroutput>VBoxManage modifyhd</computeroutput>; again, please
+        see <xref linkend="vboxmanage-modifyvdi" />. Alternatively, open an
+        existing image in "immutable" mode using <computeroutput>VBoxManage
+        openmedium</computeroutput>; see <xref
+        linkend="vboxmanage-registerimage" />.</para>
+
+        <para>If you take a snapshot of a machine with immutable images, then
+        on every machine power-up, those images are reset to the state of the
+        last (current) snapshot (instead of the state of the original
+        immutable image).</para>
+
+        <note>
+          <para>As a special exception, immutable images are
+          <emphasis>not</emphasis> reset if they are attached to a machine
+          whose last snapshot was taken while the machine was running (a
+          so-called "online" snapshot). As a result, if the machine's current
+          snapshot is such an "online" snapshot, its immutable images behave
+          exactly like the "normal" images described previously. To re-enable
+          the automatic resetting of such images, delete the current snapshot
+          of the machine.</para>
+        </note>
+
+        <para>Again, technically, VirtualBox never writes to an immutable
+        image directly at all. All write operations from the machine will be
+        directed to a differencing image; the next time the VM is powered on,
+        the differencing image is reset so that every time the VM starts, its
+        immutable images have exactly the same content.<footnote>
+            <para>This behavior also changed with VirtualBox 2.2. Previously,
+            the differencing images were discarded when the machine session
+            <emphasis>ended</emphasis>; now they are discarded every time the
+            machine is powered on.</para>
+          </footnote> The differencing image is only reset when the machine is
+        powered on from within VirtualBox, not when you reboot by requesting a
+        reboot from within the machine. This is also why immutable images
+        behave as described above when snapshots are also present, which use
+        differencing images as well.</para>
+
+        <para>If the automatic discarding of the differencing image on VM
+        startup does not fit your needs, you can turn it off using the
+        <computeroutput>autoreset</computeroutput> parameter of
+        <computeroutput>VBoxManage modifyhd</computeroutput>; see <xref
+        linkend="vboxmanage-modifyvdi" /> for details.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>To illustrate the differences between the various types with respect
+    to snapshots: Assume you have installed your guest operating system in
+    your VM, and you have taken a snapshot. Imagine you have accidentally
+    infected your VM with a virus and would like to go back to the snapshot.
+    With a normal hard disk image, you simply restore the snapshot, and the
+    earlier state of your hard disk image will be restored as well (and your
+    virus infection will be undone). With an immutable hard disk, all it takes
+    is to shut down and power on your VM, and the virus infection will be
+    discarded. With a write-through image however, you cannot easily undo the
+    virus infection by means of virtualization, but will have to disinfect
+    your virtual machine like a real computer.</para>
+
+    <para>Still, you might find write-through images useful if you want to
+    preserve critical data irrespective of snapshots, and since you can attach
+    more than one image to a VM, you may want to have one immutable for the
+    operating system and one write-through for your data files.</para>
+  </sect1>
+
+  <sect1 id="diffimages">
+    <title>Differencing images</title>
+
+    <para>The previous section hinted at differencing images and how they are
+    used with snapshots, immutable images and multiple disk attachments. For
+    the inquisitive VirtualBox user, this section describes in more detail how
+    they work.</para>
+
+    <para>A differencing image is a special disk image that only holds the
+    differences to another image. A differencing image by itself is useless,
+    it must always refer to another image. The differencing image is then
+    typically referred to as a "child", which holds the differences to its
+    "parent".</para>
+
+    <para>When a differencing image is active, it receives all write
+    operations from the virtual machine instead of its parent. The
+    differencing image only contains the sectors of the virtual hard disk that
+    have changed since the differencing image was created. When the machine
+    reads a sector from such a virtual hard disk, it looks into the
+    differencing image first. If the sector is present, it is returned from
+    there; if not, VirtualBox looks into the parent. In other words, the
+    parent becomes "read-only"; it is never written to again, but it is read
+    from if a sector has not changed.</para>
+
+    <para>Differencing images can be chained. If another differencing image is
+    created for a virtual disk that already has a differencing image, then it
+    becomes a "grandchild" of the original parent. The first differencing
+    image then becomes read-only as well, and write operations only go to the
+    second-level differencing image. When reading from the virtual disk,
+    VirtualBox needs to look into the second differencing image first, then
+    into the first if the sector was not found, and then into the original
+    image.</para>
+
+    <para>There can be an unlimited number of differencing images, and each
+    image can have more than one child. As a result, the differencing images
+    can form a complex tree with parents, "siblings" and children, depending
+    on how complex your machine configuration is. Write operations always go
+    to the one "active" differencing image that is attached to the machine,
+    and for read operations, VirtualBox may need to look up all the parents in
+    the chain until the sector in question is found. You can look at such a
+    tree in the Virtual Media Manager:<mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/virtual-disk-manager2.png"
+                     width="10cm" />
+        </imageobject>
+      </mediaobject></para>
+
+    <para>In all of these situations, from the point of view of the virtual
+    machine, the virtual hard disk behaves like any other disk. While the
+    virtual machine is running, there is a slight run-time I/O overhead
+    because VirtualBox might need to look up sectors several times. This is
+    not noticeable however since the tables with sector information are always
+    kept in memory and can be looked up quickly.</para>
+
+    <para>Differencing images are used in the following
+    situations:<orderedlist>
+        <listitem>
+          <para><emphasis role="bold">Snapshots.</emphasis> When you create a
+          snapshot, as explained in the previous section, VirtualBox "freezes"
+          the images attached to the virtual machine and creates differencing
+          images for each of them (to be precise: one for each image that is
+          not in "write-through" mode). From the point of view of the virtual
+          machine, the virtual disks continue to operate before, but all write
+          operations go into the differencing images. Each time you create
+          another snapshot, for each hard disk attachment, another
+          differencing image is created and attached, forming a chain or
+          tree.</para>
+
+          <para>In the above screenshot, you see that the original disk image
+          is now attached to a snapshot, representing the state of the disk
+          when the snapshot was taken.</para>
+
+          <para>If you now <emphasis role="bold">restore</emphasis> a snapshot
+          -- that is, if you want to go back to the exact machine state that
+          was stored in the snapshot --, the following happens:<orderedlist>
+              <listitem>
+                <para>VirtualBox copies the virtual machine settings that were
+                copied into the snapshot back to the virtual machine. As a
+                result, if you have made changes to the machine configuration
+                since taking the snapshot, they are undone.</para>
+              </listitem>
+
+              <listitem>
+                <para>If the snapshot was taken while the machine was running,
+                it contains a saved machine state, and that state is restored
+                as well; after restoring the snapshot, the machine will then
+                be in "Saved" state and resume execution from there when it is
+                next started. Otherwise the machine will be in "Powered Off"
+                state and do a full boot.</para>
+              </listitem>
+
+              <listitem>
+                <para>For each disk image attached to the machine, the
+                differencing image holding all the write operations since the
+                current snapshot was taken is thrown away, and the original
+                parent image is made active again. (If you restored the "root"
+                snapshot, then this will be the root disk image for each
+                attachment; otherwise, some other differencing image descended
+                from it.) This effectively restores the old machine
+                state.</para>
+              </listitem>
+            </orderedlist></para>
+
+          <para>If you later <emphasis role="bold">delete</emphasis> a
+          snapshot in order to free disk space, for each disk attachment, one
+          of the differencing images becomes obsolete. In this case, the
+          differencing image of the disk attachment cannot simply be deleted.
+          Instead, VirtualBox needs to look at each sector of the differencing
+          image and needs to copy it back into its parent; this is called
+          "merging" images and can be a potentially lengthy process, depending
+          on how large the differencing image is. It can also temporarily need
+          a considerable amount of extra disk space, before the differencing
+          image obsoleted by the merge operation is deleted.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Immutable images.</emphasis> When an
+          image is switched to "immutable" mode, a differencing image is
+          created as well. As with snapshots, the parent image then becomes
+          read-only, and the differencing image receives all the write
+          operations. Every time the virtual machine is started, all the
+          immutable images which are attached to it have their respective
+          differencing image thrown away, effectively resetting the virtual
+          machine's virtual disk with every restart.</para>
+        </listitem>
+      </orderedlist></para>
+  </sect1>
+
+  <sect1 id="cloningvdis">
+    <title>Cloning disk images</title>
+
+    <para>You can duplicate hard disk image files on the same host to quickly
+    produce a second virtual machine with the same operating system setup.
+    However, you should <emphasis>only</emphasis> make copies of virtual disk
+    images using the utility supplied with VirtualBox; see <xref
+    linkend="vboxmanage-clonevdi" />. This is because VirtualBox assigns a
+    unique identity number (UUID) to each disk image, which is also stored
+    inside the image, and VirtualBox will refuse to work with two images that
+    use the same number. If you do accidentally try to reimport a disk image
+    which you copied normally, you can make a second copy using VirtualBox's
+    utility and import that instead.</para>
+
+    <para>Note that newer Linux distributions identify the boot hard disk from
+    the ID of the drive. The ID VirtualBox reports for a drive is determined
+    from the UUID of the virtual disk image. So if you clone a disk image and
+    try to boot the copied image the guest might not be able to determine its
+    own boot disk as the UUID changed. In this case you have to adapt the disk
+    ID in your boot loader script (for example
+    <computeroutput>/boot/grub/menu.lst</computeroutput>). The disk ID looks
+    like this:<screen>scsi-SATA_VBOX_HARDDISK_VB5cfdb1e2-c251e503</screen></para>
+
+    <para>The ID for the copied image can be determined with <screen>hdparm -i /dev/sda</screen></para>
+  </sect1>
+
+  <sect1 id="iocaching">
+    <title>Disk images and I/O caching</title>
+
+    <para>VirtualBox can optionally disable the I/O caching that the host
+    operating system would otherwise perform on disk image files.</para>
+
+    <para>Traditionally, VirtualBox has opened disk image files as normal
+    files, which results in them being cached by the host operating system
+    like any other file. The main advantage of this is speed: when the guest
+    OS writes to disk and the host OS cache uses delayed writing, the write
+    operation can be reported as completed to the guest OS quickly while the
+    host OS can perform the operation asynchronously. Also, when you start a
+    VM a second time and have enough memory available for the OS to use for
+    caching, large parts of the virtual disk may be in system memory, and the
+    VM can access the data much faster.</para>
+
+    <para>Note that this applies only to image files; buffering never occured
+    virtual disks residing on remote iSCSI storage, which is the more common
+    scenario in enterprise-class setups (see <xref
+    linkend="storage-iscsi" />).</para>
+
+    <para>While buffering is a useful default setting for virtualizating a few
+    machines on a desktop computer, there are some disadvantages to this
+    approach:<orderedlist>
+        <listitem>
+          <para>Delayed writing through the host OS cache is less secure. When
+          the guest OS writes data, it considers the data written even though
+          it has not yet arrived on a physical disk. If for some reason the
+          write does not happen (power failure, host crash), the likelihood of
+          data loss increases.</para>
+        </listitem>
+
+        <listitem>
+          <para>Disk image files tend to be very large. Caching them can
+          therefore quickly use up the entire host OS cache. Depending on the
+          efficiency of the host OS caching, this may slow down the host
+          immensely, especially if several VMs run at the same time. For
+          example, on Linux hosts, host caching may result in Linux delaying
+          all writes until the host cache is nearly full and then writing out
+          all these changes at once, possibly stalling VM execution for
+          minutes. This can result in I/O errors in the guest as I/O requests
+          time out there.</para>
+        </listitem>
+
+        <listitem>
+          <para>Physical memory is often wasted as guest operating systems
+          typically have their own I/O caches, which may result in the data
+          being cached twice (in both the guest and the host caches) for
+          little effect.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>As a result, starting with version 3.2, VirtualBox allows you to
+    optionally disable host I/O caching of disk image files. In that case,
+    VirtualBox uses its own small cache to buffer writes, but there is no read
+    caching since this is already performed by the guest OS. In addition,
+    VirtualBox fully supports asynchronous I/O for its virtual SATA, SCSI and
+    SAS controllers through multiple I/O threads.</para>
+
+    <para>Since asynchronous I/O is not supported by IDE controllers, for
+    performance reasons, you may want to leave host caching enabled for your
+    VM's virtual IDE controllers.</para>
+
+    <para>For this reason, VirtualBox allows you to configure whether the host
+    I/O cache is used for each I/O controller separately. Either uncheck the
+    "Use host I/O cache" box in the "Storage" settings for a given virtual
+    storage controller, or use the following VBoxManage command to disable the
+    host I/O cache for a virtual storage controller:<screen>VBoxManage storagectl &lt;vm&gt; --name &lt;controllername&gt; --hostiocache off</screen></para>
+
+    <para>See <xref linkend="vboxmanage-storagectl" /> for details.</para>
+
+    <para>For the above reasons also, VirtualBox now uses SATA controllers by
+    default for new virtual machines.</para>
+
+    <note>
+      <para>Disabling the host I/O caches will currently yield poor
+      performance with VHD and sparse VMDK files. See <xref
+      linkend="KnownIssues" /> for details.</para>
+    </note>
+  </sect1>
+
+  <sect1 id="storage-cds">
+    <title>CD/DVD drive operation</title>
+
+    <para>The virtual CD/DVD drive(s) by default support only reading. The
+    medium configuration is changeable at runtime. You can select between
+    three options to provide the medium data:<itemizedlist>
+        <listitem>
+          <para><emphasis role="bold">Host Drive</emphasis> defines that the
+          guest can read from the medium in the host drive. Medium changes of
+          the host drives are signalled to the guest.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Image file</emphasis> gives the guest
+          read-only access to the image data (often referred to as ISO image).
+          A medium change is signalled when switching to a different image or
+          selecting another option.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">Empty</emphasis> stands for a drive
+          without an inserted medium. The drive responds as usual to this
+          situation, however no data can be read.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>As mentioned, the medium change signalling depends on the selected
+    option for the medium. Medium changes can be prevented by the guest, and
+    VirtualBox reflects that by locking the host drive if appropriate. You can
+    force a medium removal in such situation via the VirtualBox GUI or the
+    VBoxManage command line tool. Effectively this is the equivalent of the
+    emergency eject which many CD/DVD drives provide, with all associated side
+    effects. The guest OS can issue error messages in this case, just like on
+    real hardware. Use with caution.</para>
+
+    <para>In any case, only data media is supported for CD/DVD drives. This
+    means that all data CD formats and all DVD formats can be used in
+    principle. Since host DVD drives refuse to read encrypted DVD video media,
+    you cannot play such videos with the regular CD/DVD drive emulation. You
+    may be able to get it working with the experimental passthrough support
+    described in <xref linkend="storage-write-cds" />.</para>
+
+    <para>Audio CD and video CD formats are not supported, which means you
+    cannot play such media from a virtual machine.</para>
+  </sect1>
+
+  <sect1 id="storage-write-cds">
+    <title>Writing CDs and DVDs using the host drive</title>
+
+    <para>When you attach your host's CD/DVD drive to a virtual machine (see
+    <xref linkend="settings-storage" />), this normally gives the machine
+    read-only access to the host drive. This prevents the guest from writing
+    to the host drive. In particular, you cannot burn CDs and DVDs from the
+    guest this way.</para>
+
+    <para>As an experimental feature (which currently works for data media
+    only, audio and video CD formats are not supported), it is possible to
+    give the guest access to the CD/DVD writing features of the host drive (if
+    available). There is a "Passthrough" checkbox in the GUI dialog for
+    configuring the media attached to a storage controller, or you can use the
+    command line:</para>
+
+    <screen>VBoxManage storageattach &lt;uuid|vmname&gt;
+                        --storagectl &lt;name&gt;
+                        --port &lt;number&gt;
+                        --device &lt;number&gt;
+                        [--type &lt;dvddrive|hdd|fdd&gt;
+                         --medium &lt;none|emptydrive|uuid|filename|host:&lt;drive&gt;&gt;]
+                        [--passthrough &lt;on|off&gt;]
+                        [--forceunmount]</screen>
+
+    <para>See also <xref linkend="vboxmanage-storage" />.</para>
+
+    <para>Even if pass-through is enabled, unsafe commands, such as updating
+    the drive firmware, will be blocked. On some host drives the pass-through
+    feature allows playing encrypted DVD video media.</para>
+
+    <para>On Solaris hosts, pass-through requires running VirtualBox with real
+    root permissions due to security measures enforced by the host.</para>
+  </sect1>
+
+  <sect1>
+    <title id="storage-iscsi">iSCSI servers</title>
+
+    <para>iSCSI stands for "Internet SCSI" and is a standard that allows for
+    using the SCSI protocol over Internet (TCP/IP) connections. Especially
+    with the advent of Gigabit Ethernet, it has become affordable to attach
+    iSCSI storage servers simply as remote hard disks to a computer network.
+    In iSCSI terminology, the server providing storage resources is called an
+    "iSCSI target", while the client connecting to the server and accessing
+    its resources is called "iSCSI initiator".</para>
+
+    <para>VirtualBox can transparently present iSCSI remote storage to a
+    virtual machine as a virtual hard disk. The guest operating system will
+    not see any difference between a virtual disk image (VDI file) and an
+    iSCSI target. To achieve this, VirtualBox has an integrated iSCSI
+    initiator.</para>
+
+    <para>VirtualBox's iSCSI support has been developed according to the iSCSI
+    standard and should work with all standard-conforming iSCSI targets. To
+    use an iSCSI target with VirtualBox, you must first register it as a
+    virtual hard disk with <computeroutput>VBoxManage</computeroutput>; see
+    <xref linkend="vboxmanage-addiscsidisk" />. The target will show up in the
+    list of disk images, as described in <xref linkend="vdis" />, and can thus
+    be attached to one of the VM's three hard disk slots the usual way.</para>
+
+    <sect2>
+      <title id="iscsi-intnet">Access iSCSI targets via Internal
+      Networking</title>
+
+      <para>As an experimental feature, VirtualBox allows for accessing an
+      iSCSI target running in a virtual machine which is configured for using
+      Internal Networking mode (as described in <xref
+      linkend="network_internal" />). The setup of the virtual machine which
+      uses such an iSCSI target is done as described above. The only
+      difference is that the IP address of the target must be specified as a
+      numeric IP address.</para>
+
+      <para>The IP stack accessing Internal Networking must be configured in
+      the virtual machine which accesses the iSCSI target. A free static IP
+      and a MAC address not used by other virtual machines must be chosen. In
+      the example below, adapt the name of the virtual machine, the MAC
+      address, the IP configuration and the Internal Networking name
+      ("MyIntNet") according to your needs. The following seven commands must
+      be issued:<screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Trusted 1
+VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
+VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
+VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0
+VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet
+VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
+VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen></para>
+
+      <para>Finally the iSCSI disk must be registered with the
+      <code>--intnet</code> option to tell the iSCSI initiator to use internal
+      networking:<screen>VBoxManage addiscsidisk --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen></para>
+
+      <para>The target address must be specified as a numeric IP address, as
+      there is no DNS resolver for internal networking.</para>
+
+      <para>The virtual machine with the iSCSI target should be started before
+      the VM using it is powered on. If a virtual machine using an iSCSI disk
+      is started without having the iSCSI target powered up, it can take up to
+      200 seconds to detect this situation. The VM will fail to power
+      up.</para>
+    </sect2>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_Technical.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_Technical.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_Technical.xml	(revision 33555)
@@ -0,0 +1,609 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="TechnicalBackground">
+  <title>Technical background</title>
+
+  <para>The contents of this chapter are not required to use VirtualBox
+  successfully. The following is provided as additional information for
+  readers who are more familiar with computer architecture and technology and
+  wish to find out more about how VirtualBox works "under the hood".</para>
+
+  <sect1>
+    <title>VirtualBox executables and components</title>
+
+    <para>VirtualBox was designed to be modular and flexible. When the
+    VirtualBox graphical user interface (GUI) is opened and a VM is started,
+    at least three processes are running:<orderedlist>
+        <listitem>
+          <para><computeroutput>VBoxSVC</computeroutput>, the VirtualBox
+          service process which always runs in the background. This process is
+          started automatically by the first VirtualBox client process (the
+          GUI, <computeroutput>VBoxManage</computeroutput>,
+          <computeroutput>VBoxHeadless</computeroutput>, the web service or
+          others) and exits a short time after the last client exits. The
+          service is responsible for bookkeeping, maintaining the state of all
+          VMs, and for providing communication between VirtualBox components.
+          This communication is implemented via COM/XPCOM.<note>
+              <para>When we refer to "clients" here, we mean the local clients
+              of a particular <computeroutput>VBoxSVC</computeroutput> server
+              process, not clients in a network. VirtualBox employs its own
+              client/server design to allow its processes to cooperate, but
+              all these processes run under the same user account on the host
+              operating system, and this is totally transparent to the
+              user.</para>
+            </note></para>
+        </listitem>
+
+        <listitem>
+          <para>The GUI process, <computeroutput>VirtualBox</computeroutput>,
+          a client application based on the cross-platform Qt library. When
+          started without the <computeroutput>--startvm</computeroutput>
+          option, this application acts as the VirtualBox main window,
+          displaying the VMs and their settings. It then communicates settings
+          and state changes to <computeroutput>VBoxSVC</computeroutput> and
+          also reflects changes effected through other means, e.g.,
+          <computeroutput>VBoxManage</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>If the <computeroutput>VirtualBox</computeroutput> client
+          application is started with the
+          <computeroutput>--startvm</computeroutput> argument, it loads the
+          VMM library which includes the actual hypervisor and then runs a
+          virtual machine and provides the input and output for the
+          guest.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>Any VirtualBox front-end (client) will communicate with the service
+    process and can both control and reflect the current state. For example,
+    either the VM selector or the VM window or VBoxManage can be used to pause
+    the running VM, and other components will always reflect the changed
+    state.</para>
+
+    <para>The VirtualBox GUI application is only one of several available
+    front-ends (clients). The complete list shipped with VirtualBox
+    is:<orderedlist>
+        <listitem>
+          <para><computeroutput>VirtualBox</computeroutput>, the Qt GUI front
+          end mentioned earlier.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxManage</computeroutput>, a less
+          user-friendly but more powerful alternative to the GUI described in
+          <xref linkend="vboxmanage" />.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxSDL</computeroutput>, a simple graphical
+          front end based on the SDL library; see <xref
+          linkend="vboxsdl" />.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxHeadless</computeroutput>, a VM front end
+          which does not directly provide any video output and keyboard/mouse
+          input, but allows redirection via VRDP; see <xref
+          linkend="vboxheadless" />.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>vboxwebsrv</computeroutput>, the VirtualBox
+          web service process which allows for controlling a VirtualBox host
+          remotely. This is described in detail in the VirtualBox Software
+          Development Kit (SDK) reference; please see <xref
+          linkend="VirtualBoxAPI" /> for details.</para>
+        </listitem>
+
+        <listitem>
+          <para>The VirtualBox Python shell, a Python alternative to
+          VBoxManage. This is also described in the SDK reference.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>Internally, VirtualBox consists of many more or less separate
+    components. You may encounter these when analyzing VirtualBox internal
+    error messages or log files. These include:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>IPRT, a portable runtime library which abstracts file access,
+        threading, string manipulation, etc. Whenever VirtualBox accesses host
+        operating features, it does so through this library for cross-platform
+        portability.</para>
+      </listitem>
+
+      <listitem>
+        <para>VMM (Virtual Machine Monitor), the heart of the
+        hypervisor.</para>
+      </listitem>
+
+      <listitem>
+        <para>EM (Execution Manager), controls execution of guest code.</para>
+      </listitem>
+
+      <listitem>
+        <para>REM (Recompiled Execution Monitor), provides software emulation
+        of CPU instructions.</para>
+      </listitem>
+
+      <listitem>
+        <para>TRPM (Trap Manager), intercepts and processes guest traps and
+        exceptions.</para>
+      </listitem>
+
+      <listitem>
+        <para>HWACCM (Hardware Acceleration Manager), provides support for
+        VT-x and AMD-V.</para>
+      </listitem>
+
+      <listitem>
+        <para>PDM (Pluggable Device Manager), an abstract interface between
+        the VMM and emulated devices which separates device implementations
+        from VMM internals and makes it easy to add new emulated devices.
+        Through PDM, third-party developers can add new virtual devices to
+        VirtualBox without having to change VirtualBox itself.</para>
+      </listitem>
+
+      <listitem>
+        <para>PGM (Page Manager), a component controlling guest paging.</para>
+      </listitem>
+
+      <listitem>
+        <para>PATM (Patch Manager), patches guest code to improve and speed up
+        software virtualization.</para>
+      </listitem>
+
+      <listitem>
+        <para>TM (Time Manager), handles timers and all aspects of time inside
+        guests.</para>
+      </listitem>
+
+      <listitem>
+        <para>CFGM (Configuration Manager), provides a tree structure which
+        holds configuration settings for the VM and all emulated
+        devices.</para>
+      </listitem>
+
+      <listitem>
+        <para>SSM (Saved State Manager), saves and loads VM state.</para>
+      </listitem>
+
+      <listitem>
+        <para>VUSB (Virtual USB), a USB layer which separates emulated USB
+        controllers from the controllers on the host and from USB devices;
+        this also enables remote USB.</para>
+      </listitem>
+
+      <listitem>
+        <para>DBGF (Debug Facility), a built-in VM debuger.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox emulates a number of devices to provide the hardware
+        environment that various guests need. Most of these are standard
+        devices found in many PC compatible machines and widely supported by
+        guest operating systems. For network and storage devices in
+        particular, there are several options for the emulated devices to
+        access the underlying hardware. These devices are managed by
+        PDM.</para>
+      </listitem>
+
+      <listitem>
+        <para>Guest Additions for various guest operating systems. This is
+        code that is installed from within a virtual machine; see <xref
+        linkend="guestadditions" />.</para>
+      </listitem>
+
+      <listitem>
+        <para>The "Main" component is special: it ties all the above bits
+        together and is the only public API that VirtualBox provides. All the
+        client processes listed above use only this API and never access the
+        hypervisor components directly. As a result, third-party applications
+        that use the VirtualBox Main API can rely on the fact that it is
+        always well-tested and that all capabilities of VirtualBox are fully
+        exposed. It is this API that is described in the VirtualBox SDK
+        mentioned above (again, see <xref linkend="VirtualBoxAPI" />).</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="hwvirt">
+    <title>Hardware vs. software virtualization</title>
+
+    <para>VirtualBox allows software in the virtual machine to run directly on
+    the processor of the host, but an array of complex techniques is employed
+    to intercept operations that would interfere with your host. Whenever the
+    guest attempts to do something that could be harmful to your computer and
+    its data, VirtualBox steps in and takes action. In particular, for lots of
+    hardware that the guest believes to be accessing, VirtualBox simulates a
+    certain "virtual" environment according to how you have configured a
+    virtual machine. For example, when the guest attempts to access a hard
+    disk, VirtualBox redirects these requests to whatever you have configured
+    to be the virtual machine's virtual hard disk -- normally, an image file
+    on your host.</para>
+
+    <para>Unfortunately, the x86 platform was never designed to be
+    virtualized. Detecting situations in which VirtualBox needs to take
+    control over the guest code that is executing, as described above, is
+    difficult. There are two ways in which to achive this:<itemizedlist>
+        <listitem>
+          <para>Since 2006, Intel and AMD processors have had support for
+          so-called <emphasis role="bold">"hardware
+          virtualization"</emphasis>. This means that these processors can
+          help VirtualBox to intercept potentially dangerous operations that a
+          guest operating system may be attempting and also makes it easier to
+          present virtual hardware to a virtual machine.</para>
+
+          <para>These hardware features differ between Intel and AMD
+          processors. Intel named its technology <emphasis
+          role="bold">VT-x</emphasis>; AMD calls theirs <emphasis
+          role="bold">AMD-V</emphasis>. The Intel and AMD support for
+          virtualization is very different in detail, but not very different
+          in principle.<note>
+              <para>On many systems, the hardware virtualization features
+              first need to be enabled in the BIOS before VirtualBox can use
+              them.</para>
+            </note></para>
+        </listitem>
+
+        <listitem>
+          <para>As opposed to other virtualization software, for many usage
+          scenarios, VirtualBox does not <emphasis>require</emphasis> hardware
+          virtualization features to be present. Through sophisticated
+          techniques, VirtualBox virtualizes many guest operating systems
+          entirely in <emphasis role="bold">software</emphasis>. This means
+          that you can run virtual machines even on older processors which do
+          not support hardware virtualization.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>Even though VirtualBox does not always require hardware
+    virtualization, enabling it is <emphasis>required</emphasis> in the
+    following scenarios:<itemizedlist>
+        <listitem>
+          <para>Certain rare guest operating systems like OS/2 make use of
+          very esoteric processor instructions that are not supported with our
+          software virtualization. For virtual machines that are configured to
+          contain such an operating system, hardware virtualization is enabled
+          automatically.</para>
+        </listitem>
+
+        <listitem>
+          <para>VirtualBox's 64-bit guest support (added with version 2.0) and
+          multiprocessing (SMP, added with version 3.0) both require hardware
+          virtualization to be enabled. (This is not much of a limitation
+          since the vast majority of today's 64-bit and multicore CPUs ship
+          with hardware virtualization anyway; the exceptions to this rule are
+          e.g. older Intel Celeron and AMD Opteron CPUs.)</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <warning>
+      <para>Do not run other hypervisors (open-source or commercial
+      virtualization products) together with VirtualBox! While several
+      hypervisors can normally be <emphasis>installed</emphasis> in parallel,
+      do not attempt to <emphasis>run</emphasis> several virtual machines from
+      competing hypervisors at the same time. VirtualBox cannot track what
+      another hypervisor is currently attempting to do on the same host, and
+      especially if several products attempt to use hardware virtualization
+      features such as VT-x, this can crash the entire host. Also, within
+      VirtualBox, you can mix software and hardware virtualization when
+      running multiple VMs. In certain cases a small performance penalty will
+      be unavoidable when mixing VT-x and software virtualization VMs. We
+      recommend not mixing virtualization modes if maximum performance and low
+      overhead are essential. This does <emphasis>not</emphasis> apply to
+      AMD-V.</para>
+    </warning>
+  </sect1>
+
+  <sect1>
+    <title>Details about software virtualization</title>
+
+    <para>Implementing virtualization on x86 CPUs with no hardware
+    virtualization support is an extraordinarily complex task because the CPU
+    architecture was not designed to be virtualized. The problems can usually
+    be solved, but at the cost of reduced performance. Thus, there is a
+    constant clash between virtualization performance and accuracy.</para>
+
+    <para>The x86 instruction set was originally designed in the 1970s and
+    underwent significant changes with the addition of protected mode in the
+    1980s with the 286 CPU architecture and then again with the Intel 386 and
+    its 32-bit architecture. Whereas the 386 did have limited virtualization
+    support for real mode operation (V86 mode, as used by the "DOS Box" of
+    Windows 3.x and OS/2 2.x), no support was provided for virtualizing the
+    entire architecture.</para>
+
+    <para>In theory, software virtualization is not overly complex. In
+    addition to the four privilege levels ("rings") provided by the hardware
+    (of which typically only two are used: ring 0 for kernel mode and ring 3
+    for user mode), one needs to differentiate between "host context" and
+    "guest context".</para>
+
+    <para>In "host context", everything is as if no hypervisor was active.
+    This might be the active mode if another application on your host has been
+    scheduled CPU time; in that case, there is a host ring 3 mode and a host
+    ring 0 mode. The hypervisor is not involved.</para>
+
+    <para>In "guest context", however, a virtual machine is active. So long as
+    the guest code is running in ring 3, this is not much of a problem since a
+    hypervisor can set up the page tables properly and run that code natively
+    on the processor. The problems mostly lie in how to intercept what the
+    guest's kernel does.</para>
+
+    <para>There are several possible solutions to these problems. One approach
+    is full software emulation, usually involving recompilation. That is, all
+    code to be run by the guest is analyzed, transformed into a form which
+    will not allow the guest to either modify or see the true state of the
+    CPU, and only then executed. This process is obviously highly complex and
+    costly in terms of performance. (VirtualBox contains a recompiler based on
+    QEMU which can be used for pure software emulation, but the recompiler is
+    only activated in special situations, described below.)</para>
+
+    <para>Another possible solution is paravirtualization, in which only
+    specially modified guest OSes are allowed to run. This way, most of the
+    hardware access is abstracted and any functions which would normally
+    access the hardware or privileged CPU state are passed on to the
+    hypervisor instead. Paravirtualization can achieve good functionality and
+    performance on standard x86 CPUs, but it can only work if the guest OS can
+    actually be modified, which is obviously not always the case.</para>
+
+    <para>VirtualBox chooses a different approach. When starting a virtual
+    machine, through its ring-0 support kernel driver, VirtualBox has set up
+    the host system so that it can run most of the guest code natively, but it
+    has inserted itself at the "bottom" of the picture. It can then assume
+    control when needed -- if a privileged instruction is executed, the guest
+    traps (in particular because an I/O register was accessed and a device
+    needs to be virtualized) or external interrupts occur. VirtualBox may then
+    handle this and either route a request to a virtual device or possibly
+    delegate handling such things to the guest or host OS. In guest context,
+    VirtualBox can therefore be in one of three states:</para>
+
+    <para><itemizedlist>
+        <listitem>
+          <para>Guest ring 3 code is run unmodified, at full speed, as much as
+          possible. The number of faults will generally be low (unless the
+          guest allows port I/O from ring 3, something we cannot do as we
+          don't want the guest to be able to access real ports). This is also
+          referred to as "raw mode", as the guest ring-3 code runs
+          unmodified.</para>
+        </listitem>
+
+        <listitem>
+          <para>For guest code in ring 0, VirtualBox employs a nasty trick: it
+          actually reconfigures the guest so that its ring-0 code is run in
+          ring 1 instead (which is normally not used in x86 operating
+          systems). As a result, when guest ring-0 code (actually running in
+          ring 1) such as a guest device driver attempts to write to an I/O
+          register or execute a privileged instruction, the VirtualBox
+          hypervisor in "real" ring 0 can take over.</para>
+        </listitem>
+
+        <listitem>
+          <para>The hypervisor (VMM) can be active. Every time a fault occurs,
+          VirtualBox looks at the offending instruction and can relegate it to
+          a virtual device or the host OS or the guest OS or run it in the
+          recompiler.</para>
+
+          <para>In particular, the recompiler is used when guest code disables
+          interrupts and VirtualBox cannot figure out when they will be
+          switched back on (in these situations, VirtualBox actually analyzes
+          the guest code using its own disassembler). Also, certain privileged
+          instructions such as LIDT need to be handled specially. Finally, any
+          real-mode or protected-mode code (e.g. BIOS code, a DOS guest, or
+          any operating system startup) is run in the recompiler
+          entirely.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>Unfortunately this only works to a degree. Among others, the
+    following situations require special handling:</para>
+
+    <para><orderedlist>
+        <listitem>
+          <para>Running ring 0 code in ring 1 causes a lot of additional
+          instruction faults, as ring 1 is not allowed to execute any
+          privileged instructions (of which guest's ring-0 contains plenty).
+          With each of these faults, the VMM must step in and emulate the code
+          to achieve the desired behavior. While this works, emulating
+          thousands of these faults is very expensive and severely hurts the
+          performance of the virtualized guest.</para>
+        </listitem>
+
+        <listitem>
+          <para>There are certain flaws in the implementation of ring 1 in the
+          x86 architecture that were never fixed. Certain instructions that
+          <emphasis>should</emphasis> trap in ring 1 don't. This affect for
+          example the LGDT/SGDT, LIDT/SIDT, or POPF/PUSHF instruction pairs.
+          Whereas the "load" operation is privileged and can therefore be
+          trapped, the "store" instruction always succeed. If the guest is
+          allowed to execute these, it will see the true state of the CPU, not
+          the virtualized state. The CPUID instruction also has the same
+          problem.</para>
+        </listitem>
+
+        <listitem>
+          <para>A hypervisor typically needs to reserve some portion of the
+          guest's address space (both linear address space and selectors) for
+          its own use. This is not entirely transparent to the guest OS and
+          may cause clashes.</para>
+        </listitem>
+
+        <listitem>
+          <para>The SYSENTER instruction (used for system calls) executed by
+          an application running in a guest OS always transitions to ring 0.
+          But that is where the hypervisor runs, not the guest OS. In this
+          case, the hypervisor must trap and emulate the instruction even when
+          it is not desirable.</para>
+        </listitem>
+
+        <listitem>
+          <para>The CPU segment registers contain a "hidden" descriptor cache
+          which is not software-accessible. The hypervisor cannot read, save,
+          or restore this state, but the guest OS may use it.</para>
+        </listitem>
+
+        <listitem>
+          <para>Some resources must (and can) be trapped by the hypervisor,
+          but the access is so frequent that this creates a significant
+          performance overhead. An example is the TPR (Task Priority) register
+          in 32-bit mode. Accesses to this register must be trapped by the
+          hypervisor, but certain guest operating systems (notably Windows and
+          Solaris) write this register very often, which adversely affects
+          virtualization performance.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>To fix these performance and security issues, VirtualBox contains a
+    Code Scanning and Analysis Manager (CSAM), which disassembles guest code,
+    and the Patch Manager (PATM), which can replace it at runtime.</para>
+
+    <para>Before executing ring 0 code, CSAM scans it recursively to discover
+    problematic instructions. PATM then performs <emphasis>in-situ
+    </emphasis>patching, i.e. it replaces the instruction with a jump to
+    hypervisor memory where an integrated code generator has placed a more
+    suitable implementation. In reality, this is a very complex task as there
+    are lots of odd situations to be discovered and handled correctly. So,
+    with its current complexity, one could argue that PATM is an advanced
+    <emphasis>in-situ</emphasis> recompiler.</para>
+
+    <para>In addition, every time a fault occurs, VirtualBox analyzes the
+    offending code to determine if it is possible to patch it in order to
+    prevent it from causing more faults in the future. This approach works
+    well in practice and dramatically improves software virtualization
+    performance.</para>
+  </sect1>
+
+  <sect1>
+    <title>Details about hardware virtualization</title>
+
+    <para>With Intel VT-x, there are two distinct modes of CPU operation: VMX
+    root mode and non-root mode.<itemizedlist>
+        <listitem>
+          <para>In root mode, the CPU operates much like older generations of
+          processors without VT-x support. There are four privilege levels
+          ("rings"), and the same instruction set is supported, with the
+          addition of several virtualization specific instruction. Root mode
+          is what a host operating system without virtualization uses, and it
+          is also used by a hypervisor when virtualization is active.</para>
+        </listitem>
+
+        <listitem>
+          <para>In non-root mode, CPU operation is significantly different.
+          There are still four privilege rings and the same instruction set,
+          but a new structure called VMCS (Virtual Machine Control Structure)
+          now controls the CPU operation and determines how certain
+          instructions behave. Non-root mode is where guest systems
+          run.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>Switching from root mode to non-root mode is called "VM entry", the
+    switch back is "VM exit". The VMCS includes a guest and host state area
+    which is saved/restored at VM entry and exit. Most importantly, the VMCS
+    controls which guest operations will cause VM exits.</para>
+
+    <para>The VMCS provides fairly fine-grained control over what the guests
+    can and can't do. For example, a hypervisor can allow a guest to write
+    certain bits in shadowed control registers, but not others. This enables
+    efficient virtualization in cases where guests can be allowed to write
+    control bits without disrupting the hypervisor, while preventing them from
+    altering control bits over which the hypervisor needs to retain full
+    control. The VMCS also provides control over interrupt delivery and
+    exceptions.</para>
+
+    <para>Whenever an instruction or event causes a VM exit, the VMCS contains
+    information about the exit reason, often with accompanying detail. For
+    example, if a write to the CR0 register causes an exit, the offending
+    instruction is recorded, along with the fact that a write access to a
+    control register caused the exit, and information about source and
+    destination register. Thus the hypervisor can efficiently handle the
+    condition without needing advanced techniques such as CSAM and PATM
+    described above.</para>
+
+    <para>VT-x inherently avoids several of the problems which software
+    virtualization faces. The guest has its own completely separate address
+    space not shared with the hypervisor, which eliminates potential clashes.
+    Additionally, guest OS kernel code runs at privilege ring 0 in VMX
+    non-root mode, obviating the problems by running ring 0 code at less
+    privileged levels. For example the SYSENTER instruction can transition to
+    ring 0 without causing problems. Naturally, even at ring 0 in VMX non-root
+    mode, any I/O access by guest code still causes a VM exit, allowing for
+    device emulation.</para>
+
+    <para>The biggest difference between VT-x and AMD-V is that AMD-V provides
+    a more complete virtualization environment. VT-x requires the VMX non-root
+    code to run with paging enabled, which precludes hardware virtualization
+    of real-mode code and non-paged protected-mode software. This typically
+    only includes firmware and OS loaders, but nevertheless complicates VT-x
+    hypervisor implementation. AMD-V does not have this restriction.</para>
+
+    <para>Of course hardware virtualization is not perfect. Compared to
+    software virtualization, the overhead of VM exits is relatively high. This
+    causes problems for devices whose emulation requires high number of traps.
+    One example is the VGA device in 16-color modes, where not only every I/O
+    port access but also every access to the framebuffer memory must be
+    trapped.</para>
+  </sect1>
+
+  <sect1 id="nestedpaging">
+    <title>Nested paging and VPIDs</title>
+
+    <para>In addition to "plain" hardware virtualization, your processor may
+    also support additional sophisticated techniques:<footnote>
+        <para>VirtualBox 2.0 added support for AMD's nested paging; support
+        for Intel's EPT and VPIDs was added with version 2.1.</para>
+      </footnote><itemizedlist>
+        <listitem>
+          <para>A newer feature called <emphasis role="bold">"nested
+          paging"</emphasis> implements some memory management in hardware,
+          which can greatly accelerate hardware virtualization since these
+          tasks no longer need to be performed by the virtualization
+          software.</para>
+
+          <para>With nested paging, the hardware provides another level of
+          indirection when translating linear to physical addresses. Page
+          tables function as before, but linear addresses are now translated
+          to "guest physical" addresses first and not physical addresses
+          directly. A new set of paging registers now exists under the
+          traditional paging mechanism and translates from guest physical
+          addresses to host physical addresses, which are used to access
+          memory.</para>
+
+          <para>Nested paging eliminates the overhead caused by VM exits and
+          page table accesses. In essence, with nested page tables the guest
+          can handle paging without intervention from the hypervisor. Nested
+          paging thus significantly improves virtualization
+          performance.</para>
+
+          <para>On AMD processors, nested paging has been available starting
+          with the Barcelona (K10) architecture; Intel added support for
+          nested paging, which they call "extended page tables" (EPT), with
+          their Core i7 (Nehalem) processors.</para>
+
+          <para>If nested paging is enabled, the VirtualBox hypervisor can
+          also use <emphasis role="bold">large pages</emphasis> to reduce TLB
+          usage and overhead. This can yield a performance improvement of up
+          to 5%. To enable this feature for a VM, you need to use the
+          <computeroutput>VBoxManage modifyvm
+          </computeroutput><computeroutput>--largepages</computeroutput>
+          command; see <xref linkend="vboxmanage-modifyvm" />.</para>
+        </listitem>
+
+        <listitem>
+          <para>On Intel CPUs, another hardware feature called <emphasis
+          role="bold">"Virtual Processor Identifiers" (VPIDs)</emphasis> can
+          greatly accelerate context switching by reducing the need for
+          expensive flushing of the processor's Translation Lookaside Buffers
+          (TLBs).</para>
+
+          <para>To enable these features for a VM, you need to use the
+          <computeroutput>VBoxManage modifyvm --vtxvpids</computeroutput> and
+          <computeroutput>--largepages</computeroutput> commands; see <xref
+          linkend="vboxmanage-modifyvm" />.</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_ThirdParty.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_ThirdParty.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_ThirdParty.xml	(revision 33555)
@@ -0,0 +1,2591 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<appendix id="ThirdParty">
+  <title>Third-party materials and licenses</title>
+
+  <para>VirtualBox incorporates materials from several Open Source software
+  projects. Therefore the use of these materials by VirtualBox is governed by
+  different Open Source licenses. This document reproduces these licenses and
+  provides a list of the materials used and their respective licensing
+  conditions. Section 1 contains a list of the materials used. Section 2
+  reproduces the applicable Open Source licenses. For each material, a
+  reference to its license is provided.</para>
+
+  <para>The source code for the materials listed below as well as the rest of
+  the VirtualBox code which is released as open source are available at <ulink
+  url="http://www.virtualbox.org">http://www.virtualbox.org</ulink>, both as
+  tarballs for particular releases and as a live SVN repository.</para>
+
+  <sect1>
+    <title>Materials</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>VirtualBox contains portions of QEMU which is governed by the
+        licenses in <xref linkend="licX11" xrefstyle="template: %n" /> and
+        <xref linkend="licLGPL" xrefstyle="template: %n" /> and</para>
+
+        <para>(C) 2003-2005 Fabrice Bellard; Copyright (C) 2004-2005 Vassili
+        Karpov (malc); Copyright (c) 2004 Antony T Curtis; Copyright (C) 2003
+        Jocelyn Mayer</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains code which is governed by the license in
+        <xref linkend="licX11" xrefstyle="template: %n" /> and</para>
+
+        <para>Copyright 2004 by the Massachusetts Institute of
+        Technology.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains code of the BOCHS VGA BIOS which is governed
+        by the license in <xref linkend="licLGPL" xrefstyle="template: %n" />
+        and</para>
+
+        <para>Copyright (C) 2001, 2002 the LGPL VGABios developers
+        Team.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains code of the BOCHS ROM BIOS which is governed
+        by the license in <xref linkend="licLGPL" xrefstyle="template: %n" />
+        and</para>
+
+        <para>Copyright (C) 2002 MandrakeSoft S.A.; Copyright (C) 2004 Fabrice
+        Bellard; Copyright (C) 2005 Struan Bartlett.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains the zlib library which is governed by the
+        license in <xref linkend="licZLIB" xrefstyle="template: %n" />
+        and</para>
+
+        <para>Copyright (C) 1995-2003 Jean-loup Gailly and Mark Adler.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox may contain OpenSSL which is governed by the license
+        in <xref linkend="licSSL" xrefstyle="template: %n" /> and</para>
+
+        <para>Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com). This
+        product includes software written by Tim Hudson
+        (tjh@cryptsoft.com).</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox may contain NSPR and XPCOM which is governed by the
+        license in <xref linkend="licMPL" xrefstyle="template: %n" />
+        and</para>
+
+        <para>Copyright (C) The Authors.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains Slirp which is governed by the license in
+        <xref linkend="licSlirp" xrefstyle="template: %n" /> and was written
+        by Danny Gasparovski.</para>
+
+        <para>Copyright (C) 1995, 1996 All Rights Reserved.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains liblzf which is governed by the license in
+        <xref linkend="licLZF" xrefstyle="template: %n" /> and</para>
+
+        <para>Copyright (C) 2000-2005 Marc Alexander Lehmann
+        &lt;schmorp@schmorp.de&gt;</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox may ship with a modified copy of rdesktop which is
+        governed by the license in <xref linkend="licGPL"
+        xrefstyle="template: %n" /> and</para>
+
+        <para>Copyright (C) Matthew Chapman and others.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox may ship with a copy of kchmviewer which is governed
+        by the license in <xref linkend="licGPL" xrefstyle="template: %n" />
+        and</para>
+
+        <para>Copyright (C) George Yunaev and others.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox may contain Etherboot which is governed by the
+        license in <xref linkend="licGPL" xrefstyle="template: %n" /> with the
+        exception that aggregating Etherboot with another work does not
+        require the other work to be released under the same license (see
+        <literal><ulink
+        url="http://etherboot.sourceforge.net/clinks.html">http://etherboot.sourceforge.net/clinks.html</ulink></literal>).
+        Etherboot is</para>
+
+        <para>Copyright (C) Etherboot team.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains code from Wine which is governed by the
+        license in <xref linkend="licLGPL" xrefstyle="template: %n" />
+        and</para>
+
+        <para>Copyright 1993 Bob Amstadt, Copyright 1996 Albrecht Kleine,
+        Copyright 1997 David Faure, Copyright 1998 Morten Welinder, Copyright
+        1998 Ulrich Weigand, Copyright 1999 Ove Koven</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains code from lwIP which is governed by the
+        license in <xref linkend="licLWIP" xrefstyle="template: %n" />
+        and</para>
+
+        <para>Copyright (C) 2001, 2002 Swedish Institute of Computer
+        Science.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains libxml which is governed by the license in
+        <xref linkend="licLibXML" /> and</para>
+
+        <para>Copyright (C) 1998-2003 Daniel Veillard.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains libxslt which is governed by the license in
+        <xref linkend="licLibXSLT" /> and</para>
+
+        <para>Copyright (C) 2001-2002 Daniel Veillard and Copyright (C)
+        2001-2002 Thomas Broyer, Charlie Bozeman and Daniel Veillard.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains code from the gSOAP XML web services
+        tools, which are licensed under the license in <xref
+        linkend="licgSOAP" /> and</para>
+
+        <para>Copyright (C) 2000-2007, Robert van Engelen, Genivia Inc., and
+        others.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox ships with the application tunctl (shipped as
+        VBoxTunctl) from the User-mode Linux suite which is governed by the
+        license in <xref linkend="licGPL" xrefstyle="template: %n" />
+        and</para>
+
+        <para>Copyright (C) 2002 Jeff Dike.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains code from Chromium, an OpenGL
+        implementation, which is goverened by the licenses in <xref
+        linkend="licChromium" /> and</para>
+
+        <para>Copyright (C) Stanford University, The Regents of the University
+        of California, Red Hat, and others.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains libcurl which is governed by the license in
+        <xref linkend="licLibCurl" /> and</para>
+
+        <para>Copyright (C) 1996-2009, Daniel Stenberg.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains dnsproxy which is governed by the license in
+        <xref linkend="licMIT" /> and</para>
+
+        <para>Copyright (c) 2003, 2004, 2005 Armin Wolfermann.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox may contain iniparser which is governed by the
+        license in <xref linkend="licMIT" /> and</para>
+
+        <para>Copyright (c) 2000-2008 by Nicolas Devillard.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains some code from libgd which is governed by
+        the license in <xref linkend="licLibgd" /> and</para>
+
+        <para>Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+        Pierre-Alain Joye (pierre@libgd.org).</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains code from the EFI Development Kit II
+          which is governed by the license in
+          <xref linkend="licBsdIntel" /> and</para>
+
+        <para>Copyright (c) 2004-2008, Intel Corporation.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox contains libjpeg which is governed by the
+        license in <xref linkend="licJPEG" /> and</para>
+
+        <para>Copyright (C) 1991-2010, Thomas G. Lane, Guido Vollbeding.</para>
+      </listitem>
+
+      <listitem>
+        <para>VirtualBox may contain x86 SIMD extension for IJG JPEG library
+        which is governed by the license in <xref linkend="licJPEGSIMD" /> and</para>
+
+        <para>Copyright 2009 Pierre Ossman &lt;ossman@cendio.se&gt; for Cendio AB;
+        Copyright 2010 D. R. Commander; Copyright (C) 1999-2006, MIYASAKA Masaru.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Licenses</title>
+
+    <sect2 id="licGPL">
+      <title>GNU General Public License (GPL)</title>
+
+      <para>GNU GENERAL PUBLIC LICENSE Version 2, June 1991</para>
+
+      <para>Copyright (C) 1989, 1991 Free Software Foundation, Inc.</para>
+
+      <para>51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</para>
+
+      <para>Everyone is permitted to copy and distribute verbatim copies of
+      this license document, but changing it is not allowed.</para>
+
+      <para>Preamble</para>
+
+      <para>The licenses for most software are designed to take away your
+      freedom to share and change it. By contrast, the GNU General Public
+      License is intended to guarantee your freedom to share and change free
+      software--to make sure the software is free for all its users. This
+      General Public License applies to most of the Free Software Foundation's
+      software and to any other program whose authors commit to using it.
+      (Some other Free Software Foundation software is covered by the GNU
+      Library General Public License instead.) You can apply it to your
+      programs, too.</para>
+
+      <para>When we speak of free software, we are referring to freedom, not
+      price. Our General Public Licenses are designed to make sure that you
+      have the freedom to distribute copies of free software (and charge for
+      this service if you wish), that you receive source code or can get it if
+      you want it, that you can change the software or use pieces of it in new
+      free programs; and that you know you can do these things.</para>
+
+      <para>To protect your rights, we need to make restrictions that forbid
+      anyone to deny you these rights or to ask you to surrender the rights.
+      These restrictions translate to certain responsibilities for you if you
+      distribute copies of the software, or if you modify it.</para>
+
+      <para>For example, if you distribute copies of such a program, whether
+      gratis or for a fee, you must give the recipients all the rights that
+      you have. You must make sure that they, too, receive or can get the
+      source code. And you must show them these terms so they know their
+      rights.</para>
+
+      <para>We protect your rights with two steps: (1) copyright the software,
+      and (2) offer you this license which gives you legal permission to copy,
+      distribute and/or modify the software.</para>
+
+      <para>Also, for each author's protection and ours, we want to make
+      certain that everyone understands that there is no warranty for this
+      free software. If the software is modified by someone else and passed
+      on, we want its recipients to know that what they have is not the
+      original, so that any problems introduced by others will not reflect on
+      the original authors' reputations.</para>
+
+      <para>Finally, any free program is threatened constantly by software
+      patents. We wish to avoid the danger that redistributors of a free
+      program will individually obtain patent licenses, in effect making the
+      program proprietary. To prevent this, we have made it clear that any
+      patent must be licensed for everyone's free use or not licensed at
+      all.</para>
+
+      <para>The precise terms and conditions for copying, distribution and
+      modification follow.</para>
+
+      <para>GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING,
+      DISTRIBUTION AND MODIFICATION</para>
+
+      <para>0. This License applies to any program or other work which
+      contains a notice placed by the copyright holder saying it may be
+      distributed under the terms of this General Public License. The
+      "Program", below, refers to any such program or work, and a "work based
+      on the Program" means either the Program or any derivative work under
+      copyright law: that is to say, a work containing the Program or a
+      portion of it, either verbatim or with modifications and/or translated
+      into another language. (Hereinafter, translation is included without
+      limitation in the term "modification".) Each licensee is addressed as
+      "you".</para>
+
+      <para>Activities other than copying, distribution and modification are
+      not covered by this License; they are outside its scope. The act of
+      running the Program is not restricted, and the output from the Program
+      is covered only if its contents constitute a work based on the Program
+      (independent of having been made by running the Program). Whether that
+      is true depends on what the Program does.</para>
+
+      <para>1. You may copy and distribute verbatim copies of the Program's
+      source code as you receive it, in any medium, provided that you
+      conspicuously and appropriately publish on each copy an appropriate
+      copyright notice and disclaimer of warranty; keep intact all the notices
+      that refer to this License and to the absence of any warranty; and give
+      any other recipients of the Program a copy of this License along with
+      the Program.</para>
+
+      <para>You may charge a fee for the physical act of transferring a copy,
+      and you may at your option offer warranty protection in exchange for a
+      fee.</para>
+
+      <para>2. You may modify your copy or copies of the Program or any
+      portion of it, thus forming a work based on the Program, and copy and
+      distribute such modifications or work under the terms of Section 1
+      above, provided that you also meet all of these conditions:</para>
+
+      <para>a) You must cause the modified files to carry prominent notices
+      stating that you changed the files and the date of any change.</para>
+
+      <para>b) You must cause any work that you distribute or publish, that in
+      whole or in part contains or is derived from the Program or any part
+      thereof, to be licensed as a whole at no charge to all third parties
+      under the terms of this License.</para>
+
+      <para>c) If the modified program normally reads commands interactively
+      when run, you must cause it, when started running for such interactive
+      use in the most ordinary way, to print or display an announcement
+      including an appropriate copyright notice and a notice that there is no
+      warranty (or else, saying that you provide a warranty) and that users
+      may redistribute the program under these conditions, and telling the
+      user how to view a copy of this License. (Exception: if the Program
+      itself is interactive but does not normally print such an announcement,
+      your work based on the Program is not required to print an
+      announcement.)</para>
+
+      <para>These requirements apply to the modified work as a whole. If
+      identifiable sections of that work are not derived from the Program, and
+      can be reasonably considered independent and separate works in
+      themselves, then this License, and its terms, do not apply to those
+      sections when you distribute them as separate works. But when you
+      distribute the same sections as part of a whole which is a work based on
+      the Program, the distribution of the whole must be on the terms of this
+      License, whose permissions for other licensees extend to the entire
+      whole, and thus to each and every part regardless of who wrote
+      it.</para>
+
+      <para>Thus, it is not the intent of this section to claim rights or
+      contest your rights to work written entirely by you; rather, the intent
+      is to exercise the right to control the distribution of derivative or
+      collective works based on the Program.</para>
+
+      <para>In addition, mere aggregation of another work not based on the
+      Program with the Program (or with a work based on the Program) on a
+      volume of a storage or distribution medium does not bring the other work
+      under the scope of this License.</para>
+
+      <para>3. You may copy and distribute the Program (or a work based on it,
+      under Section 2) in object code or executable form under the terms of
+      Sections 1 and 2 above provided that you also do one of the
+      following:</para>
+
+      <para>a) Accompany it with the complete corresponding machine-readable
+      source code, which must be distributed under the terms of Sections 1 and
+      2 above on a medium customarily used for software interchange;
+      or,</para>
+
+      <para>b) Accompany it with a written offer, valid for at least three
+      years, to give any third party, for a charge no more than your cost of
+      physically performing source distribution, a complete machine-readable
+      copy of the corresponding source code, to be distributed under the terms
+      of Sections 1 and 2 above on a medium customarily used for software
+      interchange; or,</para>
+
+      <para>c) Accompany it with the information you received as to the offer
+      to distribute corresponding source code. (This alternative is allowed
+      only for noncommercial distribution and only if you received the program
+      in object code or executable form with such an offer, in accord with
+      Subsection b above.)</para>
+
+      <para>The source code for a work means the preferred form of the work
+      for making modifications to it. For an executable work, complete source
+      code means all the source code for all modules it contains, plus any
+      associated interface definition files, plus the scripts used to control
+      compilation and installation of the executable. However, as a special
+      exception, the source code distributed need not include anything that is
+      normally distributed (in either source or binary form) with the major
+      components (compiler, kernel, and so on) of the operating system on
+      which the executable runs, unless that component itself accompanies the
+      executable.</para>
+
+      <para>If distribution of executable or object code is made by offering
+      access to copy from a designated place, then offering equivalent access
+      to copy the source code from the same place counts as distribution of
+      the source code, even though third parties are not compelled to copy the
+      source along with the object code.</para>
+
+      <para>4. You may not copy, modify, sublicense, or distribute the Program
+      except as expressly provided under this License. Any attempt otherwise
+      to copy, modify, sublicense or distribute the Program is void, and will
+      automatically terminate your rights under this License. However, parties
+      who have received copies, or rights, from you under this License will
+      not have their licenses terminated so long as such parties remain in
+      full compliance.</para>
+
+      <para>5. You are not required to accept this License, since you have not
+      signed it. However, nothing else grants you permission to modify or
+      distribute the Program or its derivative works. These actions are
+      prohibited by law if you do not accept this License. Therefore, by
+      modifying or distributing the Program (or any work based on the
+      Program), you indicate your acceptance of this License to do so, and all
+      its terms and conditions for copying, distributing or modifying the
+      Program or works based on it.</para>
+
+      <para>6. Each time you redistribute the Program (or any work based on
+      the Program), the recipient automatically receives a license from the
+      original licensor to copy, distribute or modify the Program subject to
+      these terms and conditions. You may not impose any further restrictions
+      on the recipients' exercise of the rights granted herein. You are not
+      responsible for enforcing compliance by third parties to this
+      License.</para>
+
+      <para>7. If, as a consequence of a court judgment or allegation of
+      patent infringement or for any other reason (not limited to patent
+      issues), conditions are imposed on you (whether by court order,
+      agreement or otherwise) that contradict the conditions of this License,
+      they do not excuse you from the conditions of this License. If you
+      cannot distribute so as to satisfy simultaneously your obligations under
+      this License and any other pertinent obligations, then as a consequence
+      you may not distribute the Program at all. For example, if a patent
+      license would not permit royalty-free redistribution of the Program by
+      all those who receive copies directly or indirectly through you, then
+      the only way you could satisfy both it and this License would be to
+      refrain entirely from distribution of the Program.</para>
+
+      <para>If any portion of this section is held invalid or unenforceable
+      under any particular circumstance, the balance of the section is
+      intended to apply and the section as a whole is intended to apply in
+      other circumstances.</para>
+
+      <para>It is not the purpose of this section to induce you to infringe
+      any patents or other property right claims or to contest validity of any
+      such claims; this section has the sole purpose of protecting the
+      integrity of the free software distribution system, which is implemented
+      by public license practices. Many people have made generous
+      contributions to the wide range of software distributed through that
+      system in reliance on consistent application of that system; it is up to
+      the author/donor to decide if he or she is willing to distribute
+      software through any other system and a licensee cannot impose that
+      choice.</para>
+
+      <para>This section is intended to make thoroughly clear what is believed
+      to be a consequence of the rest of this License.</para>
+
+      <para>8. If the distribution and/or use of the Program is restricted in
+      certain countries either by patents or by copyrighted interfaces, the
+      original copyright holder who places the Program under this License may
+      add an explicit geographical distribution limitation excluding those
+      countries, so that distribution is permitted only in or among countries
+      not thus excluded. In such case, this License incorporates the
+      limitation as if written in the body of this License.</para>
+
+      <para>9. The Free Software Foundation may publish revised and/or new
+      versions of the General Public License from time to time. Such new
+      versions will be similar in spirit to the present version, but may
+      differ in detail to address new problems or concerns.</para>
+
+      <para>Each version is given a distinguishing version number. If the
+      Program specifies a version number of this License which applies to it
+      and "any later version", you have the option of following the terms and
+      conditions either of that version or of any later version published by
+      the Free Software Foundation. If the Program does not specify a version
+      number of this License, you may choose any version ever published by the
+      Free Software Foundation.</para>
+
+      <para>10. If you wish to incorporate parts of the Program into other
+      free programs whose distribution conditions are different, write to the
+      author to ask for permission. For software which is copyrighted by the
+      Free Software Foundation, write to the Free Software Foundation; we
+      sometimes make exceptions for this. Our decision will be guided by the
+      two goals of preserving the free status of all derivatives of our free
+      software and of promoting the sharing and reuse of software
+      generally.</para>
+
+      <para>NO WARRANTY</para>
+
+      <para>11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+      WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+      EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+      OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
+      EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
+      ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
+      YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
+      NECESSARY SERVICING, REPAIR OR CORRECTION.</para>
+
+      <para>12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+      AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
+      DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+      DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
+      (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
+      INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
+      THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
+      OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</para>
+
+      <para>END OF TERMS AND CONDITIONS</para>
+    </sect2>
+
+    <sect2 id="licLGPL">
+      <title>GNU Lesser General Public License (LGPL)</title>
+
+      <para>GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February
+      1999</para>
+
+      <para>Copyright (C) 1991, 1999 Free Software Foundation, Inc. 59 Temple
+      Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to
+      copy and distribute verbatim copies of this license document, but
+      changing it is not allowed.</para>
+
+      <para>[This is the first released version of the Lesser GPL. It also
+      counts as the successor of the GNU Library Public License, version 2,
+      hence the version number 2.1.]</para>
+
+      <para>Preamble</para>
+
+      <para>The licenses for most software are designed to take away your
+      freedom to share and change it. By contrast, the GNU General Public
+      Licenses are intended to guarantee your freedom to share and change free
+      software--to make sure the software is free for all its users.</para>
+
+      <para>This license, the Lesser General Public License, applies to some
+      specially designated software packages--typically libraries--of the Free
+      Software Foundation and other authors who decide to use it. You can use
+      it too, but we suggest you first think carefully about whether this
+      license or the ordinary General Public License is the better strategy to
+      use in any particular case, based on the explanations below.</para>
+
+      <para>When we speak of free software, we are referring to freedom of
+      use, not price. Our General Public Licenses are designed to make sure
+      that you have the freedom to distribute copies of free software (and
+      charge for this service if you wish); that you receive source code or
+      can get it if you want it; that you can change the software and use
+      pieces of it in new free programs; and that you are informed that you
+      can do these things.</para>
+
+      <para>To protect your rights, we need to make restrictions that forbid
+      distributors to deny you these rights or to ask you to surrender these
+      rights. These restrictions translate to certain responsibilities for you
+      if you distribute copies of the library or if you modify it.</para>
+
+      <para>For example, if you distribute copies of the library, whether
+      gratis or for a fee, you must give the recipients all the rights that we
+      gave you. You must make sure that they, too, receive or can get the
+      source code. If you link other code with the library, you must provide
+      complete object files to the recipients, so that they can relink them
+      with the library after making changes to the library and recompiling it.
+      And you must show them these terms so they know their rights.</para>
+
+      <para>We protect your rights with a two-step method: (1) we copyright
+      the library, and (2) we offer you this license, which gives you legal
+      permission to copy, distribute and/or modify the library.</para>
+
+      <para>To protect each distributor, we want to make it very clear that
+      there is no warranty for the free library. Also, if the library is
+      modified by someone else and passed on, the recipients should know that
+      what they have is not the original version, so that the original
+      author's reputation will not be affected by problems that might be
+      introduced by others.</para>
+
+      <para>Finally, software patents pose a constant threat to the existence
+      of any free program. We wish to make sure that a company cannot
+      effectively restrict the users of a free program by obtaining a
+      restrictive license from a patent holder. Therefore, we insist that any
+      patent license obtained for a version of the library must be consistent
+      with the full freedom of use specified in this license.</para>
+
+      <para>Most GNU software, including some libraries, is covered by the
+      ordinary GNU General Public License. This license, the GNU Lesser
+      General Public License, applies to certain designated libraries, and is
+      quite different from the ordinary General Public License. We use this
+      license for certain libraries in order to permit linking those libraries
+      into non-free programs.</para>
+
+      <para>When a program is linked with a library, whether statically or
+      using a shared library, the combination of the two is legally speaking a
+      combined work, a derivative of the original library. The ordinary
+      General Public License therefore permits such linking only if the entire
+      combination fits its criteria of freedom. The Lesser General Public
+      License permits more lax criteria for linking other code with the
+      library.</para>
+
+      <para>We call this license the "Lesser" General Public License because
+      it does Less to protect the user's freedom than the ordinary General
+      Public License. It also provides other free software developers Less of
+      an advantage over competing non-free programs. These disadvantages are
+      the reason we use the ordinary General Public License for many
+      libraries. However, the Lesser license provides advantages in certain
+      special circumstances.</para>
+
+      <para>For example, on rare occasions, there may be a special need to
+      encourage the widest possible use of a certain library, so that it
+      becomes a de-facto standard. To achieve this, non-free programs must be
+      allowed to use the library. A more frequent case is that a free library
+      does the same job as widely used non-free libraries. In this case, there
+      is little to gain by limiting the free library to free software only, so
+      we use the Lesser General Public License.</para>
+
+      <para>In other cases, permission to use a particular library in non-free
+      programs enables a greater number of people to use a large body of free
+      software. For example, permission to use the GNU C Library in non-free
+      programs enables many more people to use the whole GNU operating system,
+      as well as its variant, the GNU/Linux operating system.</para>
+
+      <para>Although the Lesser General Public License is Less protective of
+      the users' freedom, it does ensure that the user of a program that is
+      linked with the Library has the freedom and the wherewithal to run that
+      program using a modified version of the Library.</para>
+
+      <para>The precise terms and conditions for copying, distribution and
+      modification follow. Pay close attention to the difference between a
+      "work based on the library" and a "work that uses the library". The
+      former contains code derived from the library, whereas the latter must
+      be combined with the library in order to run.</para>
+
+      <para>GNU LESSER GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR
+      COPYING, DISTRIBUTION AND MODIFICATION</para>
+
+      <para>0. This License Agreement applies to any software library or other
+      program which contains a notice placed by the copyright holder or other
+      authorized party saying it may be distributed under the terms of this
+      Lesser General Public License (also called "this License"). Each
+      licensee is addressed as "you".</para>
+
+      <para>A "library" means a collection of software functions and/or data
+      prepared so as to be conveniently linked with application programs
+      (which use some of those functions and data) to form executables.</para>
+
+      <para>The "Library", below, refers to any such software library or work
+      which has been distributed under these terms. A "work based on the
+      Library" means either the Library or any derivative work under copyright
+      law: that is to say, a work containing the Library or a portion of it,
+      either verbatim or with modifications and/or translated
+      straightforwardly into another language. (Hereinafter, translation is
+      included without limitation in the term "modification".)</para>
+
+      <para>"Source code" for a work means the preferred form of the work for
+      making modifications to it. For a library, complete source code means
+      all the source code for all modules it contains, plus any associated
+      interface definition files, plus the scripts used to control compilation
+      and installation of the library.</para>
+
+      <para>Activities other than copying, distribution and modification are
+      not covered by this License; they are outside its scope. The act of
+      running a program using the Library is not restricted, and output from
+      such a program is covered only if its contents constitute a work based
+      on the Library (independent of the use of the Library in a tool for
+      writing it). Whether that is true depends on what the Library does and
+      what the program that uses the Library does.</para>
+
+      <para>1. You may copy and distribute verbatim copies of the Library's
+      complete source code as you receive it, in any medium, provided that you
+      conspicuously and appropriately publish on each copy an appropriate
+      copyright notice and disclaimer of warranty; keep intact all the notices
+      that refer to this License and to the absence of any warranty; and
+      distribute a copy of this License along with the Library.</para>
+
+      <para>You may charge a fee for the physical act of transferring a copy,
+      and you may at your option offer warranty protection in exchange for a
+      fee.</para>
+
+      <para>2. You may modify your copy or copies of the Library or any
+      portion of it, thus forming a work based on the Library, and copy and
+      distribute such modifications or work under the terms of Section 1
+      above, provided that you also meet all of these conditions:</para>
+
+      <para>a) The modified work must itself be a software library.</para>
+
+      <para>b) You must cause the files modified to carry prominent notices
+      stating that you changed the files and the date of any change.</para>
+
+      <para>c) You must cause the whole of the work to be licensed at no
+      charge to all third parties under the terms of this License.</para>
+
+      <para>d) If a facility in the modified Library refers to a function or a
+      table of data to be supplied by an application program that uses the
+      facility, other than as an argument passed when the facility is invoked,
+      then you must make a good faith effort to ensure that, in the event an
+      application does not supply such function or table, the facility still
+      operates, and performs whatever part of its purpose remains
+      meaningful.</para>
+
+      <para>(For example, a function in a library to compute square roots has
+      a purpose that is entirely well-defined independent of the application.
+      Therefore, Subsection 2d requires that any application-supplied function
+      or table used by this function must be optional: if the application does
+      not supply it, the square root function must still compute square
+      roots.)</para>
+
+      <para>These requirements apply to the modified work as a whole. If
+      identifiable sections of that work are not derived from the Library, and
+      can be reasonably considered independent and separate works in
+      themselves, then this License, and its terms, do not apply to those
+      sections when you distribute them as separate works. But when you
+      distribute the same sections as part of a whole which is a work based on
+      the Library, the distribution of the whole must be on the terms of this
+      License, whose permissions for other licensees extend to the entire
+      whole, and thus to each and every part regardless of who wrote
+      it.</para>
+
+      <para>Thus, it is not the intent of this section to claim rights or
+      contest your rights to work written entirely by you; rather, the intent
+      is to exercise the right to control the distribution of derivative or
+      collective works based on the Library.</para>
+
+      <para>In addition, mere aggregation of another work not based on the
+      Library with the Library (or with a work based on the Library) on a
+      volume of a storage or distribution medium does not bring the other work
+      under the scope of this License.</para>
+
+      <para>3. You may opt to apply the terms of the ordinary GNU General
+      Public License instead of this License to a given copy of the Library.
+      To do this, you must alter all the notices that refer to this License,
+      so that they refer to the ordinary GNU General Public License, version
+      2, instead of to this License. (If a newer version than version 2 of the
+      ordinary GNU General Public License has appeared, then you can specify
+      that version instead if you wish.) Do not make any other change in these
+      notices.</para>
+
+      <para>Once this change is made in a given copy, it is irreversible for
+      that copy, so the ordinary GNU General Public License applies to all
+      subsequent copies and derivative works made from that copy.</para>
+
+      <para>This option is useful when you wish to copy part of the code of
+      the Library into a program that is not a library.</para>
+
+      <para>4. You may copy and distribute the Library (or a portion or
+      derivative of it, under Section 2) in object code or executable form
+      under the terms of Sections 1 and 2 above provided that you accompany it
+      with the complete corresponding machine-readable source code, which must
+      be distributed under the terms of Sections 1 and 2 above on a medium
+      customarily used for software interchange.</para>
+
+      <para>If distribution of object code is made by offering access to copy
+      from a designated place, then offering equivalent access to copy the
+      source code from the same place satisfies the requirement to distribute
+      the source code, even though third parties are not compelled to copy the
+      source along with the object code.</para>
+
+      <para>5. A program that contains no derivative of any portion of the
+      Library, but is designed to work with the Library by being compiled or
+      linked with it, is called a "work that uses the Library". Such a work,
+      in isolation, is not a derivative work of the Library, and therefore
+      falls outside the scope of this License.</para>
+
+      <para>However, linking a "work that uses the Library" with the Library
+      creates an executable that is a derivative of the Library (because it
+      contains portions of the Library), rather than a "work that uses the
+      library". The executable is therefore covered by this License. Section 6
+      states terms for distribution of such executables.</para>
+
+      <para>When a "work that uses the Library" uses material from a header
+      file that is part of the Library, the object code for the work may be a
+      derivative work of the Library even though the source code is not.
+      Whether this is true is especially significant if the work can be linked
+      without the Library, or if the work is itself a library. The threshold
+      for this to be true is not precisely defined by law.</para>
+
+      <para>If such an object file uses only numerical parameters, data
+      structure layouts and accessors, and small macros and small inline
+      functions (ten lines or less in length), then the use of the object file
+      is unrestricted, regardless of whether it is legally a derivative work.
+      (Executables containing this object code plus portions of the Library
+      will still fall under Section 6.) Otherwise, if the work is a derivative
+      of the Library, you may distribute the object code for the work under
+      the terms of Section 6. Any executables containing that work also fall
+      under Section 6, whether or not they are linked directly with the
+      Library itself.</para>
+
+      <para>6. As an exception to the Sections above, you may also combine or
+      link a "work that uses the Library" with the Library to produce a work
+      containing portions of the Library, and distribute that work under terms
+      of your choice, provided that the terms permit modification of the work
+      for the customer's own use and reverse engineering for debugging such
+      modifications.</para>
+
+      <para>You must give prominent notice with each copy of the work that the
+      Library is used in it and that the Library and its use are covered by
+      this License. You must supply a copy of this License. If the work during
+      execution displays copyright notices, you must include the copyright
+      notice for the Library among them, as well as a reference directing the
+      user to the copy of this License. Also, you must do one of these
+      things:</para>
+
+      <para>a) Accompany the work with the complete corresponding
+      machine-readable source code for the Library including whatever changes
+      were used in the work (which must be distributed under Sections 1 and 2
+      above); and, if the work is an executable linked with the Library, with
+      the complete machine-readable "work that uses the Library", as object
+      code and/or source code, so that the user can modify the Library and
+      then relink to produce a modified executable containing the modified
+      Library. (It is understood that the user who changes the contents of
+      definitions files in the Library will not necessarily be able to
+      recompile the application to use the modified definitions.)</para>
+
+      <para>b) Use a suitable shared library mechanism for linking with the
+      Library. A suitable mechanism is one that (1) uses at run time a copy of
+      the library already present on the user's computer system, rather than
+      copying library functions into the executable, and (2) will operate
+      properly with a modified version of the library, if the user installs
+      one, as long as the modified version is interface-compatible with the
+      version that the work was made with.</para>
+
+      <para>c) Accompany the work with a written offer, valid for at least
+      three years, to give the same user the materials specified in Subsection
+      6a, above, for a charge no more than the cost of performing this
+      distribution.</para>
+
+      <para>d) If distribution of the work is made by offering access to copy
+      from a designated place, offer equivalent access to copy the above
+      specified materials from the same place.</para>
+
+      <para>e) Verify that the user has already received a copy of these
+      materials or that you have already sent this user a copy.</para>
+
+      <para>For an executable, the required form of the "work that uses the
+      Library" must include any data and utility programs needed for
+      reproducing the executable from it. However, as a special exception, the
+      materials to be distributed need not include anything that is normally
+      distributed (in either source or binary form) with the major components
+      (compiler, kernel, and so on) of the operating system on which the
+      executable runs, unless that component itself accompanies the
+      executable.</para>
+
+      <para>It may happen that this requirement contradicts the license
+      restrictions of other proprietary libraries that do not normally
+      accompany the operating system. Such a contradiction means you cannot
+      use both them and the Library together in an executable that you
+      distribute.</para>
+
+      <para>7. You may place library facilities that are a work based on the
+      Library side-by-side in a single library together with other library
+      facilities not covered by this License, and distribute such a combined
+      library, provided that the separate distribution of the work based on
+      the Library and of the other library facilities is otherwise permitted,
+      and provided that you do these two things:</para>
+
+      <para>a) Accompany the combined library with a copy of the same work
+      based on the Library, uncombined with any other library facilities. This
+      must be distributed under the terms of the Sections above.</para>
+
+      <para>b) Give prominent notice with the combined library of the fact
+      that part of it is a work based on the Library, and explaining where to
+      find the accompanying uncombined form of the same work.</para>
+
+      <para>8. You may not copy, modify, sublicense, link with, or distribute
+      the Library except as expressly provided under this License. Any attempt
+      otherwise to copy, modify, sublicense, link with, or distribute the
+      Library is void, and will automatically terminate your rights under this
+      License. However, parties who have received copies, or rights, from you
+      under this License will not have their licenses terminated so long as
+      such parties remain in full compliance.</para>
+
+      <para>9. You are not required to accept this License, since you have not
+      signed it. However, nothing else grants you permission to modify or
+      distribute the Library or its derivative works. These actions are
+      prohibited by law if you do not accept this License. Therefore, by
+      modifying or distributing the Library (or any work based on the
+      Library), you indicate your acceptance of this License to do so, and all
+      its terms and conditions for copying, distributing or modifying the
+      Library or works based on it.</para>
+
+      <para>10. Each time you redistribute the Library (or any work based on
+      the Library), the recipient automatically receives a license from the
+      original licensor to copy, distribute, link with or modify the Library
+      subject to these terms and conditions. You may not impose any further
+      restrictions on the recipients' exercise of the rights granted herein.
+      You are not responsible for enforcing compliance by third parties with
+      this License.</para>
+
+      <para>11. If, as a consequence of a court judgment or allegation of
+      patent infringement or for any other reason (not limited to patent
+      issues), conditions are imposed on you (whether by court order,
+      agreement or otherwise) that contradict the conditions of this License,
+      they do not excuse you from the conditions of this License. If you
+      cannot distribute so as to satisfy simultaneously your obligations under
+      this License and any other pertinent obligations, then as a consequence
+      you may not distribute the Library at all. For example, if a patent
+      license would not permit royalty-free redistribution of the Library by
+      all those who receive copies directly or indirectly through you, then
+      the only way you could satisfy both it and this License would be to
+      refrain entirely from distribution of the Library.</para>
+
+      <para>If any portion of this section is held invalid or unenforceable
+      under any particular circumstance, the balance of the section is
+      intended to apply, and the section as a whole is intended to apply in
+      other circumstances.</para>
+
+      <para>It is not the purpose of this section to induce you to infringe
+      any patents or other property right claims or to contest validity of any
+      such claims; this section has the sole purpose of protecting the
+      integrity of the free software distribution system which is implemented
+      by public license practices. Many people have made generous
+      contributions to the wide range of software distributed through that
+      system in reliance on consistent application of that system; it is up to
+      the author/donor to decide if he or she is willing to distribute
+      software through any other system and a licensee cannot impose that
+      choice.</para>
+
+      <para>This section is intended to make thoroughly clear what is believed
+      to be a consequence of the rest of this License.</para>
+
+      <para>12. If the distribution and/or use of the Library is restricted in
+      certain countries either by patents or by copyrighted interfaces, the
+      original copyright holder who places the Library under this License may
+      add an explicit geographical distribution limitation excluding those
+      countries, so that distribution is permitted only in or among countries
+      not thus excluded. In such case, this License incorporates the
+      limitation as if written in the body of this License.</para>
+
+      <para>13. The Free Software Foundation may publish revised and/or new
+      versions of the Lesser General Public License from time to time. Such
+      new versions will be similar in spirit to the present version, but may
+      differ in detail to address new problems or concerns.</para>
+
+      <para>Each version is given a distinguishing version number. If the
+      Library specifies a version number of this License which applies to it
+      and "any later version", you have the option of following the terms and
+      conditions either of that version or of any later version published by
+      the Free Software Foundation. If the Library does not specify a license
+      version number, you may choose any version ever published by the Free
+      Software Foundation.</para>
+
+      <para>14. If you wish to incorporate parts of the Library into other
+      free programs whose distribution conditions are incompatible with these,
+      write to the author to ask for permission. For software which is
+      copyrighted by the Free Software Foundation, write to the Free Software
+      Foundation; we sometimes make exceptions for this. Our decision will be
+      guided by the two goals of preserving the free status of all derivatives
+      of our free software and of promoting the sharing and reuse of software
+      generally.</para>
+
+      <para>NO WARRANTY</para>
+
+      <para>15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+      WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+      EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+      OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND,
+      EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
+      ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH
+      YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
+      NECESSARY SERVICING, REPAIR OR CORRECTION.</para>
+
+      <para>16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+      AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
+      DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+      DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY
+      (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
+      INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
+      THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR
+      OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</para>
+
+      <para>END OF TERMS AND CONDITIONS</para>
+    </sect2>
+
+    <sect2 id="licMPL">
+      <title>Mozilla Public License (MPL)</title>
+
+      <para>MOZILLA PUBLIC LICENSE Version 1.1</para>
+
+      <para>1. Definitions.</para>
+
+      <para>1.0.1. "Commercial Use" means distribution or otherwise making the
+      Covered Code available to a third party.</para>
+
+      <para>1.1. "Contributor" means each entity that creates or contributes
+      to the creation of Modifications.</para>
+
+      <para>1.2. "Contributor Version" means the combination of the Original
+      Code, prior Modifications used by a Contributor, and the Modifications
+      made by that particular Contributor.</para>
+
+      <para>1.3. "Covered Code" means the Original Code or Modifications or
+      the combination of the Original Code and Modifications, in each case
+      including portions thereof.</para>
+
+      <para>1.4. "Electronic Distribution Mechanism" means a mechanism
+      generally accepted in the software development community for the
+      electronic transfer of data.</para>
+
+      <para>1.5. "Executable" means Covered Code in any form other than Source
+      Code.</para>
+
+      <para>1.6. "Initial Developer" means the individual or entity identified
+      as the Initial Developer in the Source Code notice required by Exhibit
+      A.</para>
+
+      <para>1.7. "Larger Work" means a work which combines Covered Code or
+      portions thereof with code not governed by the terms of this
+      License.</para>
+
+      <para>1.8. "License" means this document.</para>
+
+      <para>1.8.1. "Licensable" means having the right to grant, to the
+      maximum extent possible, whether at the time of the initial grant or
+      subsequently acquired, any and all of the rights conveyed herein.</para>
+
+      <para>1.9. "Modifications" means any addition to or deletion from the
+      substance or structure of either the Original Code or any previous
+      Modifications. When Covered Code is released as a series of files, a
+      Modification is:</para>
+
+      <para>A. Any addition to or deletion from the contents of a file
+      containing Original Code or previous Modifications.</para>
+
+      <para>B. Any new file that contains any part of the Original Code or
+      previous Modifications.</para>
+
+      <para>1.10. "Original Code" means Source Code of computer software code
+      which is described in the Source Code notice required by Exhibit A as
+      Original Code, and which, at the time of its release under this License
+      is not already Covered Code governed by this License.</para>
+
+      <para>1.10.1. "Patent Claims" means any patent claim(s), now owned or
+      hereafter acquired, including without limitation, method, process, and
+      apparatus claims, in any patent Licensable by grantor.</para>
+
+      <para>1.11. "Source Code" means the preferred form of the Covered Code
+      for making modifications to it, including all modules it contains, plus
+      any associated interface definition files, scripts used to control
+      compilation and installation of an Executable, or source code
+      differential comparisons against either the Original Code or another
+      well known, available Covered Code of the Contributor's choice. The
+      Source Code can be in a compressed or archival form, provided the
+      appropriate decompression or de-archiving software is widely available
+      for no charge.</para>
+
+      <para>1.12. "You" (or "Your") means an individual or a legal entity
+      exercising rights under, and complying with all of the terms of, this
+      License or a future version of this License issued under Section 6.1.
+      For legal entities, "You" includes any entity which controls, is
+      controlled by, or is under common control with You. For purposes of this
+      definition, "control" means (a) the power, direct or indirect, to cause
+      the direction or management of such entity, whether by contract or
+      otherwise, or (b) ownership of more than fifty percent (50%) of the
+      outstanding shares or beneficial ownership of such entity.</para>
+
+      <para>2. Source Code License.</para>
+
+      <para>2.1. The Initial Developer Grant. The Initial Developer hereby
+      grants You a world-wide, royalty-free, non-exclusive license, subject to
+      third party intellectual property claims:</para>
+
+      <para>(a) under intellectual property rights (other than patent or
+      trademark) Licensable by Initial Developer to use, reproduce, modify,
+      display, perform, sublicense and distribute the Original Code (or
+      portions thereof) with or without Modifications, and/or as part of a
+      Larger Work; and</para>
+
+      <para>(b) under Patents Claims infringed by the making, using or selling
+      of Original Code, to make, have made, use, practice, sell, and offer for
+      sale, and/or otherwise dispose of the Original Code (or portions
+      thereof).</para>
+
+      <para>(c) the licenses granted in this Section 2.1(a) and (b) are
+      effective on the date Initial Developer first distributes Original Code
+      under the terms of this License.</para>
+
+      <para>(d) Notwithstanding Section 2.1(b) above, no patent license is
+      granted: 1) for code that You delete from the Original Code; 2) separate
+      from the Original Code; or 3) for infringements caused by: i) the
+      modification of the Original Code or ii) the combination of the Original
+      Code with other software or devices.</para>
+
+      <para>2.2. Contributor Grant. Subject to third party intellectual
+      property claims, each Contributor hereby grants You a world-wide,
+      royalty-free, non-exclusive license</para>
+
+      <para>(a) under intellectual property rights (other than patent or
+      trademark) Licensable by Contributor, to use, reproduce, modify,
+      display, perform, sublicense and distribute the Modifications created by
+      such Contributor (or portions thereof) either on an unmodified basis,
+      with other Modifications, as Covered Code and/or as part of a Larger
+      Work; and</para>
+
+      <para>(b) under Patent Claims infringed by the making, using, or selling
+      of Modifications made by that Contributor either alone and/or in
+      combination with its Contributor Version (or portions of such
+      combination), to make, use, sell, offer for sale, have made, and/or
+      otherwise dispose of: 1) Modifications made by that Contributor (or
+      portions thereof); and 2) the combination of Modifications made by that
+      Contributor with its Contributor Version (or portions of such
+      combination).</para>
+
+      <para>(c) the licenses granted in Sections 2.2(a) and 2.2(b) are
+      effective on the date Contributor first makes Commercial Use of the
+      Covered Code.</para>
+
+      <para>(d) Notwithstanding Section 2.2(b) above, no patent license is
+      granted: 1) for any code that Contributor has deleted from the
+      Contributor Version; 2) separate from the Contributor Version; 3) for
+      infringements caused by: i) third party modifications of Contributor
+      Version or ii) the combination of Modifications made by that Contributor
+      with other software (except as part of the Contributor Version) or other
+      devices; or 4) under Patent Claims infringed by Covered Code in the
+      absence of Modifications made by that Contributor.</para>
+
+      <para>3. Distribution Obligations.</para>
+
+      <para>3.1. Application of License. The Modifications which You create or
+      to which You contribute are governed by the terms of this License,
+      including without limitation Section 2.2. The Source Code version of
+      Covered Code may be distributed only under the terms of this License or
+      a future version of this License released under Section 6.1, and You
+      must include a copy of this License with every copy of the Source Code
+      You distribute. You may not offer or impose any terms on any Source Code
+      version that alters or restricts the applicable version of this License
+      or the recipients' rights hereunder. However, You may include an
+      additional document offering the additional rights described in Section
+      3.5.</para>
+
+      <para>3.2. Availability of Source Code. Any Modification which You
+      create or to which You contribute must be made available in Source Code
+      form under the terms of this License either on the same media as an
+      Executable version or via an accepted Electronic Distribution Mechanism
+      to anyone to whom you made an Executable version available; and if made
+      available via Electronic Distribution Mechanism, must remain available
+      for at least twelve (12) months after the date it initially became
+      available, or at least six (6) months after a subsequent version of that
+      particular Modification has been made available to such recipients. You
+      are responsible for ensuring that the Source Code version remains
+      available even if the Electronic Distribution Mechanism is maintained by
+      a third party.</para>
+
+      <para>3.3. Description of Modifications. You must cause all Covered Code
+      to which You contribute to contain a file documenting the changes You
+      made to create that Covered Code and the date of any change. You must
+      include a prominent statement that the Modification is derived, directly
+      or indirectly, from Original Code provided by the Initial Developer and
+      including the name of the Initial Developer in (a) the Source Code, and
+      (b) in any notice in an Executable version or related documentation in
+      which You describe the origin or ownership of the Covered Code.</para>
+
+      <para>3.4. Intellectual Property Matters</para>
+
+      <para>(a) Third Party Claims. If Contributor has knowledge that a
+      license under a third party's intellectual property rights is required
+      to exercise the rights granted by such Contributor under Sections 2.1 or
+      2.2, Contributor must include a text file with the Source Code
+      distribution titled "LEGAL" which describes the claim and the party
+      making the claim in sufficient detail that a recipient will know whom to
+      contact. If Contributor obtains such knowledge after the Modification is
+      made available as described in Section 3.2, Contributor shall promptly
+      modify the LEGAL file in all copies Contributor makes available
+      thereafter and shall take other steps (such as notifying appropriate
+      mailing lists or newsgroups) reasonably calculated to inform those who
+      received the Covered Code that new knowledge has been obtained.</para>
+
+      <para>(b) Contributor APIs. If Contributor's Modifications include an
+      application programming interface and Contributor has knowledge of
+      patent licenses which are reasonably necessary to implement that API,
+      Contributor must also include this information in the LEGAL file.</para>
+
+      <para>3.5. Required Notices. You must duplicate the notice in Exhibit A
+      in each file of the Source Code. If it is not possible to put such
+      notice in a particular Source Code file due to its structure, then You
+      must include such notice in a location (such as a relevant directory)
+      where a user would be likely to look for such a notice. If You created
+      one or more Modification(s) You may add your name as a Contributor to
+      the notice described in Exhibit A. You must also duplicate this License
+      in any documentation for the Source Code where You describe recipients'
+      rights or ownership rights relating to Covered Code. You may choose to
+      offer, and to charge a fee for, warranty, support, indemnity or
+      liability obligations to one or more recipients of Covered Code.
+      However, You may do so only on Your own behalf, and not on behalf of the
+      Initial Developer or any Contributor. You must make it absolutely clear
+      than any such warranty, support, indemnity or liability obligation is
+      offered by You alone, and You hereby agree to indemnify the Initial
+      Developer and every Contributor for any liability incurred by the
+      Initial Developer or such Contributor as a result of warranty, support,
+      indemnity or liability terms You offer.</para>
+
+      <para>3.6. Distribution of Executable Versions. You may distribute
+      Covered Code in Executable form only if the requirements of Section
+      3.1-3.5 have been met for that Covered Code, and if You include a notice
+      stating that the Source Code version of the Covered Code is available
+      under the terms of this License, including a description of how and
+      where You have fulfilled the obligations of Section 3.2. The notice must
+      be conspicuously included in any notice in an Executable version,
+      related documentation or collateral in which You describe recipients'
+      rights relating to the Covered Code. You may distribute the Executable
+      version of Covered Code or ownership rights under a license of Your
+      choice, which may contain terms different from this License, provided
+      that You are in compliance with the terms of this License and that the
+      license for the Executable version does not attempt to limit or alter
+      the recipient's rights in the Source Code version from the rights set
+      forth in this License. If You distribute the Executable version under a
+      different license You must make it absolutely clear that any terms which
+      differ from this License are offered by You alone, not by the Initial
+      Developer or any Contributor. You hereby agree to indemnify the Initial
+      Developer and every Contributor for any liability incurred by the
+      Initial Developer or such Contributor as a result of any such terms You
+      offer.</para>
+
+      <para>3.7. Larger Works. You may create a Larger Work by combining
+      Covered Code with other code not governed by the terms of this License
+      and distribute the Larger Work as a single product. In such a case, You
+      must make sure the requirements of this License are fulfilled for the
+      Covered Code.</para>
+
+      <para>4. Inability to Comply Due to Statute or Regulation.If it is
+      impossible for You to comply with any of the terms of this License with
+      respect to some or all of the Covered Code due to statute, judicial
+      order, or regulation then You must: (a) comply with the terms of this
+      License to the maximum extent possible; and (b) describe the limitations
+      and the code they affect. Such description must be included in the LEGAL
+      file described in Section 3.4 and must be included with all
+      distributions of the Source Code. Except to the extent prohibited by
+      statute or regulation, such description must be sufficiently detailed
+      for a recipient of ordinary skill to be able to understand it.</para>
+
+      <para>5. Application of this License. This License applies to code to
+      which the Initial Developer has attached the notice in Exhibit A and to
+      related Covered Code.</para>
+
+      <para>6. Versions of the License.</para>
+
+      <para>6.1. New Versions. Netscape Communications Corporation
+      ("Netscape") may publish revised and/or new versions of the License from
+      time to time. Each version will be given a distinguishing version
+      number.</para>
+
+      <para>6.2. Effect of New Versions. Once Covered Code has been published
+      under a particular version of the License, You may always continue to
+      use it under the terms of that version. You may also choose to use such
+      Covered Code under the terms of any subsequent version of the License
+      published by Netscape. No one other than Netscape has the right to
+      modify the terms applicable to Covered Code created under this
+      License.</para>
+
+      <para>6.3. Derivative Works. If You create or use a modified version of
+      this License (which you may only do in order to apply it to code which
+      is not already Covered Code governed by this License), You must (a)
+      rename Your license so that the phrases "Mozilla", "MOZILLAPL", "MOZPL",
+      "Netscape", "MPL", "NPL" or any confusingly similar phrase do not appear
+      in your license (except to note that your license differs from this
+      License) and (b) otherwise make it clear that Your version of the
+      license contains terms which differ from the Mozilla Public License and
+      Netscape Public License. (Filling in the name of the Initial Developer,
+      Original Code or Contributor in the notice described in Exhibit A shall
+      not of themselves be deemed to be modifications of this License.)</para>
+
+      <para>7. DISCLAIMER OF WARRANTY.</para>
+
+      <para>COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS" BASIS,
+      WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+      WITHOUT LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF DEFECTS,
+      MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE
+      RISK AS TO THE QUALITY AND PERFORMANCE OF THE COVERED CODE IS WITH YOU.
+      SHOULD ANY COVERED CODE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE
+      INITIAL DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY
+      NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY
+      CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY COVERED
+      CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.</para>
+
+      <para>8. TERMINATION.</para>
+
+      <para>8.1. This License and the rights granted hereunder will terminate
+      automatically if You fail to comply with terms herein and fail to cure
+      such breach within 30 days of becoming aware of the breach. All
+      sublicenses to the Covered Code which are properly granted shall survive
+      any termination of this License. Provisions which, by their nature, must
+      remain in effect beyond the termination of this License shall
+      survive.</para>
+
+      <para>8.2. If You initiate litigation by asserting a patent infringement
+      claim (excluding declaratory judgment actions) against Initial Developer
+      or a Contributor (the Initial Developer or Contributor against whom You
+      file such action is referred to as "Participant") alleging that:</para>
+
+      <para>(a) such Participant's Contributor Version directly or indirectly
+      infringes any patent, then any and all rights granted by such
+      Participant to You under Sections 2.1 and/or 2.2 of this License shall,
+      upon 60 days notice from Participant terminate prospectively, unless if
+      within 60 days after receipt of notice You either: (i) agree in writing
+      to pay Participant a mutually agreeable reasonable royalty for Your past
+      and future use of Modifications made by such Participant, or (ii)
+      withdraw Your litigation claim with respect to the Contributor Version
+      against such Participant. If within 60 days of notice, a reasonable
+      royalty and payment arrangement are not mutually agreed upon in writing
+      by the parties or the litigation claim is not withdrawn, the rights
+      granted by Participant to You under Sections 2.1 and/or 2.2
+      automatically terminate at the expiration of the 60 day notice period
+      specified above.</para>
+
+      <para>(b) any software, hardware, or device, other than such
+      Participant's Contributor Version, directly or indirectly infringes any
+      patent, then any rights granted to You by such Participant under
+      Sections 2.1(b) and 2.2(b) are revoked effective as of the date You
+      first made, used, sold, distributed, or had made, Modifications made by
+      that Participant.</para>
+
+      <para>8.3. If You assert a patent infringement claim against Participant
+      alleging that such Participant's Contributor Version directly or
+      indirectly infringes any patent where such claim is resolved (such as by
+      license or settlement) prior to the initiation of patent infringement
+      litigation, then the reasonable value of the licenses granted by such
+      Participant under Sections 2.1 or 2.2 shall be taken into account in
+      determining the amount or value of any payment or license.</para>
+
+      <para>8.4. In the event of termination under Sections 8.1 or 8.2 above,
+      all end user license agreements (excluding distributors and resellers)
+      which have been validly granted by You or any distributor hereunder
+      prior to termination shall survive termination.</para>
+
+      <para>9. LIMITATION OF LIABILITY. UNDER NO CIRCUMSTANCES AND UNDER NO
+      LEGAL THEORY, WHETHER TORT (INCLUDING NEGLIGENCE), CONTRACT, OR
+      OTHERWISE, SHALL YOU, THE INITIAL DEVELOPER, ANY OTHER CONTRIBUTOR, OR
+      ANY DISTRIBUTOR OF COVERED CODE, OR ANY SUPPLIER OF ANY OF SUCH PARTIES,
+      BE LIABLE TO ANY PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR
+      CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION,
+      DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR
+      MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF
+      SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.
+      THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR
+      PERSONAL INJURY RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT
+      APPLICABLE LAW PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT
+      ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL
+      DAMAGES, SO THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.</para>
+
+      <para>10. U.S. GOVERNMENT END USERS. The Covered Code is a "commercial
+      item," as that term is defined in 48 C.F.R. 2.101 (Oct. 1995),
+      consisting of "commercial computer software" and "commercial computer
+      software documentation," as such terms are used in 48 C.F.R. 12.212
+      (Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1
+      through 227.7202-4 (June 1995), all U.S. Government End Users acquire
+      Covered Code with only those rights set forth herein.</para>
+
+      <para>11. MISCELLANEOUS. This License represents the complete agreement
+      concerning subject matter hereof. If any provision of this License is
+      held to be unenforceable, such provision shall be reformed only to the
+      extent necessary to make it enforceable. This License shall be governed
+      by California law provisions (except to the extent applicable law, if
+      any, provides otherwise), excluding its conflict-of-law provisions. With
+      respect to disputes in which at least one party is a citizen of, or an
+      entity chartered or registered to do business in the United States of
+      America, any litigation relating to this License shall be subject to the
+      jurisdiction of the Federal Courts of the Northern District of
+      California, with venue lying in Santa Clara County, California, with the
+      losing party responsible for costs, including without limitation, court
+      costs and reasonable attorneys' fees and expenses. The application of
+      the United Nations Convention on Contracts for the International Sale of
+      Goods is expressly excluded. Any law or regulation which provides that
+      the language of a contract shall be construed against the drafter shall
+      not apply to this License.</para>
+
+      <para>12. RESPONSIBILITY FOR CLAIMS. As between Initial Developer and
+      the Contributors, each party is responsible for claims and damages
+      arising, directly or indirectly, out of its utilization of rights under
+      this License and You agree to work with Initial Developer and
+      Contributors to distribute such responsibility on an equitable basis.
+      Nothing herein is intended or shall be deemed to constitute any
+      admission of liability.</para>
+
+      <para>13. MULTIPLE-LICENSED CODE. Initial Developer may designate
+      portions of the Covered Code as "Multiple-Licensed". "Multiple-Licensed"
+      means that the Initial Developer permits you to utilize portions of the
+      Covered Code under Your choice of the NPL or the alternative licenses,
+      if any, specified by the Initial Developer in the file described in
+      Exhibit A.</para>
+
+      <para>EXHIBIT A -Mozilla Public License.</para>
+
+      <para>``The contents of this file are subject to the Mozilla Public
+      License Version 1.1 (the "License"); you may not use this file except in
+      compliance with the License. You may obtain a copy of the License at
+      http://www.mozilla.org/MPL/</para>
+
+      <para>Software distributed under the License is distributed on an "AS
+      IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.</para>
+
+      <para>The Original Code is
+      ______________________________________.</para>
+
+      <para>The Initial Developer of the Original Code is
+      ________________________. Portions created by ______________________ are
+      Copyright (C) ______ _______________________. All Rights
+      Reserved.</para>
+
+      <para>Contributor(s): ______________________________________.</para>
+
+      <para>Alternatively, the contents of this file may be used under the
+      terms of the _____ license (the "[___] License"), in which case the
+      provisions of [______] License are applicable instead of those above. If
+      you wish to allow use of your version of this file only under the terms
+      of the [____] License and not to allow others to use your version of
+      this file under the MPL, indicate your decision by deleting the
+      provisions above and replace them with the notice and other provisions
+      required by the [___] License. If you do not delete the provisions
+      above, a recipient may use your version of this file under either the
+      MPL or the [___] License."</para>
+
+      <para>[NOTE: The text of this Exhibit A may differ slightly from the
+      text of the notices in the Source Code files of the Original Code. You
+      should use the text of this Exhibit A rather than the text found in the
+      Original Code Source Code for Your Modifications.]</para>
+    </sect2>
+
+    <sect2 id="licMIT">
+      <title>MIT License</title>
+
+      <para>Permission is hereby granted, free of charge, to any person
+      obtaining a copy of this software and associated documentation files
+      (the "Software"), to deal in the Software without restriction, including
+      without limitation the rights to use, copy, modify, merge, publish,
+      distribute, sublicense, and/or sell copies of the Software, and to
+      permit persons to whom the Software is furnished to do so, subject to
+      the following conditions:</para>
+
+      <para>The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Software.</para>
+
+      <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+      IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+      CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+      TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+      SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para>
+    </sect2>
+
+    <sect2 id="licX11">
+      <title>X Consortium License (X11)</title>
+
+      <para>Permission is hereby granted, free of charge, to any person
+      obtaining a copy of this software and associated documentation files
+      (the "Software"), to deal in the Software without restriction, including
+      without limitation the rights to use, copy, modify, merge, publish,
+      distribute, sublicense, and/or sell copies of the Software, and to
+      permit persons to whom the Software is furnished to do so, subject to
+      the following conditions:</para>
+
+      <para>The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Software.</para>
+
+      <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+      IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+      CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+      TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+      SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para>
+    </sect2>
+
+    <sect2 id="licZLIB">
+      <title>zlib license</title>
+
+      <para>This software is provided 'as-is', without any express or implied
+      warranty. In no event will the authors be held liable for any damages
+      arising from the use of this software.</para>
+
+      <para>Permission is granted to anyone to use this software for any
+      purpose, including commercial applications, and to alter it and
+      redistribute it freely, subject to the following restrictions:</para>
+
+      <para>1. The origin of this software must not be misrepresented; you
+      must not claim that you wrote the original software. If you use this
+      software in a product, an acknowledgment in the product documentation
+      would be appreciated but is not required.</para>
+
+      <para>2. Altered source versions must be plainly marked as such, and
+      must not be misrepresented as being the original software.</para>
+
+      <para>3. This notice may not be removed or altered from any source
+      distribution.</para>
+
+      <screen>Jean-loup Gailly        Mark Adler
+jloup@gzip.org          madler@alumni.caltech.edu</screen>
+    </sect2>
+
+    <sect2 id="licSSL">
+      <title>OpenSSL license</title>
+
+      <para>This package is an SSL implementation written by Eric Young
+      (eay@cryptsoft.com). The implementation was written so as to conform
+      with Netscape's SSL.</para>
+
+      <para>This library is free for commercial and non-commercial use as long
+      as the following conditions are adhered to. The following conditions
+      apply to all code found in this distribution, be it the RC4, RSA, lhash,
+      DES, etc., code; not just the SSL code. The SSL documentation included
+      with this distribution is covered by the same copyright terms except
+      that the holder is Tim Hudson (tjh@cryptsoft.com).</para>
+
+      <para>Copyright remains Eric Young's, and as such any Copyright notices
+      in the code are not to be removed. If this package is used in a product,
+      Eric Young should be given attribution as the author of the parts of the
+      library used. This can be in the form of a textual message at program
+      startup or in documentation (online or textual) provided with the
+      package.</para>
+
+      <para>Redistribution and use in source and binary forms, with or without
+      modification, are permitted provided that the following conditions are
+      met:</para>
+
+      <para>1. Redistributions of source code must retain the copyright
+      notice, this list of conditions and the following disclaimer.</para>
+
+      <para>2. Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following disclaimer
+      in the documentation and/or other materials provided with the
+      distribution.</para>
+
+      <para>3. All advertising materials mentioning features or use of this
+      software must display the following acknowledgement: "This product
+      includes cryptographic software written by Eric Young
+      (eay@cryptsoft.com)" The word 'cryptographic' can be left out if the
+      routines from the library being used are not cryptographic related
+      :-).</para>
+
+      <para>4. If you include any Windows specific code (or a derivative
+      thereof) from the apps directory (application code) you must include an
+      acknowledgement: "This product includes software written by Tim Hudson
+      (tjh@cryptsoft.com)"</para>
+
+      <para>THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS
+      OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+      DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+      ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+      DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+      OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+      ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+      POSSIBILITY OF SUCH DAMAGE.</para>
+
+      <para>The licence and distribution terms for any publicly available
+      version or derivative of this code cannot be changed. i.e. this code
+      cannot simply be copied and put under another distribution licence
+      [including the GNU Public Licence.]</para>
+    </sect2>
+
+    <sect2 id="licSlirp">
+      <title>Slirp license</title>
+
+      <para>Redistribution and use in source and binary forms, with or without
+      modification, are permitted provided that the following conditions are
+      met:</para>
+
+      <para>1. Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.</para>
+
+      <para>2. Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following disclaimer
+      in the documentation and/or other materials provided with the
+      distribution.</para>
+
+      <para>3. All advertising materials mentioning features or use of this
+      software must display the following acknowledgment: This product
+      includes software developed by Danny Gasparovski.</para>
+
+      <para>THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
+      WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+      MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+      NO EVENT SHALL DANNY GASPAROVSKI OR CONTRIBUTORS BE LIABLE FOR ANY
+      DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+      DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+      OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+      ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+      POSSIBILITY OF SUCH DAMAGE.</para>
+    </sect2>
+
+    <sect2 id="licLZF">
+      <title>liblzf license</title>
+
+      <para>Redistribution and use in source and binary forms, with or without
+      modification, are permitted provided that the following conditions are
+      met:</para>
+
+      <para>1. Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.</para>
+
+      <para>2. Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following disclaimer
+      in the documentation and/or other materials provided with the
+      distribution.</para>
+
+      <para>3. The name of the author may not be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.</para>
+
+      <para>THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
+      OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+      DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+      ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+      POSSIBILITY OF SUCH DAMAGE.</para>
+    </sect2>
+
+    <sect2>
+      <title>libpng license</title>
+
+      <para>The PNG Reference Library is supplied "AS IS". The Contributing
+      Authors and Group 42, Inc. disclaim all warranties, expressed or
+      implied, including, without limitation, the warranties of
+      merchantability and of fitness for any purpose. The Contributing Authors
+      and Group 42, Inc. assume no liability for direct, indirect, incidental,
+      special, exemplary, or consequential damages, which may result from the
+      use of the PNG Reference Library, even if advised of the possibility of
+      such damage.</para>
+
+      <para>Permission is hereby granted to use, copy, modify, and distribute
+      this source code, or portions hereof, for any purpose, without fee,
+      subject to the following restrictions:</para>
+
+      <para>1. The origin of this source code must not be
+      misrepresented.</para>
+
+      <para>2. Altered versions must be plainly marked as such and must not be
+      misrepresented as being the original source.</para>
+
+      <para>3. This Copyright notice may not be removed or altered from any
+      source or altered source distribution.</para>
+
+      <para>The Contributing Authors and Group 42, Inc. specifically permit,
+      without fee, and encourage the use of this source code as a component to
+      supporting the PNG file format in commercial products. If you use this
+      source code in a product, acknowledgment is not required but would be
+      appreciated.</para>
+    </sect2>
+
+    <sect2 id="licLWIP">
+      <title>lwIP license</title>
+
+      <para>Redistribution and use in source and binary forms, with or without
+      modification, are permitted provided that the following conditions are
+      met:</para>
+
+      <para>1. Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.</para>
+
+      <para>2. Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following disclaimer
+      in the documentation and/or other materials provided with the
+      distribution.</para>
+
+      <para>3. The name of the author may not be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.</para>
+
+      <para>THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
+      OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+      DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+      ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+      POSSIBILITY OF SUCH DAMAGE.</para>
+    </sect2>
+
+    <sect2 id="licLibXML">
+      <title>libxml license</title>
+
+      <para>Except where otherwise noted in the source code (e.g. the files
+      hash.c, list.c and the trio files, which are covered by a similar
+      licence but with different Copyright notices) all the files are:</para>
+
+      <para>Copyright (C) 1998-2003 Daniel Veillard. All Rights
+      Reserved.</para>
+
+      <para>Permission is hereby granted, free of charge, to any person
+      obtaining a copy of this software and associated documentation files
+      (the "Software"), to deal in the Software without restriction, including
+      without limitation the rights to use, copy, modify, merge, publish,
+      distribute, sublicense, and/or sell copies of the Software, and to
+      permit persons to whom the Software is furnished to do so, subject to
+      the following conditions:</para>
+
+      <para>The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Software.</para>
+
+      <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+      IN NO EVENT SHALL THE DANIEL VEILLARD BE LIABLE FOR ANY CLAIM, DAMAGES
+      OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+      ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+      OTHER DEALINGS IN THE SOFTWARE.</para>
+
+      <para>Except as contained in this notice, the name of Daniel Veillard
+      shall not be used in advertising or otherwise to promote the sale, use
+      or other dealings in this Software without prior written authorization
+      from him.</para>
+    </sect2>
+
+    <sect2 id="licLibXSLT">
+      <title>libxslt licenses</title>
+
+      <para>Licence for libxslt except libexslt:</para>
+
+      <para>Copyright (C) 2001-2002 Daniel Veillard. All Rights
+      Reserved.</para>
+
+      <para>Permission is hereby granted, free of charge, to any person
+      obtaining a copy of this software and associated documentation files
+      (the "Software"), to deal in the Software without restriction, including
+      without limitation the rights to use, copy, modify, merge, publish,
+      distribute, sublicense, and/or sell copies of the Software, and to
+      permit persons to whom the Software is furnished to do so, subject to
+      the following conditions:</para>
+
+      <para>The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Software.</para>
+
+      <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+      IN NO EVENT SHALL THE DANIEL VEILLARD BE LIABLE FOR ANY CLAIM, DAMAGES
+      OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+      ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+      OTHER DEALINGS IN THE SOFTWARE.</para>
+
+      <para>Except as contained in this notice, the name of Daniel Veillard
+      shall not be used in advertising or otherwise to promote the sale, use
+      or other dealings in this Software without prior written authorization
+      from him.</para>
+
+      <para>Licence for libexslt:</para>
+
+      <para>Copyright (C) 2001-2002 Thomas Broyer, Charlie Bozeman and Daniel
+      Veillard. All Rights Reserved.</para>
+
+      <para>Permission is hereby granted, free of charge, to any person
+      obtaining a copy of this software and associated documentation files
+      (the "Software"), to deal in the Software without restriction, including
+      without limitation the rights to use, copy, modify, merge, publish,
+      distribute, sublicense, and/or sell copies of the Software, and to
+      permit persons to whom the Software is furnished to do so, subject to
+      the following conditions:</para>
+
+      <para>The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Software.</para>
+
+      <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+      IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+      LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+      FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+      DEALINGS IN THE SOFTWARE.</para>
+
+      <para>Except as contained in this notice, the name of the authors shall
+      not be used in advertising or otherwise to promote the sale, use or
+      other dealings in this Software without prior written authorization from
+      him.</para>
+    </sect2>
+
+    <sect2 id="licgSOAP">
+      <title>gSOAP Public License Version 1.3a</title>
+
+      <para>The gSOAP public license is derived from the Mozilla Public
+      License (MPL1.1). The sections that were deleted from the original
+      MPL1.1 text are 1.0.1, 2.1.(c),(d), 2.2.(c),(d), 8.2.(b), 10, and 11.
+      Section 3.8 was added. The modified sections are 2.1.(b), 2.2.(b), 3.2
+      (simplified), 3.5 (deleted the last sentence), and 3.6
+      (simplified).</para>
+
+      <para>1 DEFINITIONS</para>
+
+      <para>1.1. "Contributor" means each entity that creates or contributes
+      to the creation of Modifications.</para>
+
+      <para>1.2. "Contributor Version" means the combination of the Original
+      Code, prior Modifications used by a Contributor, and the Modifications
+      made by that particular Contributor.</para>
+
+      <para>1.3. "Covered Code" means the Original Code, or Modifications or
+      the combination of the Original Code, and Modifications, in each case
+      including portions thereof.</para>
+
+      <para>1.4. "Electronic Distribution Mechanism" means a mechanism
+      generally accepted in the software development community for the
+      electronic transfer of data.</para>
+
+      <para>1.5. "Executable" means Covered Code in any form other than Source
+      Code.</para>
+
+      <para>1.6. "Initial Developer" means the individual or entity identified
+      as the Initial Developer in the Source Code notice required by Exhibit
+      A.</para>
+
+      <para>1.7. "Larger Work" means a work which combines Covered Code or
+      portions thereof with code not governed by the terms of this
+      License.</para>
+
+      <para>1.8. "License" means this document.</para>
+
+      <para>1.8.1. "Licensable" means having the right to grant, to the
+      maximum extent possible, whether at the time of the initial grant or
+      subsequently acquired, any and all of the rights conveyed herein.</para>
+
+      <para>1.9. "Modifications" means any addition to or deletion from the
+      substance or structure of either the Original Code or any previous
+      Modifications. When Covered Code is released as a series of files, a
+      Modification is:</para>
+
+      <para>A. Any addition to or deletion from the contents of a file
+      containing Original Code or previous Modifications.</para>
+
+      <para>B. Any new file that contains any part of the Original Code, or
+      previous Modifications.</para>
+
+      <para>1.10. "Original Code" means Source Code of computer software code
+      which is described in the Source Code notice required by Exhibit A as
+      Original Code, and which, at the time of its release under this License
+      is not already Covered Code governed by this License.</para>
+
+      <para>1.10.1. "Patent Claims" means any patent claim(s), now owned or
+      hereafter acquired, including without limitation, method, process, and
+      apparatus claims, in any patent Licensable by grantor.</para>
+
+      <para>1.11. "Source Code" means the preferred form of the Covered Code
+      for making modifications to it, including all modules it contains, plus
+      any associated interface definition files, scripts used to control
+      compilation and installation of an Executable, or source code
+      differential comparisons against either the Original Code or another
+      well known, available Covered Code of the Contributor's choice. The
+      Source Code can be in a compressed or archival form, provided the
+      appropriate decompression or de-archiving software is widely available
+      for no charge.</para>
+
+      <para>1.12. "You" (or "Your") means an individual or a legal entity
+      exercising rights under, and complying with all of the terms of, this
+      License or a future version of this License issued under Section 6.1.
+      For legal entities, "You" includes any entity which controls, is
+      controlled by, or is under common control with You. For purposes of this
+      definition, "control" means (a) the power, direct or indirect, to cause
+      the direction or management of such entity, whether by contract or
+      otherwise, or (b) ownership of more than fifty percent (50%) of the
+      outstanding shares or beneficial ownership of such entity.</para>
+
+      <para>2 SOURCE CODE LICENSE.</para>
+
+      <para>2.1. The Initial Developer Grant.</para>
+
+      <para>The Initial Developer hereby grants You a world-wide,
+      royalty-free, non-exclusive license, subject to third party intellectual
+      property claims:</para>
+
+      <para>(a) under intellectual property rights (other than patent or
+      trademark) Licensable by Initial Developer to use, reproduce, modify,
+      display, perform, sublicense and distribute the Original Code (or
+      portions thereof) with or without Modifications, and/or as part of a
+      Larger Work; and</para>
+
+      <para>(b) under patents now or hereafter owned or controlled by Initial
+      Developer, to make, have made, use and sell ("offer to sell and import")
+      the Original Code, Modifications, or portions thereof, but solely to the
+      extent that any such patent is reasonably necessary to enable You to
+      utilize, alone or in combination with other software, the Original Code,
+      Modifications, or any combination or portions thereof.</para>
+
+      <para>(c)</para>
+
+      <para>(d)</para>
+
+      <para>2.2. Contributor Grant.</para>
+
+      <para>Subject to third party intellectual property claims, each
+      Contributor hereby grants You a world-wide, royalty-free, non-exclusive
+      license</para>
+
+      <para>(a) under intellectual property rights (other than patent or
+      trademark) Licensable by Contributor, to use, reproduce, modify,
+      display, perform, sublicense and distribute the Modifications created by
+      such Contributor (or portions thereof) either on an unmodified basis,
+      with other Modifications, as Covered Code and/or as part of a Larger
+      Work; and</para>
+
+      <para>(b) under patents now or hereafter owned or controlled by
+      Contributor, to make, have made, use and sell ("offer to sell and
+      import") the Contributor Version (or portions thereof), but solely to
+      the extent that any such patent is reasonably necessary to enable You to
+      utilize, alone or in combination with other software, the Contributor
+      Version (or portions thereof).</para>
+
+      <para>(c)</para>
+
+      <para>(d)</para>
+
+      <para>3 DISTRIBUTION OBLIGATIONS.</para>
+
+      <para>3.1. Application of License.</para>
+
+      <para>The Modifications which You create or to which You contribute are
+      governed by the terms of this License, including without limitation
+      Section 2.2. The Source Code version of Covered Code may be distributed
+      only under the terms of this License or a future version of this License
+      released under Section 6.1, and You must include a copy of this License
+      with every copy of the Source Code You distribute. You may not offer or
+      impose any terms on any Source Code version that alters or restricts the
+      applicable version of this License or the recipients' rights hereunder.
+      However, You may include an additional document offering the additional
+      rights described in Section 3.5.</para>
+
+      <para>3.2. Availability of Source Code.</para>
+
+      <para>Any Modification created by You will be provided to the Initial
+      Developer in Source Code form and are subject to the terms of the
+      License. 3.3. Description of Modifications.</para>
+
+      <para>You must cause all Covered Code to which You contribute to contain
+      a file documenting the changes You made to create that Covered Code and
+      the date of any change. You must include a prominent statement that the
+      Modification is derived, directly or indirectly, from Original Code
+      provided by the Initial Developer and including the name of the Initial
+      Developer in (a) the Source Code, and (b) in any notice in an Executable
+      version or related documentation in which You describe the origin or
+      ownership of the Covered Code.</para>
+
+      <para>3.4. Intellectual Property Matters.</para>
+
+      <para>(a) Third Party Claims. If Contributor has knowledge that a
+      license under a third party's intellectual property rights is required
+      to exercise the rights granted by such Contributor under Sections 2.1 or
+      2.2, Contributor must include a text file with the Source Code
+      distribution titled "LEGAL" which describes the claim and the party
+      making the claim in sufficient detail that a recipient will know whom to
+      contact. If Contributor obtains such knowledge after the Modification is
+      made available as described in Section 3.2, Contributor shall promptly
+      modify the LEGAL file in all copies Contributor makes available
+      thereafter and shall take other steps (such as notifying appropriate
+      mailing lists or newsgroups) reasonably calculated to inform those who
+      received the Covered Code that new knowledge has been obtained.</para>
+
+      <para>(b) Contributor APIs. If Contributor's Modifications include an
+      application programming interface and Contributor has knowledge of
+      patent licenses which are reasonably necessary to implement that API,
+      Contributor must also include this information in the LEGAL file.</para>
+
+      <para>(c) Representations. Contributor represents that, except as
+      disclosed pursuant to Section 3.4(a) above, Contributor believes that
+      Contributor's Modifications are Contributor's original creation(s)
+      and/or Contributor has sufficient rights to grant the rights conveyed by
+      this License.</para>
+
+      <para>3.5. Required Notices. You must duplicate the notice in Exhibit A
+      in each file of the Source Code. If it is not possible to put such
+      notice in a particular Source Code file due to its structure, then You
+      must include such notice in a location (such as a relevant directory)
+      where a user would be likely to look for such a notice. If You created
+      one or more Modification(s) You may add your name as a Contributor to
+      the notice described in Exhibit A. You must also duplicate this License
+      in any documentation for the Source Code where You describe recipients'
+      rights or ownership rights relating to Covered Code. You may choose to
+      offer, and to charge a fee for, warranty, support, indemnity or
+      liability obligations to one or more recipients of Covered Code.
+      However, You may do so only on Your own behalf, and not on behalf of the
+      Initial Developer or any Contributor.</para>
+
+      <para>3.6. Distribution of Executable Versions. You may distribute
+      Covered Code in Executable form only if the requirements of Section
+      3.1-3.5 have been met for that Covered Code. You may distribute the
+      Executable version of Covered Code or ownership rights under a license
+      of Your choice, which may contain terms different from this License,
+      provided that You are in compliance with the terms of this License and
+      that the license for the Executable version does not attempt to limit or
+      alter the recipient's rights in the Source Code version from the rights
+      set forth in this License. If You distribute the Executable version
+      under a different license You must make it absolutely clear that any
+      terms which differ from this License are offered by You alone, not by
+      the Initial Developer or any Contributor. If you distribute executable
+      versions containing Covered Code as part of a product, you must
+      reproduce the notice in Exhibit B in the documentation and/or other
+      materials provided with the product.</para>
+
+      <para>3.7. Larger Works. You may create a Larger Work by combining
+      Covered Code with other code not governed by the terms of this License
+      and distribute the Larger Work as a single product. In such a case, You
+      must make sure the requirements of this License are fulfilled for the
+      Covered Code.</para>
+
+      <para>3.8. Restrictions. You may not remove any product identification,
+      copyright, proprietary notices or labels from gSOAP.</para>
+
+      <para>4 INABILITY TO COMPLY DUE TO STATUTE OR REGULATION.</para>
+
+      <para>If it is impossible for You to comply with any of the terms of
+      this License with respect to some or all of the Covered Code due to
+      statute, judicial order, or regulation then You must: (a) comply with
+      the terms of this License to the maximum extent possible; and (b)
+      describe the limitations and the code they affect. Such description must
+      be included in the LEGAL file described in Section 3.4 and must be
+      included with all distributions of the Source Code. Except to the extent
+      prohibited by statute or regulation, such description must be
+      sufficiently detailed for a recipient of ordinary skill to be able to
+      understand it.</para>
+
+      <para>5 APPLICATION OF THIS LICENSE.</para>
+
+      <para>This License applies to code to which the Initial Developer has
+      attached the notice in Exhibit A and to related Covered Code.</para>
+
+      <para>6 VERSIONS OF THE LICENSE.</para>
+
+      <para>6.1. New Versions.</para>
+
+      <para>Grantor may publish revised and/or new versions of the License
+      from time to time. Each version will be given a distinguishing version
+      number.</para>
+
+      <para>6.2. Effect of New Versions.</para>
+
+      <para>Once Covered Code has been published under a particular version of
+      the License, You may always continue to use it under the terms of that
+      version. You may also choose to use such Covered Code under the terms of
+      any subsequent version of the License.</para>
+
+      <para>6.3. Derivative Works.</para>
+
+      <para>If You create or use a modified version of this License (which you
+      may only do in order to apply it to code which is not already Covered
+      Code governed by this License), You must (a) rename Your license so that
+      the phrase "gSOAP" or any confusingly similar phrase do not appear in
+      your license (except to note that your license differs from this
+      License) and (b) otherwise make it clear that Your version of the
+      license contains terms which differ from the gSOAP Public License.
+      (Filling in the name of the Initial Developer, Original Code or
+      Contributor in the notice described in Exhibit A shall not of themselves
+      be deemed to be modifications of this License.)</para>
+
+      <para>7 DISCLAIMER OF WARRANTY.</para>
+
+      <para>COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS" BASIS,
+      WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS, IMPLIED OR STATUTORY,
+      INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+      MERCHANTABILITY, OF FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT OF
+      THIRD PARTY INTELLECTUAL PROPERTY RIGHTS, AND ANY WARRANTY THAT MAY
+      ARISE BY REASON OF TRADE USAGE, CUSTOM, OR COURSE OF DEALING. WITHOUT
+      LIMITING THE FOREGOING, YOU ACKNOWLEDGE THAT THE SOFTWARE IS PROVIDED
+      "AS IS" AND THAT THE AUTHORS DO NOT WARRANT THE SOFTWARE WILL RUN
+      UNINTERRUPTED OR ERROR FREE. LIMITED LIABILITY THE ENTIRE RISK AS TO
+      RESULTS AND PERFORMANCE OF THE SOFTWARE IS ASSUMED BY YOU. UNDER NO
+      CIRCUMSTANCES WILL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDIRECT,
+      INCIDENTAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES OF ANY KIND OR NATURE
+      WHATSOEVER, WHETHER BASED ON CONTRACT, WARRANTY, TORT (INCLUDING
+      NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, ARISING OUT OF OR IN ANY WAY
+      RELATED TO THE SOFTWARE, EVEN IF THE AUTHORS HAVE BEEN ADVISED ON THE
+      POSSIBILITY OF SUCH DAMAGE OR IF SUCH DAMAGE COULD HAVE BEEN REASONABLY
+      FORESEEN, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY
+      EXCLUSIVE REMEDY PROVIDED. SUCH LIMITATION ON DAMAGES INCLUDES, BUT IS
+      NOT LIMITED TO, DAMAGES FOR LOSS OF GOODWILL, LOST PROFITS, LOSS OF DATA
+      OR SOFTWARE, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION OR
+      IMPAIRMENT OF OTHER GOODS. IN NO EVENT WILL THE AUTHORS BE LIABLE FOR
+      THE COSTS OF PROCUREMENT OF SUBSTITUTE SOFTWARE OR SERVICES. YOU
+      ACKNOWLEDGE THAT THIS SOFTWARE IS NOT DESIGNED FOR USE IN ON-LINE
+      EQUIPMENT IN HAZARDOUS ENVIRONMENTS SUCH AS OPERATION OF NUCLEAR
+      FACILITIES, AIRCRAFT NAVIGATION OR CONTROL, OR LIFE-CRITICAL
+      APPLICATIONS. THE AUTHORS EXPRESSLY DISCLAIM ANY LIABILITY RESULTING
+      FROM USE OF THE SOFTWARE IN ANY SUCH ON-LINE EQUIPMENT IN HAZARDOUS
+      ENVIRONMENTS AND ACCEPTS NO LIABILITY IN RESPECT OF ANY ACTIONS OR
+      CLAIMS BASED ON THE USE OF THE SOFTWARE IN ANY SUCH ON-LINE EQUIPMENT IN
+      HAZARDOUS ENVIRONMENTS BY YOU. FOR PURPOSES OF THIS PARAGRAPH, THE TERM
+      "LIFE-CRITICAL APPLICATION" MEANS AN APPLICATION IN WHICH THE
+      FUNCTIONING OR MALFUNCTIONING OF THE SOFTWARE MAY RESULT DIRECTLY OR
+      INDIRECTLY IN PHYSICAL INJURY OR LOSS OF HUMAN LIFE. THIS DISCLAIMER OF
+      WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY
+      COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS
+      DISCLAIMER.</para>
+
+      <para>8 TERMINATION.</para>
+
+      <para>8.1.</para>
+
+      <para>This License and the rights granted hereunder will terminate
+      automatically if You fail to comply with terms herein and fail to cure
+      such breach within 30 days of becoming aware of the breach. All
+      sublicenses to the Covered Code which are properly granted shall survive
+      any termination of this License. Provisions which, by their nature, must
+      remain in effect beyond the termination of this License shall
+      survive.</para>
+
+      <para>8.2.</para>
+
+      <para>8.3.</para>
+
+      <para>If You assert a patent infringement claim against Participant
+      alleging that such Participant's Contributor Version directly or
+      indirectly infringes any patent where such claim is resolved (such as by
+      license or settlement) prior to the initiation of patent infringement
+      litigation, then the reasonable value of the licenses granted by such
+      Participant under Sections 2.1 or 2.2 shall be taken into account in
+      determining the amount or value of any payment or license.</para>
+
+      <para>8.4. In the event of termination under Sections 8.1 or 8.2 above,
+      all end user license agreements (excluding distributors and resellers)
+      which have been validly granted by You or any distributor hereunder
+      prior to termination shall survive termination.</para>
+
+      <para>9 LIMITATION OF LIABILITY.</para>
+
+      <para>UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT
+      (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE INITIAL
+      DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE, OR
+      ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY
+      INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER
+      INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK
+      STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER
+      COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY SHALL HAVE BEEN
+      INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS LIMITATION OF
+      LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY
+      RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT APPLICABLE LAW
+      PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION
+      OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS EXCLUSION
+      AND LIMITATION MAY NOT APPLY TO YOU.</para>
+
+      <para>10 U.S. GOVERNMENT END USERS.</para>
+
+      <para>11 MISCELLANEOUS.</para>
+
+      <para>12 RESPONSIBILITY FOR CLAIMS.</para>
+
+      <para>As between Initial Developer and the Contributors, each party is
+      responsible for claims and damages arising, directly or indirectly, out
+      of its utilization of rights under this License and You agree to work
+      with Initial Developer and Contributors to distribute such
+      responsibility on an equitable basis. Nothing herein is intended or
+      shall be deemed to constitute any admission of liability.</para>
+
+      <para>EXHIBIT A.</para>
+
+      <para>"The contents of this file are subject to the gSOAP Public License
+      Version 1.3 (the "License"); you may not use this file except in
+      compliance with the License. You may obtain a copy of the License at
+      <ulink
+      url="http://www.cs.fsu.edu/~engelen/soaplicense.html">http://www.cs.fsu.edu/~engelen/soaplicense.html</ulink>.
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
+      License for the specific language governing rights and limitations under
+      the License.</para>
+
+      <para>The Original Code of the gSOAP Software is: stdsoap.h, stdsoap2.h,
+      stdsoap.c, stdsoap2.c, stdsoap.cpp, stdsoap2.cpp, soapcpp2.h,
+      soapcpp2.c, soapcpp2_lex.l, soapcpp2_yacc.y, error2.h, error2.c,
+      symbol2.c, init2.c, soapdoc2.html, and soapdoc2.pdf, httpget.h,
+      httpget.c, stl.h, stldeque.h, stllist.h, stlvector.h, stlset.h.</para>
+
+      <para>The Initial Developer of the Original Code is Robert A. van
+      Engelen. Portions created by Robert A. van Engelen are Copyright (C)
+      2001-2004 Robert A. van Engelen, Genivia inc. All Rights
+      Reserved.</para>
+
+      <para>Contributor(s): "________________________." [Note: The text of
+      this Exhibit A may differ slightly form the text of the notices in the
+      Source Code files of the Original code. You should use the text of this
+      Exhibit A rather than the text found in the Original Code Source Code
+      for Your Modifications.]</para>
+
+      <para>EXHIBIT B.</para>
+
+      <para>"Part of the software embedded in this product is gSOAP software.
+      Portions created by gSOAP are Copyright (C) 2001-2004 Robert A. van
+      Engelen, Genivia inc. All Rights Reserved. THE SOFTWARE IN THIS PRODUCT
+      WAS IN PART PROVIDED BY GENIVIA INC AND ANY EXPRESS OR IMPLIED
+      WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+      MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+      NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+      INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+      NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+      USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+      ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+      (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+      THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+      DAMAGE."</para>
+    </sect2>
+
+    <sect2 id="licChromium">
+      <title>Chromium licenses</title>
+
+      <sect3>
+        <title>Main license</title>
+
+        <para>Copyright (c) 2002, Stanford University All rights
+        reserved.</para>
+
+        <para>Some portions of Chromium are copyrighted by individiual
+        organizations. Please see the files COPYRIGHT.LLNL and
+        COPYRIGHT.REDHAT for more information.</para>
+
+        <para>Redistribution and use in source and binary forms, with or
+        without modification, are permitted provided that the following
+        conditions are met:<itemizedlist>
+            <listitem>
+              <para>Redistributions of source code must retain the above
+              copyright notice, this list of conditions and the following
+              disclaimer.</para>
+            </listitem>
+
+            <listitem>
+              <para>Redistributions in binary form must reproduce the above
+              copyright notice, this list of conditions and the following
+              disclaimer in the documentation and/or other materials provided
+              with the distribution.</para>
+            </listitem>
+
+            <listitem>
+              <para>Neither the name of Stanford University nor the names of
+              its contributors may be used to endorse or promote products
+              derived from this software without specific prior written
+              permission.</para>
+            </listitem>
+          </itemizedlist></para>
+
+        <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+        CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+        BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+        FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+        COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+        INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+        BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+        OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+        ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+        TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+        USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+        DAMAGE.</para>
+      </sect3>
+
+      <sect3>
+        <title>COPYRIGHT.LLNL file</title>
+
+        <para>This Chromium distribution contains information and code which
+        is covered under the following notice:</para>
+
+        <para>Copyright (c) 2002, The Regents of the University of California.
+        Produced at the Lawrence Livermore National Laboratory For details,
+        contact: Randall Frank (rjfrank@llnl.gov). UCRL-CODE-2002-058 All
+        rights reserved.</para>
+
+        <para>This file is part of Chromium. For details, see accompanying
+        documentation.</para>
+
+        <para>Redistribution and use in source and binary forms, with or
+        without modification, are permitted provided that the following
+        conditions are met:</para>
+
+        <para>Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the disclaimer below.</para>
+
+        <para>Redistributions in binary form must reproduce the above
+        copyright notice, this list of conditions and the disclaimer (as noted
+        below) in the documentation and/or other materials provided with the
+        distribution.</para>
+
+        <para>Neither the name of the UC/LLNL nor the names of its
+        contributors may be used to endorse or promote products derived from
+        this software without specific prior written permission.</para>
+
+        <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+        CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+        BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+        FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+        REGENTS OF THE UNIVERSITY OF CALIFORNIA, THE U.S. DEPARTMENT OF ENERGY
+        OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+        THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+        DAMAGE.</para>
+
+        <para>Additional BSD Notice</para>
+
+        <para>1. This notice is required to be provided under our contract
+        with the U.S. Department of Energy (DOE). This work was produced at
+        the University of California, Lawrence Livermore National Laboratory
+        under Contract No. W-7405-ENG-48 with the DOE.</para>
+
+        <para>2. Neither the United States Government nor the University of
+        California nor any of their employees, makes any warranty, express or
+        implied, or assumes any liability or responsibility for the accuracy,
+        completeness, or usefulness of any information, apparatus, product, or
+        process disclosed, or represents that its use would not infringe
+        privately-owned rights.</para>
+
+        <para>3. Also, reference herein to any specific commercial products,
+        process, or services by trade name, trademark, manufacturer or
+        otherwise does not necessarily constitute or imply its endorsement,
+        recommendation, or favoring by the United States Government or the
+        University of California. The views and opinions of authors expressed
+        herein do not necessarily state or reflect those of the United States
+        Government or the University of California, and shall not be used for
+        advertising or product endorsement purposes.</para>
+      </sect3>
+
+      <sect3>
+        <title>COPYRIGHT.REDHAT file</title>
+
+        <para>This Chromium distribution contains information and code which
+        is covered under the following notice:</para>
+
+        <para>Copyright 2001,2002 Red Hat Inc., Durham, North Carolina.</para>
+
+        <para>All Rights Reserved.</para>
+
+        <para>Permission is hereby granted, free of charge, to any person
+        obtaining a copy of this software and associated documentation files
+        (the "Software"), to deal in the Software without restriction,
+        including without limitation on the rights to use, copy, modify,
+        merge, publish, distribute, sublicense, and/or sell copies of the
+        Software, and to permit persons to whom the Software is furnished to
+        do so, subject to the following conditions:</para>
+
+        <para>The above copyright notice and this permission notice (including
+        the next paragraph) shall be included in all copies or substantial
+        portions of the Software.</para>
+
+        <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+        NON-INFRINGEMENT. IN NO EVENT SHALL RED HAT AND/OR THEIR SUPPLIERS BE
+        LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+        OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+        WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="licLibCurl">
+      <title>curl license</title>
+
+      <para>COPYRIGHT AND PERMISSION NOTICE</para>
+
+      <para>Copyright (c) 1996 - 2009, Daniel Stenberg, daniel@haxx.se.</para>
+
+      <para>All rights reserved.</para>
+
+      <para>Permission to use, copy, modify, and distribute this software for
+      any purpose with or without fee is hereby granted, provided that the
+      above copyright notice and this permission notice appear in all
+      copies.</para>
+
+      <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+      THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+      BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+      ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+      CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+      SOFTWARE.</para>
+
+      <para>Except as contained in this notice, the name of a copyright holder
+      shall not be used in advertising or otherwise to promote the sale, use
+      or other dealings in this Software without prior written authorization
+      of the copyright holder.</para>
+    </sect2>
+
+    <sect2 id="licLibgd">
+      <title>libgd license</title>
+
+      <para>Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
+      2002 by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by
+      the National Institutes of Health.</para>
+
+      <para>Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002 by
+      Boutell.Com, Inc.</para>
+
+      <para>Portions relating to GD2 format copyright 1999, 2000, 2001, 2002
+      Philip Warner.</para>
+
+      <para>Portions relating to PNG copyright 1999, 2000, 2001, 2002 Greg
+      Roelofs.</para>
+
+      <para>Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002 John
+      Ellson (ellson@lucent.com).</para>
+
+      <para>Portions relating to gdft.c copyright 2001, 2002 John Ellson
+      (ellson@lucent.com).</para>
+
+      <para>Portions copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+      Pierre-Alain Joye (pierre@libgd.org).</para>
+
+      <para>Portions relating to JPEG and to color quantization copyright
+      2000, 2001, 2002, Doug Becker and copyright (C) 1994, 1995, 1996, 1997,
+      1998, 1999, 2000, 2001, 2002, Thomas G. Lane. This software is based in
+      part on the work of the Independent JPEG Group. See the file
+      README-JPEG.TXT for more information.</para>
+
+      <para>Portions relating to WBMP copyright 2000, 2001, 2002 Maurice
+      Szmurlo and Johan Van den Brande.</para>
+
+      <para>Permission has been granted to copy, distribute and modify gd in
+      any context without fee, including a commercial application, provided
+      that this notice is present in user-accessible supporting
+      documentation.</para>
+
+      <para>This does not affect your ownership of the derived work itself,
+      and the intent is to assure proper credit for the authors of gd, not to
+      interfere with your productive use of gd. If you have questions, ask.
+      "Derived works" includes all programs that utilize the library. Credit
+      must be given in user-accessible documentation.</para>
+
+      <para>This software is provided "AS IS." The copyright holders disclaim
+      all warranties, either express or implied, including but not limited to
+      implied warranties of merchantability and fitness for a particular
+      purpose, with respect to this code and accompanying
+      documentation.</para>
+
+      <para>Although their code does not appear in gd, the authors wish to
+      thank David Koblas, David Rowley, and Hutchison Avenue Software
+      Corporation for their prior contributions.</para>
+    </sect2>
+
+    <sect2 id="licBsdIntel">
+      <title>BSD license from Intel</title>
+
+      <para>All rights reserved.</para>
+
+      <para>Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:</para>
+      <itemizedlist>
+        <listitem>
+          <para>Redistributions of source code must retain the above copyright
+            notice, this list of conditions and the following disclaimer.</para>
+        </listitem>
+        <listitem>
+          <para>Redistributions in binary form must reproduce the above copyright
+            notice, this list of conditions and the following disclaimer in the
+            documentation and/or other materials provided with the distribution.</para>
+        </listitem>
+        <listitem>
+          <para>Neither the name of the Intel Corporation nor the names of its
+            contributors may be used to endorse or promote products derived from
+            this software without specific prior written permission.</para>
+        </listitem>
+      </itemizedlist>
+      <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+        "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+        TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+        PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
+        BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+        GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+        HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+        LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+        OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+        DAMAGE.</para>
+    </sect2>
+
+    <sect2 id="licJPEG">
+      <title>libjpeg License</title>
+
+      <para>The authors make NO WARRANTY or representation, either express or implied,
+      with respect to this software, its quality, accuracy, merchantability, or
+      fitness for a particular purpose.  This software is provided "AS IS", and you,
+      its user, assume the entire risk as to its quality and accuracy.</para>
+
+      <para>This software is copyright (C) 1991-2010, Thomas G. Lane, Guido Vollbeding.
+      All Rights Reserved except as specified below.</para>
+
+      <para>Permission is hereby granted to use, copy, modify, and distribute this
+      software (or portions thereof) for any purpose, without fee, subject to these
+      conditions:</para>
+      <para>(1) If any part of the source code for this software is distributed, then this
+      README file must be included, with this copyright and no-warranty notice
+      unaltered; and any additions, deletions, or changes to the original files
+      must be clearly indicated in accompanying documentation.</para>
+      <para>(2) If only executable code is distributed, then the accompanying
+      documentation must state that "this software is based in part on the work of
+      the Independent JPEG Group".</para>
+      <para>(3) Permission for use of this software is granted only if the user accepts
+      full responsibility for any undesirable consequences; the authors accept
+      NO LIABILITY for damages of any kind.</para>
+
+      <para>These conditions apply to any software derived from or based on the IJG code,
+      not just to the unmodified library.  If you use our work, you ought to
+      acknowledge us.</para>
+
+      <para>Permission is NOT granted for the use of any IJG author's name or company name
+      in advertising or publicity relating to this software or products derived from
+      it.  This software may be referred to only as "the Independent JPEG Group's
+      software".</para>
+
+      <para>We specifically permit and encourage the use of this software as the basis of
+      commercial products, provided that all warranty or liability claims are
+      assumed by the product vendor.</para>
+
+      <para>ansi2knr.c is included in this distribution by permission of L. Peter Deutsch,
+      sole proprietor of its copyright holder, Aladdin Enterprises of Menlo Park, CA.
+      ansi2knr.c is NOT covered by the above copyright and conditions, but instead
+      by the usual distribution terms of the Free Software Foundation; principally,
+      that you must include source code if you redistribute it.  (See the file
+      ansi2knr.c for full details.)  However, since ansi2knr.c is not needed as part
+      of any program generated from the IJG code, this does not limit you more than
+      the foregoing paragraphs do.</para>
+
+      <para>The Unix configuration script "configure" was produced with GNU Autoconf.
+      It is copyright by the Free Software Foundation but is freely distributable.
+      The same holds for its supporting scripts (config.guess, config.sub,
+      ltmain.sh).  Another support script, install-sh, is copyright by X Consortium
+      but is also freely distributable.</para>
+
+      <para>The IJG distribution formerly included code to read and write GIF files.
+      To avoid entanglement with the Unisys LZW patent, GIF reading support has
+      been removed altogether, and the GIF writer has been simplified to produce
+      "uncompressed GIFs".  This technique does not use the LZW algorithm; the
+      resulting GIF files are larger than usual, but are readable by all standard
+      GIF decoders.</para>
+
+      <para>We are required to state that</para>
+      <para>"The Graphics Interchange Format(c) is the Copyright property of
+      CompuServe Incorporated.  GIF(sm) is a Service Mark property of
+      CompuServe Incorporated."</para>
+    </sect2>
+
+    <sect2 id="licJPEGSIMD">
+      <title>x86 SIMD extension for IJG JPEG library license</title>
+
+      <para>Copyright 2009 Pierre Ossman &lt;ossman@cendio.se&gt; for Cendio AB</para>
+      <para>Copyright 2010 D. R. Commander</para>
+
+      <para>Based on</para>
+      <para>x86 SIMD extension for IJG JPEG library - version 1.02</para>
+
+      <para>Copyright (C) 1999-2006, MIYASAKA Masaru.</para>
+
+      <para>This software is provided 'as-is', without any express or implied
+      warranty.  In no event will the authors be held liable for any damages
+      arising from the use of this software.</para>
+
+      <para>Permission is granted to anyone to use this software for any purpose,
+      including commercial applications, and to alter it and redistribute it
+      freely, subject to the following restrictions:</para>
+
+      <para>1. The origin of this software must not be misrepresented; you must not
+         claim that you wrote the original software. If you use this software
+         in a product, an acknowledgment in the product documentation would be
+         appreciated but is not required.</para>
+      <para>2. Altered source versions must be plainly marked as such, and must not be
+         misrepresented as being the original software.</para>
+      <para>3. This notice may not be removed or altered from any source distribution.</para>
+    </sect2>
+
+  </sect1>
+</appendix>
Index: trunk/doc/manual/fr_FR/user_Troubleshooting.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_Troubleshooting.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_Troubleshooting.xml	(revision 33555)
@@ -0,0 +1,1217 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="Troubleshooting">
+  <title>Troubleshooting</title>
+
+  <para>This chapter provides answers to commonly asked questions. In order to
+  improve your user experience with VirtualBox, it is recommended to read this
+  section to learn more about common pitfalls and get recommendations on how
+  to use the product.</para>
+
+  <sect1>
+    <title>Procedures and tools</title>
+
+    <sect2>
+      <title>Categorizing and isolating problems</title>
+
+      <para>More often than not, a virtualized guest behaves like a physical
+      system. Any problems that a physical machine would encounter, a virtual
+      machine will encounter as well. If, for example, Internet connectivity
+      is lost due to external issues, virtual machines will be affected just
+      as much as physical ones.</para>
+
+      <para>If a true VirtualBox problem is encountered, it helps to
+      categorize and isolate the problem first. Here are some of the questions
+      that should be answered before reporting a problem:<orderedlist>
+          <listitem>
+            <para>Is the problem specific to a certain guest OS? Specific
+            release of a guest OS? Especially with Linux guest related
+            problems, the issue may be specific to a certain distribution and
+            version of Linux.</para>
+          </listitem>
+
+          <listitem>
+            <para>Is the problem specific to a certain host OS? Problems are
+            usually not host OS specific (because most of the VirtualBox code
+            base is shared across all supported platforms), but especially in
+            the areas of networking and USB support, there are significant
+            differences between host platforms. Some GUI related issues are
+            also host specific.</para>
+          </listitem>
+
+          <listitem>
+            <para>Is the problem specific to certain host hardware? This
+            category of issues is typically related to the host CPU. Because
+            of significant differences between VT-x and AMD-V, problems may be
+            specific to one or the other technology. The exact CPU model may
+            also make a difference (even for software virtualization) because
+            different CPUs support different features, which may affect
+            certain aspects of guest CPU operation.</para>
+          </listitem>
+
+          <listitem>
+            <para>Is the problem specific to a certain virtualization mode?
+            Some problems may only occur in software virtualization mode,
+            others may be specific to hardware virtualization.</para>
+          </listitem>
+
+          <listitem>
+            <para>Is the problem specific to guest SMP? That is, is it related
+            to the number of virtual CPUs (VCPUs) in the guest? Using more
+            than one CPU usually significantly affects the internal operation
+            of a guest OS.</para>
+          </listitem>
+
+          <listitem>
+            <para>Is the problem specific to the Guest Additions? In some
+            cases, this is a given (e.g., a shared folders problem), in other
+            cases it may be less obvious (for example, display problems). And
+            if the problem is Guest Additions specific, is it also specific to
+            a certain version of the Additions?</para>
+          </listitem>
+
+          <listitem>
+            <para>Is the problem specific to a certain environment? Some
+            problems are related to a particular environment external to the
+            VM; this usually involves network setup. Certain configurations of
+            external servers such as DHCP or PXE may expose problems which do
+            not occur with other, similar servers.</para>
+          </listitem>
+
+          <listitem>
+            <para>Is the problem a regression? Knowing that an issue is a
+            regression usually makes it significantly easier to find the
+            solution. In this case, it is crucial to know which version is
+            affected and which is not.</para>
+          </listitem>
+        </orderedlist></para>
+    </sect2>
+
+    <sect2>
+      <title>Collecting debugging information</title>
+
+      <para>For problem determination, it is often important to collect
+      debugging information which can be analyzed by VirtualBox support. This
+      section contains information about what kind of information can be
+      obtained.</para>
+
+      <para>Every time VirtualBox starts up a VM, a so-called <emphasis
+      role="bold">"release log file"</emphasis> is created containing lots of
+      information about the VM configuration and runtime events. The log file
+      is called <computeroutput><literal>VBox.log</literal></computeroutput>
+      and resides in the VM log file folder. Typically this will be a
+      directory like this:<screen>$HOME/.VirtualBox/Machines/{machinename}/Logs</screen>When
+      starting a VM, the configuration file of the last run will be renamed to
+      <computeroutput>.1</computeroutput>, up to
+      <computeroutput>.3</computeroutput>. Sometimes when there is a problem,
+      it is useful to have a look at the logs. Also when requesting support
+      for VirtualBox, supplying the corresponding log file is
+      mandatory.</para>
+
+      <para>For convenience, for each virtual machine, the VirtualBox main
+      window can show these logs in a window. To access it, select a virtual
+      machine from the list on the left and select "Show logs..." from the
+      "Machine" window.</para>
+
+      <para>The release log file (VBox.log) contains a wealth of diagnostic
+      information, such as Host OS type and version, VirtualBox version and
+      build (32-bit or 64-bit), a complete dump of the guest's configuration
+      (CFGM), detailed information about the host CPU type and supported
+      features, whether hardware virtualization is enabled, information about
+      VT-x/AMD-V setup, state transitions (creating, running, paused,
+      stopping, etc.), guest BIOS messages, guest Additions messages, device
+      specific log entries and at the end of execution, final guest state and
+      condensed statistics.</para>
+
+      <para>In case of crashes, it is very important to collect <emphasis
+      role="bold">crash dumps</emphasis>. This is true for both host and guest
+      crashes. For information about enabling core dumps on Linux, Solaris,
+      and OS X systems, refer to the core dump article on the VirtualBox
+      website.<footnote>
+          <para><ulink
+          url="http://www.virtualbox.org/wiki/Core_dump">http://www.virtualbox.org/wiki/Core_dump</ulink>.</para>
+        </footnote></para>
+
+      <para>For network related problems, it is often helpful to capture a
+      trace of network traffic. If the traffic is routed through an adapter on
+      the host, it is possible to use Wireshark or a similar tool to capture
+      the traffic there. However, this often also includes a lot of traffic
+      unrelated to the VM.</para>
+
+      <para>VirtualBox provides an ability to capture network traffic only on
+      a specific VM's network adapter. Refer to the network tracing article on
+      the VirtualBox website<footnote>
+          <para><ulink
+          url="http://www.virtualbox.org/wiki/Network_tips">http://www.virtualbox.org/wiki/Network_tips</ulink>.</para>
+        </footnote> for information on enabling this capture. Note that the
+      trace files created by VirtualBox are in .pcap format and can be easily
+      analyzed with Wireshark.</para>
+    </sect2>
+
+    <sect2>
+      <title>The built-in VM debugger</title>
+
+      <para>VirtualBox includes a built-in VM debugger, which advanced users
+      may find useful. This debugger allows the user to examine, and to some
+      extent, control, the VM state.<note>
+          <para>Use the VM debugger at your own risk. There is no support for
+          it, and the following documentation is only made available for
+          advanced users with a very high level of familiarity with the
+          x86/AMD64 machine instruction set, as well as detailed knowledge of
+          the PC architecture. A degree of familiarity with the internals of
+          the guest OS in question is not required, but may be very
+          helpful.</para>
+        </note></para>
+
+      <para>The VM debugger is available in all regular production versions of
+      VirtualBox, but it is disabled by default because the average user will
+      have little use for it. There are two ways to access the
+      debugger:<itemizedlist>
+          <listitem>
+            <para>A debugger console window displayed alongside the VM</para>
+          </listitem>
+
+          <listitem>
+            <para>Via the <computeroutput>telnet</computeroutput> protocol at
+            port 5000</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>The debugger can be enabled in three ways:<itemizedlist>
+          <listitem>
+            <para>Start the <computeroutput>VirtualBox</computeroutput>
+            process with a <computeroutput>--dbg</computeroutput>,
+            <computeroutput>--debug</computeroutput>, or
+            <computeroutput>--debug-command-line</computeroutput> argument.
+            See the VirtualBox usage help for details. Note that these
+            arguments are only useful when a VM is started immediately, using
+            the <computeroutput>--startvm</computeroutput> argument.</para>
+          </listitem>
+
+          <listitem>
+            <para>Set the
+            <computeroutput>VBOX_GUI_DBG_ENABLED</computeroutput> or
+            <computeroutput>VBOX_GUI_DBG_AUTO_SHOW</computeroutput>
+            environment variable to <computeroutput>true</computeroutput>
+            before launching the VirtualBox process. Setting these variables
+            (only their presence is checked) is effective even when the first
+            VirtualBox process is the VM selector window. VMs subsequently
+            launched from the selector will have the debugger enabled.</para>
+          </listitem>
+
+          <listitem>
+            <para>Set the <computeroutput>GUI/Dbg/Enabled</computeroutput>
+            extra data item to <computeroutput>true</computeroutput> before
+            launching the VM. This can be set globally or on a per VM
+            basis.</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>A new 'Debug' menu entry will be added to the VirtualBox
+      application. This menu allows the user to open the debugger
+      console.</para>
+
+      <para>The VM debugger command syntax is loosely modeled on Microsoft and
+      IBM debuggers used on DOS, OS/2 and Windows. Users familiar with symdeb,
+      CodeView, or the OS/2 kernel debugger will find the VirtualBox VM
+      debugger familiar.</para>
+
+      <para>The most important command is
+      <computeroutput>help</computeroutput>. This will print brief usage help
+      for all debugger commands. The set of commands supported by the VM
+      debugger changes frequently and the
+      <computeroutput>help</computeroutput> command is always
+      up-to-date.</para>
+
+      <para>A brief summary of frequently used commands follows:<itemizedlist>
+          <listitem>
+            <para><computeroutput>stop</computeroutput> -- stops the VM
+            execution and enables single stepping</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>g</computeroutput> -- continue VM
+            execution</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>t</computeroutput> -- single step an
+            instruction</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>rg/rh/r</computeroutput> -- print the
+            guest/hypervisor/current registers</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>kg/kh/k</computeroutput> -- print the
+            guest/hypervisor/current call stack</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>da/db/dw/dd/dq</computeroutput> -- print
+            memory contents as ASCII/bytes/words/dwords/qwords</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>u</computeroutput> -- unassemble
+            memory</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>dg</computeroutput> -- print the guest's
+            GDT</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>di</computeroutput> -- print the guest's
+            IDT</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>dl</computeroutput> -- print the guest's
+            LDT</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>dt</computeroutput> -- print the guest's
+            TSS</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>dp*</computeroutput> -- print the guest's
+            page table structures</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>bp/br</computeroutput> -- set a
+            normal/recompiler breakpoint</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>bl</computeroutput> -- list
+            breakpoints</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>bc</computeroutput> -- clear a
+            breakpoint</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>writecore</computeroutput> -- writes a VM
+            core file to disk, refer <xref linkend="guestcoreformat" />
+            </para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>See the built-in <computeroutput>help</computeroutput> for other
+      available commands.</para>
+
+      <para>The VM debugger supports symbolic debugging, although symbols for
+      guest code are often not available. For Solaris guests, the
+      <computeroutput>detect</computeroutput> command automatically determines
+      the guest OS version and locates kernel symbols in guest's memory.
+      Symbolic debugging is then available. For Linux guests, the
+      <computeroutput>detect</computeroutput> commands also determines the
+      guest OS version, but there are no symbols in the guest's memory. Kernel
+      symbols are available in the file
+      <computeroutput>/proc/kallsyms</computeroutput> on Linux guests. This
+      file must be copied to the host, for example using
+      <computeroutput>scp</computeroutput>. The
+      <computeroutput>loadmap</computeroutput> debugger command can be used to
+      make the symbol information available to the VM debugger. Note that the
+      <computeroutput>kallsyms</computeroutput> file contains the symbols for
+      the currently loaded modules; if the guest's configuration changes, the
+      symbols will change as well and must be updated.</para>
+
+      <para>For all guests, a simple way to verify that the correct symbols
+      are loaded is the <computeroutput>k</computeroutput> command. The guest
+      is normally idling and it should be clear from the symbolic information
+      that the guest operating system's idle loop is being executed.</para>
+
+      <para>Another group of debugger commands is the set of
+      <computeroutput>info</computeroutput> commands. Running
+      <computeroutput>info help</computeroutput> provides complete usage
+      information. The information commands provide ad-hoc data pertinent to
+      various emulated devices and aspects of the VMM. There is no general
+      guideline for using the <computeroutput>info</computeroutput> commands,
+      the right command to use depends entirely on the problem being
+      investigated. Some of the info commands are:<itemizedlist>
+          <listitem>
+            <para><computeroutput>cfgm</computeroutput> -- print a branch of
+            the configuration tree</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>cpuid</computeroutput> -- display the guest
+            CPUID leaves</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>ioport</computeroutput> -- print registered
+            I/O port ranges</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>mmio</computeroutput> -- print registered
+            MMIO ranges</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>mode</computeroutput> -- print the current
+            paging mode</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>pit</computeroutput> -- print the i8254 PIT
+            state</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>pic</computeroutput> -- print the i8259A PIC
+            state</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>ohci/ehci</computeroutput> -- print a subset
+            of the OHCI/EHCI USB controller state</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>pcnet0</computeroutput> -- print the PCnet
+            state</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>vgatext</computeroutput> -- print the
+            contents of the VGA framebuffer formatted as standard text
+            mode</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>timers</computeroutput> -- print all VM
+            timers</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>The output of the <computeroutput>info</computeroutput> commands
+      generally requires in-depth knowledge of the emulated device and/or
+      VirtualBox VMM internals. However, when used properly, the information
+      provided can be invaluable.</para>
+    </sect2>
+
+    <sect2 id="guestcoreformat">
+      <title>VM core format</title>
+
+      <para>VirtualBox uses the 64-bit ELF format for its VM core files. The
+      VM core file contain the memory and CPU dumps of the VM and can be
+      useful for debugging your guest OS. The 64-bit ELF object format
+      specficiation can be obtained here: <literal><ulink
+      url="http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf">http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf</ulink></literal>.</para>
+
+      <para>The overall layout of the VM core format is as follows:</para>
+
+      <para><screen>[ ELF 64 Header]
+[ Program Header, type PT_NOTE ]
+  -&gt; offset to COREDESCRIPTOR
+[ Program Header, type PT_LOAD ] - one for each contiguous physical memory range
+  -&gt; Memory offset of range
+  -&gt; File offset
+[ Note Header, type NT_VBOXCORE ]
+[ COREDESCRIPTOR ]
+  -&gt; Magic
+  -&gt; VM core file version
+  -&gt; VBox version
+  -&gt; Number of vCPUs etc.
+[ Note Header, type NT_VBOXCPU ] - one for each vCPU
+[ vCPU 1 Note Header ]
+  [ CPUMCTX - vCPU 1 dump ]
+[ Additional Notes + Data ] - currently unused
+[ Memory dump ]</screen></para>
+
+      <para>The memory descriptors contain physical addresses relative to the
+      guest and not virtual addresses. Regions of memory such as MMIO regions
+      are not included in the core file.</para>
+
+      <para>The relevant data structures and definitions can be found in the
+      VirtualBox sources under the following header files:
+      <computeroutput>include/VBox/dbgfcorefmt.h</computeroutput>,
+      <computeroutput>include/VBox/cpumctx.h</computeroutput> and
+      <computeroutput>src/VBox/Runtime/include/internal/ldrELFCommon.h</computeroutput>.</para>
+
+      <para>The VM core file can be inspected using
+      <computeroutput>elfdump</computeroutput> and GNU
+      <computeroutput>readelf</computeroutput> or other similar
+      utilities.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>General</title>
+
+    <sect2 id="configPeriodicFlush">
+      <title>Guest shows IDE/SATA errors for file-based images on slow host
+      file system</title>
+
+      <para>Occasionally, some host file systems provide very poor writing
+      performance and as a consequence cause the guest to time out IDE/SATA
+      commands. This is normal behavior and should normally cause no real
+      problems, as the guest should repeat commands that have timed out.
+      However some guests (e.g. some Linux versions) have severe problems if a
+      write to an image file takes longer than about 15 seconds. Some file
+      systems however require more than a minute to complete a single write,
+      if the host cache contains a large amount of data that needs to be
+      written.</para>
+
+      <para>The symptom for this problem is that the guest can no longer
+      access its files during large write or copying operations, usually
+      leading to an immediate hang of the guest.</para>
+
+      <para>In order to work around this problem (the true fix is to use a
+      faster file system that doesn't exhibit such unacceptable write
+      performance), it is possible to flush the image file after a certain
+      amount of data has been written. This interval is normally infinite, but
+      can be configured individually for each disk of a VM.</para>
+
+      <para>For IDE disks use the following command:</para>
+
+      <screen>VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/FlushInterval" [b]</screen>
+
+      <para>For SATA disks use the following command:</para>
+
+      <screen>VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/FlushInterval" [b]</screen>
+
+      <para>The value [x] that selects the disk for IDE is 0 for the master
+      device on the first channel, 1 for the slave device on the first
+      channel, 2 for the master device on the second channel or 3 for the
+      master device on the second channel. For SATA use values between 0 and
+      29. Only disks support this configuration option; it must not be set for
+      CD/DVD drives.</para>
+
+      <para>The unit of the interval [b] is the number of bytes written since
+      the last flush. The value for it must be selected so that the occasional
+      long write delays do not occur. Since the proper flush interval depends
+      on the performance of the host and the host filesystem, finding the
+      optimal value that makes the problem disappear requires some
+      experimentation. Values between 1000000 and 10000000 (1 to 10 megabytes)
+      are a good starting point. Decreasing the interval both decreases the
+      probability of the problem and the write performance of the guest.
+      Setting the value unnecessarily low will cost performance without
+      providing any benefits. An interval of 1 will cause a flush for each
+      write operation and should solve the problem in any case, but has a
+      severe write performance penalty.</para>
+
+      <para>Providing a value of 0 for [b] is treated as an infinite flush
+      interval, effectively disabling this workaround. Removing the extra data
+      key by specifying no value for [b] has the same effect.</para>
+    </sect2>
+
+    <sect2>
+      <title>Responding to guest IDE/SATA flush requests</title>
+
+      <para>If desired, the virtual disk images can be flushed when the guest
+      issues the IDE FLUSH CACHE command. Normally these requests are ignored
+      for improved performance. The parameters below are only accepted for
+      disk drives. They must not be set for DVD drives.</para>
+
+      <para>To enable flushing for IDE disks, issue the following
+      command:</para>
+
+      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/IgnoreFlush" 0</screen>
+
+      <para>The value [x] that selects the disk is 0 for the master device on
+      the first channel, 1 for the slave device on the first channel, 2 for
+      the master device on the second channel or 3 for the master device on
+      the second channel.</para>
+
+      <para>To enable flushing for SATA disks, issue the following
+      command:</para>
+
+      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0</screen>
+
+      <para>The value [x] that selects the disk can be a value between 0 and
+      29.</para>
+
+      <para>Note that this doesn't affect the flushes performed according to
+      the configuration described in <xref linkend="configPeriodicFlush"
+      xrefstyle="template: %n" />. Restoring the default of ignoring flush
+      commands is possible by setting the value to 1 or by removing the
+      key.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Windows guests</title>
+
+    <sect2>
+      <title>Windows bluescreens after changing VM configuration</title>
+
+      <para>Changing certain virtual machine settings can cause Windows guests
+      to fail during start up with a bluescreen. This may happen if you change
+      VM settings after installing Windows, or if you copy a disk image with
+      an already installed Windows to a newly created VM which has settings
+      that differ from the original machine.</para>
+
+      <para>This applies in particular to the following settings:<itemizedlist>
+          <listitem>
+            <para>The ACPI and I/O APIC settings should never be changed after
+            installing Windows. Depending on the presence of these hardware
+            features, the Windows installation program chooses special kernel
+            and device driver versions and will fail to startup should these
+            hardware features be removed. (Enabling them for a Windows VM
+            which was installed without them does not cause any harm. However,
+            Windows will not use these features in this case.)</para>
+          </listitem>
+
+          <listitem>
+            <para>Changing the storage controller hardware will cause bootup
+            failures as well. This might also apply to you if you copy a disk
+            image from an older version of VirtualBox to a virtual machine
+            created with a newer VirtualBox version; the default subtype of
+            IDE controller hardware was changed from PIIX3 to PIIX4 with
+            VirtualBox 2.2. Make sure these settings are identical.</para>
+          </listitem>
+        </itemizedlist></para>
+    </sect2>
+
+    <sect2>
+      <title>Windows 0x101 bluescreens with SMP enabled (IPI timeout)</title>
+
+      <para>If a VM is configured to have more than one processor (symmetrical
+      multiprocessing, SMP), some configurations of Windows guests crash with
+      an 0x101 error message, indicating a timeout for inter-processor
+      interrupts (IPIs). These interrupts synchronize memory management
+      between processors.</para>
+
+      <para>According to Microsoft, this is due to a race condition in
+      Windows. A hotfix is available.<footnote>
+          <para>See <ulink
+          url="http://support.microsoft.com/kb/955076">http://support.microsoft.com/kb/955076</ulink>.</para>
+        </footnote> If this does not help, please reduce the number of virtual
+      processors to 1.</para>
+    </sect2>
+
+    <sect2>
+      <title>Windows 2000 installation failures</title>
+
+      <para>When installing Windows 2000 guests, you might run into one of the
+      following issues:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Installation reboots, usually during component
+          registration.</para>
+        </listitem>
+
+        <listitem>
+          <para>Installation fills the whole hard disk with empty log
+          files.</para>
+        </listitem>
+
+        <listitem>
+          <para>Installation complains about a failure installing
+          <literal>msgina.dll</literal>.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>These problems are all caused by a bug in the hard disk driver of
+      Windows 2000. After issuing a hard disk request, there is a race
+      condition in the Windows driver code which leads to corruption if the
+      operation completes too fast, i.e. the hardware interrupt from the IDE
+      controller arrives too soon. With physical hardware, there is a
+      guaranteed delay in most systems so the problem is usually hidden there
+      (however it should be possible to reproduce it on physical hardware as
+      well). In a virtual environment, it is possible for the operation to be
+      done immediately (especially on very fast systems with multiple CPUs)
+      and the interrupt is signaled sooner than on a physical system. The
+      solution is to introduce an artificial delay before delivering such
+      interrupts. This delay can be configured for a VM using the following
+      command:</para>
+
+      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1</screen>
+
+      <para>This sets the delay to one millisecond. In case this doesn't help,
+      increase it to a value between 1 and 5 milliseconds. Please note that
+      this slows down disk performance. After installation, you should be able
+      to remove the key (or set it to 0).</para>
+    </sect2>
+
+    <sect2>
+      <title>How to record bluescreen information from Windows guests</title>
+
+      <para>When Windows guests run into a kernel crash, they display the
+      infamous bluescreen. Depending on how Windows is configured, the
+      information will remain on the screen until the machine is restarted or
+      it will reboot automatically. During installation, Windows is usually
+      configured to reboot automatically. With automatic reboots, there is no
+      chance to record the bluescreen information which might be important for
+      problem determination.</para>
+
+      <para>VirtualBox provides a method of halting a guest when it wants to
+      perform a reset. In order to enable this feature, issue the following
+      command:</para>
+
+      <para><screen>VBoxManage setextradata "VM name" "VBoxInternal/PDM/HaltOnReset" 1</screen></para>
+    </sect2>
+
+    <sect2>
+      <title>No networking in Windows Vista guests</title>
+
+      <para>Unfortunately, with Vista, Microsoft dropped support for the
+      virtual AMD PCNet card that we are providing to virtual machines. As a
+      result, after installation, Vista guests initially have no networking.
+      VirtualBox therefore ships a driver for that card with the Windows Guest
+      Additions; see <xref linkend="vista_networking" />.</para>
+
+      <para>Starting with version 1.6.0 VirtualBox can emulate an Intel E1000
+      network device which is supported by Vista without any third-party
+      drivers.</para>
+    </sect2>
+
+    <sect2>
+      <title>Windows guests may cause a high CPU load</title>
+
+      <para>Several background applications of Windows guests, especially
+      virus scanners, are known to increases the CPU load notably even if the
+      guest appears to be idle. We recommend to deactivate virus scanners
+      within virtualized guests if possible.</para>
+    </sect2>
+
+    <sect2 id="win7_audio">
+      <title>No audio in Windows Vista (64-bit) and Windows 7 guests</title>
+
+      <para>32-bit Windows 7 does not ship with drivers for our emulated audio
+      hardware (AC'97). However, running Windows Update should solve the
+      problem by getting an appropriate driver for it automatically. After
+      that update followed by a reboot you should have working audio.</para>
+
+      <para>For the 64-bit versions of Windows Vista and 7 you have to
+      download the Realtek AC'97 drivers to enable audio.</para>
+
+      <para>See <ulink
+      url="http://www.realtek.com.tw/downloads">http://www.realtek.com.tw/downloads</ulink>
+      for download instructions.</para>
+    </sect2>
+
+    <sect2>
+      <title>Long delays when accessing shared folders</title>
+
+      <para>The performance for accesses to shared folders from a Windows
+      guest might be decreased due to delays during the resolution of the
+      VirtualBox shared folders name service. To fix these delays, add the
+      following entries to the file
+      <computeroutput>\windows\system32\drivers\etc\lmhosts</computeroutput>
+      of the Windows guest:</para>
+
+      <screen>255.255.255.255        VBOXSVR #PRE
+255.255.255.255        VBOXSRV #PRE</screen>
+
+      <para>After doing this change, a reboot of the guest is required.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Linux and X11 guests</title>
+
+    <sect2>
+      <title>Linux guests may cause a high CPU load</title>
+
+      <para>Some Linux guests may cause a high CPU load even if the guest
+      system appears to be idle. This can be caused by a high timer frequency
+      of the guest kernel. Some Linux distributions, for example Fedora, ship
+      a Linux kernel configured for a timer frequency of <emphasis
+      role="bold"> 1000Hz</emphasis>. We recommend to recompile the guest
+      kernel and to select a timer frequency of 100Hz.</para>
+
+      <para>Linux kernels shipped with Red Hat Enterprise Linux (RHEL) as of
+      release 4.7 and 5.1 as well as kernels of related Linux distributions
+      (for instance CentOS and Oracle Enterprise Linux) support a kernel
+      parameter <emphasis>divider=N</emphasis>. Hence, such kernels support a
+      lower timer frequency without recompilation. We suggest to add the
+      kernel parameter <emphasis>divider=10</emphasis> to select a guest
+      kernel timer frequency of 100Hz.</para>
+    </sect2>
+
+    <sect2>
+      <title>AMD Barcelona CPUs</title>
+
+      <para>Most Linux-based guests will fail with AMD Phenoms or
+      Barcelona-level Opterons due to a bug in the Linux kernel. Enable the
+      I/O-APIC to work around the problem (see <xref
+      linkend="settings-general-advanced" />).</para>
+    </sect2>
+
+    <sect2 id="trouble-linux-buggy">
+      <title>Buggy Linux 2.6 kernel versions</title>
+
+      <para>The following bugs in Linux kernels prevent them from executing
+      correctly in VirtualBox, causing VM boot crashes:<itemizedlist>
+          <listitem>
+            <para>The Linux kernel version 2.6.18 (and some 2.6.17 versions)
+            introduced a race condition that can cause boot crashes in
+            VirtualBox. Please use a kernel version 2.6.19 or later.</para>
+          </listitem>
+
+          <listitem>
+            <para>With hardware virtualization and the I/O APIC enabled,
+            kernels before 2.6.24-rc6 may panic on boot with the following
+            message:<screen>Kernel panic - not syncing: IO-APIC + timer doesn't work!  Boot with
+apic=debug and send a report.  Then try booting with the 'noapic' option</screen></para>
+
+            <para>If you see this message, either disable hardware
+            virtualization or the I/O APIC (see <xref
+            linkend="settings-system" />), or upgrade the guest to a newer
+            kernel.<footnote>
+                <para>See <ulink
+                url="http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html">http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html</ulink>
+                for details about the kernel fix.</para>
+              </footnote></para>
+          </listitem>
+        </itemizedlist></para>
+    </sect2>
+
+    <sect2>
+      <title>Shared clipboard, auto-resizing and seamless desktop in X11
+      guests</title>
+
+      <para>Guest desktop services in guests running the X11 window system
+      (Solaris, Linux and others) are provided by a guest service called
+      <computeroutput>VBoxClient</computeroutput>, which runs under the ID of
+      the user who started the desktop session and is automatically started
+      using the following command lines <screen>VBoxClient --clipboard
+VBoxClient --display
+VBoxClient --seamless</screen> when your X11 user session is started if you
+      are using a common desktop environment (Gnome, KDE and others). If a
+      particular desktop service is not working correctly, it is worth
+      checking whether the process which should provide it is running.</para>
+
+      <para>The <computeroutput>VBoxClient</computeroutput> processes create
+      files in the user's home directory with names of the form
+      <computeroutput>.vboxclient-*.pid</computeroutput> when they are running
+      in order to prevent a given service from being started twice. It can
+      happen due to misconfiguration that these files are created owned by
+      root and not deleted when the services are stopped, which will prevent
+      them from being started in future sessions. If the services cannot be
+      started, you may wish to check whether these files still exist.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Windows hosts</title>
+
+    <sect2>
+      <title>VBoxSVC out-of-process COM server issues</title>
+
+      <para>VirtualBox makes use of the Microsoft Component Object Model (COM)
+      for inter- and intra-process communication. This allows VirtualBox to
+      share a common configuration among different virtual machine processes
+      and provide several user interface options based on a common
+      architecture. All global status information and configuration is
+      maintained by the process <computeroutput>VBoxSVC.exe</computeroutput>,
+      which is an out-of-process COM server. Whenever a VirtualBox process is
+      started, it requests access to the COM server and Windows automatically
+      starts the process. Note that it should never be started by the end
+      user.</para>
+
+      <para>When the last process disconnects from the COM server, it will
+      terminate itself after some seconds. The VirtualBox configuration (XML
+      files) is maintained and owned by the COM server and the files are
+      locked whenever the server runs.</para>
+
+      <para>In some cases - such as when a virtual machine is terminated
+      unexpectedly - the COM server will not notice that the client is
+      disconnected and stay active for a longer period (10 minutes or so)
+      keeping the configuration files locked. In other rare cases the COM
+      server might experience an internal error and subsequently other
+      processes fail to initialize it. In these situations, it is recommended
+      to use the Windows task manager to kill the process
+      <computeroutput>VBoxSVC.exe</computeroutput>.</para>
+    </sect2>
+
+    <sect2>
+      <title>CD/DVD changes not recognized</title>
+
+      <para>In case you have assigned a physical CD/DVD drive to a guest and
+      the guest does not notice when the medium changes, make sure that the
+      Windows media change notification (MCN) feature is not turned off. This
+      is represented by the following key in the Windows registry:<screen><literal>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun</literal></screen>Certain
+      applications may disable this key against Microsoft's advice. If it is
+      set to 0, change it to 1 and reboot your system. VirtualBox relies on
+      Windows notifying it of media changes.</para>
+    </sect2>
+
+    <sect2>
+      <title>Sluggish response when using Microsoft RDP client</title>
+
+      <para>If connecting to a Virtual Machine via the Microsoft RDP client
+      (called Remote Desktop Connection), there can be large delays between
+      input (moving the mouse over a menu is the most obvious situation) and
+      output. This is because this RDP client collects input for a certain
+      time before sending it to the VRDP server built into VirtualBox.</para>
+
+      <para>The interval can be decreased by setting a Windows registry key to
+      smaller values than the default of 100. The key does not exist initially
+      and must be of type DWORD. The unit for its values is milliseconds.
+      Values around 20 are suitable for low-bandwidth connections between the
+      RDP client and server. Values around 4 can be used for a gigabit
+      Ethernet connection. Generally values below 10 achieve a performance
+      that is very close to that of the local input devices and screen of the
+      host on which the Virtual Machine is running.</para>
+
+      <para>Depending whether the setting should be changed for an individual
+      user or for the system, either</para>
+
+      <screen>HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval</screen>
+
+      <para>or</para>
+
+      <screen>HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval</screen>
+
+      <para>can be set appropriately.</para>
+    </sect2>
+
+    <sect2>
+      <title>Running an iSCSI initiator and target on a single system</title>
+
+      <para>Deadlocks can occur on a Windows host when attempting to access an
+      iSCSI target running in a guest virtual machine with an iSCSI initiator
+      (e.g. Microsoft iSCSI Initiator) that is running on the host. This is
+      caused by a flaw in the Windows cache manager component, and causes
+      sluggish host system response for several minutes, followed by a
+      "Delayed Write Failed" error message in the system tray or in a separate
+      message window. The guest is blocked during that period and may show
+      error messages or become unstable.</para>
+
+      <para>Setting the environment variable
+      <computeroutput>VBOX_DISABLE_HOST_DISK_CACHE</computeroutput> to 1 will
+      enable a workaround for this problem until Microsoft addresses the
+      issue. For example, open a command prompt window and start VirtualBox
+      like this:</para>
+
+      <screen>set VBOX_DISABLE_HOST_DISK_CACHE=1
+VirtualBox</screen>
+
+      <para>While this will decrease guest disk performance (especially
+      writes), it does not affect the performance of other applications
+      running on the host.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Linux hosts</title>
+
+    <sect2 id="linuxkernelmodulefailstoload">
+      <title>Linux kernel module refuses to load</title>
+
+      <para>If the VirtualBox kernel module
+      (<computeroutput>vboxdrv</computeroutput>) refuses to load, i.e. you get
+      an "Error inserting vboxdrv: Invalid argument", check (as root) the
+      output of the <computeroutput>dmesg</computeroutput> command to find out
+      why the load failed. The most common reasons are:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>With Linux 2.6.19 and higher, the NMI watchdog may be active.
+          Add <computeroutput>nmi_watchdog=0</computeroutput> to the kernel
+          command line (e.g. in your grub configuration) and reboot. With the
+          Debian and Ubuntu installation modules, execute <computeroutput>sudo
+          dpkg-reconfigure virtualbox</computeroutput> again.</para>
+        </listitem>
+
+        <listitem>
+          <para>The kernel disagrees about the version of the gcc used to
+          compile the module. Make sure that you use the same compiler as used
+          to build the kernel.</para>
+        </listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Linux host CD/DVD drive not found</title>
+
+      <para>If you have configured a virtual machine to use the host's CD/DVD
+      drive, but this does not appear to work, make sure that the current user
+      has permission to access the corresponding Linux device file
+      (<computeroutput>/dev/hdc</computeroutput> or
+      <computeroutput>/dev/scd0</computeroutput> or
+      <computeroutput>/dev/cdrom</computeroutput> or similar). On most
+      distributions, the user must be added to a corresponding group (usually
+      called <computeroutput>cdrom</computeroutput> or
+      <computeroutput>cdrw</computeroutput>).</para>
+    </sect2>
+
+    <sect2>
+      <title>Linux host CD/DVD drive not found (older distributions)</title>
+
+      <para>On older Linux distributions, if your CD/DVD device has a
+      different name, VirtualBox may be unable to find it. On older Linux
+      hosts, VirtualBox performs the following steps to locate your CD/DVD
+      drives:</para>
+
+      <para><orderedlist>
+          <listitem>
+            <para>VirtualBox examines if the environment variable
+            <computeroutput>VBOX_CDROM</computeroutput> is defined (see
+            below). If so, VirtualBox omits all the following checks.</para>
+          </listitem>
+
+          <listitem>
+            <para>VirtualBox tests if
+            <computeroutput>/dev/cdrom</computeroutput> works.</para>
+          </listitem>
+
+          <listitem>
+            <para>In addition, VirtualBox checks if any CD/DVD drives are
+            currently mounted by checking
+            <computeroutput>/etc/mtab</computeroutput>.</para>
+          </listitem>
+
+          <listitem>
+            <para>In addition, VirtualBox checks if any of the entries in
+            <computeroutput>/etc/fstab</computeroutput> point to CD/DVD
+            devices.</para>
+          </listitem>
+        </orderedlist></para>
+
+      <para>In other words, you can try to set VBOX_CDROM to contain a list of
+      your CD/DVD devices, separated by colons, for example as follows:</para>
+
+      <para><screen>export VBOX_CDROM='/dev/cdrom0:/dev/cdrom1'</screen>On
+      modern Linux distributions, VirtualBox uses the hardware abstraction
+      layer (hal) to locate CD and DVD hardware.</para>
+    </sect2>
+
+    <sect2>
+      <title>Linux host floppy not found</title>
+
+      <para>The previous instructions (for CD and DVD drives) apply
+      accordingly to floppy disks, except that on older distributions
+      VirtualBox tests for <computeroutput>/dev/fd*</computeroutput> devices
+      by default, and this can be overridden with the
+      <computeroutput>VBOX_FLOPPY</computeroutput> environment
+      variable.</para>
+    </sect2>
+
+    <sect2>
+      <title>Strange guest IDE error messages when writing to CD/DVD</title>
+
+      <para>If the experimental CD/DVD writer support is enabled with an
+      incorrect VirtualBox, host or guest configuration, it is possible that
+      any attempt to access the CD/DVD writer fails and simply results in
+      guest kernel error messages (for Linux guests) or application error
+      messages (for Windows guests). VirtualBox performs the usual consistency
+      checks when a VM is powered up (in particular it aborts with an error
+      message if the device for the CD/DVD writer is not writable by the user
+      starting the VM), but it cannot detect all misconfigurations. The
+      necessary host and guest OS configuration is not specific for
+      VirtualBox, but a few frequent problems are listed here which occurred
+      in connection with VirtualBox.</para>
+
+      <para>Special care must be taken to use the correct device. The
+      configured host CD/DVD device file name (in most cases
+      <literal>/dev/cdrom</literal>) must point to the device that allows
+      writing to the CD/DVD unit. For CD/DVD writer units connected to a SCSI
+      controller or to a IDE controller that interfaces to the Linux SCSI
+      subsystem (common for some SATA controllers), this must refer to the
+      SCSI device node (e.g. <literal>/dev/scd0</literal>). Even for IDE
+      CD/DVD writer units this must refer to the appropriate SCSI CD-ROM
+      device node (e.g. <literal>/dev/scd0</literal>) if the
+      <literal>ide-scsi</literal> kernel module is loaded. This module is
+      required for CD/DVD writer support with all Linux 2.4 kernels and some
+      early 2.6 kernels. Many Linux distributions load this module whenever a
+      CD/DVD writer is detected in the system, even if the kernel would
+      support CD/DVD writers without the module. VirtualBox supports the use
+      of IDE device files (e.g. <literal>/dev/hdc</literal>), provided the
+      kernel supports this and the <literal>ide-scsi</literal> module is not
+      loaded.</para>
+
+      <para>Similar rules (except that within the guest the CD/DVD writer is
+      always an IDE device) apply to the guest configuration. Since this setup
+      is very common, it is likely that the default configuration of the guest
+      works as expected.</para>
+    </sect2>
+
+    <sect2>
+      <title>VBoxSVC IPC issues</title>
+
+      <para>On Linux, VirtualBox makes use of a custom version of Mozilla
+      XPCOM (cross platform component object model) for inter- and
+      intra-process communication (IPC). The process
+      <computeroutput>VBoxSVC</computeroutput> serves as a communication hub
+      between different VirtualBox processes and maintains the global
+      configuration, i.e. the XML database. When starting a VirtualBox
+      component, the processes <computeroutput>VBoxSVC</computeroutput> and
+      <computeroutput>VirtualBoxXPCOMIPCD</computeroutput> are started
+      automatically. They are only accessible from the user account they are
+      running under. <computeroutput>VBoxSVC</computeroutput> owns the
+      VirtualBox configuration database which normally resides in
+      <computeroutput>~/.VirtualBox</computeroutput>. While it is running, the
+      configuration files are locked. Communication between the various
+      VirtualBox components and <computeroutput>VBoxSVC</computeroutput> is
+      performed through a local domain socket residing in
+      <computeroutput>/tmp/.vbox-&lt;username&gt;-ipc</computeroutput>. In
+      case there are communication problems (i.e. a VirtualBox application
+      cannot communicate with <computeroutput>VBoxSVC</computeroutput>),
+      terminate the daemons and remove the local domain socket
+      directory.</para>
+    </sect2>
+
+    <sect2 id="usb_linux">
+      <title>USB not working</title>
+
+      <para>If USB is not working on your Linux host, make sure that the
+      current user is a member of the
+      <computeroutput>vboxusers</computeroutput> group. On older hosts, you
+      need to make sure that the user has permission to access the USB
+      filesystem (<computeroutput>usbfs</computeroutput>), which VirtualBox
+      relies on to retrieve valid information about your host's USB devices.
+      The rest of this section only applies to those older systems.</para>
+
+      <note>
+        <para>The current rdesktop-vrdp implementation does not support
+        accessing USB devices through the
+        <computeroutput>sysfs</computeroutput>!</para>
+      </note>
+
+      <para>As <computeroutput>usbfs</computeroutput> is a virtual filesystem,
+      a <computeroutput>chmod</computeroutput> on
+      <computeroutput>/proc/bus/usb</computeroutput> has no effect. The
+      permissions for <computeroutput>usbfs</computeroutput> can therefore
+      <emphasis>only</emphasis> be changed by editing the
+      <computeroutput>/etc/fstab</computeroutput> file.</para>
+
+      <para>For example, most Linux distributions have a user group called
+      <computeroutput>usb</computeroutput> or similar, of which the current
+      user must be a member. To give all users of that group access to usbfs,
+      make sure the following line is present:<screen># 85 is the USB group
+none     /proc/bus/usb     usbfs      devgid=85,devmode=664    0    0</screen>Replace
+      85 with the group ID that matches your system (search
+      <computeroutput>/etc/group</computeroutput> for "usb" or similar).
+      Alternatively, if you don't mind the security hole, give all users
+      access to USB by changing "664" to "666".</para>
+
+      <para>The various distributions are very creative from which script the
+      <computeroutput>usbfs</computeroutput> filesystem is mounted. Sometimes
+      the command is hidden in unexpected places. For SuSE 10.0 the mount
+      command is part of the udev configuration file
+      <computeroutput>/etc/udev/rules.d/50-udev.rules</computeroutput>. As
+      this distribution has no user group called
+      <computeroutput>usb</computeroutput>, you may e.g. use the
+      <computeroutput>vboxusers</computeroutput> group which was created by
+      the VirtualBox installer. Since group numbers are allocated dynamically,
+      the following example uses 85 as a placeholder. Modify the line
+      containing (a linebreak has been inserted to improve
+      readability)<screen>DEVPATH="/module/usbcore", ACTION=="add",
+    RUN+="/bin/mount -t usbfs usbfs /proc/bus/usb"</screen> and add the
+      necessary options (make sure that everything is in a single
+      line):<screen>DEVPATH="/module/usbcore", ACTION=="add",
+    RUN+="/bin/mount -t usbfs usbfs /proc/bus/usb -o devgid=85,devmode=664"</screen></para>
+
+      <para>Debian Etch has the mount command in
+      <computeroutput>/etc/init.d/mountkernfs.sh</computeroutput>. Since that
+      distribution has no group <computeroutput>usb</computeroutput>, it is
+      also the easiest solution to allow all members of the group
+      <computeroutput>vboxusers</computeroutput> to access the USB subsystem.
+      Modify the line <screen>domount usbfs usbdevfs /proc/bus/usb -onoexec,nosuid,nodev</screen>
+      so that it contains <screen>domount usbfs usbdevfs /proc/bus/usb -onoexec,nosuid,nodev,devgid=85,devmode=664</screen>
+      As usual, replace the 85 with the actual group number which should get
+      access to USB devices.</para>
+
+      <para>Other distributions do similar operations in scripts stored in the
+      <computeroutput>/etc/init.d</computeroutput> directory.</para>
+    </sect2>
+
+    <sect2>
+      <title>PAX/grsec kernels</title>
+
+      <para>Linux kernels including the grsec patch (see <literal><ulink
+      url="http://www.grsecurity.net/">http://www.grsecurity.net/</ulink></literal>)
+      and derivates have to disable PAX_MPROTECT for the VBox binaries to be
+      able to start a VM. The reason is that VBox has to create executable
+      code on anonymous memory.</para>
+    </sect2>
+
+    <sect2>
+      <title>Linux kernel vmalloc pool exhausted</title>
+
+      <para>When running a large number of VMs with a lot of RAM on a Linux
+      system (say 20 VMs with 1GB of RAM each), additional VMs might fail to
+      start with a kernel error saying that the vmalloc pool is exhausted and
+      should be extended. The error message also tells you to specify
+      <computeroutput>vmalloc=256MB</computeroutput> in your kernel parameter
+      list. If adding this parameter to your GRUB or LILO configuration makes
+      the kernel fail to boot (with a weird error message such as "failed to
+      mount the root partition"), then you have probably run into a memory
+      conflict of your kernel and initial RAM disk. This can be solved by
+      adding the following parameter to your GRUB configuration:</para>
+
+      <screen>uppermem 524288</screen>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Solaris hosts</title>
+
+    <sect2>
+      <title>Cannot start VM, not enough contiguous memory</title>
+
+      <para>The ZFS file system is known to use all available RAM as cache if
+      the default system settings are not changed. This may lead to a heavy
+      fragmentation of the host memory preventing VirtualBox VMs from being
+      started. We recommend to limit the ZFS cache by adding a line<screen>set zfs:zfs_arc_max = xxxx</screen>
+      to /etc/system where <computeroutput>xxxx</computeroutput> bytes is the
+      amount of memory usable for the ZFS cache.</para>
+    </sect2>
+
+    <sect2>
+      <title>VM aborts with out of memory errors on Solaris 10 hosts</title>
+
+      <para>32-bit Solaris 10 hosts (bug 1225025) require swap space equal to,
+      or greater than the host's physical memory size. For example, 8 GB
+      physical memory would require at least 8 GB swap. This can be configured
+      during a Solaris 10 install by choosing a 'custom install' and changing
+      the default partitions.</para>
+
+      <note>
+        <para>This restriction applies only to 32-bit Solaris hosts, 64-bit
+        hosts are not affected!</para>
+      </note>
+
+      <para>For existing Solaris 10 installs, an additional swap image needs
+      to be mounted and used as swap. Hence if you have 1 GB swap and 8 GB of
+      physical memory, you require to add 7 GB more swap. This can be done as
+      follows:</para>
+
+      <para>For ZFS (as root user):</para>
+
+      <para><screen>zfs create -V 8gb /_&lt;ZFS volume&gt;_/swap
+swap -a /dev/zvol/dsk/_&lt;ZFS volume&gt;_/swap</screen></para>
+
+      <para>To mount if after reboot, add the following line to
+      /etc/vfstab:</para>
+
+      <screen>/dev/zvol/dsk/_&lt;ZFS volume&gt;_/swap - - swap - no -</screen>
+
+      <para>Alternatively, you could grow the existing swap using:</para>
+
+      <screen>zfs set volsize=8G rpool/swap</screen>
+
+      <para>And reboot the system for the changes to take effect.</para>
+
+      <para>For UFS (as root user):</para>
+
+      <screen>mkfile 7g /path/to/swapfile.img
+swap -a /path/to/swapfile.img</screen>
+
+      <para>To mount it after reboot, add the following line to
+      /etc/vfstab:</para>
+
+      <screen>/path/to/swap.img - - swap - no -</screen>
+    </sect2>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_VBoxManage.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_VBoxManage.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_VBoxManage.xml	(revision 33555)
@@ -0,0 +1,2632 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="vboxmanage">
+  <title>VBoxManage</title>
+
+  <sect1>
+    <title>Introduction</title>
+
+    <para>As briefly mentioned in <xref linkend="frontends" />, VBoxManage is
+    the command-line interface to VirtualBox. With it, you can completely
+    control VirtualBox from the command line of your host operating system.
+    VBoxManage supports all the features that the graphical user interface
+    gives you access to, but it supports a lot more than that. It exposes
+    really all the features of the virtualization engine, even those that
+    cannot (yet) be accessed from the GUI.</para>
+
+    <para>You will need to use the command line if you want to</para>
+
+    <para><itemizedlist>
+        <listitem>
+          <para>use a different user interface than the main GUI (for example,
+          VBoxSDL or the VBoxHeadless server);</para>
+        </listitem>
+
+        <listitem>
+          <para>control some of the more advanced and experimental
+          configuration settings for a VM.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>There are two main things to keep in mind when using
+    <computeroutput>VBoxManage</computeroutput>: First,
+    <computeroutput>VBoxManage</computeroutput> must always be used with a
+    specific "subcommand", such as "list" or "createvm" or "startvm". All the
+    subcommands that <computeroutput>VBoxManage</computeroutput> supports are
+    described in detail in <xref linkend="vboxmanage" />.</para>
+
+    <para>Second, most of these subcommands require that you specify a
+    particular virtual machine after the subcommand. There are two ways you
+    can do this:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>You can specify the VM name, as it is shown in the VirtualBox
+        GUI. Note that if that name contains spaces, then you must enclose the
+        entire name in double quotes (as it is always required with command
+        line arguments that contain spaces).</para>
+
+        <para>For example:<screen>VBoxManage startvm "Windows XP"</screen></para>
+      </listitem>
+
+      <listitem>
+        <para>You can specify the UUID, which is the internal unique
+        identifier that VirtualBox uses to refer to the virtual machine.
+        Assuming that the aforementioned VM called "Windows XP" has the UUID
+        shown below, the following command has the same effect as the
+        previous:<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen></para>
+      </listitem>
+    </itemizedlist>
+
+    <para>You can type <computeroutput>VBoxManage list vms</computeroutput> to
+    have all currently registered VMs listed with all their settings,
+    including their respective names and UUIDs.</para>
+
+    <para>Some typical examples of how to control VirtualBox from the command
+    line are listed below:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>To create a new virtual machine from the command line and
+        immediately register it with VirtualBox, use
+        <computeroutput>VBoxManage createvm</computeroutput> with the
+        <computeroutput>--register</computeroutput> option,<footnote>
+            <para>For details, see <xref
+            linkend="vboxmanage-createvm" />.</para>
+          </footnote> like this:</para>
+
+        <screen>$ VBoxManage createvm --name "SUSE 10.2" --register
+VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
+(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
+All rights reserved.
+
+Virtual machine 'SUSE 10.2' is created.
+UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
+Settings file: '/home/username/.VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'
+</screen>
+
+        <para>As can be seen from the above output, a new virtual machine has
+        been created with a new UUID and a new XML settings file.</para>
+      </listitem>
+
+      <listitem>
+        <para>To show the configuration of a particular VM, use
+        <computeroutput>VBoxManage showvminfo</computeroutput>; see <xref
+        linkend="vboxmanage-showvminfo" /> for details and an example.</para>
+      </listitem>
+
+      <listitem>
+        <para>To change settings while a VM is powered off, use
+        <computeroutput>VBoxManage modifyvm</computeroutput>, e.g. as
+        follows:<screen>VBoxManage modifyvm "Windows XP" --memory "512MB"</screen></para>
+
+        <para>For details, see <xref linkend="vboxmanage-modifyvm" />.</para>
+      </listitem>
+
+      <listitem>
+        <para>To change the storage configuration (e.g. to add a storage
+        controller and then a virtual disk), use <computeroutput>VBoxManage
+        storagectl</computeroutput> and <computeroutput>VBoxManage
+        storageattach</computeroutput>; see <xref
+        linkend="vboxmanage-storage" /> for details.</para>
+      </listitem>
+
+      <listitem>
+        <para>To control VM operation, use one of the following:<itemizedlist>
+            <listitem>
+              <para>To start a VM that is currently powered off, use
+              <computeroutput>VBoxManage startvm</computeroutput>; see <xref
+              linkend="vboxmanage-startvm" /> for details.</para>
+            </listitem>
+
+            <listitem>
+              <para>To pause or save a VM that is currently running or change
+              some of its settings, use <computeroutput>VBoxManage
+              controlvm</computeroutput>; see <xref
+              linkend="vboxmanage-controlvm" /> for details.</para>
+            </listitem>
+          </itemizedlist></para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Commands overview</title>
+
+    <para>When running VBoxManage without parameters or when supplying an
+    invalid command line, the below syntax diagram will be shown. Note that
+    the output will be slightly different depending on the host platform; when
+    in doubt, check the output of <computeroutput>VBoxManage</computeroutput>
+    for the commands available on your particular host.</para>
+
+    <screen>$VBOX_MANAGE_OUTPUT</screen>
+
+    <para>Each time VBoxManage is invoked, only one command can be executed.
+    However, a command might support several subcommands which then can be
+    invoked in one single call. The following sections provide detailed
+    reference information on the different commands.</para>
+  </sect1>
+
+  <sect1 id="vboxmanage-list">
+    <title>VBoxManage list</title>
+
+    <para>The <computeroutput>list</computeroutput> command gives relevant
+    information about your system and information about VirtualBox's current
+    settings.</para>
+
+    <para>The following subcommands are available with
+    <computeroutput>VBoxManage list</computeroutput>: <itemizedlist>
+        <listitem>
+          <para><computeroutput>vms</computeroutput> lists all virtual
+          machines currently registered with VirtualBox. By default this
+          displays a compact list with each VM's name and UUID; if you also
+          specify <computeroutput>--long</computeroutput> or
+          <computeroutput>-l</computeroutput>, this will be a detailed list as
+          with the <computeroutput>showvminfo</computeroutput> command (see
+          below).</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>runningvms</computeroutput> lists all
+          currently running virtual machines by their unique identifiers
+          (UUIDs) in the same format as with
+          <computeroutput>vms</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>hdds</computeroutput>,
+          <computeroutput>dvds</computeroutput> and
+          <computeroutput>floppies</computeroutput> all give you information
+          about virtual disk images currently registered in VirtualBox,
+          including all their settings, the unique identifiers (UUIDs)
+          associated with them by VirtualBox and all files associated with
+          them.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>ostypes</computeroutput> lists all guest
+          operating systems presently known to VirtualBox, along with the
+          identifiers used to refer to them with the
+          <computeroutput>modifyvm</computeroutput> command.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>hostdvds</computeroutput>,
+          <computeroutput>hostfloppies</computeroutput> and
+          <computeroutput>hostifs</computeroutput>, respectively, list DVD,
+          floppy and host networking interfaces on the host, along with the
+          name used to access them from within VirtualBox.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>hostusb</computeroutput> supplies information
+          about USB devices attached to the host, notably information useful
+          for constructing USB filters and whether they are currently in use
+          by the host.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>usbfilters</computeroutput> lists all global
+          USB filters registered with VirtualBox -- that is, filters for
+          devices which are accessible to all virtual machines -- and displays
+          the filter parameters.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>systemproperties</computeroutput> displays
+          some global VirtualBox settings, such as minimum and maximum guest
+          RAM and virtual hard disk size, folder settings and the current
+          authentication library in use.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>hddbackends</computeroutput> lists all known
+          hdd backends of VirtualBox. Beside the name of the backend itself,
+          descriptions about the capabilities, configuration and other useful
+          informations are displayed.</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+
+  <sect1 id="vboxmanage-showvminfo">
+    <title>VBoxManage showvminfo</title>
+
+    <para>The <computeroutput>showvminfo</computeroutput> command shows
+    information about a particular virtual machine. This is the same
+    information as <computeroutput>VBoxManage list vms --long</computeroutput>
+    would show for all virtual machines.</para>
+
+    <para>You will get information similar to the following:</para>
+
+    <para><screen>$ VBoxManage showvminfo "Windows XP"
+VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
+(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
+All rights reserved.
+
+Name:            Windows XP
+Guest OS:        Other/Unknown
+UUID:            1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
+Config file:     /home/username/.VirtualBox/Machines/Windows XP/Windows XP.xml
+Memory size:     512MB
+VRAM size:       12MB
+Number of CPUs:  2
+Synthetic Cpu:   off
+Boot menu mode:  message and menu
+Boot Device (1): DVD
+Boot Device (2): HardDisk
+Boot Device (3): Not Assigned
+Boot Device (4): Not Assigned
+ACPI:            on
+IOAPIC:          on
+PAE:             on
+Time offset:     0 ms
+Hardw. virt.ext: on
+Hardw. virt.ext exclusive: on
+Nested Paging:   on
+VT-x VPID:       off
+State:           powered off (since 2009-10-20T14:52:19.000000000)
+Monitor count:   1
+3D Acceleration: off
+2D Video Acceleration: off
+Teleporter Enabled: off
+Teleporter Port: 0
+Teleporter Address:
+Teleporter Password:
+Storage Controller      (0): IDE Controller
+Storage Controller Type (0): PIIX4
+Storage Controller      (1): Floppy Controller 1
+Storage Controller Type (1): I82078
+IDE Controller (0, 0): /home/user/windows.vdi (UUID: 46f6e53a-4557-460a-9b95-68b0f17d744b)
+IDE Controller (0, 1): /home/user/openbsd-cd46.iso (UUID: 4335e162-59d3-4512-91d5-b63e94eebe0b)
+Floppy Controller 1 (0, 0): /home/user/floppy.img (UUID: 62ac6ccb-df36-42f2-972e-22f836368137)
+NIC 1:           disabled
+NIC 2:           disabled
+NIC 3:           disabled
+NIC 4:           disabled
+NIC 5:           disabled
+NIC 6:           disabled
+NIC 7:           disabled
+NIC 8:           disabled
+UART 1:          disabled
+UART 2:          disabled
+Audio:           disabled (Driver: Unknown)
+Clipboard Mode:  Bidirectional
+VRDP:            disabled
+USB:             disabled
+
+USB Device Filters:
+&lt;none&gt;
+
+Shared folders:
+&lt;none&gt;
+
+Statistics update:  disabled
+</screen></para>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage registervm / unregistervm</title>
+
+    <para>The <computeroutput>registervm</computeroutput> command allows you
+    to import a virtual machine definition in an XML file into VirtualBox. The
+    machine must not conflict with one already registered in VirtualBox and it
+    may not have any hard or removable disks attached. It is advisable to
+    place the definition file in the machines folder before registering
+    it.<note>
+        <para>When creating a new virtual machine with
+        <computeroutput>VBoxManage createvm</computeroutput> (see below), you
+        can directly specify the <computeroutput>--register</computeroutput>
+        option to avoid having to register it separately.</para>
+      </note></para>
+
+    <para>The <computeroutput>unregistervm</computeroutput> command
+    unregisters a virtual machine. If
+    <computeroutput>--delete</computeroutput> is also specified, the following
+    files will automatically be deleted as well:<orderedlist>
+        <listitem>
+          <para>all hard disk image files, including differencing files, which
+          are used by the machine and not shared with other machines;</para>
+        </listitem>
+
+        <listitem>
+          <para>saved state files that the machine created, if any (one if the
+          machine was in "saved" state and one for each online
+          snapshot);</para>
+        </listitem>
+
+        <listitem>
+          <para>the machine XML file and its backups;</para>
+        </listitem>
+
+        <listitem>
+          <para>the machine log files, if any;</para>
+        </listitem>
+
+        <listitem>
+          <para>the machine directory, if it is empty after having deleted all
+          the above.</para>
+        </listitem>
+      </orderedlist></para>
+  </sect1>
+
+  <sect1>
+    <title id="vboxmanage-createvm">VBoxManage createvm</title>
+
+    <para>This command creates a new XML virtual machine definition
+    file.</para>
+
+    <para>The <computeroutput>--name &lt;name&gt;</computeroutput> parameter
+    is required and must specify the name of the machine. Since this name is
+    used by default as the file name of the settings file (with the extension
+    <computeroutput>.xml</computeroutput>) and the machine folder (a subfolder
+    of the <computeroutput>.VirtualBox/Machines</computeroutput> folder), it
+    must conform to your host operating system's requirements for file name
+    specifications. If the VM is later renamed, the file and folder names will
+    change automatically.</para>
+
+    <para>However, if the <computeroutput>--basefolder
+    &lt;path&gt;</computeroutput> option is used, the machine folder will be
+    named <computeroutput>&lt;path&gt;</computeroutput>. In this case, the
+    names of the file and the folder will not change if the virtual machine is
+    renamed.</para>
+
+    <para>By default, this command only creates the XML file without
+    automatically registering the VM with your VirtualBox installation. To
+    register the VM instantly, use the optional
+    <computeroutput>--register</computeroutput> option, or run
+    <computeroutput>VBoxManage registervm</computeroutput> separately
+    afterwards.</para>
+  </sect1>
+
+  <sect1 id="vboxmanage-modifyvm">
+    <title>VBoxManage modifyvm</title>
+
+    <para>This command changes the properties of a registered virtual machine
+    which is not running. Most of the properties that this command makes
+    available correspond to the VM settings that VirtualBox graphical user
+    interface displays in each VM's "Settings" dialog; these were described in
+    <xref linkend="BasicConcepts" />. Some of the more advanced settings,
+    however, are only available through the
+    <computeroutput>VBoxManage</computeroutput> interface.</para>
+
+    <para>These commands require that the machine is powered off (neither
+    running nor in "saved" state). Some machine settings can also be changed
+    while a machine is running; those settings will then have a corresponding
+    subcommand with the <computeroutput>VBoxManage controlvm</computeroutput>
+    subcommand (see <xref linkend="vboxmanage-controlvm" />).</para>
+
+    <sect2>
+      <title>General settings</title>
+
+      <para>The following general settings are available through
+      <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
+          <listitem>
+            <para><computeroutput>--name &lt;name&gt;</computeroutput>: This
+            changes the VM's name and possibly renames the internal virtual
+            machine files, as described with <computeroutput>VBoxManage
+            createvm</computeroutput> above.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--ostype &lt;ostype&gt;</computeroutput>:
+            This specifies what guest operating system is supposed to run in
+            the VM. To learn about the various identifiers that can be used
+            here, use <computeroutput>VBoxManage list
+            ostypes</computeroutput>.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--memory
+            &lt;memorysize&gt;</computeroutput>: This sets the amount of RAM,
+            in MB, that the virtual machine should allocate for itself from
+            the host. See the remarks in <xref linkend="gui-createvm" /> for
+            more information.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vram &lt;vramsize&gt;</computeroutput>:
+            This sets the amount of RAM that the virtual graphics card should
+            have. See <xref linkend="settings-display" /> for details.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--acpi on|off</computeroutput>;
+            <computeroutput>--ioapic on|off</computeroutput>: These two
+            determine whether the VM should have ACPI and I/O APIC support,
+            respectively; see <xref linkend="settings-motherboard" /> for
+            details.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--hardwareuuid
+            &lt;uuid&gt;</computeroutput>: The UUID presented to the guest via
+            memory tables (DMI/SMBIOS), hardware and guest properties. By
+            default this is the same as the VM uuid. Useful when cloning a VM.
+            Teleporting takes care of this automatically.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--cpus &lt;cpucount&gt;</computeroutput>:
+            This sets the number of virtual CPUs for the virtual machine (see
+            <xref linkend="settings-processor" />). If CPU hot-plugging is
+            enabled (see below), this then sets the
+            <emphasis>maximum</emphasis> number of virtual CPUs that can be
+            plugged into the virtual machines.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--rtcuseutc on|off</computeroutput>: This
+            option lets the real-time clock (RTC) operate in UTC time (see
+            <xref linkend="settings-motherboard" />).</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--cpuhotplug on|off</computeroutput>: This
+            enables CPU hot-plugging. When enabled, virtual CPUs can be added
+            to and removed from a virtual machine while it is running. See
+            <xref linkend="cpuhotplug" /> for more information.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--plugcpu|unplugcpu
+            &lt;id&gt;</computeroutput>: If CPU hot-plugging is enabled (see
+            above), this adds a virtual CPU to the virtual machines (or
+            removes one). <computeroutput>&lt;id&gt;</computeroutput>
+            specifies the index of the virtual CPU to be added or removed and
+            must be a number from 0 to the maximum no. of CPUs configured with
+            the <computeroutput>--cpus</computeroutput> option. CPU 0 can
+            never be removed.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--synthcpu on|off</computeroutput>: This
+            setting determines whether VirtualBox will expose a synthetic CPU
+            to the guest to allow live migration between host systems that
+            differ significantly.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--pae on|off</computeroutput>: This
+            enables/disables PAE (see <xref
+            linkend="settings-processor" />).</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--hpet on|off</computeroutput>: This
+            enables/disables a High Precision Event Timer (HPET) which can
+            replace the legacy system timers. This is turned off by default.
+            Note that Windows supports a HPET only from Vista onwards.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--hwvirtex on|off</computeroutput>: This
+            enables or disables the use of hardware virtualization extensions
+            (Intel VT-x or AMD-V) in the processor of your host system; see
+            <xref linkend="hwvirt" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--hwvirtexexcl on|off</computeroutput>: This
+            specifies whether VirtualBox will make exclusive use of the
+            hardware virtualization extensions (Intel VT-x or AMD-V) in the
+            processor of your host system; see <xref linkend="hwvirt" />. If
+            you wish to simultaneously share these extensions with other
+            hypervisors, then you must disable this setting. Doing so has
+            negative performance implications.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--nestedpaging on|off</computeroutput>: If
+            hardware virtualization is enabled, this additional setting
+            enables or disables the use of the nested paging feature in the
+            processor of your host system; see <xref
+            linkend="hwvirt" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--largepages on|off</computeroutput>: If
+            hardware virtualization <emphasis>and</emphasis> nested paging are
+            enabled, for Intel VT-x only, an additional performance
+            improvement of up to 5% can be obtained by enabling this setting.
+            This causes the hypervisor to use large pages to reduce TLB use
+            and overhead.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vtxvpid on|off</computeroutput>: If
+            hardware virtualization is enabled, for Intel VT-x only, this
+            additional setting enables or disables the use of the tagged TLB
+            (VPID) feature in the processor of your host system; see <xref
+            linkend="hwvirt" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--accelerate3d on|off</computeroutput>: This
+            enables, if the Guest Additions are installed, whether hardware 3D
+            acceleration should be available; see <xref
+            linkend="guestadd-3d" />.</para>
+          </listitem>
+
+          <listitem>
+            <para>You can influence the BIOS logo that is displayed when a
+            virtual machine starts up with a number of settings. Per default,
+            a VirtualBox logo is displayed.</para>
+
+            <para>With <computeroutput>--bioslogofadein
+            on|off</computeroutput> and <computeroutput>--bioslogofadeout
+            on|off</computeroutput>, you can determine whether the logo should
+            fade in and out, respectively.</para>
+
+            <para>With <computeroutput>--bioslogodisplaytime
+            &lt;msec&gt;</computeroutput> you can set how long the logo should
+            be visible, in milliseconds.</para>
+
+            <para>With <computeroutput>--bioslogoimagepath
+            &lt;imagepath&gt;</computeroutput> you can, if you are so
+            inclined, replace the image that is shown, with your own logo. The
+            image must be an uncompressed 256 color BMP file.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--biosbootmenu
+            disabled|menuonly|messageandmenu</computeroutput>: This specifies
+            whether the BIOS allows the user to select a temporary boot
+            device. <computeroutput>menuonly</computeroutput> suppresses the
+            message, but the user can still press F12 to select a temporary
+            boot device.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--boot&lt;1-4&gt;
+            none|floppy|dvd|disk|net</computeroutput>: This specifies the boot
+            order for the virtual machine. There are four "slots", which the
+            VM will try to access from 1 to 4, and for each of which you can
+            set a device that the VM should attempt to boot from.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--snapshotfolder
+            default|&lt;path&gt;</computeroutput>: This allows you to specify
+            the folder in which snapshots will be kept for a virtual
+            machine.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--firmware efi|bios</computeroutput>:
+            Specifies which firmware is used to boot particular virtual
+            machine: EFI or BIOS. Use EFI only if your fully understand what
+            you're doing.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--guestmemoryballoon
+            &lt;size&gt;</computeroutput> sets the default size of the guest
+            memory balloon, that is, memory allocated by the VirtualBox Guest
+            Additions from the guest operating system and returned to the
+            hypervisor for re-use by other virtual machines. &lt;size&gt; must
+            be specified in megabytes. The default size is 0 megabytes. For
+            details, see <xref linkend="guestadd-balloon" />.</para>
+          </listitem>
+        </itemizedlist></para>
+    </sect2>
+
+    <sect2>
+      <title>Networking settings</title>
+
+      <para>The following networking settings are available through
+      <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
+      settings, the decimal number directly following the option name ("1-N"
+      in the list below) specifies the virtual network adapter whose settings
+      should be changed.<itemizedlist>
+          <listitem>
+            <para><computeroutput>--nic&lt;1-N&gt;
+            none|null|nat|bridged|intnet|hostonly|vde</computeroutput>: With
+            this, you can set, for each of the VM's virtual network cards,
+            what type of networking should be available. They can be not
+            present (<computeroutput>none</computeroutput>), not connected to
+            the host (<computeroutput>null</computeroutput>), use network
+            address translation (<computeroutput>nat</computeroutput>),
+            bridged networking (<computeroutput>bridged</computeroutput>) or
+            communicate with other virtual machines using internal networking
+            (<computeroutput>intnet</computeroutput>), host-only networking
+            (<computeroutput>hostonly</computeroutput>) or on Linux and
+            FreeBSD hosts a Virtual Distributed Ethernet switch
+            (<computeroutput>vde</computeroutput>). These options correspond
+            to the modes which are described in detail in <xref
+            linkend="networkingmodes" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--nictype&lt;1-N&gt;
+            Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio</computeroutput>:
+            This allows you, for each of the VM's virtual network cards, to
+            specify which networking hardware VirtualBox presents to the
+            guest; see <xref linkend="nichardware" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--cableconnected&lt;1-N&gt;
+            on|off</computeroutput>: This allows you to temporarily disconnect
+            a virtual network interface, as if a network cable had been pulled
+            from a real network card. This might be useful for resetting
+            certain software components in the VM.</para>
+          </listitem>
+
+          <listitem>
+            <para>With the "nictrace" options, you can optionally trace
+            network traffic by dumping it to a file, for debugging
+            purposes.</para>
+
+            <para>With <computeroutput>--nictrace&lt;1-N&gt;
+            on|off</computeroutput>, you can enable network tracing for a
+            particular virtual network card.</para>
+
+            <para>If enabled, you must specify with
+            <computeroutput>--nictracefile&lt;1-N&gt;
+            &lt;filename&gt;</computeroutput> what file the trace should be
+            logged to.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--bridgeadapter&lt;1-N&gt;
+            none|&lt;devicename&gt;</computeroutput>: If bridged networking
+            has been enabled for a virtual network card (see the
+            <computeroutput>--nic</computeroutput> option above; otherwise
+            this setting has no effect), use this option to specify which host
+            interface the given virtual network interface will use. For
+            details, please see <xref linkend="network_bridged" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--hostonlyadapter&lt;1-N&gt;
+            none|&lt;devicename&gt;</computeroutput>: If host-only networking
+            has been enabled for a virtual network card (see the --nic option
+            above; otherwise this setting has no effect), use this option to
+            specify which host-only networking interface the given virtual
+            network interface will use. For details, please see <xref
+            linkend="network_hostonly" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--intnet&lt;1-N&gt;
+            network</computeroutput>: If internal networking has been enabled
+            for a virtual network card (see the
+            <computeroutput>--nic</computeroutput> option above; otherwise
+            this setting has no effect), use this option to specify the name
+            of the internal network (see <xref
+            linkend="network_internal" />).</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--macaddress&lt;1-N&gt;
+            auto|&lt;mac&gt;</computeroutput>: With this option you can set
+            the MAC address of the virtual network card. Normally, each
+            virtual network card is assigned a random address by VirtualBox at
+            VM creation.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vdenet&lt;1-N&gt;
+            network</computeroutput>: If Virtual Distributed Ethernet is
+            available on the host and has been enabled for a virtual network
+            card (see the <computeroutput>--nic</computeroutput> option above;
+            otherwise this setting has no effect). Use this option to specify
+            the name of a VDE network for the interface to connect to (see
+            <xref linkend="networkingmodes" /> and the VDE
+            documentation).</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <sect3>
+        <title>NAT Networking settings.</title>
+
+        <para>The following NAT networking settings are available through
+        <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
+        settings, the decimal number directly following the option name ("1-N"
+        in the list below) specifies the virtual network adapter whose
+        settings should be changed.<itemizedlist>
+            <listitem>
+              <para><computeroutput>--natpf&lt;1-N&gt;
+              [&lt;name&gt;],tcp|udp,[&lt;hostip&gt;],&lt;hostport&gt;,[&lt;guestip&gt;],
+              &lt;guestport&gt;</computeroutput>: This option defines a NAT
+              port-forwarding rule (please see <xref linkend="natforward" />
+              for details).</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--natpf&lt;1-N&gt; delete
+              &lt;name&gt;</computeroutput>: This option deletes a NAT
+              port-forwarding rule (please see <xref linkend="natforward" />
+              for details).</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--nattftpprefix&lt;1-N&gt;
+              &lt;prefix&gt;</computeroutput>: This option defines a prefix
+              for the built-in TFTP server, i.e. where the boot file is
+              located (please see <xref linkend="nat-tftp" /> and <xref
+              linkend="nat-adv-tftp" /> for details).</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--nattftpfile&lt;1-N&gt;
+              &lt;bootfile&gt;</computeroutput>: This option defines the TFT
+              boot file (please see <xref linkend="nat-adv-tftp" /> for
+              details).</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--nattftpserver&lt;1-N&gt;
+              &lt;tftpserver&gt;</computeroutput>: This option defines the
+              TFTP server address to boot from (please see <xref
+              linkend="nat-adv-tftp" /> for details).</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--natdnspassdomain&lt;1-N&gt;
+              on|off</computeroutput>: This option specifies whether the
+              built-in DHCP server passes the domain name for network name
+              resolution.</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--natdnsproxy&lt;1-N&gt;
+              on|off</computeroutput>: This option makes the NAT engine proxy
+              all guest DNS requests to the host's DNS servers (please see
+              <xref linkend="nat-adv-dns" /> for details).</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--natdnshostresolver&lt;1-N&gt;
+              on|off</computeroutput>: This option makes the NAT engine use
+              the host's resolver mechanisms to handle DNS requests (please
+              see <xref linkend="nat-adv-dns" /> for details).</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--natnatsettings&lt;1-N&gt;
+              [&lt;mtu&gt;],[&lt;socksnd&gt;],[&lt;sockrcv&gt;],[&lt;tcpsnd&gt;],
+              [&lt;tcprcv&gt;]</computeroutput>: This option controls several
+              NAT settings (please see <xref linkend="nat-adv-settings" /> for
+              details).</para>
+            </listitem>
+
+            <listitem>
+              <para><computeroutput>--nataliasmode&lt;1-N&gt;
+              default|[log],[proxyonly],[sameports]</computeroutput>: This
+              option defines behaviour of NAT engine core: log - enables
+              logging, proxyonly - switches of aliasing mode makes NAT
+              transparent, sameports enforces NAT engine to send packets via
+              the same port as they originated on, default - disable all
+              mentioned modes above . (please see <xref
+              linkend="nat-adv-alias" /> for details).</para>
+            </listitem>
+          </itemizedlist></para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="vboxmanage-modifyvm-other">
+      <title>Serial port, audio, clipboard, VRDP and USB settings</title>
+
+      <para>The following other hardware settings are available through
+      <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
+          <listitem>
+            <para><computeroutput>--uart&lt;1-N&gt; off|&lt;I/O base&gt;
+            &lt;IRQ&gt;</computeroutput>: With this option you can configure
+            virtual serial ports for the VM; see <xref
+            linkend="serialports" /> for an introduction.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--uartmode&lt;1-N&gt;
+            &lt;arg&gt;</computeroutput>: This setting controls how VirtualBox
+            connects a given virtual serial port (previously configured with
+            the <computeroutput>--uartX</computeroutput> setting, see above)
+            to the host on which the virtual machine is running. As described
+            in detail in <xref linkend="serialports" />, for each such port,
+            you can specify <computeroutput>&lt;arg&gt;</computeroutput> as
+            one of the following options:<itemizedlist>
+                <listitem>
+                  <para><computeroutput>disconnected</computeroutput>: Even
+                  though the serial port is shown to the guest, it has no
+                  "other end" -- like a real COM port without a cable.</para>
+                </listitem>
+
+                <listitem>
+                  <para><computeroutput>server
+                  &lt;pipename&gt;</computeroutput>: On a Windows host, this
+                  tells VirtualBox to create a named pipe on the host named
+                  <computeroutput>&lt;pipename&gt;</computeroutput> and
+                  connect the virtual serial device to it. Note that Windows
+                  requires that the name of a named pipe begin with
+                  <computeroutput>\\.\pipe\</computeroutput>.</para>
+
+                  <para>On a Linux host, instead of a named pipe, a local
+                  domain socket is used.</para>
+                </listitem>
+
+                <listitem>
+                  <para><computeroutput>client
+                  &lt;pipename&gt;</computeroutput>: This operates just like
+                  <computeroutput>server ...</computeroutput>, except that the
+                  pipe (or local domain socket) is not created by VirtualBox,
+                  but assumed to exist already.</para>
+                </listitem>
+
+                <listitem>
+                  <para><computeroutput>&lt;devicename&gt;</computeroutput>:
+                  If, instead of the above, the device name of a physical
+                  hardware serial port of the host is specified, the virtual
+                  serial port is connected to that hardware port. On a Windows
+                  host, the device name will be a COM port such as
+                  <computeroutput>COM1</computeroutput>; on a Linux host, the
+                  device name will look like
+                  <computeroutput>/dev/ttyS0</computeroutput>. This allows you
+                  to "wire" a real serial port to a virtual machine.</para>
+                </listitem>
+              </itemizedlist></para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--audio none|null|oss</computeroutput>: With
+            this option, you can set whether the VM should have audio
+            support.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--clipboard
+            disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
+            With this setting, you can select whether the guest operating
+            system's clipboard should be shared with the host; see <xref
+            linkend="generalsettings" />. This requires that the Guest
+            Additions be installed in the virtual machine.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--monitorcount
+            &lt;count&gt;</computeroutput>: This enables multi-monitor
+            support; see <xref linkend="settings-display" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--usb on|off</computeroutput>: This option
+            enables or disables the VM's virtual USB controller; see <xref
+            linkend="settings-usb" /> for details.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--usbehci on|off</computeroutput>: This
+            option enables or disables the VM's virtual USB 2.0 controller;
+            see <xref linkend="settings-usb" /> for details.</para>
+          </listitem>
+        </itemizedlist></para>
+    </sect2>
+
+    <sect2>
+      <title>Remote machine settings</title>
+
+      <para>The following settings that affect remote machine behavior are
+      available through <computeroutput>VBoxManage
+      modifyvm</computeroutput>:<itemizedlist>
+          <listitem>
+            <para><computeroutput>--vrdp on|off</computeroutput>: With the
+            VirtualBox graphical user interface, this enables or disables the
+            built-in VRDP server. Note that if you are using
+            <computeroutput>VBoxHeadless</computeroutput> (see <xref
+            linkend="vboxheadless" />), VRDP output is always enabled.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vrdpport
+            default|&lt;ports&gt;</computeroutput>: A port or a range of ports
+            the VRDP server can bind to; "default" or "0" means port 3389, the
+            standard port for RDP. You can specify a comma-separated list of
+            ports or ranges of ports. Use a dash between two port numbers to
+            specify a range. The VRDP server will bind to <emphasis
+            role="bold">one</emphasis> of available ports from the specified
+            list. Only one machine can use a given port at a time. For
+            example, the option <computeroutput> --vrdpport
+            5000,5010-5012</computeroutput> will tell the server to bind to
+            one of following ports: 5000, 5010, 5011 or 5012.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vrdpaddress &lt;IP
+            address&gt;</computeroutput>: The IP address of the host network
+            interface the VRDP server will bind to. If specified, the VRDP
+            server will accept connections only on the specified host network
+            interface.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vrdpauthtype
+            null|external|guest</computeroutput>: This allows you to choose
+            whether and how authorization will be performed; see <xref
+            linkend="vbox-auth" /> for details.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vrdpmulticon on|off</computeroutput>: This
+            enables multiple VRDP connections to the same VRDP server; see
+            <xref lang="" linkend="vrdp-multiconnection" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vrdpreusecon on|off</computeroutput>: This
+            specifies the VRDP server behavior when multiple connections are
+            disabled. When this option is enabled, the VRDP server will allow
+            a new client to connect and drop the existing connection. When
+            this option is disabled (this is the default setting), a new
+            connection will not be accepted if there is already a client
+            connected to the server.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vrdpvideochannel on|off</computeroutput>:
+            This enables VRDP video acceleration; see <xref lang=""
+            linkend="vrdp-videochannel" />.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--vrdpvideochannelquality
+            &lt;percent&gt;</computeroutput>: Sets the image quality for VRDP
+            video acceleration; see <xref lang=""
+            linkend="vrdp-videochannel" />.</para>
+          </listitem>
+        </itemizedlist></para>
+    </sect2>
+
+    <sect2 id="vboxmanage-modifyvm-teleport">
+      <title>Teleporting settings</title>
+
+      <para>With the following commands for <computeroutput>VBoxManage
+      modifyvm</computeroutput> you can configure a machine to be a target for
+      teleporting. See <xref linkend="teleporting" /> for an
+      introduction.<itemizedlist>
+          <listitem>
+            <para><computeroutput>--teleporter on|off</computeroutput>: With
+            this setting you turn on or off whether a machine waits for a
+            teleporting request to come in on the network when it is started.
+            If "on", when the machine is started, it does not boot the virtual
+            machine as it would normally; instead, it then waits for a
+            teleporting request to come in on the port and address listed with
+            the next two parameters.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--teleporterport
+            &lt;port&gt;</computeroutput>, <computeroutput>--teleporteraddress
+            &lt;address&gt;</computeroutput>: these must be used with
+            --teleporter and tell the virtual machine on which port and
+            address it should listen for a teleporting request from another
+            virtual machine. <computeroutput>&lt;port&gt;</computeroutput> can
+            be any free TCP/IP port number (e.g. 6000);
+            <computeroutput>&lt;address&gt;</computeroutput> can be any IP
+            address or hostname and specifies the TCP/IP socket to bind to.
+            The default is "0.0.0.0", which means any address.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--teleporterpassword
+            &lt;password&gt;</computeroutput>: if this optional argument is
+            given, then the teleporting request will only succeed if the
+            source machine specifies the same password as the one given with
+            this command.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--cpuid &lt;leaf&gt; &lt;eax&gt; &lt;ebx&gt;
+            &lt;ecx&gt; &lt;edx&gt;</computeroutput>: Advanced users can use
+            this command before a teleporting operation to restrict the
+            virtual CPU capabilities that VirtualBox presents to the guest
+            operating system. This must be run on both the source and the
+            target machines involved in the teleporting and will then modify
+            what the guest sees when it executes the
+            <computeroutput>CPUID</computeroutput> machine instruction. This
+            might help with misbehaving applications that wrongly assume that
+            certain CPU capabilities are present. The meaning of the
+            parameters is hardware dependent; please refer to the AMD or Intel
+            processor manuals.</para>
+          </listitem>
+        </itemizedlist></para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="vboxmanage-import">
+    <title>VBoxManage import</title>
+
+    <para>This command imports a virtual appliance in OVF format by copying
+    the virtual disk images and creating virtual machines in VirtualBox. See
+    <xref linkend="ovf" /> for an introduction to appliances.</para>
+
+    <para>The <computeroutput>import</computeroutput> subcommand takes at
+    least the path name of an OVF file as input and expects the disk images,
+    if needed, in the same directory as the OVF file. A lot of additional
+    command-line options are supported to control in detail what is being
+    imported and modify the import parameters, but the details depend on the
+    content of the OVF file.</para>
+
+    <para>It is therefore recommended to first run the import subcommand with
+    the <computeroutput>--dry-run</computeroutput> or
+    <computeroutput>-n</computeroutput> option. This will then print a
+    description of the appliance's contents to the screen how it would be
+    imported into VirtualBox, together with the optional command-line options
+    to influence the import behavior.</para>
+
+    <para>As an example, here is the screen output with a sample appliance
+    containing a Windows XP guest:<screen>VBoxManage import WindowsXp.ovf --dry-run
+Interpreting WindowsXp.ovf...
+OK.
+Virtual system 0:
+ 0: Suggested OS type: "WindowsXP"
+    (change with "--vsys 0 --ostype &lt;type&gt;"; use "list ostypes" to list all)
+ 1: Suggested VM name "Windows XP Professional_1"
+    (change with "--vsys 0 --vmname &lt;name&gt;")
+ 3: Number of CPUs: 1
+    (change with "--vsys 0 --cpus &lt;n&gt;")
+ 4: Guest memory: 956 MB (change with "--vsys 0 --memory &lt;MB&gt;")
+ 5: Sound card (appliance expects "ensoniq1371", can change on import)
+    (disable with "--vsys 0 --unit 5 --ignore")
+ 6: USB controller
+    (disable with "--vsys 0 --unit 6 --ignore")
+ 7: Network adapter: orig bridged, config 2, extra type=bridged
+ 8: Floppy
+    (disable with "--vsys 0 --unit 8 --ignore")
+ 9: SCSI controller, type BusLogic
+    (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}";
+    disable with "--vsys 0 --unit 9 --ignore")
+10: IDE controller, type PIIX4
+    (disable with "--vsys 0 --unit 10 --ignore")
+11: Hard disk image: source image=WindowsXp.vmdk,
+      target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
+    (change controller with "--vsys 0 --unit 11 --controller &lt;id&gt;";
+    disable with "--vsys 0 --unit 11 --ignore")</screen></para>
+
+    <para>As you can see, the individual configuration items are numbered, and
+    depending on their type support different command-line options. The import
+    subcommand can be directed to ignore many such items with a
+    <computeroutput>--vsys X --unit Y --ignore</computeroutput> option, where
+    X is the number of the virtual system (zero unless there are several
+    virtual system descriptions in the appliance) and Y the item number, as
+    printed on the screen.</para>
+
+    <para>In the above example, Item #1 specifies the name of the target
+    machine in VirtualBox. Items #9 and #10 specify hard disk controllers,
+    respectively. Item #11 describes a hard disk image; in this case, the
+    additional <computeroutput>--controller</computeroutput> option indicates
+    which item the disk image should be connected to, with the default coming
+    from the OVF file.</para>
+
+    <para>You can combine several items for the same virtual system behind the
+    same <computeroutput>--vsys</computeroutput> option. For example, to
+    import a machine as described in the OVF, but without the sound card and
+    without the USB controller, and with the disk image connected to the IDE
+    controller instead of the SCSI controller, use this:<screen>VBoxManage import WindowsXp.ovf
+      --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen></para>
+  </sect1>
+
+  <sect1 id="vboxmanage-export">
+    <title>VBoxManage export</title>
+
+    <para>This command exports one or more virtual machines from VirtualBox
+    into a virtual appliance in OVF format, including copying their virtual
+    disk images to compressed VMDK. See <xref linkend="ovf" /> for an
+    introduction to appliances.</para>
+
+    <para>The <computeroutput>export</computeroutput> command is simple to
+    use: list the machine (or the machines) that you would like to export to
+    the same OVF file and specify the target OVF file after an additional
+    <computeroutput>--output</computeroutput> or
+    <computeroutput>-o</computeroutput> option. Note that the directory of the
+    target OVF file will also receive the exported disk images in the
+    compressed VMDK format (regardless of the original format) and should have
+    enough disk space left for them.</para>
+
+    <para>Beside a simple export of a given virtual machine, you can append
+    several product information to the appliance file. Use
+    <computeroutput>--product</computeroutput>,
+    <computeroutput>--producturl</computeroutput>,
+    <computeroutput>--vendor</computeroutput>,
+    <computeroutput>--vendorurl</computeroutput> and
+    <computeroutput>--version</computeroutput> to specify this additional
+    information. For legal reasons you may add a license text or the content
+    of a license file by using the <computeroutput>--eula</computeroutput> and
+    <computeroutput>--eulafile</computeroutput> option respectively. As with
+    OVF import, you must use the <computeroutput>--vsys X</computeroutput>
+    option to direct the previously mentioned options to the correct virtual
+    machine.</para>
+
+    <para>For virtualization products which aren't fully compatible with the
+    OVF standard 1.0 you can enable a OVF 0.9 legacy mode with the
+    <computeroutput>--legacy09</computeroutput> option.</para>
+  </sect1>
+
+  <sect1 id="vboxmanage-startvm">
+    <title>VBoxManage startvm</title>
+
+    <para>This command starts a virtual machine that is currently in the
+    "Powered off" or "Saved" states.</para>
+
+    <note>
+      <para>This is provided for backwards compatibility only. We recommend to
+      start virtual machines directly by running the respective front-end, as
+      you might otherwise miss important error and state information that
+      VirtualBox may display on the console. This is especially important for
+      front-ends other than <computeroutput>VirtualBox</computeroutput>, our
+      graphical user interface, because those cannot display error messages in
+      a popup window. See <xref linkend="vboxheadless" /> for more
+      information.</para>
+    </note>
+
+    <para>The optional <computeroutput>--type</computeroutput> specifier
+    determines whether the machine will be started in a window (GUI mode,
+    which is the default) or whether the output should go through
+    <computeroutput>VBoxHeadless</computeroutput>, with VRDP enabled or not;
+    see <xref linkend="vboxheadless" /> for more information. The list of
+    types is subject to change, and it's not guaranteed that all types are
+    accepted by any product variant.</para>
+
+    <para>The following values are allowed:</para>
+
+    <glosslist>
+      <glossentry>
+        <glossterm>gui</glossterm>
+
+        <glossdef>
+          <para>Starts a VM showing a GUI window. This is the default.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>vrdp</glossterm>
+
+        <glossdef>
+          <para>Starts a VM showing a GUI window, with its graphics card
+          output accessible by an RDP client.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>headless</glossterm>
+
+        <glossdef>
+          <para>Starts a VM without a window for remote RDP display
+          only.</para>
+        </glossdef>
+      </glossentry>
+    </glosslist>
+  </sect1>
+
+  <sect1 id="vboxmanage-controlvm">
+    <title>VBoxManage controlvm</title>
+
+    <para>The <computeroutput>controlvm</computeroutput> subcommand allows you
+    to change the state of a virtual machine that is currently running. The
+    following can be specified:</para>
+
+    <para><itemizedlist>
+        <listitem>
+          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
+          pause</computeroutput> temporarily puts a virtual machine on hold,
+          without changing its state for good. The VM window will be painted
+          in gray to indicate that the VM is currently paused. (This is
+          equivalent to selecting the "Pause" item in the "Machine" menu of
+          the GUI.)</para>
+        </listitem>
+
+        <listitem>
+          <para>Use <computeroutput>VBoxManage controlvm &lt;vm&gt;
+          resume</computeroutput> to undo a previous
+          <computeroutput>pause</computeroutput> command. (This is equivalent
+          to selecting the "Resume" item in the "Machine" menu of the
+          GUI.)</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
+          reset</computeroutput> has the same effect on a virtual machine as
+          pressing the "Reset" button on a real computer: a cold reboot of the
+          virtual machine, which will restart and boot the guest operating
+          system again immediately. The state of the VM is not saved
+          beforehand, and data may be lost. (This is equivalent to selecting
+          the "Reset" item in the "Machine" menu of the GUI.)</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
+          poweroff</computeroutput> has the same effect on a virtual machine
+          as pulling the power cable on a real computer. Again, the state of
+          the VM is not saved beforehand, and data may be lost. (This is
+          equivalent to selecting the "Close" item in the "Machine" menu of
+          the GUI or pressing the window's close button, and then selecting
+          "Power off the machine" in the dialog.)</para>
+
+          <para>After this, the VM's state will be "Powered off". From there,
+          it can be started again; see <xref
+          linkend="vboxmanage-startvm" />.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
+          savestate</computeroutput> will save the current state of the VM to
+          disk and then stop the VM. (This is equivalent to selecting the
+          "Close" item in the "Machine" menu of the GUI or pressing the
+          window's close button, and then selecting "Save the machine state"
+          in the dialog.)</para>
+
+          <para>After this, the VM's state will be "Saved". From there, it can
+          be started again; see <xref linkend="vboxmanage-startvm" />.</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>VBoxManage controlvm &lt;vm&gt; teleport
+          --hostname &lt;name&gt; --port &lt;port&gt; [--password
+          &lt;password&gt;]</computeroutput> makes the machine the source of a
+          teleporting operation and initiates a teleport to the given target.
+          See <xref linkend="teleporting" /> for an introduction. If the
+          optional password is specified, it must match the password that was
+          given to the <computeroutput>modifyvm</computeroutput> command for
+          the target machine; see <xref
+          linkend="vboxmanage-modifyvm-teleport" /> for details.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>A few extra options are available with
+    <computeroutput>controlvm</computeroutput> that do not directly affect the
+    VM's running state:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>The <computeroutput>setlinkstate&lt;1-N&gt;</computeroutput>
+        operation connects or disconnects virtual network cables from their
+        network interfaces.</para>
+      </listitem>
+
+      <listitem>
+        <para><computeroutput>nic&lt;1-N&gt;
+        null|nat|bridged|intnet|hostonly</computeroutput>: With this, you can
+        set, for each of the VM's virtual network cards, what type of
+        networking should be available. They can be not connected to the host
+        (<computeroutput>null</computeroutput>), use network address
+        translation (<computeroutput>nat</computeroutput>), bridged networking
+        (<computeroutput>bridged</computeroutput>) or communicate with other
+        virtual machines using internal networking
+        (<computeroutput>intnet</computeroutput>) or host-only networking
+        (<computeroutput>hostonly</computeroutput>). These options correspond
+        to the modes which are described in detail in <xref
+        linkend="networkingmodes" />.</para>
+      </listitem>
+
+      <listitem>
+        <para><computeroutput>usbattach</computeroutput> and
+        <computeroutput>usbdettach</computeroutput> make host USB devices
+        visible to the virtual machine on the fly, without the need for
+        creating filters first. The USB devices can be specified by UUID
+        (unique identifier) or by address on the host system.</para>
+
+        <para>You can use <computeroutput>VBoxManage list
+        usbhost</computeroutput> to locate this information.</para>
+      </listitem>
+
+      <listitem>
+        <para><computeroutput>vrdp on|off</computeroutput> lets you enable or
+        disable the built-in VRDP server.</para>
+      </listitem>
+
+      <listitem>
+        <para><computeroutput>vrdpport default|&lt;ports&gt;</computeroutput>
+        changes the port or a range of ports that the VRDP server can bind to;
+        "default" or "0" means port 3389, the standard port for RDP. For
+        details, see the description for the
+        <computeroutput>--vrdpport</computeroutput> option in <xref
+        linkend="vboxmanage-modifyvm-other" />.</para>
+      </listitem>
+
+      <listitem>
+        <para><computeroutput>setvideomodehint</computeroutput> requests that
+        the guest system change to a particular video mode. This requires that
+        the Guest Additions be installed, and will not work for all guest
+        systems.</para>
+      </listitem>
+
+      <listitem>
+        <para>The <computeroutput>setcredentials</computeroutput> operation is
+        used for remote logons in Windows guests. For details, please refer to
+        <xref linkend="autologon" />.</para>
+      </listitem>
+
+      <listitem>
+        <para>The <computeroutput>guestmemoryballoon</computeroutput>
+        operation changes the size of the guest memory balloon, that is,
+        memory allocated by the VirtualBox Guest Additions from the guest
+        operating system and returned to the hypervisor for re-use by other
+        virtual machines. This must be specified in megabytes. For details,
+        see <xref linkend="guestadd-balloon" />.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage discardstate</title>
+
+    <para>This command discards the saved state of a virtual machine which is
+    not currently running, which will cause its operating system to restart
+    next time you start it. This is the equivalent of pulling out the power
+    cable on a physical machine, and should be avoided if possible.</para>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage snapshot</title>
+
+    <para>This command is used to control snapshots from the command line. A
+    snapshot consists of a complete copy of the virtual machine settings,
+    copied at the time when the snapshot was taken, and optionally a virtual
+    machine saved state file if the snapshot was taken while the machine was
+    running. After a snapshot has been taken, VirtualBox creates differencing
+    hard disk for each normal hard disk associated with the machine so that
+    when a snapshot is restored, the contents of the virtual machine's virtual
+    hard disks can be quickly reset by simply dropping the pre-existing
+    differencing files.</para>
+
+    <para>The <computeroutput>take</computeroutput> operation takes a snapshot
+    of the current state of the virtual machine. You must supply a name for
+    the snapshot and can optionally supply a description. The new snapshot is
+    inserted into the snapshots tree as a child of the current snapshot and
+    then becomes the new current snapshot.</para>
+
+    <para>The <computeroutput>delete</computeroutput> operation deletes a
+    snapshot (specified by name or by UUID). This can take a while to finish
+    since the differencing images associated with the snapshot might need to
+    be merged with their child differencing images.</para>
+
+    <para>The <computeroutput>restore</computeroutput> operation will restore
+    the given snapshot (specified by name or by UUID) by resetting the virtual
+    machine's settings and current state to that of the snapshot. The previous
+    current state of the machine will be lost. After this, the given snapshot
+    becomes the new "current" snapshot so that subsequent snapshots are
+    inserted under the snapshot from which was restored.</para>
+
+    <para>The <computeroutput>restorecurrent</computeroutput> operation is a
+    shortcut to restore the current snapshot (i.e. the snapshot from which the
+    current state is derived). This subcommand is equivalent to using the
+    "restore" subcommand with the name or UUID of the current snapshot, except
+    that it avoids the extra step of determining that name or UUID.</para>
+
+    <para>With the <computeroutput>edit</computeroutput> operation, you can
+    change the name or description of an existing snapshot.</para>
+
+    <para>With the <computeroutput>showvminfo</computeroutput> operation, you
+    can view the virtual machine settings that were stored with an existing
+    snapshot.</para>
+  </sect1>
+
+  <sect1 id="vboxmanage-storage">
+    <title>VBoxManage storagectl / storageattach</title>
+
+    <para>These commands allow to attach new storage controllers to a VM,
+    modify or remove the existing ones and also allows the user to change the
+    hard disk, DVD or floppy images attached to them. The list of the storage
+    controllers attached to the VM can be found by the command:</para>
+
+    <screen>VBoxManage showvminfo &lt;vmname&gt;</screen>
+
+    <para>See also <xref linkend="vboxmanage-showvminfo" />.</para>
+
+    <sect2 id="vboxmanage-storagectl">
+      <title>VBoxManage storagectl</title>
+
+      <para>This command attaches/modifies/removes a storage controller. The
+      syntax is as follows:</para>
+
+      <screen>VBoxManage storagectl       &lt;uuid|vmname&gt;
+                            --name &lt;name&gt;
+                            [--add &lt;ide/sata/scsi/floppy&gt;]
+                            [--controller &lt;LsiLogic/BusLogic/IntelAhci/PIIX3/
+                                           PIIX4/ICH6/I8207&gt;]
+                            [--sataideemulation&lt;1-4&gt; &lt;1-30&gt;]
+                            [--sataportcount &lt;1-30&gt;]
+                            [--hostiocache on|off]
+                            [--remove]</screen>
+
+      <para>where the parameters mean: <glosslist>
+          <glossentry>
+            <glossterm>uuid|vmname</glossterm>
+
+            <glossdef>
+              <para>The VM UUID or VM Name. Mandatory.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>name</glossterm>
+
+            <glossdef>
+              <para>Name of the storage controller. Mandatory.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>add</glossterm>
+
+            <glossdef>
+              <para>Define the type of the system bus to which the storage
+              controller must be connected.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>controller</glossterm>
+
+            <glossdef>
+              <para>Allows to choose the type of chipset being emulated for
+              the given storage controller.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>sataideemulation</glossterm>
+
+            <glossdef>
+              <para>This specifies which SATA ports should operate in IDE
+              emulation mode. As explained in <xref
+              linkend="harddiskcontrollers" />, by default, this is the case
+              for SATA ports 1-4; with this command, you can map four IDE
+              channels to any of the 30 supported SATA ports.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>sataportcount</glossterm>
+
+            <glossdef>
+              <para>This determines how many ports the SATA controller should
+              support.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>hostiocache</glossterm>
+
+            <glossdef>
+              <para>Configures the use of the host I/O cache for all disk
+              images attached to this storage controller. For details, please
+              see <xref linkend="iocaching" />.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>remove</glossterm>
+
+            <glossdef>
+              <para>Removes the storage controller from the VM config.</para>
+            </glossdef>
+          </glossentry>
+        </glosslist></para>
+    </sect2>
+
+    <sect2>
+      <title>VBoxManage storageattach</title>
+
+      <para>This command attaches/modifies/removes a storage medium connected
+      to the storage controller named by --storagectl. The syntax is as
+      follows:</para>
+
+      <screen>VBoxManage storageattach    &lt;uuid|vmname&gt;
+                            --storagectl &lt;name&gt;
+                            --port &lt;number&gt;
+                            --device &lt;number&gt;
+                            [--type dvddrive|hdd|fdd
+                             --medium none|emptydrive|uuid|filename|host:&lt;drive&gt;]
+                            [--passthrough on|off]
+                            [--forceunmount]</screen>
+
+      <para>where the parameters mean: <glosslist>
+          <glossentry>
+            <glossterm>uuid|vmname</glossterm>
+
+            <glossdef>
+              <para>The VM UUID or VM Name. Mandatory.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>storagectl</glossterm>
+
+            <glossdef>
+              <para>Name of the storage controller. Mandatory.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>port</glossterm>
+
+            <glossdef>
+              <para>Port number to which the medium has to be
+              attached/detached/modified. Mandatory.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>device</glossterm>
+
+            <glossdef>
+              <para>Device Number to which the medium has to be
+              attached/detached/modified. Mandatory.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>type</glossterm>
+
+            <glossdef>
+              <para>Define the type of the drive to which the medium is being
+              attached/detached/modified.</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>medium</glossterm>
+
+            <glossdef>
+              <para>Specifies what is to be attached. The following values are
+              supported:<itemizedlist>
+                  <listitem>
+                    <para>"none": Any existing device should be removed from
+                    the given slot.</para>
+
+                    <note>
+                      <para>DVD/floppy drives or harddisks cannot be removed
+                      while the VM is running.</para>
+                    </note>
+                  </listitem>
+
+                  <listitem>
+                    <para>"emptydrive": This is only allowed if the given slot
+                    is a DVD or floppy drive. In this case, the slot behaves
+                    like a removeable drive into which no media has been
+                    inserted.</para>
+                  </listitem>
+
+                  <listitem>
+                    <para>If a UUID is specified, it must be the UUID of a
+                    storage medium that is already known to VirtualBox (e.g.
+                    because it has been attached to another virtual machine).
+                    This medium is then attached to the given device
+                    slot.</para>
+                  </listitem>
+
+                  <listitem>
+                    <para>If a filename is specified, it must be the full path
+                    of an existing disk image (ISO, RAW, VDI, VMDK or other),
+                    which is then attached to the given device slot.</para>
+                  </listitem>
+
+                  <listitem>
+                    <para>"host:&lt;drive&gt;: This is only allowed if the
+                    given slot is a DVD or floppy drive, in which case the
+                    device slot is attached to the specified DVD or floppy
+                    drive on the host computer.</para>
+                  </listitem>
+                </itemizedlist></para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>passthrough</glossterm>
+
+            <glossdef>
+              <para>With this, you can enable DVD writing support (currently
+              experimental; see <xref linkend="storage-write-cds" />).</para>
+            </glossdef>
+          </glossentry>
+
+          <glossentry>
+            <glossterm>forceunmount</glossterm>
+
+            <glossdef>
+              <para>If this option is specified then you can unmount the
+              DVD/CD/Floppy or mount a new DVD/CD/Floppy even if the previous
+              one is locked down by the guest for reading.</para>
+            </glossdef>
+          </glossentry>
+        </glosslist></para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage showhdinfo</title>
+
+    <para>This command shows information about a virtual hard disk image,
+    notably its size, its size on disk, its type and the VM it is in use
+    by.<note>
+        <para>For compatibility with earlier versions of VirtualBox, the
+        "showvdiinfo" command is also supported and mapped internally to the
+        "showhdinfo" command.</para>
+      </note></para>
+  </sect1>
+
+  <sect1 id="vboxmanage-createvdi">
+    <title>VBoxManage createhd</title>
+
+    <para>This command creates a new virtual hard disk image. The syntax is as
+    follows:</para>
+
+    <screen>VBoxManage createhd         --filename &lt;filename&gt;
+                            --size &lt;megabytes&gt;
+                            [--format VDI|VMDK|VHD] (default: VDI)
+                            [--variant Standard,Fixed,Split2G,Stream,ESX]
+                            [--type normal|writethrough] (default: normal)
+                            [--comment &lt;comment&gt;]
+                            [--remember]</screen>
+
+    <para>where the parameters mean:<glosslist>
+        <glossentry>
+          <glossterm>filename</glossterm>
+
+          <glossdef>
+            <para>Allows to choose a file name. Mandatory.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>size</glossterm>
+
+          <glossdef>
+            <para>Allows to define the image capacity, in 1 MiB units.
+            Mandatory.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>format</glossterm>
+
+          <glossdef>
+            <para>Allows to choose a file format for the output file different
+            from the file format of the input file.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>variant</glossterm>
+
+          <glossdef>
+            <para>Allows to choose a file format variant for the output file.
+            It is a comma-separated list of variant flags. Not all
+            combinations are supported, and specifying inconsistent flags will
+            result in an error message.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>type</glossterm>
+
+          <glossdef>
+            <para>Only honored if --remember is also specified. Defines what
+            kind of hard disk type this image should be.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>comment</glossterm>
+
+          <glossdef>
+            <para>Allows to attach a comment to the image.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>remember</glossterm>
+
+          <glossdef>
+            <para>Keep the destination image registered after it was
+            successfully written.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist> <note>
+        <para>For compatibility with earlier versions of VirtualBox, the
+        "createvdi" command is also supported and mapped internally to the
+        "createhd" command.</para>
+      </note></para>
+  </sect1>
+
+  <sect1 id="vboxmanage-modifyvdi">
+    <title>VBoxManage modifyhd</title>
+
+    <para>With the <computeroutput>modifyhd</computeroutput> command, you can
+    change the type of an existing image between the normal, immutable and
+    write-through modes; see <xref linkend="hdimagewrites" /> for
+    details.<note>
+        <para>For compatibility with earlier versions of VirtualBox, the
+        "modifyvdi" command is also supported and mapped internally to the
+        "modifyhd" command.</para>
+      </note></para>
+
+    <para>For immutable (differencing) hard disks only, the
+    <computeroutput>modifyhd autoreset on|off</computeroutput> command
+    determines whether the disk is automatically reset on every VM startup
+    (again, see <xref linkend="hdimagewrites" />). The default is "on".</para>
+
+    <para>In addition, the <computeroutput>modifyhd --compact</computeroutput>
+    command can be used to compact disk images, i.e. remove blocks that only
+    contains zeroes. For this operation to be effective, it is required to
+    zero out free space in the guest system using a suitable software tool.
+    Microsoft provides the <computeroutput>sdelete</computeroutput> tool for
+    Windows guests. Execute <computeroutput>sdelete -c</computeroutput> in the
+    guest to zero the free disk space before compressing the virtual disk
+    image. Compaction works both for base images and for diff images created
+    as part of a snapshot.</para>
+  </sect1>
+
+  <sect1 id="vboxmanage-clonevdi">
+    <title>VBoxManage clonehd</title>
+
+    <para>This command duplicates a registered virtual hard disk image to a
+    new image file with a new unique identifier (UUID). The new image can be
+    transferred to another host system or imported into VirtualBox again using
+    the Virtual Media Manager; see <xref linkend="vdis" /> and <xref
+    linkend="cloningvdis" />. The syntax is as follows:</para>
+
+    <screen>VBoxManage clonehd         &lt;uuid&gt;|&lt;filename&gt; &lt;outputfile&gt;
+                           [--format VDI|VMDK|VHD|RAW|&lt;other&gt;]
+                           [--variant Standard,Fixed,Split2G,Stream,ESX]
+                           [--type normal|writethrough|immutable]
+                           [--remember]</screen>
+
+    <para>where the parameters mean:<glosslist>
+        <glossentry>
+          <glossterm>format</glossterm>
+
+          <glossdef>
+            <para>Allow to choose a file format for the output file different
+            from the file format of the input file.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>variant</glossterm>
+
+          <glossdef>
+            <para>Allow to choose a file format variant for the output file.
+            It is a comma-separated list of variant flags. Not all
+            combinations are supported, and specifying inconsistent flags will
+            result in an error message.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>type</glossterm>
+
+          <glossdef>
+            <para>Only honored if --remember is also specified. Defines what
+            kind of hard disk type this image should be.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>remember</glossterm>
+
+          <glossdef>
+            <para>Keep the destination image registered after it was
+            successfully written.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist> <note>
+        <para>For compatibility with earlier versions of VirtualBox, the
+        "clonevdi" command is also supported and mapped internally to the
+        "clonehd" command.</para>
+      </note></para>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage convertfromraw</title>
+
+    <para>This command converts a raw disk image to a VirtualBox Disk Image
+    (VDI) file. The syntax is as follows:</para>
+
+    <screen>VBoxManage convertfromraw   &lt;filename&gt; &lt;outputfile&gt;
+                            [--format VDI|VMDK|VHD]
+                            [--variant Standard,Fixed,Split2G,Stream,ESX]
+VBoxManage convertfromraw   stdin &lt;outputfile&gt; &lt;bytes&gt;
+                            [--format VDI|VMDK|VHD]
+                            [--variant Standard,Fixed,Split2G,Stream,ESX]</screen>
+
+    <para>where the parameters mean:<glosslist>
+        <glossentry>
+          <glossterm>format</glossterm>
+
+          <glossdef>
+            <para>Select the disk image format to create. Default is
+            VDI.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>variant</glossterm>
+
+          <glossdef>
+            <para>Allow to choose a file format variant for the output file.
+            It is a comma-separated list of variant flags. Not all
+            combinations are supported, and specifying inconsistent flags will
+            result in an error message.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist> The second form forces VBoxManage to read the content for
+    the disk image from standard input (useful for using that command in a
+    pipe).</para>
+
+    <para><note>
+        <para>For compatibility with earlier versions of VirtualBox, the
+        "convertdd" command is also supported and mapped internally to the
+        "convertfromraw" command.</para>
+      </note></para>
+  </sect1>
+
+  <sect1 id="vboxmanage-addiscsidisk">
+    <title>VBoxManage addiscsidisk</title>
+
+    <para>The <computeroutput>addiscsidisk</computeroutput> command attaches
+    an iSCSI network storage unit to VirtualBox. The iSCSI target can then be
+    made available to and used by a virtual machine as though it were a
+    standard write-through virtual disk image.</para>
+
+    <para>This command has the following syntax:<screen>VBoxManage addiscsidisk --server &lt;name&gt;|&lt;ip&gt;
+                        --target &lt;target&gt;
+                        [--port &lt;port&gt;]
+                        [--lun &lt;lun&gt;]
+                        [--username &lt;username&gt;]
+                        [--password &lt;password&gt;]
+                        [--type normal|writethrough|immutable]
+                        [--comment &lt;comment&gt;]
+                        [--intnet]</screen></para>
+
+    <para>where the parameters mean:<glosslist>
+        <glossentry>
+          <glossterm>server</glossterm>
+
+          <glossdef>
+            <para>The host name or IP address of the iSCSI target.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>target</glossterm>
+
+          <glossdef>
+            <para>Target name string. This is determined by the iSCSI target
+            and used to identify the storage resource.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>port</glossterm>
+
+          <glossdef>
+            <para>TCP/IP port number of the iSCSI service on the target
+            (optional).</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>lun</glossterm>
+
+          <glossdef>
+            <para>Logical Unit Number of the target resource (optional).
+            Often, this value is zero.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>username, password</glossterm>
+
+          <glossdef>
+            <para>Username and password for target authentication, if required
+            (optional).<note>
+                <para>Currently, username and password are stored without
+                encryption (i.e. in cleartext) in the machine configuration
+                file.</para>
+              </note></para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>type</glossterm>
+
+          <glossdef>
+            <para>Defines what kind of hard disk type this image should
+            be.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>comment</glossterm>
+
+          <glossdef>
+            <para>Any description that you want to have stored with this item
+            (optional; e.g. "Big storage server downstairs"). This is stored
+            internally only and not needed for operation.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>intnet</glossterm>
+
+          <glossdef>
+            <para>Connect to the iSCSI target via Internal Networking. This
+            needs further configuration which is described in <xref
+            linkend="iscsi-intnet" />.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+  </sect1>
+
+  <sect1 id="vboxmanage-closemedium">
+    <title>VBoxManage closemedium</title>
+
+    <para>This commands removes a hard disk, DVD or floppy image from a
+    VirtualBox media registry.<footnote>
+        <para>Before VirtualBox 4.0, it was necessary to call VBoxManage
+        openmedium before a medium could be attached to a virtual machine;
+        that call "registered" the medium with the global VirtualBox media
+        registry. With VirtualBox 4.0 this is no longer necessary; media are
+        added to media registries automatically. The "closemedium" call has
+        been retained, however, to allow for explicitly removing a medium from
+        a registry.</para>
+      </footnote></para>
+
+    <para>Optionally, you can request that the image be deleted. You will get
+    appropriate diagnostics that the deletion failed, however the image will
+    become unregistered in any case.</para>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage getextradata/setextradata</title>
+
+    <para>These commands let you attach and retrieve string data to a virtual
+    machine or to a VirtualBox configuration (by specifying
+    <computeroutput>global</computeroutput> instead of a virtual machine
+    name). You must specify a key (as a text string) to associate the data
+    with, which you can later use to retrieve it. For example:</para>
+
+    <screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
+VBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
+
+    <para>would associate the string "2006.01.01" with the key installdate for
+    the virtual machine Fedora5, and "2006.02.02" on the machine SUSE10. You
+    could retrieve the information as follows:</para>
+
+    <screen>VBoxManage getextradata Fedora5 installdate</screen>
+
+    <para>which would return</para>
+
+    <screen>VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
+(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
+All rights reserved.
+
+Value: 2006.01.01</screen>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage setproperty</title>
+
+    <para>This command is used to change global settings which affect the
+    entire VirtualBox installation. Some of these correspond to the settings
+    in the "Global settings" dialog in the graphical user interface. The
+    following properties are available:<glosslist>
+        <glossentry>
+          <glossterm>hdfolder</glossterm>
+
+          <glossdef>
+            <para>This specifies the default folder that is used to keep disk
+            image files (.vdi, .vmdk, .vhd).</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>machinefolder</glossterm>
+
+          <glossdef>
+            <para>This specifies the default folder in which virtual machine
+            definitions are kept; see <xref linkend="vboxconfigdata" /> for
+            details.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>vrdeauthlibrary</glossterm>
+
+          <glossdef>
+            <para>This specifies which library to use when "external"
+            authentication has been selected for a particular virtual machine;
+            see <xref linkend="vbox-auth" /> for details.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>websrvauthlibrary</glossterm>
+
+          <glossdef>
+            <para>This specifies which library the web service uses to
+            authenticate users. For details about the VirtualBox web service,
+            please refer to the separate VirtualBox SDK reference (see <xref
+            linkend="VirtualBoxAPI" />).</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>vrdelibrary</glossterm>
+
+          <glossdef>
+            <para>This specifies which library implements the VirtualBox
+            Remote Desktop Extension.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>hwvirtexenabled</glossterm>
+
+          <glossdef>
+            <para>This selects whether or not hardware virtualization support
+            is enabled by default.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage usbfilter add/modify/remove</title>
+
+    <para>The <computeroutput>usbfilter</computeroutput> commands are used for
+    working with USB filters in virtual machines, or global filters which
+    affect the whole VirtualBox setup. Global filters are applied before
+    machine-specific filters, and may be used to prevent devices from being
+    captured by any virtual machine. Global filters are always applied in a
+    particular order, and only the first filter which fits a device is
+    applied. So for example, if the first global filter says to hold (make
+    available) a particular Kingston memory stick device and the second to
+    ignore all Kingston devices, that memory stick will be available to any
+    machine with an appropriate filter, but no other Kingston device
+    will.</para>
+
+    <para>When creating a USB filter using <computeroutput>usbfilter
+    add</computeroutput>, you must supply three or four mandatory parameters.
+    The index specifies the position in the list at which the filter should be
+    placed. If there is already a filter at that position, then it and the
+    following ones will be shifted back one place. Otherwise the new filter
+    will be added onto the end of the list. The
+    <computeroutput>target</computeroutput> parameter selects the virtual
+    machine that the filter should be attached to or use "global" to apply it
+    to all virtual machines. <computeroutput>name</computeroutput> is a name
+    for the new filter and for global filters,
+    <computeroutput>action</computeroutput> says whether to allow machines
+    access to devices that fit the filter description ("hold") or not to give
+    them access ("ignore"). In addition, you should specify parameters to
+    filter by. You can find the parameters for devices attached to your system
+    using <computeroutput>VBoxManage list usbhost</computeroutput>. Finally,
+    you can specify whether the filter should be active, and for local
+    filters, whether they are for local devices, remote (over an RDP
+    connection) or either.</para>
+
+    <para>When you modify a USB filter using <computeroutput>usbfilter
+    modify</computeroutput>, you must specify the filter by index (see the
+    output of <computeroutput>VBoxManage list usbfilters</computeroutput> to
+    find global filter indexes and that of <computeroutput>VBoxManage
+    showvminfo</computeroutput> to find indexes for individual machines) and
+    by target, which is either a virtual machine or "global". The properties
+    which can be changed are the same as for <computeroutput>usbfilter
+    add</computeroutput>. To remove a filter, use <computeroutput>usbfilter
+    remove</computeroutput> and specify the index and the target.</para>
+  </sect1>
+
+  <sect1>
+    <title>VBoxManage sharedfolder add/remove</title>
+
+    <para>This command allows you to share folders on the host computer with
+    guest operating systems. For this, the guest systems must have a version
+    of the VirtualBox Guest Additions installed which supports this
+    functionality.</para>
+
+    <para>Shared folders are described in detail in <xref
+    linkend="sharedfolders" />.</para>
+  </sect1>
+
+  <sect1>
+    <title id="metrics">VBoxManage metrics</title>
+
+    <para>This command supports monitoring the usage of system resources.
+    Resources are represented by various metrics associated with the host
+    system or a particular VM. For example, the host system has a
+    <computeroutput>CPU/Load/User</computeroutput> metric that shows the
+    percentage of time CPUs spend executing in user mode over a specific
+    sampling period.</para>
+
+    <para>Metric data is collected and retained internally; it may be
+    retrieved at any time with the <computeroutput>VBoxManage metrics
+    query</computeroutput> subcommand. The data is available as long as the
+    background <computeroutput>VBoxSVC</computeroutput> process is alive. That
+    process terminates shortly after all VMs and frontends have been
+    closed.</para>
+
+    <para>By default no metrics are collected at all. Metrics collection does
+    not start until <computeroutput>VBoxManage metrics setup</computeroutput>
+    is invoked with a proper sampling interval and the number of metrics to be
+    retained. The interval is measured in seconds. For example, to enable
+    collecting the host processor and memory usage metrics every second and
+    keeping the 5 most current samples, the following command can be
+    used:</para>
+
+    <screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
+
+    <para>Metric collection can only be enabled for started VMs. Collected
+    data and collection settings for a particular VM will disappear as soon as
+    it shuts down. Use <computeroutput>VBoxManage metrics list
+    </computeroutput> subcommand to see which metrics are currently available.
+    You can also use <computeroutput>--list</computeroutput> option with any
+    subcommand that modifies metric settings to find out which metrics were
+    affected.</para>
+
+    <para>Note that the <computeroutput>VBoxManage metrics
+    setup</computeroutput> subcommand discards all samples that may have been
+    previously collected for the specified set of objects and metrics.</para>
+
+    <para>To enable or disable metrics collection without discarding the data
+    <computeroutput>VBoxManage metrics enable</computeroutput> and
+    <computeroutput>VBoxManage metrics disable</computeroutput> subcommands
+    can be used. Note that these subcommands expect metrics, not submetrics,
+    like <code>CPU/Load</code> or <code>RAM/Usage</code> as parameters. In
+    other words enabling <code>CPU/Load/User</code> while disabling
+    <code>CPU/Load/Kernel</code> is not supported.</para>
+
+    <para>The host and VMs have different sets of associated metrics.
+    Available metrics can be listed with <computeroutput>VBoxManage metrics
+    list</computeroutput> subcommand.</para>
+
+    <para>A complete metric name may include an aggregate function. The name
+    has the following form:
+    <computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
+    For example, <computeroutput>RAM/Usage/Free:min</computeroutput> stands
+    for the minimum amount of available memory over all retained data if
+    applied to the host object.</para>
+
+    <para>Subcommands may apply to all objects and metrics or can be limited
+    to one object or/and a list of metrics. If no objects or metrics are given
+    in the parameters, the subcommands will apply to all available metrics of
+    all objects. You may use an asterisk
+    ("<computeroutput>*</computeroutput>") to explicitly specify that the
+    command should be applied to all objects or metrics. Use "host" as the
+    object name to limit the scope of the command to host-related metrics. To
+    limit the scope to a subset of metrics, use a metric list with names
+    separated by commas.</para>
+
+    <para>For example, to query metric data on the CPU time spent in user and
+    kernel modes by the virtual machine named "test", you can use the
+    following command:</para>
+
+    <screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
+
+    <para>The following list summarizes the available subcommands:</para>
+
+    <glosslist>
+      <glossentry>
+        <glossterm>list</glossterm>
+
+        <glossdef>
+          <para>This subcommand shows the parameters of the currently existing
+          metrics. Note that VM-specific metrics are only available when a
+          particular VM is running.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>setup</glossterm>
+
+        <glossdef>
+          <para>This subcommand sets the interval between taking two samples
+          of metric data and the number of samples retained internally. The
+          retained data is available for displaying with the
+          <code>query</code> subcommand. The <computeroutput>--list
+          </computeroutput> option shows which metrics have been modified as
+          the result of the command execution.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>enable</glossterm>
+
+        <glossdef>
+          <para>This subcommand "resumes" data collection after it has been
+          stopped with <code>disable</code> subcommand. Note that specifying
+          submetrics as parameters will not enable underlying metrics. Use
+          <computeroutput>--list</computeroutput> to find out if the command
+          did what was expected.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>disable</glossterm>
+
+        <glossdef>
+          <para>This subcommand "suspends" data collection without affecting
+          collection parameters or collected data. Note that specifying
+          submetrics as parameters will not disable underlying metrics. Use
+          <computeroutput>--list</computeroutput> to find out if the command
+          did what was expected.</para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>query</glossterm>
+
+        <glossdef>
+          <para>This subcommand retrieves and displays the currently retained
+          metric data.<note>
+              <para>The <code>query</code> subcommand does not remove or
+              "flush" retained data. If you query often enough you will see
+              how old samples are gradually being "phased out" by new
+              samples.</para>
+            </note></para>
+        </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm>collect</glossterm>
+
+        <glossdef>
+          <para>This subcommand sets the interval between taking two samples
+          of metric data and the number of samples retained internally. The
+          collected data is displayed periodically until Ctrl-C is pressed
+          unless the <computeroutput>--detach</computeroutput> option is
+          specified. With the <computeroutput>--detach</computeroutput>
+          option, this subcommand operates the same way as <code>setup</code>
+          does. The <computeroutput>--list</computeroutput> option shows which
+          metrics match the specified filter.</para>
+        </glossdef>
+      </glossentry>
+    </glosslist>
+  </sect1>
+
+  <sect1 id="vboxmanage-guestproperty">
+    <title>VBoxManage guestproperty</title>
+
+    <para>The "guestproperty" commands allow you to get or set properties of a
+    running virtual machine. Please see <xref linkend="guestadd-guestprops" />
+    for an introduction. As explained there, guest properties are arbitrary
+    key/value string pairs which can be written to and read from by either the
+    guest or the host, so they can be used as a low-volume communication
+    channel for strings, provided that a guest is running and has the Guest
+    Additions installed. In addition, a number of values whose keys begin with
+    "/VirtualBox/" are automatically set and maintained by the Guest
+    Additions.</para>
+
+    <para>The following subcommands are available (where
+    <computeroutput>&lt;vm&gt;</computeroutput>, in each case, can either be a
+    VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
+        <listitem>
+          <para><computeroutput>enumerate &lt;vm&gt; [-patterns
+          &lt;pattern&gt;]</computeroutput>: This lists all the guest
+          properties that are available for the given VM, including the value.
+          This list will be very limited if the guest's service process cannot
+          be contacted, e.g. because the VM is not running or the Guest
+          Additions are not installed.</para>
+
+          <para>If <computeroutput>--patterns &lt;pattern&gt;</computeroutput>
+          is specified, it acts as a filter to only list properties that match
+          the given pattern. The pattern can contain the following wildcard
+          characters:<itemizedlist>
+              <listitem>
+                <para><computeroutput>*</computeroutput> (asterisk):
+                represents any number of characters; for example,
+                "<computeroutput>/VirtualBox*</computeroutput>" would match
+                all properties beginning with "/VirtualBox".</para>
+              </listitem>
+
+              <listitem>
+                <para><computeroutput>?</computeroutput> (question mark):
+                represents a single arbitrary character; for example,
+                "<computeroutput>fo?</computeroutput>" would match both "foo"
+                and "for".</para>
+              </listitem>
+
+              <listitem>
+                <para><computeroutput>|</computeroutput> (pipe symbol): can be
+                used to specify multiple alternative patterns; for example,
+                "<computeroutput>s*|t*</computeroutput>" would match anything
+                starting with either "s" or "t".</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>get &lt;vm&gt;</computeroutput>: This
+          retrieves the value of a single property only. If the property
+          cannot be found (e.g. because the guest is not running), this will
+          print "No value set!".</para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>set &lt;vm&gt; &lt;property&gt; [&lt;value&gt;
+          [-flags &lt;flags&gt;]]</computeroutput>: This allows you to set a
+          guest property by specifying the key and value. If
+          <computeroutput>&lt;value&gt;</computeroutput> is omitted, the
+          property is deleted. With <computeroutput>--flags</computeroutput>
+          you can optionally specify additional behavior (you can combine
+          several by separating them with commas):<itemizedlist>
+              <listitem>
+                <para><computeroutput>TRANSIENT</computeroutput>: the value
+                will not be stored with the VM data when the VM exits;</para>
+              </listitem>
+
+              <listitem>
+                <para><computeroutput>RDONLYGUEST</computeroutput>: the value
+                can only be changed by the host, but the guest can only read
+                it;</para>
+              </listitem>
+
+              <listitem>
+                <para><computeroutput>RDONLYHOST</computeroutput>: reversely,
+                the value can only be changed by the guest, but the host can
+                only read it;</para>
+              </listitem>
+
+              <listitem>
+                <para><computeroutput>READONLY</computeroutput>: a combination
+                of the two, the value cannot be changed at all.</para>
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para><computeroutput>wait &lt;vm&gt; &lt;pattern&gt; --timeout
+          &lt;timeout&gt;</computeroutput>: This waits for a particular value
+          described by "pattern" to change or to be deleted or created. The
+          pattern rules are the same as for the "enumerate" subcommand
+          above.</para>
+        </listitem>
+      </itemizedlist></para>
+  </sect1>
+
+  <sect1 id="vboxmanage-guestcontrol">
+    <title>VBoxManage guestcontrol</title>
+
+    <para>The "guestcontrol" commands allow you to control certain things
+    inside a guest from the host. Please see <xref
+    linkend="guestadd-guestcontrol" /> for an introduction.</para>
+
+    <para>Generally, the syntax is as follows:</para>
+
+    <screen>VBoxManage guestcontrol &lt;command&gt;</screen>
+
+    <para>At this time, the only available
+    <computeroutput>&lt;command&gt;</computeroutput> is "execute", which
+    allows for executing a program/script (process) which is already installed
+    and runnable on the guest. This command only works while a VM is up and
+    running and has the following syntax:</para>
+
+    <screen>VBoxManage guestcontrol execute &lt;vmname&gt;|&lt;uuid&gt;
+        &lt;pathToProgram&gt;
+        --username &lt;name&gt; --password &lt;password&gt;
+        [--arguments "&lt;arguments&gt;"]
+        [--environment "&lt;NAME&gt;=&lt;VALUE&gt; [&lt;NAME&gt;=&lt;VALUE&gt;]"]
+        [--flags &lt;flags&gt;] [--timeout &lt;msec&gt;]
+        [--verbose] [--wait-for exit,stdout,stderr||]</screen>
+
+    <para>where the parameters mean: <glosslist>
+        <glossentry>
+          <glossterm>uuid|vmname</glossterm>
+
+          <glossdef>
+            <para>The VM UUID or VM name. Mandatory.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>pathToProgram</glossterm>
+
+          <glossdef>
+            <para>Absolute path and process name of process to execute in the
+            guest, e.g.
+            <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>--arguments "&lt;arguments&gt;"</glossterm>
+
+          <glossdef>
+            <para>One or more arguments to pass to the process being
+            executed.</para>
+
+            <para>Arguments containing spaces must be enclosed in quotation
+            marks. More than one <computeroutput>--arguments</computeroutput>
+            at a time can be specified to keep the command line tidy.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>--environment "&lt;NAME&gt;=&lt;VALUE&gt;"</glossterm>
+
+          <glossdef>
+            <para>One or more environment variables to be set or unset.</para>
+
+            <para>By default, the new process in the guest will be created
+            with the the standard environment of the guest OS. This option
+            allows for modifying that environment. To set/modify a variable, a
+            pair of <computeroutput>NAME=VALUE</computeroutput> must be
+            specified; to unset a certain variable, the name with no value
+            must set, e.g. <computeroutput>NAME=</computeroutput>.</para>
+
+            <para>Arguments containing spaces must be enclosed in quotation
+            marks. More than one
+            <computeroutput>--environment</computeroutput> at a time can be
+            specified to keep the command line tidy.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>--flags &lt;flags&gt;</glossterm>
+
+          <glossdef>
+            <para>Additional flags to set. This is not used at the
+            moment.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>--timeout &lt;msec&gt;</glossterm>
+
+          <glossdef>
+            <para>Value (in milliseconds) that specifies the time how long the
+            started process is allowed to run and how long VBoxManage waits
+            for getting output from that process. If no timeout is specified,
+            VBoxManage will wait forever until the started process ends or an
+            error occured.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>--username &lt;name&gt;</glossterm>
+
+          <glossdef>
+            <para>Name of the user the process should run under. This user
+            must exist on the guest OS.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>--password &lt;password&gt;</glossterm>
+
+          <glossdef>
+            <para>Password of the user account specified with
+            <computeroutput>--username</computeroutput>. If not given, an
+            empty password is assumed.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>--verbose</glossterm>
+
+          <glossdef>
+            <para>Tells VBoxManage to be more verbose during the
+            execution.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>--wait-for &lt;action&gt;</glossterm>
+
+          <glossdef>
+            <para>Tells VBoxManage to wait for a certain action to happen and
+            react to it. The following actions are available: <glosslist>
+                <glossentry>
+                  <glossterm>exit</glossterm>
+
+                  <glossdef>
+                    <para>Waits until the process ends and outputs its exit
+                    code along with the exit reason/flags.</para>
+                  </glossdef>
+                </glossentry>
+
+                <glossentry>
+                  <glossterm>stdout or stderr</glossterm>
+
+                  <glossdef>
+                    <para>Waits until the process ends and outputs its exit
+                    code along with the exit reason/flags. After that
+                    VBoxManage retrieves the output collected from the guest
+                    process's stdout and stderr.</para>
+                  </glossdef>
+                </glossentry>
+              </glosslist></para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+
+    <para><note>
+        <para>On Windows there are certain limitations for graphical
+        applications; please see <xref linkend="KnownIssues" /> for more
+        information.</para>
+      </note> Examples: <screen>VBoxManage --nologo guestcontrol execute "My VM" "/bin/ls" --arguments "-l /usr"
+           --username foo --password bar --wait-for stdout</screen> <screen>VBoxManage --nologo guestcontrol execute "My VM" "c:\\windows\\system32\\ipconfig.exe"
+           --username foo --password bar --wait-for stdout</screen> Note that
+    the double backslashes in the second example are only required on Unix
+    hosts.</para>
+  </sect1>
+
+  <sect1 id="vboxmanage-dhcpserver">
+    <title>VBoxManage dhcpserver</title>
+
+    <para>The "dhcpserver" commands allow you to control the DHCP server that
+    is built into VirtualBox. You may find this useful when using internal or
+    host-only networking. (Theoretically, you can enable it for a bridged
+    network as well, but that will likely cause conflicts with other DHCP
+    servers in your physical network.)</para>
+
+    <para>Use the following command line options:<itemizedlist>
+        <listitem>
+          <para>If you use internal networking for a virtual network adapter
+          of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
+          --netname &lt;network_name&gt;</computeroutput>, where
+          <computeroutput>&lt;network_name&gt;</computeroutput> is the same
+          network name you used with <computeroutput>VBoxManage modifyvm
+          &lt;vmname&gt; --intnet&lt;X&gt;
+          &lt;network_name&gt;</computeroutput>.</para>
+        </listitem>
+
+        <listitem>
+          <para>If you use host-only networking for a virtual network adapter
+          of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
+          --ifname &lt;hostonly_if_name&gt;</computeroutput> instead, where
+          <computeroutput>&lt;hostonly_if_name&gt;</computeroutput> is the
+          same host-only interface name you used with
+          <computeroutput>VBoxManage modifyvm &lt;vmname&gt;
+          --hostonlyadapter&lt;X&gt;
+          &lt;hostonly_if_name&gt;</computeroutput>.</para>
+
+          <para>Alternatively, you can also use the --netname option as with
+          internal networks if you know the host-only network's name; you can
+          see the names with <computeroutput>VBoxManage list
+          hostonlyifs</computeroutput> (see <xref linkend="vboxmanage-list" />
+          above).</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>The following additional parameters are required when first adding a
+    DHCP server:<itemizedlist>
+        <listitem>
+          <para>With <computeroutput>--ip</computeroutput>, specify the IP
+          address of the DHCP server itself.</para>
+        </listitem>
+
+        <listitem>
+          <para>With <computeroutput>--netmask</computeroutput>, specify the
+          netmask of the network.</para>
+        </listitem>
+
+        <listitem>
+          <para>With <computeroutput>--lowerip</computeroutput> and
+          <computeroutput>--upperip</computeroutput>, you can specify the
+          lowest and highest IP address, respectively, that the DHCP server
+          will hand out to clients.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>Finally, you must specify <computeroutput>--enable</computeroutput>
+    or the DHCP server will be created in the disabled state, doing
+    nothing.</para>
+
+    <para>After this, VirtualBox will automatically start the DHCP server for
+    given internal or host-only network as soon as the first virtual machine
+    which uses that network is started.</para>
+
+    <para>Reversely, use <computeroutput>VBoxManage dhcpserver
+    remove</computeroutput> with the given <computeroutput>--netname
+    &lt;network_name&gt;</computeroutput> or <computeroutput>--ifname
+    &lt;hostonly_if_name&gt;</computeroutput> to remove the DHCP server again
+    for the given internal or host-only network.</para>
+
+    <para>To modify the settings of a DHCP server created earlier with
+    <computeroutput>VBoxManage dhcpserver add</computeroutput>, you can use
+    <computeroutput>VBoxManage dhcpserver modify</computeroutput> for a given
+    network or host-only interface name.</para>
+  </sect1>
+</chapter>
Index: trunk/doc/manual/fr_FR/user_VirtualBoxAPI.xml
===================================================================
--- trunk/doc/manual/fr_FR/user_VirtualBoxAPI.xml	(revision 33555)
+++ trunk/doc/manual/fr_FR/user_VirtualBoxAPI.xml	(revision 33555)
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="VirtualBoxAPI">
+  <title>VirtualBox programming interfaces</title>
+
+  <para>VirtualBox comes with comprehensive support for third-party
+  developers. The so-called "Main API" of VirtualBox exposes the entire
+  feature set of the virtualization engine. It is completely documented and
+  available to anyone who wishes to control VirtualBox programmatically.
+  </para>
+
+  <para>The Main API is made available to C++ clients through COM (on Windows
+  hosts) or XPCOM (on other hosts). Bridges also exist for SOAP, Java and
+  Python.</para>
+
+  <para>All programming information (documentation, reference information,
+  header and other interface files as well as samples) have been split out to
+  a separate <emphasis role="bold">Software Development Kit (SDK),</emphasis>
+  which is available for download from <ulink type=""
+  url="http://www.virtualbox.org">http://www.virtualbox.org</ulink>. In
+  particular, the SDK comes with a "Programming Guide and Reference" in PDF
+  format, which contains, among other things, the information that was
+  previously in this chapter of the User Manual.</para>
+</chapter>
